steering

type AppliedControl struct {
	// Type is the control type that was applied.
	Type ControlType
	// RunID is the run the control targeted (a session may host multiple
	// concurrent runs — the run component disambiguates).
	RunID string
	// AppliedAt is the wall-clock time the side effect was applied,
	// stamped from the RunLoop's Clock.
	AppliedAt time.Time
	// Err is the non-nil error when the side effect failed (e.g. a
	// PRIORITIZE whose task does not exist). A failed apply is still
	// recorded — the history is the audit trail, and a silent drop would
	// violate CLAUDE.md §5 "fail loudly".
	Err error
}

type Clock interface {
	Now() time.Time
}

type CompletionHookSpec struct {
	// Tool is the catalog tool name the transcript is dispatched to. The
	// executor resolves it against the FULL catalog, so the hook target
	// need not be exposed to the planner. An empty Tool disables the hook
	// (treated as no hook configured).
	Tool string
	// Timeout bounds the detached dispatch. A non-positive value falls
	// back to DefaultCompletionHookTimeout.
	Timeout time.Duration
	// AgentID is the acting agent's registration id, carried as payload
	// metadata (never an isolation key — §6). Empty for a bare embed run
	// whose wiring layer knows no agent.
	AgentID string
}

type ControlEvent struct {
	// Type is one of the nine canonical control types. An invalid
	// Type is rejected by Inbox.Enqueue with ErrUnknownControlType.
	Type ControlType
	// Identity is the run quadruple this control targets. It MUST
	// match the Inbox's own quadruple — Enqueue rejects a mismatch
	// (an event for run A must never land on run B's inbox).
	Identity identity.Quadruple
	// CallerScope is the (trust-based) Scope the Protocol
	// edge derived from the submitting caller's JWT. Enqueue runs
	// CheckScope against it.
	CallerScope Scope
	// CallerTenant is the tenant the submitting caller authenticated
	// under. Used by the cross-tenant scope check (RFC §6.3).
	CallerTenant string
	// Payload is the sanitised, bounds-checked control payload. May
	// be nil — a bare CANCEL / PAUSE carries no payload. Enqueue runs
	// ValidatePayload against it.
	Payload map[string]any
	// EventID is the caller-supplied idempotency / correlation key
	// (ULID-shaped, mirrors events.EventID). Optional —
	// the control-history dedupe uses it. Empty is permitted.
	EventID string
	// EnqueuedAt is stamped by Inbox.Enqueue from the Inbox's Clock.
	// Callers MUST NOT pre-fill it; a non-zero value is rejected so
	// the Inbox owns the timeline (mirrors events.Event.Sequence).
	EnqueuedAt time.Time
}

type ControlLifecyclePayload struct {
	events.SafeSealed
	// Type is the control type that was received / applied.
	Type string
	// Outcome is a stable, low-cardinality classification of the apply
	// result — "received" for control.received, and one of "applied" /
	// "failed" for control.applied. Empty on a control.received event.
	Outcome string
	// Err is a short, redaction-safe description of why the side
	// effect failed, when Outcome == "failed". Empty otherwise. The
	// RunLoop derives this from a sentinel classification, never the
	// raw error message (which may quote caller data).
	Err string
}

type ControlRejectedPayload struct {
	events.SafeSealed
	// Type is the control type that was rejected (may be the empty
	// string when the rejection was an unknown / unparsable type).
	Type string
	// Reason is a stable, low-cardinality classification of why the
	// submission was rejected — one of "unknown_type",
	// "payload_invalid", "scope_mismatch", "identity_invalid".
	Reason string
	// CallerScope is the scope the rejected caller presented.
	CallerScope string
}

type ControlType string

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

type Option func(*Registry)

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

