planner

package
v0.9.0 Latest Latest
Warning

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

Go to latest
Published: Sep 17, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

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

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

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

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

func New(cfg Config) (adkagent.Agent, error)

New constructs the planner as a Task-mode LlmAgent via pkg/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

func NewRoot(cfg Config) (adkagent.Agent, error)

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

func NotImplemented(toolName string) map[string]any

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 added in v0.5.0

func Vocabulary(cfg Config) ([]tool.Tool, error)

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 pkg/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 PauseRecorder added in v0.2.0

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 added in v0.5.0

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 added in v0.5.0

type SubRunSink interface {
	Observe(ev *session.Event) error
	Close()
}

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.

Jump to

Keyboard shortcuts

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