planner

type ActionExtraFieldDroppedPayload ¶

type ActionExtraFieldDroppedPayload struct {
	events.SafeSealed
	Identity   identity.Quadruple
	Field      string
	OccurredAt time.Time
}

ActionExtraFieldDroppedPayload is the typed payload for EventTypePlannerActionExtraFieldDropped. SafePayload — every field is operator-visible debug data, never secret-shaped:

• `Identity` is the run's identity quadruple.
• `Field` is the name of the dropped extra field (`reasoning` or `thought`) — the parser strips fields the narrowed `{tool, args}` action schema no longer recognises.

The event is a SOFT telemetry signal: extra fields are stripped, the step proceeds. It is NOT a fail-loudly surface — the runtime fails OPEN on extra fields for backward compatibility with older trained models. The captured thinking trace flows through the provider channel onto `trajectory.Step.ReasoningTrace` instead.

type AnswerEnvelope ¶ added in v1.3.0

type AnswerEnvelope struct {
	// Answer is the assistant's final answer text extracted from the
	// Finish payload.
	Answer string `json:"answer"`
	// FinishReason is the planner's Finish.Reason, verbatim
	// (string-typed on the wire).
	FinishReason string `json:"finish_reason"`
	// ToolCallsSeen is the number of actual tool invocations the run
	// dispatched — computed via CountToolInvocations, NOT
	// len(Trajectory.Steps). A CallTool step counts once; a
	// CallParallel step counts once PER branch (the runtime dispatches
	// N tools concurrently, not one); SpawnTask and AwaitTask steps
	// count zero — they are runtime decisions, never tool dispatches.
	//
	// This field's semantics were redefined from an earlier len(Steps)
	// reading, which silently miscounted: undercounting a CallParallel
	// step (1 instead of N branches) and overcounting a SpawnTask /
	// AwaitTask step (a dispatch that never happened). This is a
	// value-semantics change on an SDK-visible field — embedders
	// comparing ToolCallsSeen against a fixed expectation should
	// re-check it after upgrading.
	ToolCallsSeen int `json:"tool_calls_seen"`
	// AnswerPayload is the schema-validated raw-JSON terminal answer of
	// a structured-output run — the run the caller opened with
	// assemble.WithOutputSchema. It is ADDITIVE and omitted (`omitempty`)
	// on plain runs, so the three pre-existing keys and their byte-shape
	// are untouched (the golden encoding test still pins them). When
	// present it carries the exact validated bytes captured at the
	// validation site (never a lossy string round-trip); Answer carries
	// the same payload's string rendering for backward compatibility.
	//
	// A structured-output run whose terminal answer failed validation
	// after the correction budget never reaches an envelope at all — the
	// runner returns ErrOutputInvalid instead (CLAUDE.md §13: no silent
	// fallback to unvalidated text).
	AnswerPayload json.RawMessage `json:"answer_payload,omitempty"`
}

AnswerEnvelope is the canonical JSON shape `tasks.TaskResult.Value` carries when a run-loop driver completes a task from a Finish with reason FinishGoal:

{"answer": "<llm text>", "finish_reason": "<FinishReason>", "tool_calls_seen": <int>}

Producers: the per-task run-loop drivers (cmd/harbor + harbortest/devstack) marshal it on MarkComplete. Consumers: the `tasks.get` Protocol projector reads it into `result_inline`, and `internal/runtime/dispatch`'s AwaitTask / retain-turn SpawnTask observation parses it back for the awaiting planner.

The encoding is byte-compatible with the map-literal shape (keys in the same order; pinned by the golden test in answer_envelope_test.go). Forward-compatible — future phases extend with new keys; never break existing ones.

