model

type APIError struct {
	Message     string
	StatusCode  int
	IsRetryable bool
}

type AssistantTextInfo struct {
	Text string
	// Iteration is the 0-based loop iteration (see LLMRequestInfo.Iteration).
	Iteration int
}

type AsyncAskBinder interface {
	BindAsyncAsk(ctx context.Context, runID, nodeID string) AsyncAskHook
}

type AsyncAskHook interface {
	// Post persists a pending Kind=async Interaction and emits
	// human_input_requested{async:true}. Returns the interaction ID.
	Post(ctx context.Context, q delegate.AsyncQuestion) (string, error)
	// Pending lists the node's still-unanswered async questions
	// (oldest first).
	Pending(ctx context.Context) ([]delegate.PendingAsync, error)
	// CollectAnswers formats every answered async question of the node
	// into one human-readable block (the await_answers success result).
	CollectAnswers(ctx context.Context) (string, error)
}

type AttachmentInfo struct {
	Name             string
	Path             string // absolute host path; empty in cloud unless prefetched
	OriginalFilename string
	MIME             string
	Size             int64
	SHA256           string
	// PresignURL, when set, is invoked lazily the first time a
	// `.url` reference is resolved. Returns "" when no presigner
	// is wired (e.g. unit-test stubs).
	PresignURL func() (string, error)
}

type AttachmentWriter interface {
	WriteAttachment(ctx context.Context, runID string, rec store.AttachmentRecord, body io.Reader) error
}

type CapabilitySource string

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

type ClawBackendOption func(*ClawBackend)

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

type ClawExecutorOption func(*ClawExecutor)

type CompactInfo struct {
	// BeforeMessages is the message count before compaction.
	BeforeMessages int

	// AfterMessages is the message count after compaction.
	AfterMessages int

	// RemovedMessageCount is reported by claw's CompactionResult.
	RemovedMessageCount int
}

type ContextOverflowError struct {
	Message string
}

type DelegateInfo struct {
	BackendName        string        // e.g. "claude_code", "codex"
	Duration           time.Duration // subprocess wall-clock time
	Tokens             int           // estimated total tokens consumed
	ExitCode           int           // process exit code
	Stderr             string        // captured stderr output
	RawOutputLen       int           // byte length of raw stdout
	ParseFallback      bool          // true if structured output fell back to text wrapper
	FormattingPassUsed bool          // true if two-pass execution was used (tools + schema)
	Error              error         // non-nil for OnDelegateError
	Attempt            int           // 1-based retry number (for OnDelegateRetry)
	Delay              time.Duration // backoff delay (for OnDelegateRetry)
}

type ErrNeedsInteraction struct {
	NodeID    string
	Questions map[string]any // question_key → question text
	SessionID string         // delegate session ID for re-invocation
	Backend   string         // delegate backend name (empty for claw direct)

	// Conversation is the persisted backend-specific conversation history
	// captured at the pause point (claw: marshalled []api.Message). The
	// runtime relays this opaque blob into the checkpoint so that resume
	// can rehydrate the LLM's mid-tool-loop state instead of restarting
	// from system+user prompts. Backends that cannot persist conversation
	// state (CLI: claude_code, codex) leave this nil.
	Conversation json.RawMessage
	// PendingToolUseID is the ID of the tool_use block in Conversation
	// that is awaiting an answer. Required when Conversation is non-nil.
	PendingToolUseID string
}

type EventEmitter interface {
	AppendEvent(ctx context.Context, runID string, evt store.Event) (*store.Event, error)
}

