feat(agent): add AgentDispatcher execution seam

[localai-bot]

What

Adds an opt-in execution seam so embedders can run spawned sub-agents out of process (e.g. dispatch to a remote worker over a message bus) while cogito keeps owning all sub-agent lifecycle bookkeeping.

Why

Today spawn_agent always runs the sub-agent loop in-process (go runAgent → recursive ExecuteTools). The only extension point is the LLM factory (which model to talk to), not where the loop runs. Distributed embedders therefore have to reimplement cogito's entire agent-lifecycle layer (registry, status, completion notification, detach) on top of their own transport. This seam lets them reuse cogito's lifecycle and only supply the transport.

API

type AgentRunSpec struct {
    ID, Type, Task, SystemPrompt, Model string
    Temperature float32
    Metadata    map[string]string
    Tools       []string
    Background  bool
    Emit        func(AgentEvent) // optional per-sub-agent progress stream
}
type AgentEvent struct { AgentID, Kind, Delta, Result, Err string } // Kind: running|delta|done|error
type AgentDispatcher func(ctx context.Context, spec AgentRunSpec) (Fragment, error)
var ErrDispatchFallback = errors.New("cogito: dispatch fallback to in-process")
func WithAgentDispatcher(d AgentDispatcher) Option

Behavior

• Nil dispatcher → existing in-process behavior, unchanged.
• Dispatcher set → cogito calls it instead of running the loop in-process, but STILL does registration, status, the done channel, spawn/completion callbacks, and the completion injection into the parent loop. The dispatcher only returns the final Fragment.
• ErrDispatchFallback → defer a given spawn back to the in-process path.
• runAgent branches on the dispatcher; spawn builds an AgentRunSpec (resolved persona/tools/model) and an optional Emit stream tagged with the agent ID.

Tests

New agent_dispatcher_test.go: foreground dispatch, background dispatch (asserts cogito auto-injects completion), ErrDispatchFallback, and nil-dispatcher (existing behavior preserved). All green. No changes to existing in-process agent semantics.

🤖 Generated with Claude Code