planner

type AgentState interface {
	// Get returns the value stored under key, if any.
	Get(key string) (any, bool)

	// Set stores value under key for the duration of the run.
	Set(key string, value any)

	// Keys returns all currently stored keys.
	Keys() []string
}

type Await struct {
	Items []AwaitItem
}

type AwaitClarification struct {
	// ID uniquely identifies this clarification request.
	ID string

	// Question is the user-facing question to ask.
	Question string

	// MissingFields lists missing or invalid fields the user must supply.
	MissingFields []string

	// RestrictToTool optionally binds the clarification to a single tool.
	RestrictToTool tools.Ident

	// ExampleInput is an example payload (as a JSON object) to guide the user.
	ExampleInput map[string]any

	// ClarifyingPrompt is an optional prompt to use when building follow-up messages.
	ClarifyingPrompt string
}

type AwaitExternalTools struct {
	// ID uniquely identifies this external-tools request.
	ID string

	// Items describes the tool calls that the caller must satisfy.
	Items []AwaitToolItem
}

type AwaitItem struct {
	Kind AwaitItemKind

	Clarification *AwaitClarification
	Questions     *AwaitQuestions
	ExternalTools *AwaitExternalTools
}

type AwaitItemKind string

type AwaitQuestion struct {
	// ID uniquely identifies this question within the prompt.
	ID string

	// Prompt is the user-facing question text.
	Prompt string

	// Options enumerates the selectable answers.
	Options []AwaitQuestionOption

	// AllowMultiple reports whether multiple options may be selected.
	AllowMultiple bool
}

type AwaitQuestionOption struct {
	// ID uniquely identifies this option within the question.
	ID string

	// Label is the user-facing option label.
	Label string
}

type AwaitQuestions struct {
	// ID uniquely identifies this questions request.
	ID string

	// ToolName identifies the tool awaiting user answers (for example, "chat.ask_question.ask_question").
	ToolName tools.Ident

	// ToolCallID correlates the provided result with this requested call.
	ToolCallID string

	// Payload is the canonical JSON payload for the awaited tool call.
	Payload rawjson.Message

	// Title is an optional display title for the questions form.
	Title *string

	// Questions enumerates the questions to present to the user.
	Questions []AwaitQuestion
}

type AwaitToolItem struct {
	// Name is the tool identifier to invoke externally.
	Name tools.Ident

	// ToolCallID correlates the provided result with this requested call.
	ToolCallID string

	// Payload is the canonical JSON payload for the external tool call.
	Payload rawjson.Message
}

type FinalResponse struct {
	// Message is the assistant message returned to the user.
	Message *model.Message
}

type FinalToolResult struct {
	// Result is the canonical JSON result payload encoded with the parent tool's
	// result codec.
	Result rawjson.Message

	// ServerData carries server-only data associated with the final tool result.
	ServerData rawjson.Message

	// ResultBytes is the size, in bytes, of the canonical JSON result payload
	// when known.
	ResultBytes int

	// ResultOmitted indicates that the canonical JSON result payload was
	// intentionally omitted to satisfy workflow payload budgets.
	ResultOmitted bool

	// ResultOmittedReason provides a stable, machine-readable reason for omission.
	ResultOmittedReason string

	// Bounds describes how the result has been bounded relative to the full data
	// set when applicable.
	Bounds *agent.Bounds

	// Error is the structured tool error, when the nested planner finalized with
	// a tool-scoped failure.
	Error *ToolError

	// RetryHint provides structured recovery guidance for tool-scoped failures.
	RetryHint *RetryHint

	// Telemetry contains execution metrics attributed to the final tool result.
	Telemetry *telemetry.ToolTelemetry
}

type PlanInput struct {
	// Messages is the full conversation history at run start.
	Messages []*model.Message

	// RunContext contains durable identifiers and links for the run.
	RunContext run.Context

	// Agent provides access to runtime services (models, memory, telemetry).
	Agent PlannerContext

	// Events allows planners to emit streaming updates.
	Events PlannerEvents

	// Reminders contains the active system reminders for this planner turn.
	// Callers should treat this slice as read-only and rely on
	// PlannerContext.AddReminder to register new reminders for future turns.
	Reminders []reminder.Reminder
}