type RunCompletionPayload struct {
	// FormatVersion is the pinned schema version (RunCompletionPayloadFormatVersion).
	FormatVersion int `json:"format_version"`
	// TenantID / UserID / SessionID / RunID are the run's identity
	// quadruple.
	TenantID  string `json:"tenant_id"`
	UserID    string `json:"user_id"`
	SessionID string `json:"session_id"`
	RunID     string `json:"run_id"`
	// AgentID is the acting agent's registration id (metadata, never an
	// isolation key — §6). Empty for a bare embed run.
	AgentID string `json:"agent_id,omitempty"`
	// Outcome is the terminal outcome: "goal" / "no_path" /
	// "constraints_conflict" / "cancelled" / "deadline_exceeded" / "error".
	Outcome string `json:"outcome"`
	// StartedAt / CompletedAt bound the run; DurationMS is their delta.
	StartedAt   time.Time `json:"started_at"`
	CompletedAt time.Time `json:"completed_at"`
	DurationMS  int64     `json:"duration_ms"`
	// StepCount is the number of trajectory steps.
	StepCount int `json:"step_count"`
	// ToolInvocations is the true tool-invocation count over the trajectory
	// (planner.CountToolInvocations — attempted invocations, counting a
	// CallParallel as its branch count). The hook dispatch itself is NOT
	// counted (it appends no trajectory step).
	ToolInvocations int `json:"tool_invocations"`
	// Conversation is the ordered transcript: initial goal, steering user
	// messages / redirects in arrival order, per-step assistant preambles
	// and compact tool lines, and the final answer.
	Conversation []TranscriptEntry `json:"conversation"`
}

type RunHookDispatchedPayload struct {
	events.SafeSealed
	// Tool is the catalog tool the transcript was dispatched to.
	Tool string
	// Outcome is the run's terminal outcome carried in the payload.
	Outcome string
	// DurationMS is the hook dispatch's wall-clock duration in ms.
	DurationMS int64
	// TranscriptBytes is the size of the JSON-encoded RunCompletionPayload
	// dispatched as tool args.
	TranscriptBytes int
	// EntryCount is the number of ordered transcript entries.
	EntryCount int
}

type RunHookFailedPayload struct {
	events.SafeSealed
	// Tool is the catalog tool the dispatch targeted.
	Tool string
	// Outcome is the run's terminal outcome carried in the payload.
	Outcome string
	// ErrorClass is a stable, low-cardinality classification of the
	// dispatch failure ("timeout" / "no_executor" / "encode_failed" /
	// "unsupported_shape" / "dispatch_failed" / "cancelled" / "panic").
	// Never the raw error message.
	ErrorClass string
}

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

type RunLoopOption func(*runLoopConfig)