type EventHooks struct {
	OnLLMRequest    func(nodeID string, info LLMRequestInfo)
	OnLLMPrompt     func(nodeID string, systemPrompt string, userMessage string)
	OnLLMResponse   func(nodeID string, info LLMResponseInfo)
	OnLLMRetry      func(nodeID string, info RetryInfo)
	OnLLMStepFinish func(nodeID string, step LLMStepInfo)
	// OnAssistantText fires with each chunk of assistant narration —
	// mid-turn prose the conversation views render as the agent
	// "talking" while it works. claude_code fires it per streamed
	// assistant text block; claw derives it from tool-bearing steps in
	// the store hooks layer.
	OnAssistantText func(nodeID string, info AssistantTextInfo)
	// OnLLMTurnCapture fires once per claw tool-loop iteration after
	// the conversation has been augmented with this step's
	// assistant + tool_results blocks. The runtime persists the
	// snapshot as a store.TurnCheckpoint anchored at (run, node,
	// loop_iter, turn) — the load-bearing primitive for the
	// fork-from-here UX and the per-node timeline. Conversation is
	// an opaque []byte (JSON-encoded []api.Message) so EventHooks
	// stays neutral to the wire format.
	OnLLMTurnCapture func(nodeID string, info LLMTurnCaptureInfo)
	OnLLMCompacted   func(nodeID string, info LLMCompactInfo)
	OnToolStarted    func(nodeID string, info LLMToolStartedInfo)
	OnToolCall       func(nodeID string, info LLMToolCallInfo)
	// OnToolNodeResult is called for direct tool nodes (not LLM tool loops)
	// with full input/output content for detailed logging.
	OnToolNodeResult func(nodeID string, toolName string, input []byte, output string, elapsed time.Duration, err error)

	// Delegation lifecycle hooks.
	OnDelegateStarted  func(nodeID string, backendName string)
	OnDelegateFinished func(nodeID string, info DelegateInfo)
	OnDelegateError    func(nodeID string, info DelegateInfo)
	OnDelegateRetry    func(nodeID string, info DelegateInfo)
	// OnProviderFallback fires once each time a node's provider
	// fallback chain falls through from a failed provider to the next
	// one (see the DSL `provider: "a,b,c"` chain). It is purely
	// observational — the run continues transparently against the next
	// provider — and lets the studio / Prometheus exporter surface that
	// a credential route was exhausted without the run itself failing.
	OnProviderFallback func(nodeID string, info ProviderFallbackInfo)

	// OnNodeFinished fires after a node's executor returns successfully.
	// The output map carries iterion's conventional usage keys (`_tokens`,
	// `_cost_usd`, `_model`) so observers (e.g. the Prometheus exporter)
	// can attribute cost and tokens per-node without re-parsing the event
	// log.
	OnNodeFinished func(nodeID string, output map[string]any)
}

type FinishReason string