type PlanResult struct {
	// ToolCalls are the tool invocations the runtime should execute next.
	ToolCalls []ToolRequest

	// FinalResponse ends the run with a final assistant message.
	FinalResponse *FinalResponse

	// FinalToolResult ends a nested agent run with a canonical parent tool result
	// instead of an assistant message.
	FinalToolResult *FinalToolResult

	// Streamed reports whether assistant text for this result has already been
	// streamed via PlannerEvents.AssistantChunk. When true, runtimes should
	// avoid emitting an additional full AssistantMessageEvent for the
	// FinalResponse to prevent duplicate assistant messages.
	Streamed bool

	// Await requests the runtime to pause the run and wait for additional input.
	Await *Await

	// RetryHint provides structured guidance for recovering from failures without terminating.
	RetryHint *RetryHint

	// ExpectedChildren is an optional hint for how many nested tool results a planner expects.
	ExpectedChildren int

	// Notes are optional planner annotations surfaced to subscribers.
	Notes []PlannerAnnotation
}

type PlanResumeInput struct {
	// Messages is the full conversation history including the most recent tool_use/tool_result blocks.
	Messages []*model.Message

	// RunContext contains durable identifiers and links for the run.
	RunContext run.Context

	// Agent provides access to runtime services (models, memory, telemetry).
	Agent PlannerContext

	// Events allows planners to emit streaming updates.
	Events PlannerEvents

	// ToolOutputs is the accumulated executed tool-call history for the run so far.
	//
	// This is the single truthful planner-facing execution-history boundary.
	// Planners that need typed convenience views derive them locally from these
	// canonical tool outputs instead of relying on a duplicate runtime field.
	ToolOutputs []*ToolOutput

	// Finalize is non-nil when the runtime forces termination and requests a final response.
	Finalize *Termination

	// Reminders contains the active system reminders for this planner turn.
	Reminders []reminder.Reminder
}

type Planner interface {
	// PlanStart receives the initial messages and returns the first decision.
	// This is called exactly once at the start of each run.
	PlanStart(ctx context.Context, input *PlanInput) (*PlanResult, error)

	// PlanResume receives messages plus tool results from the previous turn.
	// This is called after each batch of tool executions until the planner
	// returns a FinalResponse or the runtime terminates due to policy limits.
	// When the runtime forces termination (caps exhausted, time budget expired),
	// the Finalize field is set and the planner should produce a final response.
	PlanResume(ctx context.Context, input *PlanResumeInput) (*PlanResult, error)
}

type PlannerAnnotation struct {
	// Text is the note content.
	Text string

	// Labels are optional structured tags for tooling/debugging.
	Labels map[string]string
}

type PlannerContext interface {
	// ID returns the agent identifier for the run currently being planned.
	ID() agent.Ident

	// RunID returns the run identifier for the run currently being planned.
	RunID() string

	// Memory returns a read-only view of the configured memory store.
	Memory() memory.Reader

	// Logger returns the run-scoped logger.
	Logger() telemetry.Logger

	// Metrics returns the metrics emitter for the run.
	Metrics() telemetry.Metrics

	// Tracer returns the distributed tracer for the run.
	Tracer() telemetry.Tracer

	// State returns ephemeral per-run storage for planner-local state.
	State() AgentState

	// ModelClient returns the model client configured for the given model ID.
	// The boolean result is false when the requested model is not configured.
	ModelClient(id string) (model.Client, bool)

	// RenderPrompt resolves and renders a registered prompt by ID.
	//
	// Runtime applies prompt override precedence using the current run scope
	// (session and labels) before rendering.
	RenderPrompt(ctx context.Context, id prompt.Ident, data any) (*prompt.PromptContent, error)

	// AddReminder registers or updates a run-scoped system reminder. Planners use
	// this to surface structured, rate-limited guidance (for example, “review
	// open todos”) without baking prompt text directly into planner logic.
	AddReminder(r reminder.Reminder)

	// RemoveReminder clears a previously registered reminder by ID. Planners call
	// this when the conditions for a reminder no longer hold so future turns and
	// prompts stop surfacing outdated guidance.
	RemoveReminder(id string)
}