named and exported what was an implicit cmd↔cmd wire contract (the SDK friction audit's Pattern 1 / P3 finding): one `package main` file marshalled what another parsed, with no named type anywhere. Home rationale (import direction, recorded in the phase plan): the envelope is the projection of Finish — it carries FinishReason verbatim — and both producers (run-loop drivers) and consumers (`internal/runtime/dispatch`, Protocol projectors) already import `internal/planner`; homing it in `internal/tasks` would force a new tasks→planner import edge (tasks is planner-free today).

type ArtifactManifestEntry ¶ added in v1.2.0

type ArtifactManifestEntry struct {
	// Ref is the content-addressed artifact identifier the model passes
	// to `artifact_fetch` to read the artifact's bytes.
	Ref string
	// Filename is the operator-supplied or producer-supplied original
	// filename, if known. May be empty.
	Filename string
	// MIME is the artifact's IANA media type (metadata for the model).
	MIME string
	// SizeBytes is the artifact's byte length (metadata, not the bytes).
	SizeBytes int64
	// Provenance is the human-readable origin of the artifact, resolved
	// by the run loop from the artifact's `Source` map (canonical
	// `source` key else the tool/producer/flow name else "unknown").
	Provenance string
}

ArtifactManifestEntry is one metadata-only row in the session-artifact manifest. The run loop builds the slice from `ArtifactStore.List` scoped to the run's `(tenant, user, session)` triple and sets it on `RunContext.SessionArtifacts`; the ReAct planner renders the rows into the read-only `<session_artifacts>` prompt block so the model can `artifact_fetch` any listed `Ref`.

The shape carries NO bytes — content stays in the store and is fetched on demand via the `artifact_fetch` meta-tool (heavy-content discipline). `Provenance` is the run-loop-resolved origin string (e.g. "user_upload", "tool: web_search", "flow: ...") — see the run loop's provenance resolver.

func BuildArtifactManifest(refs []artifacts.ArtifactRef) []ArtifactManifestEntry

type AttachmentDisposition ¶ added in v1.4.0

type AttachmentDisposition string

AttachmentDisposition declares how an uploaded input artifact is handed to the model. The zero value ("") means "no disposition declared" — the materializer falls back to the legacy per-MIME dispatch, so a headless consumer that never sets the field gets the default behaviour unchanged.

const (
	// DispositionRef emits an `ArtifactStub` by reference with the
	// existing `Fetch.Tool` hint — the developer-controllable
	// "process it myself via a tool" path. The runtime default for
	// every non-image MIME.
	DispositionRef AttachmentDisposition = "ref"
	// DispositionInline inlines the artifact bytes as a DataURL part.
	// V1.1 supports inline for `image/*` only (the sub-threshold
	// vision fast path); other MIMEs degrade to ref with a returned
	// [DispositionDegradation]. The runtime default for `image/*`.
	DispositionInline AttachmentDisposition = "inline"
	// DispositionProviderNative hands the artifact to the provider's
	// own understanding: the materializer emits a typed part with the
	// `ProviderNative` flag set, and the LLM driver uploads the
	// content to the provider's file surface inside `Complete`,
	// rewriting the part to an opaque `file_id` reference (RFC §6.5).
	// Opt-in only — never the runtime default. A provider without
	// upload support for the modality degrades loudly to the
	// `ArtifactStub` reference at the driver.
	DispositionProviderNative AttachmentDisposition = "provider_native"
)

func DefaultDisposition(mime string) AttachmentDisposition

func DispositionTool(name string) AttachmentDisposition

func ParseDisposition(s string) (AttachmentDisposition, error)

func (d AttachmentDisposition) IsZero() bool

func (d AttachmentDisposition) ToolName() (string, bool)

func (d AttachmentDisposition) Valid() bool

type AwaitTask ¶

type AwaitTask struct {
	TaskID tasks.TaskID
}

AwaitTask blocks the planner until the named task reaches a terminal state. The Runtime's executor watches the task's lifecycle and re-invokes Next with the MemberOutcome surfaced in the next trajectory step.

type BackgroundMemberOutcome ¶

type BackgroundMemberOutcome = trajectory.BackgroundMemberOutcome

BackgroundMemberOutcome is the per-member outcome inside a BackgroundResult.

type BackgroundResult ¶

type BackgroundResult = trajectory.BackgroundResult

BackgroundResult is the planner's projection of a resolved non-retain-turn task group.

type Batch ¶ added in v1.16.0

type Batch struct {
	// Tools are the catalog-tool branches, dispatched concurrently
	// and joined per Join (nil collapses to JoinAll, matching the
	// native-parallel path).
	Tools []CallTool
	// Spawns are the task spawns; every entry's Spec.RetainTurn is
	// false.
	Spawns []SpawnTask
	// Join governs ONLY Tools. It is nil (JoinAll) when Tools is
	// empty — a spawns-only Batch carries no join.
	Join *JoinSpec
}

Batch groups zero-or-more catalog-tool branches with zero-or-more task spawns projected from ONE native multi-call LLM response — the shape a projector constructs when a model batches a `_spawn_task` call alongside an ordinary tool call (or alongside other spawns) in a single response.

Batch is a distinct fourth dispatch shape, NOT a widening of CallParallel: tool-invocation accounting counts Tools and Spawns separately (a spawn is never a tool invocation — see DecisionInvocationCount, which returns len(Tools) for a Batch and counts Spawns as zero). Reserved-control terminal/blocking names (`_finish` / `_await_task`) are never Batch members; only catalog tools and non-retain-turn spawns are.

Invariants (enforced by NewBatch, failing loud on violation):

• len(Tools)+len(Spawns) >= 2. A single-branch would-be Batch is degenerate; producers construct the plain CallTool / SpawnTask / CallParallel shape instead (one representation per semantic).
• Every Spawns[i].Spec.RetainTurn is false. A turn-retaining spawn inside a non-blocking multi-dispatch is a contradiction.

func NewBatch(tools []CallTool, spawns []SpawnTask, join *JoinSpec) (Batch, error)

type BatchObservation ¶ added in v1.16.0

type BatchObservation struct {
	// Tools is the per-tool-branch outcome slice, index-aligned to
	// [Batch.Tools]. It reuses [ParallelBranchObservation] verbatim —
	// the tool half of a Batch dispatches through the SAME executor path
	// a [CallParallel] does, so its per-branch observation shape is
	// identical.
	Tools []ParallelBranchObservation `json:"tools,omitempty"`

	// Spawns is the per-spawn-branch REGISTRATION outcome slice,
	// index-aligned to [Batch.Spawns].
	Spawns []BatchSpawnObservation `json:"spawns,omitempty"`
}

BatchObservation is the aggregate observation a runtime ToolExecutor produces when it dispatches a Batch decision. A batch has two heterogeneous halves — catalog-tool branches and task spawns — and this observation carries both, each index-aligned to the originating Batch.Tools / Batch.Spawns declaration order REGARDLESS of the order the branches or spawns actually complete in. The caller MUST index or look up by CallID / Index to reconstruct per-`call_id` replies — never range a Go map — because provider tool-calling wire contracts require exactly one reply per `call_id`, some of them order-sensitive.

The shape lives in `internal/planner` (not the runtime executor's package) for the same reason ParallelObservation does: BOTH sides of the round-trip consume it — the production ToolExecutor produces it as the step's Observation / LLMObservation, and the React prompt builder reads it back to emit the per-branch `role:"tool"` messages. Both packages already import `internal/planner`, so placing the type here avoids a new cross-package dependency.

JSON-encodable: the trajectory persists Step.Observation / Step.LLMObservation across checkpoints, so every field carries a JSON tag and the embedded tool `Value`s hold only JSON-encodable results.

type BatchSpawnObservation ¶ added in v1.16.0

type BatchSpawnObservation struct {
	// CallID is the provider-assigned tool-call identifier sourced from
	// the originating [Batch.Spawns][Index].CallID (the native
	// `_spawn_task` call's id). The prompt builder stamps it onto the
	// matching `role:"tool"` message's ToolCallID. Empty when the spawn
	// carried no provider id (a programmatic spawn); the renderer then
	// falls back to a deterministic synthetic id keyed on Index.
	CallID string `json:"call_id,omitempty"`

	// Index is the spawn's position in the originating [Batch.Spawns]
	// slice. The deterministic merge key: the renderer pairs each
	// spawn's observation to its assistant tool-call by Index regardless
	// of CallID collisions.
	Index int `json:"index"`

	// TaskID is the registered task's id on a successful registration.
	// Empty on a registry reject.
	TaskID string `json:"task_id,omitempty"`

	// GroupID is the registered task's group id on a successful
	// registration — either the spawn's explicit group or the one
	// auto-created group the executor resolves for a batch's ungrouped
	// spawns. Empty on a registry reject, and empty for a single
	// ungrouped spawn that kept the ad-hoc single-member-group path.
	GroupID string `json:"group_id,omitempty"`

	// Error is the spawn's registration failure message. Non-empty only
	// on a registry reject; empty on success.
	Error string `json:"error,omitempty"`
}

BatchSpawnObservation is one Batch.Spawns entry's REGISTRATION outcome. "Complete" here means REGISTERED, not terminal: a spawn's eventual result arrives later via the task registry's group-watch path, never through this observation — so a spawn is never reported as "not done yet". Exactly one of (TaskID+GroupID) or Error is populated: a successful registration carries the assigned task id and its group id; a registry reject (depth-cap exceeded, sealed group, malformed request) carries that spawn's error as a value, so every `call_id` is answered even when one spawn is rejected.

type Budget ¶

type Budget struct {
	// Deadline is the absolute wall-clock deadline for the run. Zero
	// value means no deadline. The Runtime's ctx is set to expire at
	// Deadline; the planner SHOULD honour ctx.Err() between long
	// phases of work.
	Deadline time.Time
	// HopBudget is the maximum number of planner steps remaining.
	// Negative means no cap. Decrements per planner step.
	HopBudget int
	// CostCap is the maximum LLM cost (USD-equivalent micros) for
	// the run. Zero means no cap. The Runtime's Governance subsystem
	// enforces; the planner reads.
	CostCap int64
	// CostSpent is the cost accumulated so far this run. Same units
	// as CostCap.
	CostSpent int64
	// TokenBudget is the maximum estimated token count the planner-
	// observed trajectory may carry before the runtime invokes the
	// trajectory summariser (seam; consumer —).
	// Zero means no token-budget enforcement; the trajectory
	// grows unbounded (until the context-window safety net
	// backstops it).
	//
	// The runtime's CompressionRunner reads this field: the steering
	// RunLoop calls [CompressionRunner.MaybeCompress] at each step
	// boundary when TokenBudget > 0 and a runner is configured on the
	// run spec. When the trajectory's estimate exceeds the budget the
	// configured [Summariser] (production: the LLM-backed
	// TrajectorySummariser in internal/llm/summarizer) produces a
	// [TrajectorySummary] that replaces the raw step history in
	// subsequent prompt builds (RFC §6.2). One
	// compression per run at V1.1.x (the runner's Summary != nil
	// idempotence). Production wiring: the `planner.token_budget`
	// config knob projects here via the per-task run-loop drivers.
	// Compression is a runtime concern; the planner sees only the
	// compacted view via the trajectory summary.
	TokenBudget int
}

Budget carries the per-run hard caps the planner observes. The Runtime enforces them outside the planner — the planner reads to make budget-aware decisions (e.g. choose a cheaper model when CostRemaining is low).

type BudgetHints ¶

type BudgetHints struct {
	// MaxSteps is the advisory planner-step ceiling. Nil = no hint.
	MaxSteps *int
	// MaxCostUSD is the advisory cost ceiling, in USD. Nil = no hint.
	MaxCostUSD *float64
	// MaxLatencyMS is the advisory wall-clock latency ceiling, in
	// milliseconds. Nil = no hint.
	MaxLatencyMS *int64
}

BudgetHints carries the optional budget caps a runtime may surface to the planner through PlanningHints.Budget. Every field is a pointer: nil means "no cap for this dimension", so a partial BudgetHints renders only the dimensions it pins. The caps are advisory prompt content — the runtime's Governance subsystem and Budget enforce the hard caps; the planner reads BudgetHints to make budget-aware decisions.

type CallParallel ¶

type CallParallel struct {
	Branches []CallTool
	Join     *JoinSpec
}

CallParallel invokes N tools concurrently with a JoinSpec describing how the Runtime merges results. Atomic setup validation: any branch's invalid args fails the whole call before execution (RFC §6.2; Harbor ships the executor).

Branches share the same step-level pause/cancel atomicity contract see the plan.

type CallTool ¶

type CallTool struct {
	// Tool is the name registered in the ToolCatalogView.
	Tool string
	// Args is the JSON-encoded argument payload matching the tool's
	// ArgsSchema. Validation happens at the catalog edge; an invalid
	// payload produces `tools.ErrToolInvalidArgs` from dispatch.
	Args json.RawMessage
	// CallID is the provider-assigned tool-call identifier (Phase
	// native tool-calling). Empty for prompt-
	// engineered CallTool emissions; non-empty when the call
	// originated from a native ToolCall. Round-trips on the
	// RoleTool message's ToolCallID field.
	CallID string
}

CallTool invokes one tool with structured args. The Runtime dispatches via the production ToolCatalog + ToolPolicy; the planner does not block on the call.

The action shape is intentionally narrow — `{tool, args}` only. An earlier phase dropped the former `Reasoning` field: the model emits the action JSON, and the provider-side thinking trace is captured separately on `trajectory.Step.ReasoningTrace` via `llm.CompleteResponse.Reasoning`. Reasoning is captured content, not part of the structured decision; replaying it into prompts is an operator-controlled per-agent knob, never a schema field.

type CancelTask ¶ added in v1.16.0

type CancelTask struct {
	// TaskID is the descendant to cancel.
	TaskID tasks.TaskID
	// Reason is the human-readable cancellation reason recorded on the
	// emitted task.cancelled event.
	Reason string
}

CancelTask cancels one background task THIS run spawned — the model's own judgment applied to work it started (e.g. cancelling the losing branches of a fan-out once the first answered). A non-terminal, non-blocking decision dispatched like CallTool; the planner observes the {task_id, cancelled} outcome on its next turn.

TaskID must reach the calling run's own task by walking the parent-task chain upward — a run can cancel only its own descendants, never a sibling run's tasks in the same session. A cancel on a task the run spawned under an isolate propagation policy still succeeds: a direct cancel is never gated on the target's own propagation mode — isolate only detaches a task from an ANCESTOR's cascade, never from a direct cancel by the run that spawned it or by the operator.

type ChunkKind ¶ added in v1.2.0

type ChunkKind string

ChunkKind is a sealed enum for the streaming-chunk kind. Values: ChunkContent (model output text), ChunkReasoning (thinking trace — renders).

const (
	ChunkContent   ChunkKind = "content"
	ChunkReasoning ChunkKind = "reasoning"
)

type CompressionOption ¶

type CompressionOption func(*CompressionRunner)

CompressionOption configures a CompressionRunner at construction.

func WithTokenEstimator(est TokenEstimator) CompressionOption

type CompressionRunner ¶

type CompressionRunner struct {
	// contains filtered or unexported fields
}

CompressionRunner drives the "estimate → optional summariser → stamp Trajectory.Summary" loop the runtime invokes between planner steps. The production cadence is the steering RunLoop's step boundary (one MaybeCompress call per step, gated on Budget.TokenBudget > 0 and a configured runner).

Reusable artifact: one constructed instance is safe to share across N concurrent runs; per-call state lives entirely in `ctx` + RunContext + the per-call serialised bytes. The receiver is read-only after construction.

**Idempotent on `tr.Summary != nil`.** A second call with an already-stamped trajectory returns nil without invoking the summariser — this short-circuit IS the V1.1.x "one compression per run, no auto-cascade" scope fence (RFC §6.5; re-compaction cadence is the recorded follow-up). The layer that owns a future re-compaction policy clears the summary before re-invoking.

func NewCompressionRunner(summariser Summariser, opts ...CompressionOption) *CompressionRunner

func (r *CompressionRunner) MaybeCompress(
	ctx context.Context,
	rc RunContext,
	tr *Trajectory,
) error

type ControlSignals ¶

type ControlSignals struct {
	// Cancelled is true when a CANCEL control event was observed for
	// this run. The Planner SHOULD return Finish{Reason: Cancelled}
	// at the next step boundary.
	Cancelled bool
	// PauseRequested is true when a PAUSE control event was observed.
	// The Planner SHOULD return RequestPause{Reason: AwaitInput} at
	// the next step boundary.
	PauseRequested bool
	// InjectedContext carries INJECT_CONTEXT payloads accumulated
	// since the last planner step. The Planner SHOULD merge them
	// into its prompt construction.
	InjectedContext []map[string]any
	// UserMessages carries USER_MESSAGE payloads accumulated since
	// the last planner step.
	UserMessages []string
	// RedirectGoal is non-empty when a REDIRECT control event
	// updated the goal between planner steps.
	RedirectGoal string
}

ControlSignals carries the steering observations the planner sees at step start. The Runtime owns the inbox; the Planner reads.

Harbor ships a minimal struct — the unified pause/resume primitive + steering subsystem (later phases) populate the fields. Concrete signals (Cancel, Pause, Approve, Reject, InjectContext, Redirect, UserMessage, Prioritize, External) are observed via the typed slices; planners react in their Next implementation.

type Decision ¶

type Decision interface {
	// contains filtered or unexported methods
}

Decision is the sealed sum-type a planner returns from Next. The shapes ship per RFC §6.2:

• CallTool: invoke one tool with structured args.
• CallParallel: invoke N tools in parallel with a join spec.
• Batch: one native multi-call response mixing catalog-tool branches with non-retain-turn task spawns.
• SpawnTask: spawn a background task (retain-turn or non-retain-turn).
• AwaitTask: block the planner until a spawned task resolves.
• TaskStatusQuery: observe the state of tasks this run spawned.
• CancelTask: cancel one task this run spawned.
• SteerTask: steer one background task this run spawned.
• PauseTask: pause one background task this run spawned.
• ResumeTask: resume one paused background task this run spawned.
• RequestPause: pause the run for approval / input / external event.
• Finish: terminal decision with a reason + payload.

The interface is sealed via the unexported `isDecision()` marker — adding a further shape requires editing this file. The predecessor's "magic strings as next_node" anti-pattern is explicitly rejected here (RFC §6.2 settled decisions); each shape is its own Go type.

`NoOp` is deliberately absent. Wait-for- steering and trajectory-summarisation are Runtime short-circuits, not planner decisions.

type DecisionPayload ¶

type DecisionPayload struct {
	events.SafeSealed
	Identity       identity.Quadruple
	DecisionKind   string
	Tool           string
	ReasoningChars int
	ReasoningTrace string
	OccurredAt     time.Time
}

DecisionPayload is the typed payload for EventTypePlannerDecision. registered the event type; Harbor ships the first emitter (the ReAct planner) AND the payload — satisfying the §13 primitive-with-consumer rule for the long-registered type. SafePayload — every field is operator-visible debug data:

• `Identity` is the run's identity quadruple.
• `DecisionKind` is the resolved Decision shape name (`CallTool`, `CallParallel`, `Finish`, `SpawnTask`, `AwaitTask`, `RequestPause`).
• `Tool` is the tool name when DecisionKind is `CallTool`; empty otherwise.
• `ReasoningChars` is the rune count of the captured reasoning trace — a scannable size signal that never carries raw content.
• `ReasoningTrace` is the provider-side thinking trace captured for the step, persisted VERBATIM. Because DecisionPayload embeds SafeSealed (a SafePayload), the event bus SKIPS the audit redactor for it — the trace a sink persists is byte-identical to the one the enricher captured. Reconstruction of a run's reasoning channel relies on that fidelity, so the trace is treated as operator-only debug data, never routed to an untrusted surface. `inspect-runs` surfaces it as `steps[].reasoning_trace`.

The emit is the observability surface that lets `harbor inspect-runs` reconstruct a run's reasoning channel from the event stream.

type DispositionDegradation ¶ added in v1.4.0

type DispositionDegradation struct {
	// From is the disposition that was requested / resolved.
	From AttachmentDisposition
	// To is the disposition actually applied (always ref at V1.1).
	To AttachmentDisposition
	// Reason is the typed degradation cause.
	Reason DispositionDegradationReason
	// Tool carries the unknown tool name when Reason is
	// [DegradationUnknownTool].
	Tool string
}

DispositionDegradation is the typed degradation fact EffectiveDisposition returns when a resolved disposition cannot be honoured. The resolver never logs — the caller (run loop, devstack, or a consumer's own loop) logs and emits the fact (fail-loud, never a silent drop — CLAUDE.md §13).

type DispositionDegradationReason ¶ added in v1.4.0

type DispositionDegradationReason string

DispositionDegradationReason is the typed vocabulary of why a resolved disposition could not be honoured and degraded to DispositionRef.

const (
	// DegradationUnknownTool — a `tool:<name>` disposition named a
	// tool absent from the run's catalog view. Degrades to ref so the
	// run proceeds; the caller logs the warning (revisit as a hard
	// error if operators prefer — plan §risks).
	DegradationUnknownTool DispositionDegradationReason = "unknown_tool"
	// DegradationInlineUnsupportedMIME — `inline` resolved for a
	// non-`image/*` MIME; V1.1 inlines images only.
	DegradationInlineUnsupportedMIME DispositionDegradationReason = "inline_unsupported_mime"
	// DegradationInvalidDisposition — a directly-constructed
	// disposition value outside the grammar reached resolution.
	DegradationInvalidDisposition DispositionDegradationReason = "invalid_disposition"
)

type DispositionLayer ¶ added in v1.4.0

type DispositionLayer string

DispositionLayer names the precedence layer that resolved an attachment's disposition — returned by ResolveDisposition so the caller can record which layer won (the audit criterion: operators see the runtime never silently overrode them).

const (
	// DispositionLayerCallerHint — the per-attachment caller hint won
	// (the Protocol `disposition` field, or a directly-set
	// `InputArtifactView.Disposition` upstream of the resolver).
	DispositionLayerCallerHint DispositionLayer = "caller_hint"
	// DispositionLayerAgentPolicy — the per-agent policy map won
	// (`harbor.yaml` `multimodal.disposition`, or a programmatic
	// [DispositionPolicy]).
	DispositionLayerAgentPolicy DispositionLayer = "agent_policy"
	// DispositionLayerRuntimeDefault — the built-in runtime default
	// won: `image/*` → inline, everything else → ref (byte-for-byte
	// the legacy per-MIME dispatch).
	DispositionLayerRuntimeDefault DispositionLayer = "runtime_default"
)

type DispositionPolicy ¶ added in v1.4.0

type DispositionPolicy struct {
	// ByMIME maps a MIME key to its disposition. Keys are an exact
	// IANA type (`application/pdf`) or a family wildcard
	// (`image/*`).
	ByMIME map[string]AttachmentDisposition
	// Default is the agent-wide disposition applied when no ByMIME
	// key matches. Zero means "no agent default" — resolution falls
	// through to the runtime default layer.
	Default AttachmentDisposition
}

DispositionPolicy is the per-agent disposition policy: a per-MIME map plus an agent-wide default. The type is the programmatic seam — `internal/config` merely decodes the `harbor.yaml` `multimodal.disposition` block into it (see DispositionPolicyFromConfig); a headless library consumer constructs the value directly. Both construction paths produce the same semantics.

Lookup order within the policy layer: exact MIME match (`application/pdf`) > family wildcard (`application/*`) > Default. A zero policy (nil map, zero Default) contributes nothing and resolution falls through to the runtime default.

func DispositionPolicyFromConfig(cfg config.MultimodalConfig) (DispositionPolicy, error)

func (p DispositionPolicy) IsZero() bool

type ErrToolContextLost ¶

type ErrToolContextLost = trajectory.ErrToolContextLost

ErrToolContextLost is the fail-loudly sentinel returned by HandleRegistry.Get on a missing handle. Re-exported from the canonical subpackage.

type ErrUnserializable ¶

type ErrUnserializable = trajectory.ErrUnserializable

ErrUnserializable is the fail-loudly sentinel returned by Trajectory.Serialize on a non-JSON-encodable leaf. Re-exported from the canonical subpackage; use errors.As to extract the Field path.

type Factory ¶

type Factory func(cfg PlannerConfig, deps FactoryDeps) (Planner, error)

Factory builds a Planner from a PlannerConfig + FactoryDeps. Drivers self-register one Factory each via init() → MustRegister.

A factory MUST fail closed on missing required deps (drivers that need an LLM MUST reject a nil `deps.LLM`); the V1 `react` driver's constructor panics on nil LLM per its existing contract. Custom drivers MUST honour the same fail-loud contract — silent fallback is forbidden per §13.

type FactoryDeps ¶

type FactoryDeps struct {
	// LLM is the composed LLM client (retry → downgrade → corrections →
	// safety → driver). The V1 `react` driver consumes this
	// directly; drivers that don't use an LLM ignore the field.
	LLM llm.LLMClient
}

FactoryDeps bundles the shared collaborators every planner driver consumes at construction. The dev stack constructs the LLM client ONCE (one provider per binary; see `cmd/harbor/cmd_dev.go::bootDevStack`) and passes the same instance into every factory call.

Future drivers may need additional collaborators (a tasks subsystem handle for the deterministic planner, a sub-planner registry for the supervisor planner). Add fields here as drivers land; keep the boundary narrow so a planner driver never reaches into runtime internals (the §13 import-graph rule for `internal/planner/...`).

type FailureRecord ¶

type FailureRecord = trajectory.FailureRecord

FailureRecord is the structured-failure projection (repair).

type Finish ¶

type Finish struct {
	Reason   FinishReason
	Payload  any
	Metadata map[string]any
}

Finish is the terminal decision. The Runtime maps FinishReason → Protocol `task.completed` / `task.failed` payloads; `Payload` carries the planner's terminal observation (a summary string, a structured answer, an ArtifactRef — heavy payloads MUST be ArtifactRef-shaped).

`Reason` MUST be one of the canonical values (see IsValidFinishReason). The Runtime rejects an invalid reason with ErrInvalidDecision.

Payload's contract on an output-schema run (WithOutputSchema / the per-task output_schema field, validated at the shared internal/runtime/runctx envelope builder): a `string` payload is treated as raw JSON TEXT, never as a plain Go string to be quoted for the caller — this is the react terminal-answer reality, where `resp.Content` IS the model's JSON encoding of the answer. A plain Go string like `"done"` is NOT valid JSON and fails loud with a hint naming the fix (quote it, or return a structured payload instead). Structured payloads (a map, a struct, any non-string/[]byte/ json.RawMessage Go value) are marshaled via encoding/json. A json.RawMessage or []byte payload is captured verbatim, bytes unchanged.

type FinishReason ¶

type FinishReason string

FinishReason is the planner-side enum for the terminal reason a run finished. The Runtime maps FinishReason → Protocol `task.completed` / `task.failed` payloads.

const (
	// FinishGoal — the planner satisfied the user goal. The
	// canonical success terminal.
	FinishGoal FinishReason = "goal"
	// FinishNoPath — the planner could not find a path to the goal
	// (schema repair exhausted, no tool satisfies the requirement,
	// constraint conflict). Harbor emits this from the repair
	// pipeline's graceful-failure path.
	FinishNoPath FinishReason = "no_path"
	// FinishCancelled — the run was cancelled (CANCEL control event,
	// parent task cascade, deadline expiration honoured early).
	FinishCancelled FinishReason = "cancelled"
	// FinishDeadlineExceeded — the run hit its Budget.Deadline.
	FinishDeadlineExceeded FinishReason = "deadline_exceeded"
	// FinishConstraintsConflict — the run terminated because a
	// constraint conflict could not be resolved (operator denied an
	// approval; budget cap reached during a required tool call).
	FinishConstraintsConflict FinishReason = "constraints_conflict"
)

type HandleID ¶

type HandleID = trajectory.HandleID

HandleID is the opaque key for a non-serialisable tool-context handle. Re-exported from the canonical subpackage.

type HandleRegistry ¶

type HandleRegistry = trajectory.HandleRegistry

HandleRegistry holds the non-serialisable half of ToolContext. V1 ships a process-local driver; the distributed driver is a post-V1 RFC concern.

func NewProcessLocalRegistry() HandleRegistry

type InputArtifactView ¶

type InputArtifactView struct {
	// ID is the content-addressed artifact identifier.
	ID string
	// MIME is the artifact's IANA media type. Drives the per-MIME
	// dispatcher in the materializer.
	MIME string
	// SizeBytes is the artifact's byte length (metadata, not the bytes).
	SizeBytes int64
	// Filename is the operator-supplied original filename, if known.
	// Surfaced to the LLM as a hint when the provider supports it.
	Filename string
	// Bytes is the materialized payload, populated by the run loop
	// for `image/*` MIMEs (the Path 1 inline-bytes case). Nil for
	// every other MIME (the LLM sees an ArtifactStub ref instead).
	Bytes []byte
	// Disposition is the RESOLVED attachment disposition:
	// how this artifact is handed to the model. The run loop
	// resolves it via [ResolveDisposition] + [EffectiveDisposition]
	// (per-attachment caller hint > per-agent policy map > runtime
	// default); a headless library consumer constructing its own
	// views sets it directly — the consumer IS the top-precedence
	// layer. The zero value selects the pre-84b per-MIME dispatch in
	// the materializer, so existing consumers are byte-for-byte
	// unchanged.
	Disposition AttachmentDisposition
}

InputArtifactView is a pre-resolved multimodal input artifact the planner consumes on its first turn. The run loop reads the operator-supplied IDs from `tasks.Task.InputArtifactIDs`, looks each one up in the ArtifactStore, and (for `image/*` MIMEs) pre-fetches the bytes so the planner can construct `llm.ImagePart` with `DataURL` inline without async I/O. For non-image MIMEs the `Bytes` slot stays nil — the planner emits an `ArtifactStub` text block instead, and the LLM routes to whichever tool advertises the MIME via `tools.Tool.HandlesMIME`.

The shape is intentionally narrow: the planner's prompt assembly is synchronous, so every field it needs lives here. Future expansion (e.g. summaries, audio waveform thumbnails) extends the struct rather than reaching back into the artifact store.

type JoinKind ¶

type JoinKind string

JoinKind enumerates the parallel-result merge strategies.

const (
	// JoinAll waits for every branch to terminate before producing
	// the merged observation. The default.
	JoinAll JoinKind = "all"
	// JoinFirstSuccess returns the first successful branch; the rest
	// are cancelled. Failures are NOT cancelled until all branches
	// have terminated.
	JoinFirstSuccess JoinKind = "first_success"
	// JoinKeyed produces a keyed merge over the branches; the
	// MergeKeys slice gives the deterministic ordering.
	JoinKeyed JoinKind = "keyed"
	// JoinN waits for N branches to succeed, then cancels the
	// remaining branches. JoinSpec.N carries the threshold; the
	// executor validates 0 < N ≤ len(Branches) at setup time and
	// fails the call with ErrParallelInvalidJoin when out of range.
	// Harbor introduces JoinN as the third explicit join
	// shape (JoinAll / JoinFirstSuccess / JoinN); JoinKeyed remains
	// a documented future surface (a future runtime phase merges
	// outputs by key).
	JoinN JoinKind = "n"
)

type JoinSpec ¶

type JoinSpec struct {
	// Kind is the join strategy. Harbor ships the constants;
	// Harbor ships the implementations.
	Kind JoinKind
	// MergeKeys is the deterministic merge ordering (only meaningful
	// for JoinKeyed).
	MergeKeys []string
	// N is the success threshold for JoinN — the executor waits until
	// N branches succeed, then cancels the remaining branches. Ignored
	// for any Kind other than JoinN. Values ≤ 0 fall back to JoinAll
	// semantics (the executor validates this at setup time).
	N int
}

JoinSpec describes how the Runtime merges N CallParallel branch results into a single observation the planner sees in the next trajectory step. Harbor ships the executor; Harbor ships the shape so concretes can compile against it.

type LLMOverrides ¶ added in v1.5.0

type LLMOverrides struct {
	Model                *string
	Temperature          *float64
	MaxTokens            *int
	ReasoningEffort      *string
	ExtraInstructions    *string
	SystemPromptOverride *string
	BasePromptLayer      *string
	UserPromptLayer      *string
}

LLMOverrides is the per-run bundle of run-start-resolved LLM-parameter overrides carried on RunContext.LLMOverrides. Every field is optional (a nil pointer / zero-value means "no override for this dimension — use the agent/config default"). The Runtime resolves the bundle once at run start and the planner reads it when building each LLM request; the bundle is immutable for the run.

• Model overrides the model name the request asks for (validated at set time against the configured `ModelProfiles`).
• Temperature / MaxTokens / ReasoningEffort override the corresponding `llm.CompleteRequest` fields.
• ExtraInstructions is ADDITIVE: it is appended to the agent's system prompt (rendered into the `<additional_guidance>` section), never a replacement of the base prompt.
• SystemPromptOverride is a full REPLACE of the agent's base system prompt (the session layer's affordance, distinct from the additive ExtraInstructions). When both are set, the base prompt is replaced AND the additive guidance still appends. An empty string is a valid override (it clears the base prompt for that run); nil = no replace.
• BasePromptLayer is the durable, operator-owned base prompt layer resolved from the agent's active config at run start. When set it is the run's base system prompt (overriding the agent's configured default base); nil = inherit the configured default. A session SystemPromptOverride takes precedence over it for its single message.
• UserPromptLayer is the durable, optional user-instruction layer resolved from the agent's active config at run start. When set it composes ABOVE the base in a distinctly-framed, lower-trust position — it can extend the operator's guidance but never precede, replace, or weaken the base. A session SystemPromptOverride replaces the whole base+user spine for its single message.

type MaxStepsExceededPayload ¶

type MaxStepsExceededPayload struct {
	events.SafeSealed
	Identity      identity.Quadruple
	MaxSteps      int
	StepsObserved int
	LastTool      string
	OccurredAt    time.Time
}

MaxStepsExceededPayload is the typed payload for EventTypePlannerMaxStepsExceeded. SafePayload — every field is operator-visible debug data, not secret-shaped:

• `Identity` is the run's identity quadruple.
• `MaxSteps` is the configured circuit-breaker cap that fired.
• `StepsObserved` is the trajectory step count at the moment the breaker fired (always ≥ MaxSteps; equality is the typical case when the breaker is the load-bearing terminator).
• `LastTool` is the most-recently-dispatched tool name (from the last trajectory step's Action), or empty when the trajectory was empty AND MaxSteps == 0 (a degenerate config).

Harbor ships the payload alongside the emit site; the emit is the load-bearing fail-loudly surface that makes the circuit breaker not silent (§13).

type MemoryBlocks ¶

type MemoryBlocks struct {
	// External is the long-term / retrieved memory tier. Rendered into
	// the `<read_only_external_memory>` prompt section. Nil to omit.
	External any
	// Conversation is the short-term / session memory tier. Rendered
	// into the `<read_only_conversation_memory>` prompt section. Nil
	// to omit.
	Conversation any
}

MemoryBlocks carries the two memory tiers the ReAct planner injects into its system prompt with UNTRUSTED anti-prompt-injection framing. Both fields are optional: a nil tier is omitted from the prompt entirely (no empty wrapper is rendered).

The fields are typed `any` deliberately. The Runtime's MemoryStore and memory strategies produce free-form structured blobs whose shape is policy-dependent — a struct, a map, a slice of entries. The prompt builder compact-JSON-encodes whatever is supplied; a value `json.Marshal` rejects fails loudly with ErrMemoryBlockUnserializable rather than degrading to an empty wrapper.

Identity contract: the Runtime MUST have already filtered each blob to the run's `(tenant, user, session)` scope before populating this struct. The prompt builder never re-applies identity filtering — it renders exactly what it is handed (RFC §6.6, CLAUDE.md §6).

type MemoryView ¶

type MemoryView interface {
	// Snapshot returns the memory entries visible to the planner
	// step. The map shape is intentionally opaque — the
	// production MemoryView adapter (later wave) defines the keying
	// convention. Empty map + nil error is the no-memory case.
	Snapshot(ctx context.Context) (map[string]any, error)
}

MemoryView is the planner-facing read view over the declared-policy memory snapshot. The Runtime constructs a MemoryView at planner-step start from the production MemoryStore + scoping policy; the Planner reads the snapshot, never queries the store directly.

type OutputSchemaValidator ¶ added in v1.9.0

type OutputSchemaValidator struct {
	// contains filtered or unexported fields
}

OutputSchemaValidator is the per-run compiled output schema a structured-output run carries on RunContext.OutputSchema. It bundles the raw JSON-Schema bytes (rendered into the terminal completion's llm.ResponseFormat so the provider constrains generation) with the compiled validator (used both by the generation-steering planner's per-turn llm.CompleteRequest.Validator and by the runtime-edge final validation, so the schema is compiled EXACTLY ONCE per run).

Concurrent reuse: the value is immutable after CompileOutputSchema returns — the compiled schema is read-only, and OutputSchemaValidator.Validate is safe for concurrent invocation. It is per-run state carried on the RunContext, never a field on the shared planner artifact.

func CompileOutputSchema(raw json.RawMessage) (*OutputSchemaValidator, error)

func (v *OutputSchemaValidator) Raw() json.RawMessage

func (v *OutputSchemaValidator) Validate(payload json.RawMessage) error

type ParallelBranchObservation ¶ added in v1.2.0

type ParallelBranchObservation struct {
	// CallID is the provider-assigned tool-call identifier sourced from
	// the originating `CallParallel.Branches[Index].CallID`. The prompt
	// builder stamps it onto the matching `RoleTool` message's
	// ToolCallID so the assistant `tool_calls[i]` and its answer pair
	// up. Empty when the branch carried no provider ID (the renderer
	// then falls back to a deterministic synthetic ID keyed on Index).
	CallID string `json:"call_id,omitempty"`

	// Tool is the branch's tool name (same as CallParallel.Branches[Index].Tool).
	Tool string `json:"tool,omitempty"`

	// Index is the branch's position in the originating
	// `CallParallel.Branches` slice. The deterministic merge key: the
	// renderer pairs each branch's observation to its assistant
	// tool-call by Index regardless of CallID collisions.
	Index int `json:"index"`

	// Value is the branch's success result. For the raw aggregate it is
	// the untruncated tool value; for the LLM-facing aggregate it is the
	// projected form (heavy results replaced by an artifact-stub
	// summary). Nil on failure.
	Value any `json:"value,omitempty"`

	// Error is the branch's failure message. Non-empty only on failure
	// (resolve miss, args-validation failure, or tool Invoke error).
	Error string `json:"error,omitempty"`
}

ParallelBranchObservation is one branch's outcome inside a ParallelObservation. Exactly one of `Value` (success) or `Error` (failure) is populated — never both.

type ParallelObservation ¶ added in v1.2.0

type ParallelObservation struct {
	// Branches is the per-branch outcome slice in branch-index order.
	Branches []ParallelBranchObservation `json:"branches,omitempty"`
}

ParallelObservation is the aggregate observation a runtime ToolExecutor produces when it dispatches a CallParallel decision. It carries one ParallelBranchObservation per branch, in branch-index order (JoinAll semantics), so the planner's trajectory replay can decompose it back into the N native `role:"tool"` messages the provider wire contract requires — exactly one answer per `tool_call_id`.

The shape lives in `internal/planner` (not the runtime executor's package) because BOTH sides of the round-trip consume it: the dev `ToolExecutor` (cmd/harbor) produces it as the step's Observation / LLMObservation, and the React prompt builder (`internal/planner/react`) reads it back to emit the per-branch `RoleTool` messages. Both packages already import `internal/planner`; placing the type here avoids a new cross-package dependency.

JSON-encodable: the trajectory persists Step.Observation / Step.LLMObservation across checkpoints, so every field carries a JSON tag and `Value` holds only JSON-encodable tool results.

type PauseReason ¶

type PauseReason string

PauseReason is the planner-side enum mirroring RFC §6.3's pause taxonomy. The unified pause/resume primitive package (later phase) MAY canonicalise via a typedef bridge; the enum values match the canonical strings exactly.

const (
	// PauseApprovalRequired — a human needs to approve a planner-
	// chosen tool call before execution.
	PauseApprovalRequired PauseReason = "approval_required"
	// PauseAwaitInput — the planner needs additional input from the
	// user / supervisor before continuing.
	PauseAwaitInput PauseReason = "await_input"
	// PauseExternalEvent — the run is waiting on an external event
	// (webhook, scheduled trigger, A2A callback).
	PauseExternalEvent PauseReason = "external_event"
	// PauseConstraintsConflict — the planner detected a constraint
	// conflict (budget vs. tool requirement, identity scope mismatch)
	// that requires operator resolution.
	PauseConstraintsConflict PauseReason = "constraints_conflict"
)

type PauseTask ¶ added in v1.17.0

type PauseTask struct {
	// TaskID is the descendant to pause.
	TaskID tasks.TaskID
	// Reason is the human-readable pause reason carried onto the
	// descendant's pause record.
	Reason string
}

PauseTask pauses one background task THIS run spawned — the model parking work it started so it can be resumed later. A non-terminal, non-blocking decision dispatched like CallTool; the planner observes the {task_id, paused} outcome on its next turn.

Pausing a descendant drives that descendant through the Runtime's unified pause/resume primitive (the ONE pause path shared with HITL, tool-side OAuth, and operator/Console PAUSE) — it introduces no new pause mechanism. Pausing a descendant NEVER pauses the run issuing the verb: only the resolved descendant parks. Descendant-scope + human-supremacy invariant: identical to SteerTask — a run pauses only its own descendants; the operator reaches any task.

The observed `paused` bool means the PAUSE control was ENQUEUED onto a live descendant — it is false ONLY when the descendant has already finished (its run ended, its inbox retired). It is NOT a pause-state-transition signal: the dispatch edge does not inspect the descendant's pause state, so a redundant pause of an already-paused descendant still reports paused:true and coalesces downstream through the unified primitive (the descendant's own RunLoop parks once); there is no parent-observable "no transition" outcome.

type Planner ¶

type Planner interface {
	Next(ctx context.Context, run RunContext) (Decision, error)
}

Planner is the swappable reasoning-policy contract. Implementations MUST be safe to share across N concurrent goroutines: a shared Planner instance receives many calls; per-run state lives in `ctx` + the `RunContext` argument, never on the receiver.

`Next` returns ONE Decision per call. The Runtime executes the decision and re-invokes Next with the resulting trajectory. The Runtime owns the loop; the Planner owns the policy.

func Resolve(ctx context.Context, cfg PlannerConfig, deps FactoryDeps) (Planner, error)

type PlannerConfig ¶

type PlannerConfig struct {
	// Driver names the registered planner driver to resolve. Required;
	// the validator rejects empty + unknown values pre-boot.
	Driver string

	// MaxSteps is the optional circuit-breaker step cap. Zero =
	// driver default.
	MaxSteps int

	// ExtraGuidance is operator-supplied domain-specific guidance for
	// the rendered prompt's <additional_guidance> section.
	// The V1 `react` driver maps it onto `react.WithSystemPromptExtra`;
	// other drivers ignore it. Empty by default.
	ExtraGuidance string

	// ReasoningReplay is the agent-configured reasoning-replay mode.
	// Empty string resolves to
	// `ReasoningReplayNever` — replay is OFF unless an operator opts
	// in. The dev stack maps `config.PlannerConfig.ReasoningReplay`
	// onto this field; the react factory passes it to
	// `react.WithReasoningReplay`. The validator rejects non-canonical
	// values pre-boot.
	ReasoningReplay ReasoningReplayMode

	// MaxToolExamplesPerTool caps how many curated examples the ReAct
	// prompt's <available_tools> section renders per tool.
	// Zero resolves to the react driver's default of 3; the
	// react factory passes it to `react.WithMaxToolExamplesPerTool`.
	// Other drivers ignore it.
	MaxToolExamplesPerTool int

	// ParallelToolCalls is the optional native-parallel tool-call knob.
	// Nil (the default) resolves to `true` — the
	// react driver emits a native `CallParallel` for N>1 tool-calls in
	// one response. A non-nil `false` selects the
	// serialization fallback. The react factory passes the resolved
	// value to `react.WithParallelToolCalls` only when non-nil (the
	// planner's own default is already `true`). Other drivers ignore it.
	ParallelToolCalls *bool

	// Extra is the driver-specific extras map. Reserved for future
	// drivers' per-flow knobs; unused by the V1 `react` driver.
	Extra map[string]string
}

PlannerConfig is the boundary type the registry exposes to drivers. It mirrors `config.PlannerConfig` (the operator-facing YAML shape) but lives in `internal/planner` so concrete drivers can depend on it without forcing the `internal/config` package to import driver internals. The dev stack maps the YAML struct onto this struct at the boundary (precedent).

`MaxSteps` is the planner-side circuit-breaker cap. Zero (the loader-side and registry-side default) means "use the driver's internal default" — e.g. `react.DefaultMaxSteps` (12). Negative is rejected at the validator edge (`internal/config/validate.go`).

`Extra` is the per-driver opaque config map reserved for future per-flow knobs (e.g. a deterministic planner's scripted step sequence, a supervisor planner's sub-agent list). The V1 `react` driver ignores it. Future drivers consume their entries from `Extra` without changing the boundary's signature.

func ConfigFromOperator(cfg config.PlannerConfig) PlannerConfig

type PlanningHints ¶

type PlanningHints struct {
	// Constraints is free-form constraint text rendered verbatim.
	Constraints string
	// PreferredOrder lists tool names the planner should prefer to
	// invoke in the given order.
	PreferredOrder []string
	// ParallelGroups lists groups of tool names that may be invoked
	// in parallel — each inner slice is one independent group.
	ParallelGroups [][]string
	// DisallowTools lists tool names the planner must NOT invoke.
	DisallowTools []string
	// PreferredTools lists tool names the planner should prefer when
	// multiple tools satisfy the same goal.
	PreferredTools []string
	// Budget carries advisory budget caps. Nil = no budget hints.
	Budget *BudgetHints
}

PlanningHints carries runtime-supplied planning constraints the ReAct prompt builder renders into the `<planning_constraints>` section of the system prompt. It is the operator/runtime steering surface: tenant-specific policy, or guiding the planner around a known-bad path, expressed as prompt content rather than Go code.

Every field is optional. An empty field is omitted from the rendered section entirely — never emitted as an empty line. A PlanningHints whose every field is empty renders the empty string, so the prompt builder omits the `<planning_constraints>` section.

PlanningHints is distinct from PlanningNudges (RunContext.Hints): nudges are the legacy parallel/transport hints the planner MAY honour; PlanningHints is the richer runtime-steering surface rendered directly into the prompt.

func HintsFromConfig(cfg config.PlannerPlanningHintsCfg) *PlanningHints

type PlanningNudges ¶

type PlanningNudges struct {
	// MaxParallel hints the maximum CallParallel branch count the
	// planner should produce. The Runtime's system cap
	// (absolute_max_parallel = 50, per RFC §6.2) wins.
	// Zero means no hint.
	MaxParallel int
	// PreferTransport hints the planner should prefer tools of the
	// given transport kind when multiple tools satisfy the same
	// goal. Empty means no preference.
	PreferTransport string
}

PlanningNudges are caller-provided nudges the planner MAY honour. The Runtime hard caps win in every case.

An earlier phase renamed this type from `PlanningHints` to free that name for the richer runtime-supplied PlanningHints struct rendered into the `<planning_constraints>` prompt section. PlanningNudges stays the type of RunContext.Hints — the legacy parallel/transport nudge surface; PlanningHints is the new operator-steering surface.

type ReasoningReplayMode ¶

type ReasoningReplayMode string

ReasoningReplayMode controls whether the ReAct planner re-injects a prior step's captured reasoning trace into the next turn's prompt. The predecessor never replayed; Harbor's stance is never-replay default for ALL models, with a per-agent operator opt-in. V1 ships exactly two modes — no `provider_native` mode, because Bifrost's docs do not address signed-thinking-block round- trips.

const (
	// ReasoningReplayNever — the trajectory renderer emits prior
	// `{tool, args}` JSON only; captured reasoning is never re-injected
	// into prompts. The default for ALL models.
	ReasoningReplayNever ReasoningReplayMode = "never"
	// ReasoningReplayText — the trajectory renderer prepends each prior
	// step's captured reasoning trace as a text block ABOVE the prior
	// `{tool, args}` JSON in the assistant turn. Per-agent operator
	// opt-in for workloads that benefit from CoT continuity.
	ReasoningReplayText ReasoningReplayMode = "text"
)

func EffectiveReasoningReplay(rc RunContext, configured ReasoningReplayMode) ReasoningReplayMode

type RepairCounters ¶

type RepairCounters struct {
	// FinishRepair counts consecutive `_finish` actions that failed
	// validation. Reset to 0 on a clean finish.
	FinishRepair int
	// ArgsRepair counts consecutive tool-call actions whose args
	// failed schema validation. Reset to 0 on a clean single action.
	ArgsRepair int
	// MultiAction counts consecutive turns that emitted more than one
	// JSON action block. Reset to 0 on a clean single action.
	MultiAction int
}

RepairCounters carries the per-run, across-step failure counters that drive the ReAct planner's escalating repair guidance ( ). Each counter tracks one class of LLM-output-format failure the runtime had to repair:

• FinishRepair — a `_finish` action that failed schema validation (malformed finish args, missing answer).
• ArgsRepair — a tool-call action whose args failed the tool's schema validation.
• MultiAction — the LLM emitted more than one JSON action block in a single turn (multi-action / multi-JSON emission).

The runtime increments the matching counter when the repair pipeline had to fix an output, and resets it when a clean turn lands at that surface (a clean finish resets FinishRepair; a clean single-action-with-valid-args turn resets ArgsRepair AND MultiAction). The ReAct prompt builder reads the counters per turn and merges escalating `reminder → warning → critical` guidance into the system prompt for that turn only — closing the across-step feedback loop the per-step repair leaves open.

**Concurrent-reuse.** RepairCounters lives on the per-run RunContext, NEVER on the `ReActPlanner` struct. The runtime constructs one RepairCounters per run and threads the same pointer through every per-step RunContext; the shared planner artifact stays immutable. A counter field on the planner would be a §13-forbidden mutable-state-on-a-compiled-artifact bug.

**Parallel-branch failures do NOT increment these counters.** A `parallel` plan whose branches fail at tool execution is a tool-execution failure, not an LLM-output-format failure — the counters track only the latter (non-goal; see repair_guidance.go).

type RepairExhaustedPayload ¶

type RepairExhaustedPayload struct {
	events.SafeSealed
	Identity               identity.Quadruple
	Attempts               int
	ConsecutiveArgFailures int
	Reasons                []string
	OccurredAt             time.Time
}

RepairExhaustedPayload is the typed payload for EventTypePlannerRepairExhausted. SafePayload — every field is operator-visible debug data, not secret-shaped:

• `Identity` is the run's identity quadruple.
• `Attempts` is the total LLM re-asks the loop burned before giving up (1-based; 1 means the loop made the initial call, observed the failure, and exited without re-asking).
• `ConsecutiveArgFailures` is the consecutive-arg-failure counter value at the moment of exhaustion. When it equals `RepairLoop.cfg.MaxConsecutiveArgFailures`, the storm-guard path fired; when it is less, the `RepairAttempts` budget exhausted.
• `Reasons` is the truncated chain of validator failures seen across attempts (each entry capped to 256 chars by the loop).

Harbor ships the payload with the emit; the conformance pack asserts the round-trip.

type RepairGuidanceInjectedPayload ¶

type RepairGuidanceInjectedPayload struct {
	events.SafeSealed
	Identity   identity.Quadruple
	Tier       string
	Counter    string
	Count      int
	OccurredAt time.Time
}

RepairGuidanceInjectedPayload is the typed payload for EventTypePlannerRepairGuidanceInjected. SafePayload — every field is operator-visible debug data, never secret-shaped:

• `Identity` is the run's identity quadruple.
• `Tier` is the escalation tier the builder rendered: `reminder` (counter == 1), `warning` (counter == 2), `critical` (counter >= 3).
• `Counter` names the tripped counter: `finish`, `args`, or `multi_action`.
• `Count` is the RepairCounters field value at render time.

The emit is the observability surface that lets the Console show an operator when the LLM is repeatedly producing malformed output — the across-step companion to `planner.repair_exhausted` (the per-step terminal). Harbor ships the payload alongside the first emitter (the ReAct prompt builder).

type RequestPause ¶

type RequestPause struct {
	Reason  PauseReason
	Payload map[string]any
}

RequestPause asks the Runtime to pause the run for an external signal. The unified pause/resume primitive (later phase) drives the pause coordinator; the planner only signals "I need a pause" via this decision (RFC §3.3 + §6.3).

`Reason` MUST be one of the four canonical values (see IsValidPauseReason). The Runtime rejects an invalid reason with ErrInvalidDecision before the pause is issued.

`Payload` is sanitised and depth/size-bounded by the Runtime's pauseresume coordinator (RFC §6.3 — depth ≤ 6, ≤ 64 keys, etc.) before serialisation.

type ResumeHint ¶

type ResumeHint = trajectory.ResumeHint

ResumeHint signals a resume continuation.

type ResumeTask ¶ added in v1.17.0

type ResumeTask struct {
	// TaskID is the descendant to resume.
	TaskID tasks.TaskID
	// Directive is optional steering guidance injected on resume via the
	// unified pause/resume primitive's resume-payload seam.
	Directive string
}

ResumeTask resumes one paused background task THIS run spawned, optionally injecting a steering directive on resume. A non-terminal, non-blocking decision dispatched like CallTool; the planner observes the {task_id, resumed} outcome on its next turn.

Resuming a descendant releases it through the SAME unified pause/resume primitive PauseTask parks it with — no new mechanism. A non-empty Directive rides the resume through the primitive's existing resume-payload seam so the released descendant sees the guidance as it continues. Descendant-scope + human-supremacy invariant: identical to SteerTask / PauseTask.

The observed `resumed` bool means the RESUME control was ENQUEUED onto a live descendant — it is false ONLY when the descendant has already finished (its run ended, its inbox retired). It is NOT a resume-state-transition signal: the dispatch edge does not inspect the descendant's pause state, so a redundant resume of a descendant that is NOT paused still reports resumed:true. Such a spurious resume is not harmless downstream — the descendant's own RunLoop applies the RESUME exactly as it would an operator's mistaken resume, surfacing a no-outstanding-pause condition that ends that descendant's run loud (inherited pause/resume-primitive semantics, never a parent-observable outcome). Resume only a descendant you actually paused.

type RunContext ¶

type RunContext struct {
	// Quadruple is the (tenant, user, session, run) identity scope.
	// The triple (Identity field) is the isolation boundary; RunID is
	// the per-execution scope inside a session.
	Quadruple identity.Quadruple

	// Query is the user-facing query that started the run. Set once
	// at run start; never mutated.
	Query string

	// Goal is the current planner-visible goal. May be redirected by
	// a REDIRECT control signal; the Runtime updates the field
	// between planner steps.
	Goal string

	// LLMContext is the visible-to-LLM context (memories, system
	// notes, prior turn summaries). The Runtime populates from the
	// MemoryView + steering injections; the Planner reads only.
	LLMContext map[string]any

	// ToolContext is the tool-only handle bundle. Harbor closes
	// the split (serialisable half + handle registry); Harbor
	// ships the skeleton.
	ToolContext ToolContext

	// Trajectory is the append-only execution log. The Planner reads
	// the history (compaction artefact, prior steps); the Runtime
	// appends each step. Harbor closes the fail-loudly Serialize
	// contract; Harbor ships the type skeleton with a stub Serialize
	// that returns ErrTrajectoryNotImplemented.
	Trajectory *Trajectory

	// Hints are caller-provided ordering / parallel / budget nudges.
	// Planners MAY honour them; the Runtime enforces the hard caps
	// (system absolute_max_parallel, identity-tier budget) outside
	// the planner.
	Hints PlanningNudges

	// RepairCounters carries the per-run across-step failure counters
	// the runtime increments when the schema-repair pipeline had
	// to fix an LLM-output-format failure, and resets on a clean turn at
	// that surface. Nil means "no augmentation": the
	// ReAct prompt builder renders no repair guidance.
	//
	// The pointer is owned by the runtime, which constructs ONE
	// RepairCounters per run and threads the SAME pointer through every
	// per-step RunContext. The counters live here — on the per-run
	// scope — and NEVER on the planner struct: a mutable counter field
	// on the shared `ReActPlanner` artifact would violate the concurrent-reuse
	// concurrent-reuse contract (CLAUDE.md §5 + §13).
	RepairCounters *RepairCounters

	// PlanningHints carries runtime-supplied planning constraints the
	// ReAct prompt builder renders into the `<planning_constraints>`
	// section (anchor; body). Nil means "no
	// hints": the optional section is omitted from the prompt entirely.
	//
	// Unlike Hints (caller nudges the planner MAY honour), PlanningHints
	// is operator/runtime steering: tenant-specific policy, or guiding
	// the planner around a known-bad path, without forking the prompt.
	// The Runtime populates it from the per-run options;
	// the planner reads only.
	PlanningHints *PlanningHints

	// Catalog is the planner-facing tool view (schemas only — never
	// Descriptors). Harbor ships the production ToolCatalog; the
	// runtime engine phase wires a ToolCatalogView adapter.
	Catalog ToolCatalogView

	// Memory is the declared-policy memory view. RESERVED for future
	// planner drivers that pull memory mid-run — no shipped planner
	// concrete reads it (the react planner consumes the pre-fetched
	// `MemoryBlocks` instead; see the type godoc + SDK friction audit
	// §3). Assemblers populate `MemoryBlocks`; wiring this view is
	// optional until a driver consumes it.
	Memory MemoryView

	// Skills is the skills subsystem's search/get surface. RESERVED
	// for future planner drivers that search skills mid-run — no
	// shipped planner concrete reads it (the react planner consumes
	// the pre-fetched `SkillsContext` instead). Assemblers populate
	// `SkillsContext`; wiring this view is optional until a driver
	// consumes it.
	Skills SkillLookup

	// Artifacts is the artifact store. Heavy outputs MUST round-trip
	// through ArtifactRef; the planner is the
	// caller responsible for upgrading inline bytes to refs at the
	// LLM edge.
	Artifacts artifacts.ArtifactStore

	// InputArtifacts carry the operator-uploaded
	// multimodal inputs the run consumes on its FIRST planner turn —
	// pre-resolved by the run loop (no async I/O inside the planner).
	// The planner's first-turn user-content builder routes each entry
	// by MIME: `image/*` materializes as `llm.ImagePart{DataURL}` with
	// inline base64 bytes (Path 1); everything else stays as
	// an `ArtifactStub` the LLM routes through the tool catalog.
	// Empty on text-only turns AND on every turn after the first.
	InputArtifacts []InputArtifactView

	// Control is the accumulated steering signals (control events
	// observed since the last planner step). The Planner reads;
	// the Runtime owns the inbox.
	Control ControlSignals

	// Budget is the per-run hard caps: deadline, hop budget, cost cap.
	// The Runtime enforces them; the Planner observes them to make
	// budget-aware decisions.
	Budget Budget

	// Clock is the (typically `time.Now`) clock the Planner reads. A
	// controllable clock lets tests fix time across a planner step.
	Clock func() time.Time

	// Emit publishes onto the event bus with the run's identity
	// quadruple already attached. The Planner uses Emit to surface
	// planner-side telemetry (`planner.decision`, `planner.finish`,
	// `planner.error` — see events.go). May be nil in tests; concretes
	// MUST nil-check.
	Emit func(events.Event)

	// ReasoningReplay is a per-run override for the agent's reasoning-
	// replay policy. When nil, the planner uses
	// the agent's configured `config.PlannerConfig.ReasoningReplay`.
	// When non-nil, this value wins — letting a tenant-specific or
	// run-specific policy override the per-agent default (e.g. an
	// operator disabling replay for a cost-sensitive run). The Runtime
	// populates it from the per-run options; the planner reads only.
	ReasoningReplay *ReasoningReplayMode

	// LLMOverrides carries the per-run, run-start-resolved LLM-parameter
	// overrides the Runtime applies to this run's LLM requests: the model
	// name, sampling temperature, per-call token ceiling, reasoning-effort
	// hint, and an ADDITIVE extra-instructions block appended to the
	// agent's system prompt. Nil means "no overrides" — the planner uses
	// the agent/config defaults (the bound `llm.model`, the provider
	// defaults, the agent's base system prompt).
	//
	// The Runtime resolves these ONCE at run start from the effective
	// override layers (an admin-set tenant default today; a per-session
	// next-turn override above it later) and pins the snapshot here for
	// the whole run — a swap at any layer lands on the NEXT run, never
	// mid-flight (the same next-turn-only invariant the compiled-artifact
	// concurrent-reuse contract requires: a running planner's parameters
	// are fixed for the run; per-run state lives on rc, never on the
	// shared planner artifact). The planner reads only.
	LLMOverrides *LLMOverrides

	// MemoryBlocks carries the pre-fetched, identity-scoped memory
	// blobs the planner injects into the system prompt as UNTRUSTED-
	// framed `<read_only_*_memory>` sections. The
	// Runtime populates this from the MemoryStore per its declared
	// scoping policy; the planner only renders. Nil means "no memory
	// to inject" — the wrappers are omitted entirely. The Runtime is
	// responsible for filtering the blob to the run's identity BEFORE
	// it reaches this field; the prompt builder never re-applies
	// identity filtering (RFC §6.6).
	MemoryBlocks *MemoryBlocks

	// SkillsContext carries pre-retrieved skill bodies the runtime
	// resolved for this run. The planner renders
	// them into a single UNTRUSTED-framed `<skills_context>` section.
	// Nil/empty means "no skills to inject" — the section is omitted.
	// The element type is `any` for V1: callers may supply
	// `planner.Skill` values, maps, or operator-defined structs; the
	// renderer compact-JSON-encodes whatever is passed. The runtime,
	// not the planner, decides which skills land here (RFC §6.7).
	SkillsContext []any

	// OnReasoning is a per-step callback the Planner invokes with the
	// provider-side reasoning trace captured by the LLM call (
	// item 8). The Runtime sets it on each per-step RunContext so the
	// runloop can copy the trace onto `trajectory.Step.ReasoningTrace`
	// when it appends the step. May be nil — a planner that finds no
	// callback skips the emission silently (no observability surface
	// wired this run).
	//
	// Why a side-channel rather than a field on Decision: the Decision
	// sum is the planner→runtime instruction contract (CallTool,
	// CallParallel, SpawnTask, AwaitTask, RequestPause, Finish) and
	// must stay narrow so future planner concretes (Deterministic,
	// Workflow, Plan-Execute) implement it cleanly without populating
	// a field most planners never produce. Reasoning is per-step
	// observation, not per-step instruction — this seam matches.
	//
	// Concurrent-reuse: the callback closure is captured per
	// run on the runloop's stack; the planner reads it from rc, never
	// from itself. N concurrent runs see N independent closures.
	OnReasoning func(string)

	// OnAssistantContent is a per-step callback the Planner invokes
	// with the natural-language content the assistant emitted
	// alongside its tool_call on this step. The Runtime sets it on
	// each per-step RunContext so the runloop copies the preamble
	// onto `trajectory.Step.AssistantPreamble` when it appends the
	// step; the prompt builder then replays it as the assistant
	// message's content on subsequent turns so the model retains
	// its narrative thread.
	//
	// Under native tool-calling the response carries both a
	// `tool_calls` block AND a natural-language `content` field.
	// The Decision sum only encodes the tool_call; this callback
	// is the side-channel that ferries `content` onto the step.
	//
	// Same shape as OnReasoning: nil-safe, per-run closure,
	// invoked by the planner after each LLM call.
	OnAssistantContent func(string)

	// OnChunk is the per-step streaming callback the Planner invokes
	// per token delta from the LLM provider. The Runtime
	// sets it on each per-step RunContext so the runloop publishes
	// `llm.completion.chunk` events. May be nil — a planner without
	// streaming wired skips the emission silently.
	//
	// Concurrent-reuse: same pattern as OnReasoning — per-run
	// closure on the stack, never on the shared planner artifact.
	OnChunk func(delta string, done bool, kind ChunkKind)

	// DiscoveredTools is the per-run list of
	// tool names the LLM discovered via meta-tools during this run.
	// The React planner reads this to add discovered tools to
	// subsequent turns' Tools[] declarations. Stack-local-per-run
	// never on the planner struct.
	DiscoveredTools []string

	// PendingToolCalls carries remaining
	// serialized native ToolCalls when the LLM emits N>1 calls in
	// one response (AC-19 serialization fallback). The planner
	// consumes PendingToolCalls before consulting the LLM again.
	// Stack-local-per-run.
	PendingToolCalls []ToolCallDeferred

	// OnPendingToolCalls (— AC-19 + AC-19a) is the
	// per-step callback the planner invokes BEFORE returning a
	// Decision to surface the post-step `PendingToolCalls` queue back
	// to the runloop. rc is passed BY VALUE to Next; without this
	// bridge any append to `rc.PendingToolCalls` inside Next dies
	// with the planner's stack frame, and the AC-19 multi-ToolCall
	// serialisation fallback becomes dead code. The runloop captures
	// a stack-local slice via the closure (per-run, never on
	// the planner artifact) and writes it back into `spec.Base` so
	// the next iteration's value-copy carries the queue forward.
	//
	// Nil callback is a no-op (tests that exercise Next directly
	// without a runloop). Operators should never set it; the
	// runloop owns the closure.
	OnPendingToolCalls func([]ToolCallDeferred)

	// SessionArtifacts carries the pre-resolved,
	// identity-scoped session-artifact manifest the planner renders into
	// a read-only `<session_artifacts>` prompt block, so the model stays
	// aware of uploads and tool-materialised artifacts across turns and
	// can `artifact_fetch` any of them by ref.
	//
	// The run loop lists `ArtifactStore.List` scoped to the run's
	// `(tenant, user, session)` triple each turn and maps each ref into
	// a metadata-only entry (the run-loop pre-resolution pattern —
	// the planner does NO I/O; it reads only from rc). Nil/empty means
	// "no manifest": the planner omits the `<session_artifacts>` block
	// entirely (no fabricated rows). Newest-first; the renderer caps the
	// rendered rows and appends an explicit "+K more" line on overflow
	// (never a silent truncation, CLAUDE.md §17.6).
	//
	// Concurrent-reuse: the manifest is per-run state on rc,
	// never on the shared planner artifact.
	SessionArtifacts []ArtifactManifestEntry

	// OutputSchema is the optional, opt-in run-level output schema the
	// caller supplied (via the assemble.WithOutputSchema run option).
	// When non-nil the run is a structured-output run: the terminal
	// answer must validate against this schema. A generation-steering
	// planner (the ReAct driver) renders OutputSchema.Raw() into its
	// terminal completion's ResponseFormat and installs a
	// schema-Validator so the corrective retry-with-feedback loop
	// engages; every planner's terminal Finish is additionally validated
	// against this schema at the runtime edge (planner-agnostic, no
	// capability ceremony). Nil means "no schema" — the run is plain
	// text exactly as before.
	//
	// The schema is compiled ONCE per run at the runtime edge and the
	// compiled validator threads here; the planner reads only. Per-run
	// state on rc, never on the shared planner artifact.
	OutputSchema *OutputSchemaValidator
}

RunContext is the only surface the Planner sees. All fields are either value types, narrow read interfaces, or function closures — never concrete Runtime structs. The Runtime constructs a fresh RunContext per planner step; reading from `ctx` for cancellation, `Quadruple` for identity, and the view interfaces for tools / memory / skills / artifacts is the entire API surface.

The Runtime (assembler) is responsible for:

• Wiring `Catalog` to a visibility-filtered ToolCatalogView.
• Populating `MemoryBlocks` + `SkillsContext` with pre-fetched, identity-scoped content. These are the fields the shipped planner concretes actually read; see the note on `Memory` / `Skills` below.
• Wiring `Artifacts` to the production ArtifactStore.
• Populating `Control` with the accumulated steering signals.
• Setting `Budget` from the per-run options.
• Providing `Clock` (typically `time.Now`).
• Providing `Emit` that publishes onto the EventBus with the run's identity quadruple attached.

The `Memory` (MemoryView) and `Skills` (SkillLookup) view fields are reserved for future planner drivers that pull memory / skills mid-run: NO shipped planner concrete reads them today (the react planner consumes only the pre-fetched `MemoryBlocks` / `SkillsContext` — SDK friction audit, docs/notes/sdk-friction-audit.md §3). Assemblers should populate these fields; wiring the views is optional until a driver consumes them.

The Planner is responsible for:

• Reading from RunContext, never writing back.
• Returning a Decision (one of six shapes — see decision.go).
• Never blocking on the Runtime's internals. Long-running work ALWAYS goes through SpawnTask / AwaitTask, not via a goroutine spawned inside Next.

type Skill ¶

type Skill struct {
	// ID is the skill's stable identifier (provider-namespaced).
	ID string
	// Name is the human-readable name.
	Name string
	// Description is the one-line summary the planner shows the LLM.
	Description string
	// Body is the skill's prompt-injection content.
	Body string
	// Tags categorise the skill for filtering / search.
	Tags []string
}

Skill is the planner-facing projection of a skill record. The production internal/skills package defines the full record shape; the planner only needs the Name / Description / Body to compose an LLM prompt and the optional ToolTemplates for auto-instantiated tools.

type SkillLookup ¶

type SkillLookup interface {
	// Search returns up to `limit` skills matching `query`. Empty
	// slice + nil error is the no-match case.
	Search(ctx context.Context, query string, limit int) ([]SkillResult, error)

	// Get returns the full skill by id, or (nil, nil) on miss.
	Get(ctx context.Context, id string) (*Skill, error)
}

SkillLookup is the planner-facing read view over the skills subsystem. Harbor ships the production surface; Harbor declares the planner- facing shape so the planner package compiles without importing internal/skills (parallel fork at).

type SkillResult ¶

type SkillResult struct {
	Skill
	// Score is the search backend's relevance score, in [0.0, 1.0].
	// Higher is more relevant.
	Score float64
}

SkillResult is the search projection — a hit with a relevance score.

type Source ¶

type Source = trajectory.Source

Source records a citation / provenance entry. Re-exported.

type SpawnSpec ¶

type SpawnSpec struct {
	// Description is the human-readable task description (audit +
	// observability).
	Description string
	// Query is the goal / prompt the spawned task should pursue.
	Query string
	// Priority is the task scheduling priority (-1000..1000). Zero
	// is the default mid-priority.
	Priority int
	// RetainTurn blocks the foreground turn on the spawned task's
	// group resolution. When true the planner WILL re-enter Next
	// only after the group reaches a terminal state. When false the
	// planner returns control to the runtime; the runtime consumes
	// WatchGroup to re-invoke the planner on resolution.
	RetainTurn bool
	// FailFast applies when SpawnTask creates a fresh group: cancels
	// remaining members when the first fails. Ignored when joining
	// an existing GroupID.
	FailFast bool
	// PropagateOnCancel controls whether this spawned task survives a
	// cancellation cascade from an ANCESTOR task. Empty (the default)
	// maps to `tasks.PropagateCascade`: the task is swept when a task
	// above it in the parent chain is cancelled with a cascade policy.
	// `tasks.PropagateIsolate` detaches the task from that cascade — it
	// keeps running when its parent is cancelled. Isolate never detaches
	// a task from a DIRECT cancel: the operator (via the Protocol) and
	// the spawning run itself (via CancelTask) both reach an
	// isolate-marked task at any time. Any other value is rejected loud
	// at the dispatch edge. This is the model's brake on the parallelism
	// it spawns — paired with the observation/cancel meta-tools so
	// detached work is never unobservable or unstoppable.
	PropagateOnCancel string
}

SpawnSpec is the planner-facing spawn descriptor. The Runtime maps it into a `tasks.SpawnRequest` (or `tasks.SpawnToolRequest`) at dispatch time; identity is filled from the run's quadruple.

The shape carries only the fields the planner needs to specify; the Runtime fills the rest (Identity, IdempotencyKey, NotifyOnComplete). PropagateOnCancel became planner-controllable once the model gained the task observation/cancel meta-tools to manage detached work. Future phases MAY extend this shape with additional planner-controlled fields.

type SpawnTask ¶

type SpawnTask struct {
	Kind    tasks.TaskKind
	Spec    SpawnSpec
	GroupID tasks.TaskGroupID
	// CallID is the provider-assigned tool-call identifier of the
	// native `_spawn_task` call this spawn was projected from,
	// mirroring CallTool.CallID. Batch dispatch keys each spawn's
	// observation by it so every native tool_call_id — spawn calls
	// included — is answered. Empty for programmatic (non-native)
	// spawn emissions, exactly like CallTool.CallID; the projector
	// stamps it when partitioning a native multi-call response.
	CallID string
}

SpawnTask spawns a background task. When `Spec.RetainTurn` is true the foreground turn blocks on the spawned task's group; when false the planner returns control to the runtime and consumes `tasks.TaskRegistry.WatchGroup` to learn when the group resolves (wake-on-resolution contract).

`GroupID` is optional — when empty, the runtime creates an ad-hoc single-member group; when non-empty, the task joins the existing group (cross-task fan-in pattern).

type SteerTask ¶ added in v1.17.0

type SteerTask struct {
	// TaskID is the descendant to steer.
	TaskID tasks.TaskID
	// Directive is the free-text steering guidance enqueued onto the
	// descendant's per-sub-run steering inbox.
	Directive string
}

SteerTask steers one background task THIS run spawned — the model applying mid-flight guidance to work it started, without waiting on or cancelling it. A non-terminal, non-blocking decision the Runtime executor dispatches like CallTool; the planner observes the {task_id, steered} outcome on its next turn.

The Directive is enqueued onto the target sub-run's own steering inbox — the SAME inbox an operator's steering targets — so the steered descendant sees the guidance at its next planner-step boundary. Descendant-scope + human-supremacy invariant: TaskID must reach the calling run's own task by walking the parent-task chain upward, so a run steers ONLY the tasks it spawned (directly or transitively), never a sibling run's tasks or its own task; the operator's control surface always supersedes and reaches any task. Steering a terminal descendant returns {steered: false}, not an error (idempotent-on-terminal, mirroring CancelTask).

type SteeringInjection ¶

type SteeringInjection = trajectory.SteeringInjection

SteeringInjection records a steering event the planner observed.

type Step ¶

type Step = trajectory.Step

Step is the trajectory's per-step shape (action + observation + failure + streams). Re-exported from the canonical subpackage.

Note: earlier, this type was named TrajectoryStep at the planner-package level. The rename to Step is part of the subpackage relocation; no external consumers of TrajectoryStep existed in an earlier revision.

type StreamChunk ¶

type StreamChunk = trajectory.StreamChunk

StreamChunk captures one chunk of a streaming output.

type Summariser ¶

type Summariser interface {
	Summarise(ctx context.Context, rc RunContext, tr *Trajectory) (*TrajectorySummary, error)
}

Summariser is the runtime-side interface a configured compaction driver implements. The CompressionRunner calls Summariser.Summarise when the trajectory's token estimate exceeds Budget.TokenBudget.

Fail-loudly contract (CLAUDE.md §13): an error from Summarise propagates verbatim through CompressionRunner.MaybeCompress — no silent fall-through to raw history. Returning (nil, nil) is also a contract violation; the runner surfaces ErrEmptySummary so the bug is loud, not silent.

Implementations MUST be safe for concurrent use across runs (the runner is a reusable artifact per the concurrent-reuse contract; the summariser is called under the run's ctx from MaybeCompress).

The production implementation is the LLM-backed TrajectorySummariser in internal/llm/summarizer: it binds an LLM client + a versioned compaction prompt, invokes llm.LLMClient.Complete over the trajectory's planner-facing projection (structured-output JSON-schema mode with the existing downgrade ladder), and parses the response into the five TrajectorySummary fields. The production call site is the steering RunLoop's step loop, which calls CompressionRunner.MaybeCompress at each step boundary when Budget.TokenBudget > 0 — wired from the `planner.token_budget` config knob by the runtime assembly.

type Summary ¶

type Summary = trajectory.Summary

Summary is the trajectory's compaction artefact ( summariser output). Earlier this was TrajectorySummary at the planner-package level; the subpackage rename to Summary is part of

type TaskStatusQuery ¶ added in v1.16.0

type TaskStatusQuery struct {
	// TaskIDs are the tasks to report on; nil/empty means every task
	// this run has spawned, including nested descendants.
	TaskIDs []tasks.TaskID
}

TaskStatusQuery observes the state of the background tasks THIS run spawned — a non-terminal, non-blocking decision the Runtime executor dispatches like CallTool, appending a trajectory step the planner reads on its next turn. A model that fanned out several explorations uses it to poll which have resolved before deciding whether to await or cancel the rest.

TaskIDs names the tasks to report; an empty/nil slice means "every task this run has spawned, directly or transitively" (the run's whole descendant subtree). Every explicitly-named id is scope-checked: the executor resolves ONLY tasks whose parent-task chain reaches the calling run's own task, never an arbitrary session task — one out-of-scope id fails the whole call rather than silently omitting it.

The shape is deliberately NOT named TaskStatus: that identifier is the tasks-package lifecycle enum (pending/running/…/cancelled). This is the planner-facing query decision.

type TokenEstimator ¶

type TokenEstimator func(tr *Trajectory) (int, error)

TokenEstimator is the runner's pluggable token-count function. The default implementation (DefaultTokenEstimator) walks trajectory.Trajectory.Serialize bytes and returns `len/4 + 1` — mirroring internal/llm/tokens.go's `chars4Estimator` so the two estimators agree (single surface; no parallel implementation per §13).

Estimator errors propagate; an trajectory.ErrUnserializable from Serialize is the typical failure mode and is surfaced verbatim (fail-loudly contract).

type ToolCallDeferred ¶ added in v1.2.0

type ToolCallDeferred struct {
	Name   string
	Args   json.RawMessage
	CallID string
}

ToolCallDeferred is a pending native tool-call the planner will dispatch on the next step (AC-19 serialization fallback).

type ToolCatalogView ¶

type ToolCatalogView interface {
	// Resolve returns the Tool by name and a presence bool. The Tool
	// value carries schemas, transport kind, side-effect class, and
	// cost / latency hints — everything the planner needs to make a
	// CallTool decision without reaching into the descriptor.
	Resolve(name string) (tools.Tool, bool)

	// List returns every tool visible to the run. The slice ordering
	// is the catalog's natural order (typically registration order);
	// planners that need a stable ordering MUST sort the result.
	List() []tools.Tool
}

ToolCatalogView is the planner-facing read view over the production ToolCatalog. The view exposes schemas only — never ToolDescriptors — so the planner cannot dispatch tools directly. The Runtime owns dispatch; the Planner returns CallTool decisions.

Implementations MUST already apply visibility filtering — the planner sees the set of tools the run's identity may call, not the full catalog.

type ToolContext ¶

type ToolContext = trajectory.ToolContext

ToolContext is the split serialisable / handle-registry tool-handle bundle. Re-exported from the canonical subpackage.

type Trajectory ¶

type Trajectory = trajectory.Trajectory

Trajectory is re-exported from the canonical subpackage.

type TrajectoryCompressedPayload ¶

type TrajectoryCompressedPayload struct {
	events.SafeSealed
	Identity      identity.Quadruple
	StepsBefore   int
	StepsAfter    int
	TokenEstimate int
	OccurredAt    time.Time
}

TrajectoryCompressedPayload is the typed payload for EventTypeTrajectoryCompressed. SafePayload — every field is operator-visible debug data, not secret-shaped:

• `Identity` is the run's identity quadruple.
• `StepsBefore` is the trajectory step count when compression ran.
• `StepsAfter` is the step count after compression. Harbor does NOT truncate the Steps slice; the runner only stamps Summary. `StepsAfter == StepsBefore` in V1; the field exists so future phases that truncate (free memory; trade observability for footprint) extend the schema without a payload-version bump.
• `TokenEstimate` is the estimator's count at the moment the budget was breached.

The emit is the success-path observability surface that pairs with trajectory.compression_failed for the failure path; together they make compression observable in both directions (§13 fail-loudly).

type TrajectoryCompressionFailedPayload ¶

type TrajectoryCompressionFailedPayload struct {
	events.SafeSealed
	Identity      identity.Quadruple
	StepsObserved int
	TokenEstimate int
	ErrorCode     string
	ErrorMessage  string
	OccurredAt    time.Time
}

TrajectoryCompressionFailedPayload is the typed payload for EventTypeTrajectoryCompressionFailed. SafePayload — the fields carry operator-visible debug data:

• `Identity` is the run's identity quadruple.
• `StepsObserved` is the trajectory step count at the moment of the failure.
• `TokenEstimate` is the estimator's count when the failure happened (zero when the estimator itself failed).
• `ErrorCode` classifies the failure into one of three buckets: `summariser_error` (the Summariser returned a non-nil error), `empty_summary` (the Summariser returned (nil, nil) — contract violation), `estimator_error` (the TokenEstimator returned an error, typically an ErrUnserializable surfaced through DefaultTokenEstimator's Serialize call).
• `ErrorMessage` is the truncated original error message (capped at 256 chars to keep audit payloads bounded). Never carries raw trajectory content.

Harbor ships the payload + the emit; the bus subscribers observe the failure end-to-end. The emit is the load-bearing fail-loudly observability surface (§13 — silent degradation banned).

type TrajectorySummary ¶

type TrajectorySummary = trajectory.Summary

TrajectorySummary is the canonical name for the trajectory's compaction artefact. Aliased onto the trajectory.Summary struct: same shape, the alias matches RFC §6.2 + the master-plan vocabulary so callers outside the trajectory package use the RFC name. Five fields per RFC §6.2: `Goals`, `Facts`, `Pending`, `LastOutputDigest`, `Note`.

type WakeAware ¶

type WakeAware interface {
	WakeMode() WakeMode
}

WakeAware is the OPTIONAL interface a planner concrete may implement to declare its non-retain-turn wake strategy. The conformance pack asserts the round-trip for the declared mode; observability + the Console surface the value.

A planner that does not implement WakeAware is treated as WakePush by the conformance pack (the safe default — no polling burden).

Implementations MUST return a constant value for the lifetime of the planner instance. WakeMode is identity, not capability — a concrete picks one mode at construction time.

type WakeMode ¶

type WakeMode string

WakeMode names a planner concrete's chosen wake-on-resolution strategy. The constants match the canonical names documented at `internal/tasks/groups.go`.

const (
	// WakePush — the planner subscribes to WatchGroup; the runtime
	// re-invokes Next on group resolution. Lowest latency, lowest
	// LLM cost (no in-flight polls). ReAct uses WakePush.
	WakePush WakeMode = "push"

	// WakePoll — the planner skips WatchGroup and re-checks group
	// status deterministically on its own cadence. No subscription
	// required. Suits deterministic / workflow planners.
	WakePoll WakeMode = "poll"

	// WakeHybrid — the main planner subscribes via WatchGroup (push)
	// AND a sidecar (small LLM / templater) polls intermediate state
	// to emit user-facing progress events between push deliveries.
	WakeHybrid WakeMode = "hybrid"
)

func ResolveWakeMode(p Planner) WakeMode

func (m WakeMode) String() string