type GenerationOptions struct {
	// Model is the model ID (e.g., "claude-sonnet-4-6").
	Model string

	// System is the system prompt (plain string form).
	System string

	// SystemBlocks, when non-empty, takes precedence over System and is sent
	// as the Anthropic array-form `system` field. This is the only way to
	// attach `cache_control` markers to system content for prompt caching.
	SystemBlocks []api.ContentBlock

	// Messages is the initial conversation history.
	Messages []api.Message

	// Tools available for the model to call.
	Tools []GenerationTool

	// MaxSteps is the maximum number of tool-loop iterations (default 10).
	MaxSteps int

	// ForceInitialToolUse compels the model to call a tool before it may
	// emit a final answer: while no tool has been called yet, the tool loop
	// pins tool_choice to "any" (mapped to the provider's required/any
	// form), reverting to auto once the first tool call lands. This is the
	// agentic-parity lever for backends/models that, under the default
	// "auto" tool_choice, skip provided tools and answer from priors — the
	// exact failure that let a claw+gpt-5.5 reviewer produce an ungrounded
	// verdict (0 tool calls) while claude_code read the files. No-op when
	// Tools is empty. Set by the claw backend for tool-equipped agent/judge
	// nodes; harmless for models that already use their tools.
	ForceInitialToolUse bool

	// MaxTokens is the maximum tokens per response (default 8192).
	MaxTokens int

	// Temperature controls randomness (nil = provider default).
	Temperature *float64

	// ExplicitSchema is the JSON schema for structured output (GenerateObjectDirect).
	ExplicitSchema json.RawMessage

	// SchemaName is the name for the synthetic structured-output tool (default "structured_output").
	SchemaName string

	// ProviderOptions are provider-specific options (e.g., reasoning_effort).
	ProviderOptions map[string]any

	// MaterializeSecrets, when non-nil, swaps secret placeholders for
	// their real values in agent-emitted tool input immediately before
	// execution (Layer 1). The placeholder form is what hooks/events
	// persist, so the real secret never reaches the store.
	MaterializeSecrets func(string) string

	// CompactThresholdRatio overrides the default compaction trigger as a
	// fraction of the model's context window. 0 falls back to the built-in
	// default (0.85). Values outside (0, 1] fall back to the default.
	CompactThresholdRatio float64

	// CompactPreserveRecent overrides the default count of recent messages
	// kept verbatim during compaction. 0 falls back to the built-in default
	// (4). Values < 0 fall back to the default.
	CompactPreserveRecent int

	// OnRequest is called before each StreamResponse call.
	OnRequest func(RequestInfo)

	// OnResponse is called after each StreamResponse aggregation completes.
	OnResponse func(ResponseInfo)

	// OnStepFinish is called after each tool-loop step completes.
	OnStepFinish func(StepResult)

	// OnTurnCapture is called once per loop iteration after the
	// conversation has been augmented with the step's assistant message
	// (and tool_results, when the step contained tool calls). The
	// snapshot is a defensive copy the callback may persist or hand off
	// to a goroutine. Used by the runtime to write per-turn
	// TurnCheckpoint artifacts that anchor the fork-from-here UX
	// without disturbing the live message slice. Nil disables turn
	// capture.
	OnTurnCapture func(turn TurnCaptureInfo)

	// OnToolStarted is called immediately before each tool executes,
	// once the PreToolUse lifecycle hook (if any) has allowed the call.
	// Mirrors OnToolCall but carries no duration/error.
	OnToolStarted func(ToolCallInfo)

	// OnToolCall is called after each tool execution.
	OnToolCall func(ToolCallInfo)

	// OnBeforeCompact fires only when in-loop compaction is about to
	// shrink the history. The callback may return a modified slice
	// (e.g. with an injected session-memory user turn) that feeds the
	// summariser; the live history keeps the originals. Returning nil
	// is a no-op.
	OnBeforeCompact func(messages []api.Message) []api.Message

	// OnCompact is called once after each in-loop compaction round
	// that actually shrunk the message history. No-op compactions
	// (transcript too short) do not fire the callback.
	OnCompact func(CompactInfo)

	// OnContextCompactRetry fires when a model call was REJECTED for
	// exceeding the backend's real context window and the loop reacted by
	// force-compacting the history and retrying. afterMessages is the
	// post-compaction message count; targetTokens the budget it shrank to.
	// Lets the backend surface the recovery as an llm_retry event.
	OnContextCompactRetry func(attempt int, err error, afterMessages, targetTokens int)

	// Hooks, when non-nil, is consulted around tool execution and at
	// session end. PreToolUse fires before each Execute and may Block
	// (the tool returns a synthetic refusal). PostToolUse fires after
	// successful Execute, PostToolUseFailure fires on error. Stop
	// fires once when the generation loop exits (success or failure).
	Hooks *hooks.Runner

	// Inbox, when non-nil, plumbs the run's operator-message inbox
	// into the tool loop. After each tool-results turn the engine
	// calls Inbox.Consume (transitioning the previous round's
	// delivered messages to "consumed") and then Inbox.Drain
	// (returning new operator texts to append as a synthetic user
	// turn). Delivery is cooperative — between iterations, never
	// mid-stream — mirroring Claude Code CLI's queued-message
	// semantics. Nil disables the inbox plumbing.
	Inbox InboxHook

	// Permission, when enabled, is the tool-permission gate evaluated
	// before each tool executes (the anti-prompt-injection boundary).
	// Allow → execute; Deny → a synthetic refusal tool_result; Ask →
	// the loop aborts with a *delegate.ErrAskUser so the run pauses and
	// the human approves (claw's half of cross-backend parity with
	// claude_code's PreToolUse permission hook). Nil/disabled = no gate.
	Permission *permission.Policy
}

type GenerationTool struct {
	// Name is the tool identifier.
	Name string

	// Description describes what the tool does.
	Description string

	// InputSchema is the JSON schema for the tool's input parameters.
	InputSchema json.RawMessage

	// Execute runs the tool with the given JSON input and returns the result text.
	Execute func(ctx context.Context, input json.RawMessage) (string, error)
}

type InboxBinder interface {
	Bind(ctx context.Context, runID string) InboxHook
}

type InboxHook interface {
	Consume(ctx context.Context)
	Drain(ctx context.Context) []string
}

type KeyedProviderFactory func(modelID, apiKey string) (api.APIClient, error)

type LLMCompactInfo struct {
	BeforeMessages      int
	AfterMessages       int
	RemovedMessageCount int
	// Iteration is the 0-based loop iteration (see LLMRequestInfo.Iteration).
	Iteration int
}

type LLMRequestInfo struct {
	Model           string
	MessageCount    int
	ToolCount       int
	ReasoningEffort string
	Timestamp       time.Time
	// Iteration is the 0-based loop iteration the node is executing in,
	// threaded through by applyHooks. Drives the [node#iter/claw] console
	// tag so the studio's per-(node,iteration) Logs tab can associate the
	// line; without it every claw line stuck at #0 (the hook closures
	// captured a base context, not the live per-iteration one).
	Iteration int
}