type PlannerEvents interface {
	// AssistantChunk emits an assistant text delta. Use this for incremental
	// streaming output instead of returning a full FinalResponse at the end.
	AssistantChunk(ctx context.Context, text string)

	// ToolCallArgsDelta emits an incremental tool-call argument fragment as the
	// model streams tool input JSON.
	//
	// Naming note:
	//   - AssistantChunk streams user-visible assistant text in chunks.
	//   - ToolCallArgsDelta streams non-canonical argument fragments; we call it
	//     a delta because fragments are not guaranteed to be valid JSON boundaries
	//     and are strictly optional to consume.
	//
	// Contract:
	//   - This is a best-effort UX signal. Consumers may ignore it entirely.
	//   - Deltas are not guaranteed to be valid JSON on their own.
	//   - The canonical tool payload is still delivered via the final tool call
	//     (model.ChunkTypeToolCall) and the runtime's tool_start event.
	ToolCallArgsDelta(ctx context.Context, toolCallID string, toolName tools.Ident, delta string)

	// PlannerThinkingBlock emits a structured thinking block (for models that
	// support rich thinking parts) for debugging/trace visibility.
	PlannerThinkingBlock(ctx context.Context, block model.ThinkingPart)

	// PlannerThought emits a planner note with optional labels for debugging.
	PlannerThought(ctx context.Context, note string, labels map[string]string)

	// UsageDelta reports incremental token usage for the current planning phase.
	UsageDelta(ctx context.Context, usage model.TokenUsage)
}

type RetryHint struct {
	// Reason classifies the retry hint for policy/UX decisions.
	Reason RetryReason

	// Tool is the tool identifier associated with this hint.
	Tool tools.Ident

	// RestrictToTool instructs callers to retry only the specified tool.
	RestrictToTool bool

	// MissingFields lists required fields that were missing or invalid.
	MissingFields []string

	// ExampleInput is an example payload (as a JSON object) to guide callers.
	ExampleInput map[string]any

	// PriorInput is the payload (as a JSON object) that caused the failure when
	// available, to assist interactive repair flows.
	PriorInput map[string]any

	// ClarifyingQuestion is a natural-language question to ask the user to obtain
	// the missing or corrected information.
	ClarifyingQuestion string

	// Message is an optional additional explanation for the caller.
	Message string
}

type RetryHintProvider interface {
	RetryHint(tool tools.Ident) *RetryHint
}

type RetryReason string

type StreamSummary struct {
	// Text accumulates assistant text chunks in the order they were received.
	Text string
	// ToolCalls captures tool invocations requested by the model (if any).
	ToolCalls []ToolRequest
	// Usage aggregates the reported token usage across usage chunks/metadata.
	Usage model.TokenUsage
	// StopReason records the provider stop reason when emitted.
	StopReason string
}

type Termination struct {
	// Reason explains which policy cap triggered termination.
	Reason TerminationReason

	// Message is optional additional context suitable for logging or diagnostics.
	Message string
}

type TerminationReason string

type ToolError = toolerrors.ToolError

type ToolOutput struct {
	// Name is the fully-qualified tool identifier that was executed.
	Name tools.Ident

	// ToolCallID is the correlation identifier for this tool invocation.
	ToolCallID string

	// Payload is the canonical JSON payload passed to the tool.
	Payload rawjson.Message

	// Result is the canonical JSON result payload encoded with the tool result codec.
	Result rawjson.Message

	// ResultBytes is the size, in bytes, of the canonical JSON result payload when known.
	ResultBytes int

	// ResultOmitted indicates that the canonical JSON result payload was intentionally
	// omitted to satisfy workflow payload budgets.
	ResultOmitted bool

	// ResultOmittedReason provides a stable, machine-readable reason for omission.
	ResultOmittedReason string

	// ServerData carries canonical server-only JSON emitted alongside the tool result.
	ServerData rawjson.Message

	// Bounds describes how the result has been bounded relative to the full data set.
	Bounds *agent.Bounds

	// Error is the structured tool error, when the tool execution failed.
	Error *ToolError

	// RetryHint provides structured recovery guidance for tool-scoped failures.
	RetryHint *RetryHint

	// Telemetry contains execution metrics attributed to this tool output.
	Telemetry *telemetry.ToolTelemetry
}

