Documentation
¶
Overview ¶
Package planner implements the v0.1 scaffold of the supervisor-body planner from docs/orchestration-design.md ("The planner", shape C with light D flavor): a Task-mode LlmAgent whose tool vocabulary is the workload's execution vocabulary. Each planner turn is one tool call; the "graph" is emergent from the sequence of decisions and is recorded to the event log turn by turn; finish_task (auto-installed by ADK for Task mode) is the canonical exit.
v0.1 scaffold scope (orchestration-design phasing, "v0.1" row — "Planner scaffolded — schema for tool vocabulary in place, but run_shape_* tools may not all be implemented yet"):
- invoke_specialist(name, input) is implemented and dispatches to the bundle's built specialist roster (see dispatch.go for the mechanism and the ADK constraints that shaped it).
- run_shape_llm_router and run_shape_fan_out_fan_in are declared (their schema is part of the pinned vocabulary contract) but return a structured not_implemented result; the Phase-2 "reference-graph library" item wires them.
- request_operator_input(message, schema) pauses the planner on a durable long-running-tool interrupt (see dispatch.go for what ADK v2.1.0 does and does not allow from a tool context).
Budget: the planner introduces no budget machinery of its own. Its model calls stream past the runner event consumer like any other agent's, so the workload meter (pkg/budget, wired in cmd/mast) bounds the planner exactly as it bounds specialists. See the "sub-invocation metering" note in dispatch.go for the one known gap.
Index ¶
- Constants
- Variables
- func New(cfg Config) (adkagent.Agent, error)
- func NewRoot(cfg Config) (adkagent.Agent, error)
- func NotImplemented(toolName string) map[string]any
- func Vocabulary(cfg Config) ([]tool.Tool, error)
- type Config
- type DispatchOutcome
- type PauseRecorder
- type SubRunObserver
- type SubRunSink
Constants ¶
const ( ToolInvokeSpecialist = "invoke_specialist" ToolRunShapeLLMRouter = "run_shape_llm_router" ToolRunShapeFanOutFanIn = "run_shape_fan_out_fan_in" ToolRequestOperatorInput = "request_operator_input" // ToolPauseSession is the v0.2 plane-A self-pause // (docs/durable-execution-design.md, "The v0.2 pause/abort // mechanics"). Registered only when Config.PauseRecorder is set. ToolPauseSession = "pause_session" )
Tool names of the v0.1 planner vocabulary. Exported so callers and tests can pin the contract without string literals. finish_task is not listed: ADK auto-installs it for Task mode.
const DefaultInstructionTemplate = `` /* 1624-byte string literal not displayed */
DefaultInstructionTemplate is the planner's default system prompt (docs/orchestration-design.md "The planner": supervisor-body turn loop, plan-first gate as a first-turn prose plan, finish_task exit). Rendered with the roster; Config.Instruction overrides it wholesale.
Variables ¶
var ErrNotImplemented = fmt.Errorf("planner: tool not implemented in v0.1 scaffold")
ErrNotImplemented mirrors the NotImplemented tool result for Go callers probing the vocabulary programmatically.
Functions ¶
func New ¶
New constructs the planner as a Task-mode LlmAgent via internal/agent.NewTaskAgent, with the v0.1 tool vocabulary attached.
The returned agent CANNOT be a runner root directly: ADK v2.1.0's runner requires an LlmAgent root to be Chat-mode (runner.go, "root agent ... must be a chat LlmAgent"). Use NewRoot for the runnable wrapper.
func NewRoot ¶
NewRoot constructs the planner and wraps it as a runnable root agent: a single-node workflow (DynamicNode -> RunNode -> AgentNode) around the Task-mode planner, because ADK's runner rejects non-Chat LlmAgent roots. The wrapper:
- forwards every planner event to the runner's event stream (so the workload meter and event log see planner turns), and
- propagates a request_operator_input pause as a durable workflow interrupt (WithRaiseOnWait -> ErrNodeInterrupted -> node parks).
The body passes nil node input on every activation: the planner reads the work item from session history (the runner appends the inject turn before dispatch), which keeps fresh runs and post-interrupt resume re-runs identical — on resume the planner simply continues from history, where the operator's FunctionResponse now answers the pending call.
func NotImplemented ¶
NotImplemented is the structured result every scaffolded-but-unwired vocabulary tool returns in v0.1. It is a tool RESULT rather than a Go error so the planner LLM receives a deterministic, parseable response (a Go error would surface as {"error": ...} and invite retries); ErrNotImplemented is the programmatic counterpart for mast-side callers.
func Vocabulary ¶
Vocabulary builds the tools the planner is given for cfg, in the order New attaches them.
It is exported so an operator catalog can report the planner's control-plane tools (GET /sessions/{id}/tools, #137). ADK exposes no accessor for a built agent's tools — llmagent keeps them behind an internal Reveal, the gap behind #51 / adk-go#1229 — so by the time a caller holds the agent, the list is gone. The alternative was a hand-maintained list in the daemon, which drifts, and a catalog that names tools the planner does not have is worse than one that omits tools it does.
New calls this rather than duplicating it, which is the property that matters: the enumeration and the wiring are the same code, so a tool added to the vocabulary appears in the catalog without anyone remembering to add it twice.
The set is config-dependent, not fixed: pause_session is present only when cfg.PauseRecorder is wired. finish_task is absent because ADK installs it, not mast.
Types ¶
type Config ¶
type Config struct {
// Name is the workload name; the planner agent is named
// "<Name>_planner". Required.
Name string
// Description is a human-readable summary, surfaced in operator
// UIs and logs.
Description string
// Model is the LLM driving the planner's turn loop. Required.
Model model.LLM
// Instruction overrides the default planner instruction template.
// Empty renders DefaultInstructionTemplate against the roster —
// the planner-specific frame from orchestration-design's planner
// section (resolved open question #7: single template with
// variables; per-workload override as the escape hatch). The
// generic internal/agent DefaultTaskInstruction never applies here: a
// planner is never a generic task agent, so the template embeds
// the unattended-task discipline itself.
Instruction string
// Specialists is the bundle's built roster, indexed by specialist
// name — the invoke_specialist targets.
Specialists map[string]adkagent.Agent
// Order optionally fixes the roster ordering used in the rendered
// instruction and tool description (bundle declaration order).
// Names absent from Specialists are ignored; specialists absent
// from Order are appended in map-iteration-stable sorted order.
Order []string
// PauseRecorder mints the durable pause record + resume token for
// pause_session (the v0.2 plane-A self-pause). Nil leaves
// pause_session out of the vocabulary — callers without a durable
// store (one-shot in-memory sessions) get a coherent tool set
// rather than a pause that would die with the process.
PauseRecorder PauseRecorder
// SubRunObserver is opened once per invoke_specialist dispatch and
// handed every event that dispatch's private sub-runner emits, so a
// delegated specialist's spend and behaviour land somewhere. Nil
// leaves the sub-run unobserved, which is what it was through v0.4
// and what it should stay for a caller with nothing to fold events
// into.
//
// This is not an optional nicety for a host that meters or watches:
// a sub-run is a separate runner, so its events reach nothing the
// outer runner's consumer is wired to. See SubRunObserver and #226.
SubRunObserver SubRunObserver
}
Config describes how to construct a planner for one workload bundle.
type DispatchOutcome ¶
type DispatchOutcome struct {
// Err is the sub-runner's own failure: the specialist stopped
// because something broke under it, most often the provider
// rejecting a model call. Nil when the dispatch ran to completion
// or when the sink itself stopped it.
//
// This is the case with no other symptom. A halt is the host's own
// decision and a completed dispatch produces a result; a sub-runner
// error produces neither, and until #452 nothing anywhere recorded
// that it had happened — the planner was handed the error as an
// ordinary tool result and was free to do the specialist's work
// itself, at full parent-context cost, on a run that still scored.
Err error
// Halted is what the sink's own Observe returned to stop the run,
// echoed back so a sink that batches does not have to remember. Nil
// when the sink stopped nothing.
//
// Err and Halted are mutually exclusive: once a sink halts a
// dispatch the sub-context is cancelled, and the runner's ensuing
// "context canceled" is a symptom of the stop rather than a second
// failure, so it is not reported as one.
Halted error
}
DispatchOutcome is how one dispatch ended, handed to SubRunSink.Close.
A struct rather than an error argument because the two ways a dispatch fails to complete are not the same event and a host acts on them differently — and because a third way, if one appears, should be a field rather than another signature.
type PauseRecorder ¶
type PauseRecorder interface {
PauseInterrupt(ctx context.Context, userID, sessionID, interruptID string, spec transcript.PauseSpec) (transcript.PauseHandle, error)
}
PauseRecorder mints the durable pause record + resume token for a plane-A interrupt pause. *transcript.Store implements it.
type SubRunObserver ¶
type SubRunObserver interface {
SubRun(sessionID, specialist string) SubRunSink
}
SubRunObserver is asked for one sink per invoke_specialist dispatch, and the sink is handed every event that dispatch's private sub-runner emits.
sessionID is the OUTER session's ID — the sub-run's own session is an in-memory throwaway, and attributing a dispatch to it would file the spend under a session no operator can name. specialist is the roster name being dispatched, for a host that labels or scopes by it; the events' own Author carries the specialist's agent name, which is what lets a host's per-specialist ceilings bind here the same way they bind on a coordinator's dispatch.
A sink per dispatch rather than one flat callback, because the two hosts that consume this need opposite things from the boundary. The budget meter is cumulative and would be happy with a flat stream; the watchdog is not — it dedups an aggregator's re-emissions within a run and counts repetition across runs, so it needs to know where one dispatch ends and the next begins. A flat callback cannot say, and it cannot say it at all under parallel dispatch, where two sub-runs interleave their events into one callback with nothing to tell them apart.
Returning nil is allowed and means the host is not interested in this dispatch.
type SubRunSink ¶
type SubRunSink interface {
Observe(ev *session.Event) error
Close(DispatchOutcome)
}
SubRunSink receives one dispatch's events, in order, and is closed once when the dispatch ends however it ends.
Returning an error from Observe stops the sub-run: the specialist's remaining work is abandoned and invoke_specialist returns a partial result labelled with the reason, so the planner sees a refusal it can route around instead of a cancelled session. Sinks must therefore return an error only when the run genuinely should stop — a metering failure that is not a ceiling should be logged and swallowed.
Close is where a sink that batches gets its last word: the watchdog's end-of-run drain lands here, the same one watchdog.Tap defers at the end of a turn. It cannot stop anything — the run is over — but it can still trip a session-level latch the host holds.
It is also the only place a host learns that the dispatch did not finish. A sub-runner error — a provider rejection, most of all a transient one — ends the dispatch without producing an event, so a sink watching the stream sees a dispatch that simply stopped (#452). Close carries the reason so the host can say so.