type LLMResponseInfo struct {
	Latency          time.Duration
	InputTokens      int
	OutputTokens     int
	CacheReadTokens  int
	CacheWriteTokens int
	FinishReason     string
	Error            error
	StatusCode       int
}

type LLMStepInfo struct {
	Number           int
	Text             string
	ToolCalls        []ToolCallEntry
	FinishReason     string
	InputTokens      int
	OutputTokens     int
	CacheReadTokens  int
	CacheWriteTokens int
	// ReasoningTokens is an approximate count of extended-thinking tokens
	// (re-encoded from the thinking text); ThinkingMs is the wall-clock spent
	// in thinking blocks. Both are 0 when the step produced no thinking.
	ReasoningTokens int
	ThinkingMs      int
	// Thinking is the extended-thinking text for this step (empty when the
	// step produced no thinking).
	Thinking string
	// Iteration is the 0-based loop iteration (see LLMRequestInfo.Iteration).
	Iteration int
}

type LLMToolCallInfo struct {
	ToolName  string
	InputSize int
	// ToolUseID correlates this completion event with the matching
	// tool_started event. The studio merges the two by this id so the
	// post-execution event (duration + error) lines up with the
	// pre-execution event (structured input payload for whitelisted
	// tools). Empty when the path can't provide one — the merge then
	// falls through and the card renders with whatever data the
	// tool_called event alone carries.
	ToolUseID string
	// Output is the string the tool returned to the LLM. The hooks layer
	// truncates and persists it on the tool_called event so the studio's
	// per-node Tools tab can render in+out the way Claude Code does.
	// Empty when the backend can't surface a result (e.g. tool blocked
	// pre-execution by a lifecycle hook, unknown tool dispatch).
	Output   string
	Duration time.Duration
	Error    error
}

type LLMToolStartedInfo struct {
	ToolName  string
	InputSize int
	// ToolUseID correlates start↔completion when the same node fires
	// multiple parallel tool calls (e.g. claude_code's assistant message
	// with several tool_use blocks). Empty when the path can't provide
	// one (direct tool nodes, claw single tool loop).
	ToolUseID string
	// Input is the raw JSON arguments the LLM produced for this call.
	// May be empty when the backend cannot surface it. The hooks layer
	// persists it (truncated) on the tool_started event so the studio's
	// per-node Tools tab can render parameters (command, file_path,
	// todos, …) for every tool — symmetric with the post-execution
	// `output` field on LLMToolCallInfo.
	Input json.RawMessage
	// Iteration is the 0-based loop iteration of the node firing this
	// tool call (see LLMRequestInfo.Iteration). Populated so the plan-
	// capture hook can tag each TodoWrite snapshot with the pass it came
	// from; 0 for direct tool nodes / paths that don't carry one.
	Iteration int
}

type LLMTurnCaptureInfo struct {
	Step             int
	Text             string
	ToolCalls        []ToolCallEntry
	FinishReason     string
	InputTokens      int
	OutputTokens     int
	CacheReadTokens  int
	CacheWriteTokens int
	// Iteration is the 0-based loop iteration (see LLMRequestInfo.Iteration).
	// Threaded so TurnCheckpoint.LoopIter is correct — it previously came
	// from a stale captured context and was always 0.
	Iteration int
	// Backend names the executor that produced this turn ("claw" or
	// "claude_code"). Used by the store-backed hook to set the
	// matching TurnCheckpoint.Backend field. Empty defaults to "claw"
	// for back-compat with paths that don't fill it explicitly.
	Backend string
	// SessionID is the claude_code CLI session id captured at the end
	// of a delegate call. Empty for claw (no session-id concept) and
	// for claude_code paths that didn't surface one. The Fork API
	// passes it to `claude --resume <id> --fork-session` for the
	// claude_code rehydration path.
	SessionID string
	// contains filtered or unexported fields
}

type ModelCapabilities = llmtypes.ModelCapabilities

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

type NodeModelOverride struct {
	Backend  string
	Model    string
	Provider string
}

type NodeSessionStore = nodeSessionStore

type ObjectResult[T any] struct {
	// Object is the deserialized result.
	Object T

	// Text is the raw text that was parsed.
	Text string

	// Steps contains results from each generation step.
	Steps []StepResult

	// TotalUsage is the aggregated token usage across all steps.
	TotalUsage Usage

	// FinishReason indicates why generation stopped.
	FinishReason FinishReason
}

type PlanWriter interface {
	AppendPlanSnapshot(ctx context.Context, runID string, snap store.PlanSnapshot) (store.PlanSnapshot, bool, error)
}

type ProviderFactory func(modelID string) (api.APIClient, error)

type ProviderFallbackInfo struct {
	BackendName string // backend that ran the chain (e.g. "claude_code")
	From        string // provider hint that just failed ("" = auto)
	To          string // provider hint about to be tried next
	FromModel   string // effective model the failed provider ran (per-element override or node baseline)
	ToModel     string // effective model the next provider will run
	Attempts    int    // retry attempts spent on the failed provider
	Err         error  // the hard failure that triggered the fall-through
}

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

type RequestInfo struct {
	// Model is the model ID.
	Model string

	// MessageCount is the number of messages in the request.
	MessageCount int

	// ToolCount is the number of tools available.
	ToolCount int

	// ReasoningEffort is the resolved reasoning_effort spec sent on the
	// request, when set ("low", "medium", "high", "xhigh", "max"). Empty
	// when the node did not request a reasoning level.
	ReasoningEffort string

	// Timestamp is when the request was initiated.
	Timestamp time.Time
}

type ResolvedCapabilities struct {
	Provider      string           `json:"provider"`
	Model         string           `json:"model"`
	Spec          string           `json:"spec"`
	Source        CapabilitySource `json:"source"`
	Reasoning     bool             `json:"reasoning"`
	ToolCall      bool             `json:"tool_call"`
	Temperature   bool             `json:"temperature"`
	ContextWindow int              `json:"context_window"`
}

type ResponseInfo struct {
	// Latency is the time from request to response.
	Latency time.Duration

	// Usage is the token consumption for this call.
	Usage Usage

	// FinishReason indicates why generation stopped.
	FinishReason FinishReason

	// Error is non-nil if the call failed.
	Error error

	// StatusCode is the HTTP status code (0 if not applicable).
	StatusCode int
}

type RetryInfo struct {
	Attempt    int           // 1-based retry number (attempt 1 = first retry)
	Error      error         // the error that triggered this retry
	StatusCode int           // HTTP status code if available
	Delay      time.Duration // backoff delay before this retry
}

type RetryPolicy struct {
	// MaxAttempts is the total number of attempts (1 = no retry). Default: 3.
	MaxAttempts int
	// MaxAttemptsTransient is the attempt budget for connectivity/transient
	// failures (network blips, upstream 5xx). Default: 6. Falls back to
	// max(MaxAttempts, DefaultMaxAttemptsTransient) so it is never smaller
	// than the standard budget.
	MaxAttemptsTransient int
	// BackoffBase is the base delay for exponential backoff. Default: 1s.
	BackoffBase time.Duration
}

type ScreenshotDirective struct {
	Path       string
	URL        string
	ToolCallID string
}

type SessionCaptureSink interface {
	// Capture is called after the local store has saved the snapshot.
	// Implementations should not block — the caller is on the LLM
	// loop's hot path.
	Capture(runID, nodeID string, snapshot []byte)
}

type StepResult struct {
	// Number is the 1-based step index.
	Number int

	// Text generated in this step.
	Text string

	// ToolCalls requested in this step.
	ToolCalls []ToolCall

	// FinishReason for this step.
	FinishReason FinishReason

	// Usage for this step.
	Usage Usage

	// Thinking is the extended-thinking (reasoning) text produced during
	// this step; empty when the step produced no thinking.
	Thinking string
}

type StoreAsyncAskBinder struct {
	Store   store.RunStore
	Publish func(store.Event)
	// OnPosted, when set, is invoked after each successfully posted
	// question (e.g. to ring a notification surface). Optional.
	OnPosted func(runID, interactionID string)
}

type StoreInboxBinder struct {
	Store store.RunStore
	// Publish receives each user_message_* event after store-side
	// persistence. Local mode passes EventBroker.Publish; cloud mode
	// passes nil (the Mongo change-stream surfaces transitions).
	Publish func(store.Event)
}

type TemplateData struct {
	// Outputs is the per-node output map. Keys are node IDs.
	Outputs map[string]map[string]any

	// LoopCounters is the current iteration count per loop name
	// (1-indexed once incremented by the engine).
	LoopCounters map[string]int

	// LoopMaxIterations is the declared `as <name>(N)` upper bound
	// per loop name, sourced from ir.Workflow.Loops.
	LoopMaxIterations map[string]int

	// LoopPreviousOutput is the snapshot of the source node's output
	// at the previous traversal of each loop's edge — i.e. one
	// iteration behind the current one. Nil on the first iteration.
	LoopPreviousOutput map[string]map[string]any

	// Artifacts is the publish-name → output map for artifacts that
	// have been produced so far in this run.
	Artifacts map[string]map[string]any

	// RunID is the current run identifier, exposed to prompts as
	// `{{run.id}}`.
	RunID string

	// Attachments maps the workflow's attachment names to their
	// resolved per-run metadata. Populated from Run.Attachments at
	// the start of every node execution. Resolvers expose:
	//
	//	{{attachments.<name>}}        → host filesystem path
	//	{{attachments.<name>.path}}   → host filesystem path (explicit)
	//	{{attachments.<name>.url}}    → presigned URL (lazy: filled on demand)
	//	{{attachments.<name>.mime}}   → sniffed MIME
	//	{{attachments.<name>.size}}   → byte length as decimal string
	//	{{attachments.<name>.sha256}} → hex SHA-256
	Attachments map[string]AttachmentInfo
}

type TextResult struct {
	// Text is the accumulated generated text.
	Text string

	// ToolCalls requested by the model in the final step.
	ToolCalls []ToolCall

	// Steps contains results from each generation step.
	Steps []StepResult

	// TotalUsage is the aggregated token usage across all steps.
	TotalUsage Usage

	// FinishReason indicates why generation stopped.
	FinishReason FinishReason

	// Messages is the final accumulated conversation list, including
	// the initial input plus every assistant turn (with tool_use
	// blocks) and tool_result message produced during the loop. Hosts
	// that maintain a per-node session — e.g. for compaction-aware
	// retries — capture this slice and feed it back as opts.Messages
	// on the next attempt.
	Messages []api.Message
}

type ToolBlobWriter interface {
	WriteToolBlob(ctx context.Context, runID, toolUseID, kind string, body []byte) (int64, error)
}

type ToolCall struct {
	// ID is a unique identifier for this tool call.
	ID string

	// Name of the tool to invoke.
	Name string

	// Input is the JSON-encoded arguments.
	Input json.RawMessage
}

type ToolCallEntry struct {
	Name  string
	Input json.RawMessage
}

type ToolCallInfo struct {
	// ToolName is the name of the tool that was called.
	ToolName string

	// InputSize is the byte length of the tool input JSON.
	InputSize int

	// ToolUseID correlates start↔completion when multiple parallel tool
	// calls share a node. Populated for OnToolStarted; the post-execution
	// OnToolCall path leaves it empty (existing callers don't need it).
	ToolUseID string

	// Input is the raw JSON arguments passed to the tool. Populated for
	// OnToolStarted so observers can render the tool's target (URL, file
	// path, query, …) and persist structured input for whitelisted tools.
	// Empty on the post-execution OnToolCall path to avoid duplicating
	// payloads in events.jsonl.
	Input json.RawMessage

	// Output is the string the tool returned to the LLM. Populated only on
	// the post-execution OnToolCall path; empty on OnToolStarted. The
	// hooks layer persists it (truncated) on the tool_called event so the
	// studio's per-node Tools tab can render the in/out pair the way
	// Claude Code does.
	Output string

	// Duration is how long the tool execution took.
	Duration time.Duration

	// Error is non-nil if the tool execution failed.
	Error error
}

type TurnCaptureInfo struct {
	// Step is the 1-based step index, matching StepResult.Number.
	Step int
	// Result mirrors the StepResult passed to OnStepFinish.
	Result StepResult
	// Conversation is the snapshot the runtime persists. Treat as
	// immutable — the generation loop reuses the underlying slice
	// after the callback returns. Callbacks that hand the snapshot
	// off to a goroutine MUST take their own copy first (the
	// generation loop already does so before invoking the hook).
	Conversation []api.Message
}

type TurnWriter interface {
	WriteTurn(ctx context.Context, t *store.TurnCheckpoint) error
}

type Usage struct {
	InputTokens      int
	OutputTokens     int
	TotalTokens      int
	ReasoningTokens  int // approximate count of extended-thinking tokens (re-encoded text)
	CacheReadTokens  int
	CacheWriteTokens int
	ThinkingMs       int // wall-clock spent in thinking blocks, milliseconds
}