type ToolRequest struct {
	// Name is the fully-qualified tool identifier (for example, "svc.read.get_time_series").
	Name tools.Ident

	// Payload is the canonical JSON payload for the tool call.
	Payload rawjson.Message

	// AgentID is the identifier of the agent that issued this tool request.
	AgentID agent.Ident

	// RunID is the identifier of the run that owns this tool call.
	RunID string

	// SessionID is the logical session identifier (for example, a chat conversation).
	SessionID string

	// Labels carries caller-defined run metadata dimensions used by runtime
	// policies and prompt scoping.
	Labels map[string]string

	// TurnID identifies the conversational turn that produced this tool call.
	TurnID string

	// ToolCallID uniquely identifies this tool invocation for correlation across events.
	ToolCallID string

	// ParentToolCallID is the identifier of the parent tool call when this invocation
	// is nested (for example, a tool launched by an agent-as-tool).
	ParentToolCallID string
}

type ToolResult struct {
	// Name is the fully-qualified tool identifier that produced this result.
	Name tools.Ident

	// Result is the decoded tool result value. Its concrete type depends on the
	// tool's result schema and codec.
	Result any

	// ServerData carries server-only data emitted by tool providers (for example,
	// UI projections, evidence, or provenance records) that must not be sent to
	// model providers.
	//
	// Contract:
	//   - This is canonical JSON bytes (typically a JSON array of server-data items).
	//   - The runtime treats the payload as opaque bytes; sinks and UIs decode it
	//     using the tool specs/codecs for the corresponding kinds.
	ServerData rawjson.Message

	// ResultBytes is the size, in bytes, of the canonical JSON result payload when
	// known. It is populated by the runtime when a tool result crosses a workflow
	// boundary as an api.ToolEvent.
	ResultBytes int

	// ResultOmitted indicates that the runtime intentionally omitted the canonical
	// JSON result payload from the workflow-boundary envelope to satisfy payload
	// budgets. When true, Result is nil even though the tool produced a result.
	//
	// Planners must treat ResultOmitted as a control-plane constraint: use bounded
	// transcript projections, out-of-band persistence, or follow-up tools to narrow
	// the request rather than expecting full payloads to be carried in activity
	// inputs.
	ResultOmitted bool

	// ResultOmittedReason provides a stable, machine-readable reason for omitting
	// the result bytes. Empty when ResultOmitted is false.
	//
	// Example values: "workflow_budget".
	ResultOmittedReason string

	// Bounds, when non-nil, describes how the result has been bounded relative
	// to the full underlying data set (for example, list/window/graph caps).
	// Tool implementations and adapters populate this field; the runtime and
	// sinks surface it but never mutate or derive it.
	Bounds *agent.Bounds

	// Error is the structured tool error, when the tool execution failed.
	Error *ToolError

	// RetryHint is optional structured guidance for recovering from tool failures.
	RetryHint *RetryHint

	// Telemetry contains tool execution metrics (duration, token usage, model).
	Telemetry *telemetry.ToolTelemetry

	// ToolCallID is the correlation identifier for this tool invocation.
	ToolCallID string

	// ChildrenCount records how many nested tool results were observed when this
	// result came from an agent-as-tool execution.
	ChildrenCount int

	// RunLink, when non-nil, links this result to a nested agent run that
	// was executed as an agent-as-tool. For service-backed tools this field
	// is nil. Callers can use RunLink to subscribe to or display the child
	// agent run separately from the parent tool call.
	RunLink *run.Handle
}