delegate

package
v0.31.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 13 Imported by: 1

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

View Source
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

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

type Cache interface {
	Get(key string) (Output, bool)
	Put(key string, out Output)
}

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) Get

func (c *MemoryCache) Get(key string) (Output, bool)

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

type Overrides struct {
	MaxTokens    int
	MaxToolCalls int
	Timeout      time.Duration
}

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.

func (*Runtime) Run

func (r *Runtime) Run(ctx context.Context, in Input) (Output, error)

Run executes a single delegate call. Blocks until the sub-agent completes, the budget exhausts, the context cancels, or an error halts the loop.

type Status

type Status string

Status classifies a delegate outcome. Replay tools and the parent agent's follow-up prompt branch on this rather than parsing Error strings.

const (
	StatusSuccess  Status = "success"
	StatusPartial  Status = "partial"
	StatusError    Status = "error"
	StatusTimeout  Status = "timeout"
	StatusCancel   Status = "cancelled"
	StatusCacheHit Status = "cache_hit"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL