agent

type Agent struct {
	// ID is the stable identifier for this agent. It flows into
	// telemetry, history conversation keys, and any A2A federation
	// envelope. MUST be non-empty.
	ID string `json:"id"`

	// Card describes the agent's capabilities for discovery (A2A,
	// dashboards, …). Optional.
	Card AgentCard `json:"card,omitempty"`

	// Tools is the list of tool ids the agent is permitted to call.
	// The engine looks tools up by id in its dependency container at
	// run time; this list is the policy gate, not the wiring.
	Tools []string `json:"tools,omitempty"`

	// Observers are agent-scoped lifecycle observers. They fire on
	// every [Run] of this agent value, before any observers added
	// via [WithObserver] for the specific call. JSON-skipped because
	// observers carry runtime state (channels, stores, …) that does
	// not round-trip through serialisation.
	Observers []Observer `json:"-"`

	// Deciders are agent-scoped decision hooks (see [Decider]). They
	// run before any Decider added via [WithDecider] for the
	// specific call. Same JSON-skip rationale as Observers.
	Deciders []Decider `json:"-"`
}

type AgentCapabilities struct {
	// Streaming reports whether the agent emits server-sent events
	// during a turn.
	Streaming bool `json:"streaming,omitempty"`

	// PushNotifications reports whether the agent can push update
	// notifications back to the client.
	PushNotifications bool `json:"pushNotifications,omitempty"`

	// StateTransitionHistory reports whether the agent exposes its
	// task state-transition history.
	StateTransitionHistory bool `json:"stateTransitionHistory,omitempty"`
}

type AgentCard struct {
	// Name is a human-readable name for the agent.
	Name string `json:"name"`

	// Description explains what the agent does.
	Description string `json:"description,omitempty"`

	// Skills enumerates the capability units the agent can perform.
	Skills []Skill `json:"skills,omitempty"`

	// DefaultInputModes lists MIME types the agent accepts when a
	// skill does not override them. Per the A2A spec, this field is
	// keyed "defaultInputModes" — singular "inputModes" lives on
	// individual skills.
	DefaultInputModes []string `json:"defaultInputModes,omitempty"`

	// DefaultOutputModes lists MIME types the agent emits when a
	// skill does not override them.
	DefaultOutputModes []string `json:"defaultOutputModes,omitempty"`

	// Capabilities declares which optional A2A protocol features the
	// agent supports.
	Capabilities AgentCapabilities `json:"capabilities,omitempty"`
}

type Artifact struct {
	Name  string       `json:"name"`
	Parts []model.Part `json:"parts,omitempty"`
}

type BaseDecider struct{}

type BaseObserver struct{}

type BoardSeeder interface {
	SeedBoard(ctx context.Context, info RunInfo, req *Request) (*engine.Board, error)
}

type BoardSeederFunc func(ctx context.Context, info RunInfo, req *Request) (*engine.Board, error)

type Decider interface {
	// BeforeFinalize fires after engine.Execute returns. The Decider
	// inspects res (read-only) and the original req, and returns a
	// FinalizeDecision that Run merges with other Deciders' decisions.
	//
	// info carries the immutable identification fields agreed for
	// this turn. The Decider MUST NOT mutate res; agent will surface
	// the merged decision via [Result.Committed] and (when a Reason
	// was supplied) [Result.State]["finalize_reason"].
	BeforeFinalize(ctx context.Context, info RunInfo, req *Request, res *Result) (FinalizeDecision, error)
}

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

type FinalizeDecision struct {
	// DiscardOutput, when true, instructs Run to mark Result.Committed
	// = false regardless of Status. Observers reading Committed
	// (notably history-append observers) skip persistence on a
	// discarded run.
	//
	// Setting DiscardOutput on a StatusCompleted run is allowed and
	// useful for moderation hooks ("the answer violates policy, do
	// not persist it").
	DiscardOutput bool

	// Revise asks agent.Run to discard this attempt's output and
	// re-invoke engine.Execute with a fresh board (re-seeded from
	// the original Request). Honoured ONLY when the per-call
	// [WithMaxRevise] budget allows another attempt; the option
	// defaults to 0, so by default Revise is recorded as a
	// finalize_reason but does NOT trigger another engine call —
	// callers must opt in explicitly to avoid runaway loops on
	// faulty Deciders.
	//
	// When honoured the lifecycle is:
	//
	//   1. Decider returns Revise=true (and optionally Reason).
	//   2. Run fires [Observer.OnRunRevise] with the about-to-be-
	//      discarded Result and the next attempt index.
	//   3. Board is re-seeded via the configured BoardSeeder; the
	//      same engine.Run identifier is reused so observers that
	//      key by run id can correlate attempts.
	//   4. engine.Execute runs again. The Decider chain runs again
	//      on the new Result.
	//   5. The loop exits when either Revise=false or the attempt
	//      counter reaches WithMaxRevise. The final Result.Attempts
	//      reflects how many engine.Execute calls were made.
	//
	// Revise interacts with [WithResumeFrom]: ResumeFrom applies
	// to the FIRST attempt only. Revise restarts are fresh runs
	// (the engine should be re-entered from the start), so
	// subsequent attempts drop ResumeFrom — replaying a checkpoint
	// repeatedly would defeat the purpose of asking for a revision.
	Revise bool

	// Reason is a free-form short string explaining the decision.
	// Agent stores the first non-empty Reason in Result.State under
	// "finalize_reason" so logs / metrics can attribute the
	// outcome.
	Reason string
}

type Handoff struct {
	// ToAgentID is the stable identifier of the receiving agent.
	// The host is responsible for resolving this id to a runnable
	// Agent + Engine pair; the SDK stays out of routing.
	ToAgentID string

	// Description is shown to the LLM as the tool description so
	// it knows when to invoke the hand-off. Keep it short and
	// behavioural ("Refunds, invoices, plans"). Empty falls back
	// to a generic "Transfer the conversation to <id>".
	Description string

	// ToolName overrides the LLM-facing tool name. Default is
	// "transfer_to_<sanitised_ToAgentID>" (lowercased,
	// non-alphanumeric → "_"). Override when two hand-offs would
	// otherwise collide on the default name (e.g. multiple
	// agents whose IDs differ only in case).
	ToolName string

	// Filter, when set, is consulted by [HandoffTools] to allow
	// per-request gating without rebuilding the slice. A Filter
	// returning false hides the hand-off from this turn's LLM.
	// Typical use: tenant-aware gating, permission checks.
	Filter func(ctx context.Context, req *Request) bool

	// OnInvoke fires synchronously inside the hand-off tool's
	// Execute call. Use it for lightweight observability (a log
	// line, a metric) — heavy work should be done by the host
	// after Run returns. Returning an error from OnInvoke fails
	// the tool call and the LLM may retry; the hand-off is NOT
	// recorded in that case.
	OnInvoke func(ctx context.Context, args HandoffArgs) error
}

type HandoffArgs struct {
	// Reason is a short rationale for the transfer. Surfaced to
	// the receiving agent and to telemetry. Example:
	// "User asked about invoice for order #1234".
	Reason string `json:"reason,omitempty"`

	// Note is an optional free-form message the LLM wants the
	// receiving agent to read first. Avoid stuffing the entire
	// transcript here; the receiving side should reload history
	// via the host's normal mechanisms.
	Note string `json:"note,omitempty"`
}

type HandoffEvent struct {
	// ToAgentID mirrors [Handoff.ToAgentID].
	ToAgentID string `json:"to_agent_id"`

	// ToolName is the tool name the LLM actually invoked.
	ToolName string `json:"tool_name"`

	// ToolCallID echoes the ToolCall.ID from the model, so the
	// host can correlate downstream events back to the originating
	// call.
	ToolCallID string `json:"tool_call_id"`

	// Args carries the LLM-supplied reason / note.
	Args HandoffArgs `json:"args,omitempty"`
}