type RunSpec struct {
	// Planner is the swappable reasoning policy the loop drives. Nil
	// fails loud with ErrNoPlanner.
	Planner planner.Planner
	// Base is the run's RunContext template. RunLoop refreshes the
	// per-step fields (Control, Goal) on a copy each step; the planner
	// receives a fresh RunContext per Next call (contract).
	// Base.Quadruple is the run's identity — its triple is validated
	// identity-mandatory before the loop starts.
	Base planner.RunContext
	// TaskID is the run's task. Optional — when set, a PRIORITIZE
	// control event targets it; when empty, a PRIORITIZE fails loud.
	TaskID tasks.TaskID
	// MaxSteps caps the planner-step count. ≤ 0 ⇒ DefaultMaxSteps.
	MaxSteps int

	// ToolExecutor dispatches the planner's non-Finish, non-RequestPause
	// decisions (CallTool, CallParallel, SpawnTask, AwaitTask).
	// When nil, the runloop's default case logs and
	// appends an empty-observation step (the behaviour) so
	// existing pause/steering tests still drive deterministic finishes.
	// In production the dev binary wires a real executor backed by the
	// tool catalog so the planner's CallTool decisions actually run.
	ToolExecutor ToolExecutor

	// Compression is the optional trajectory-compression runner
	// (the §13 first call site of
	// planner.CompressionRunner.MaybeCompress). When non-nil AND the
	// run's Base.Budget.TokenBudget > 0, the runloop invokes
	// MaybeCompress at each step boundary (after the control drain +
	// projection, before Planner.Next) so an over-budget trajectory is
	// compacted into Trajectory.Summary BEFORE the next prompt build —
	// the React prompt builder's `Summary != nil` branch then renders
	// the five-field summary instead of the per-step history and the
	// prompt shrinks. Nil (or a zero TokenBudget) is byte-identical to
	// the pre-111e behaviour: no estimate, no summariser, no events.
	//
	// One compression per run at V1.1.x: the runner is idempotent on
	// `Trajectory.Summary != nil` (the documented scope fence — RFC
	// §6.5; re-compaction cadence is the recorded follow-up).
	// A MaybeCompress error fails the run LOUDLY (the runner already
	// emitted trajectory.compression_failed) — never a silent
	// fall-through that pretends compression happened.
	Compression *planner.CompressionRunner

	// OnToolDispatched is the optional per-run hook the runloop invokes
	// after the ToolExecutor returns WITHOUT ERROR. The dev binary
	// wires it to loop `count` calls of
	// `taskReg.IncrementToolCount(ctx, taskID)` so the Console Tasks
	// page's tool_count reflects the per-task count of SUCCESSFUL tool
	// dispatches, using the same per-decision counting rule as
	// `planner.DecisionInvocationCount`. Note the deliberate failure-axis
	// difference from `planner.AnswerEnvelope.ToolCallsSeen`: tool_count
	// counts successful dispatches only (this hook is skipped on an
	// executor error), while ToolCallsSeen counts ATTEMPTED invocations
	// recorded on the trajectory — a failed dispatch still appends its
	// step, so the envelope counts it. A nil hook is the legacy / test
	// path (no counter wired); a hook that errors fails the run loud —
	// silent degradation of an observability counter is forbidden per
	// §13 (the counter is an integrity surface, not a best-effort log
	// line).
	//
	// count is the decision's tool-invocation count
	// (planner.DecisionInvocationCount): 1 for a successfully-dispatched
	// CallTool, len(Branches) for a CallParallel. The runloop only calls
	// the hook when count > 0 — a SpawnTask / AwaitTask dispatch never
	// invokes it, because spawning or joining a task is not a tool
	// invocation. A dispatch the executor reports as failed (the
	// executor's own error path) also does NOT invoke the hook; the
	// planner's repair / re-plan flow records the failure on the
	// trajectory and the counter stays put.
	OnToolDispatched func(ctx context.Context, count int) error

	// CompletionHook, when set, is the operator-configured run-completion
	// hook: at Run's terminal boundary the runloop fires it exactly once —
	// for EVERY terminal outcome, never mid-run and never on pause —
	// dispatching the run's RunCompletionPayload transcript to the named
	// catalog tool through ToolExecutor. The outcome rides in the payload.
	// The hook runs AFTER the run's (fin, err) are settled and can NEVER
	// alter them: a dispatch failure emits run.hook_failed + a Warn log and
	// nothing else. A nil CompletionHook is byte-identical to the pre-hook
	// behaviour. See completion.go for the payload contract + the detached
	// cancellation bridge.
	CompletionHook *CompletionHookSpec
}

type Scope string

type ToolExecutor interface {
	// ExecuteDecision dispatches `decision` and returns BOTH the raw
	// observation (preserved for inspect-runs / audit) AND the
	// projection the next prompt sees (`llmObservation`, the
	// heavy-content-discipline projection: a small summary +
	// ArtifactRef when the raw result is over the heavy threshold,
	// or just == raw when the result is small enough to inline).
	//
	// The runloop appends a trajectory.Step{Action: decision,
	// Observation: raw, LLMObservation: projection} so the planner's
	// renderer sees only the projection.
	//
	// `rc` is the per-step RunContext (identity, ToolContext, etc.).
	// ctx is the per-step ctx; the executor MUST honour cancellation.
	ExecuteDecision(ctx context.Context, rc planner.RunContext, decision planner.Decision) (observation, llmObservation any, err error)
}

type TranscriptEntry struct {
	Role    string     `json:"role"`
	Kind    string     `json:"kind"`
	Content string     `json:"content"`
	Step    int        `json:"step"`
	At      *time.Time `json:"at,omitempty"`
}