Documentation
¶
Overview ¶
Package delegate is the sub-agent invocation primitive — the runtime that lets a parent agent call another agent with a different reasoning posture, system prompt, allowed-tools subset, and resource budget. From the parent's perspective a delegate call is a single tool invocation; underneath, the runtime spawns a sub-session that has its own context window, its own envelope identity (Causation.AgentID and Depth), and its own budget.
Postures are looked up via the posture.Registry capability; budgets are non-negotiable and enforced here; recursion depth is capped per-posture (falling back to MaxDepth on the Runtime). Results are optionally cached by a content-addressable key including the posture's Version, so any edit to the posture invalidates previously-cached outputs.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrRecursionLimit = errors.New("delegate: recursion depth limit exceeded")
ErrRecursionLimit is returned when a delegate call exceeds MaxDepth or the posture's MaxRecursionDepth.
Functions ¶
func SyncLLM ¶
func SyncLLM(ctx context.Context, bus engine.EventBus, req events.LLMRequest) (events.LLMResponse, error)
SyncLLM emits an llm.request and synchronously returns the matching llm.response. It is the shared implementation behind every blocking sub-agent LLM call (delegate runtime, subagent worker loop, and any future blocking caller) — the pattern was previously copy-pasted across both call sites.
Semantics:
Stream is forced to false. The helper relies on the bus dispatching synchronously: a non-streaming provider emits llm.response inside the Emit("llm.request") call, the subscriber pushes onto respCh, and the select below picks it up. A streaming response would arrive after Emit returns and miss the select, surfacing as ErrNoResponse.
RequestID is generated when empty. Subscribers match the response primarily by req.RequestID; a metadata "_source" fallback keeps compatibility with callers that haven't migrated their downstream filters yet.
A block veto on before:llm.request surfaces as an error wrapping engine.ErrLLMRequestBlocked rather than waiting for a response that will never come.
An interception (engine.InterceptLLMRequest — a fanout role, the test IO mock) is answered asynchronously, so the helper waits on ctx for the correlated llm.response and returns ctx.Err() if ctx ends first. Fanout legs, which share the RequestID, are skipped for the merged response.
If a published request gets no synchronous response (no provider wired for the request's role), engine.ErrNoLLMResponse is returned — same diagnostic behavior the call sites had before extraction. See engine.AwaitLLMResponse.
Types ¶
type Cache ¶
Cache caches Output by key. Implementations must be safe for concurrent use. Default in-process cache is bounded by the configured Capacity.
type Input ¶
type Input struct {
Posture string
Task string
Context map[string]any
ParentTurn string
ParentDepth int
Overrides Overrides
}
Input is the parent agent's request. Posture names the registered AgentPosture; Task is the natural-language instruction; Context is a structured map the runtime serializes into the sub-agent's initial user message under a <delegate_context> XML wrapper.
type MemoryCache ¶
type MemoryCache struct {
// contains filtered or unexported fields
}
MemoryCache is a goroutine-safe in-process cache with a fixed capacity and least-recently-used eviction. Suitable for the single-engine default.
func NewMemoryCache ¶
func NewMemoryCache(capacity int) *MemoryCache
NewMemoryCache returns a cache with the given capacity (events, not bytes). Capacity <= 0 disables eviction — the cache grows unbounded.
func (*MemoryCache) Put ¶
func (c *MemoryCache) Put(key string, out Output)
type Output ¶
type Output struct {
Result string
Status Status
Error string
TokensUsed int
ToolCallsUsed int
Elapsed time.Duration
SubSessionID string
PostureName string
PostureVer string
Depth int
}
Output is the runtime's response to the parent agent. SubSessionID correlates this call with the journal entries the sub-agent produced.
type Overrides ¶
Overrides let a single call tighten (or loosen) the posture default budget. Zero fields fall back to the posture's DefaultBudget.
type Runtime ¶
type Runtime struct {
Registry posture.Registry
Bus engine.EventBus
Logger *slog.Logger
Cache Cache
// MaxDepth caps recursion depth across all postures. Zero disables the
// global cap (postures may still set MaxRecursionDepth).
MaxDepth int
// ToolSnapshot returns the currently-registered tool defs the
// sub-agent should choose from. Filtered by AllowedTools before the
// LLM request is built.
ToolSnapshot func() []events.ToolDef
}
Runtime executes delegate calls against a posture registry.