type Observer interface {
	// OnRunStart fires after Run prepared the engine inputs but
	// before engine.Execute is invoked. info carries the immutable
	// identification fields agreed for this turn.
	OnRunStart(ctx context.Context, info RunInfo, req *Request)

	// OnInterrupt fires only when the engine returned an interrupt
	// error. It runs before OnRunEnd. intr carries the structured
	// reason supplied by the host.
	OnInterrupt(ctx context.Context, info RunInfo, intr engine.Interrupt)

	// OnRunRevise fires when a Decider asked agent.Run to re-invoke
	// engine.Execute (FinalizeDecision{Revise: true}) AND the
	// per-call WithMaxRevise budget allows another attempt. It
	// runs after the discarded attempt's classification but BEFORE
	// the next OnRunStart, so observers see the lifecycle as:
	//
	//	OnRunStart → engine.Execute → OnRunRevise → OnRunStart → engine.Execute → OnRunEnd
	//
	// prevRes is the (about-to-be-replaced) Result from the failed
	// attempt — observers MUST treat it as read-only. nextAttempt
	// is the 1-indexed attempt number the next engine.Execute will
	// be (== prevRes.Attempts + 1).
	//
	// OnRunRevise is the canonical hook for "log how many times the
	// answer needed revision" / "page on excessive revise loops" /
	// "snapshot intermediate boards before they are discarded". It
	// fires zero times for runs that complete on the first attempt
	// or whose Decider never asks for revise.
	OnRunRevise(ctx context.Context, info RunInfo, prevRes *Result, nextAttempt int)

	// OnRunEnd fires after engine.Execute returned and Run finished
	// classifying the outcome. res is the same pointer Run is about
	// to return; observers MUST treat it as read-only.
	OnRunEnd(ctx context.Context, info RunInfo, res *Result)
}

type Request struct {
	// TaskID identifies a long-lived task the request is part of.
	// Empty when the caller is not tracking tasks. Maps to A2A's
	// "taskId".
	TaskID string `json:"taskId,omitempty"`

	// ContextID identifies the conversation / session. Used as the
	// conversation key passed to History.Load / Append. Empty means
	// "no persistent transcript for this turn". Maps to A2A's
	// "contextId".
	ContextID string `json:"contextId,omitempty"`

	// RunID is the host-supplied execution id. When empty Run mints
	// one. The same value is propagated as engine.Run.ID and as the
	// run id attribute on emitted events. Not part of the A2A wire
	// schema — it is an internal correlation key, kept camelCase for
	// stylistic consistency.
	RunID string `json:"runId,omitempty"`

	// Message is the user's turn input (text, parts, attachments).
	Message model.Message `json:"message"`

	// Inputs are arbitrary structured inputs the engine reads off
	// the Board (form fields, parameters, …). They are written under
	// their map keys as Board vars before the engine starts.
	Inputs map[string]any `json:"inputs,omitempty"`

	// Config carries per-request preferences (output modes, …).
	// Maps to A2A's "configuration".
	Config *RequestConfig `json:"configuration,omitempty"`

	// Extensions is host-passed-through metadata.
	//
	// Deprecated: agent has never interpreted this field — the
	// previous godoc only documented "engines may read it from
	// Run.Attributes if the host chose to forward it", and no
	// such forwarding was ever implemented (contract-audit #8).
	// The map[string]any → map[string]string type mismatch with
	// engine.Run.Attributes also forces an ad-hoc serialisation
	// strategy on every host that wants to forward.
	//
	// Use [WithAttributes] instead: it is a typed map[string]string
	// the caller controls, the wire format is uniform with the
	// canonical attribute bag (sdk/telemetry.Attr* dot-keys), and
	// engines find it under engine.Run.Attributes via the same
	// codepath as agent_id / run_id / task_id / context_id.
	//
	// This field is scheduled for removal in sdk v0.5.0. Migrate
	// callers by serialising any non-string values at the call
	// site and passing them through agent.WithAttributes(...) on
	// the agent.Run option list. Engines that need to introspect
	// caller-supplied metadata read engine.Run.Attributes today.
	Extensions map[string]any `json:"extensions,omitempty"`
}

type RequestConfig struct {
	// AcceptedOutputModes constrains what modalities the caller can
	// receive (e.g. ["text/plain"], ["audio/wav"], …). Engines that
	// can produce multiple modalities consult it to pick one. Maps
	// to A2A's "acceptedOutputModes".
	AcceptedOutputModes []string `json:"acceptedOutputModes,omitempty"`
}

type Result struct {
	// TaskID echoes the input Request.TaskID for correlation.
	// Matches the A2A taskId casing.
	TaskID string `json:"taskId,omitempty"`

	// RunID echoes the (possibly auto-generated) execution id Run
	// used to drive the engine.
	RunID string `json:"runId,omitempty"`

	// Status classifies the outcome.
	Status Status `json:"status"`

	// Cause is set when Status == StatusInterrupted: it carries the
	// engine.Cause the host signalled. Empty otherwise.
	Cause engine.Cause `json:"cause,omitempty"`

	// Messages is the slice of NEW messages produced this turn —
	// excluding the input request and any history loaded before the
	// turn. Suitable for streaming to a UI or appending to the
	// persistent transcript (which Run already did).
	Messages []model.Message `json:"messages,omitempty"`

	// Artifacts collects named, multi-modal bundles the engine
	// emitted via dedicated board channels.
	Artifacts []Artifact `json:"artifacts,omitempty"`

	// Committed reports whether agent considered this turn's output
	// suitable for downstream commit (transcript append, archival,
	// …). It is determined by the Round B Decider chain
	// (BeforeFinalize) on top of agent's defaults:
	//
	//   - StatusCompleted defaults to Committed=true.
	//   - All non-completed statuses default to Committed=false.
	//   - Any Decider returning DiscardOutput=true forces
	//     Committed=false.
	//
	// Observers that persist transcript / artifact data are
	// expected to short-circuit when Committed is false:
	//
	//	if !res.Committed { return }
	//
	// Independent of Committed, Result.Messages always reflects the
	// engine's actual output; Committed is the *policy* signal, not
	// a content flag.
	Committed bool `json:"committed"`

	// State is a free-form bag carrying run-specific metadata. agent
	// puts a few well-known keys (run_id, board, interrupted_node,
	// …) here but does not enforce a schema beyond that.
	State map[string]any `json:"state,omitempty"`

	// Err is the engine's underlying error when Status indicates a
	// non-completed outcome. Callers that want classification call
	// errdefs.IsXxx on it; the JSON tag is "-" because errors do not
	// JSON-marshal usefully.
	Err error `json:"-"`

	// LastBoard is the engine's final Board (possibly partial when
	// Status != StatusCompleted). agent does not persist it; the
	// host can choose to checkpoint via engine's Checkpointer.
	LastBoard *engine.Board `json:"-"`

	// Attempts is the number of engine.Execute invocations Run made
	// before settling on this Result. 1 for fresh (single-shot)
	// runs; >1 only when WithMaxRevise was enabled and at least
	// one Decider returned FinalizeDecision{Revise: true}.
	//
	// Attempts is the post-loop count, not "remaining budget":
	// Attempts == 2 means the engine was invoked twice. Observers
	// reading res.Attempts in OnRunEnd see the final value.
	//
	// Zero is reserved for "Run never reached engine.Execute"
	// (infrastructure error). Real runs always have Attempts >= 1.
	Attempts int `json:"attempts,omitempty"`
}

type RunInfo struct {
	// AgentID is the running [Agent.ID].
	AgentID string

	// RunID is the execution id assigned by Run (req.RunID when
	// supplied, else the auto-generated one).
	RunID string

	// TaskID echoes [Request.TaskID]. Empty when the caller did not
	// scope this turn to a long-running task.
	TaskID string

	// ContextID echoes [Request.ContextID]. Empty when the turn is
	// not part of a persistent conversation.
	ContextID string
}

type RunOption func(*runConfig)

type Skill struct {
	// ID is the unique identifier for this skill within the agent.
	ID string `json:"id"`

	// Name is a human-readable label for the skill.
	Name string `json:"name"`

	// Description explains what the skill does.
	Description string `json:"description,omitempty"`

	// Tags categorises the skill (e.g. "cooking", "support").
	Tags []string `json:"tags,omitempty"`

	// Examples lists illustrative prompts the skill can handle.
	Examples []string `json:"examples,omitempty"`

	// InputModes overrides AgentCard.DefaultInputModes for this
	// specific skill. Empty means "use the agent default".
	InputModes []string `json:"inputModes,omitempty"`

	// OutputModes overrides AgentCard.DefaultOutputModes for this
	// specific skill. Empty means "use the agent default".
	OutputModes []string `json:"outputModes,omitempty"`
}

type Status string