core

type API string

type AfterToolCall func(ctx context.Context, in AfterToolCallContext) AfterToolCallDecision

type AfterToolCallContext struct {
	ToolName  string
	ToolUseID string
	// ParentToolUseID and ParentToolName are as in BeforeToolCallContext.
	ParentToolUseID string
	ParentToolName  string
	Arguments       map[string]any
	Result          *ToolResultMessage // mutable in place
	Elapsed         time.Duration
	// ToolResult is the handler's result as returned, after panic and
	// Handler-error conversion, passed by value. It is read-only: changing
	// it (or anything reached through its Metadata pointer) has no effect
	// on the emitted, persisted or stop-policy message. Result remains the
	// one mutable record and already carries Metadata.
	ToolResult ToolResult
}

type AfterToolCallDecision struct {
	// Terminate is *bool because nil means "no opinion".
	Terminate *bool
}

type AgentDoneEvent struct {
	Result RunResult
	Usage  Usage // session aggregate
}

type AgentStartEvent struct {
	SessionID string
	Provider  string
	API       API
	Model     string
}

type AssistantMessage struct {
	Content Content

	// StopReason is the canonical enum; RawStopReason is the provider's own
	// finish string, verbatim. Neither may be read by the continuation check
	// — use ExtractToolUse.
	StopReason    StopReason
	RawStopReason string
	// StopDetail is the provider's own account of why it stopped, when it
	// gives one beyond the reason — a refusal's category and explanation
	// ("cyber: …"). Like RawStopReason it never drives control flow.
	StopDetail   string
	ErrorMessage string
	Usage        Usage
	Timestamp    time.Time

	// Model is the REQUESTED model, never ResponseModel: transcript repair
	// replays a turn's thinking signatures only to the model that issued
	// them, and a fallback-served turn judged against ResponseModel would
	// have its own valid signatures stripped.
	Model         string
	ResponseModel string
	ResponseID    string
	// Effort is the thinking effort the turn was requested with.
	Effort Effort
}

type BeforeToolCall func(ctx context.Context, in BeforeToolCallContext) BeforeToolCallDecision

type BeforeToolCallContext struct {
	ToolName  string
	ToolUseID string
	// ParentToolUseID and ParentToolName identify the wrapper call that made
	// this call through CallNested. Both are empty for a call the model made
	// directly.
	ParentToolUseID string
	ParentToolName  string
	Tool            Tool
	Arguments       map[string]any
	// RawInput is the model's own bytes, key order intact.
	RawInput  json.RawMessage
	Assistant *AssistantMessage
	Batch     []ToolUseBlock
	Index     int
	TurnCount int
}

type BeforeToolCallDecision struct {
	Block bool
	// Terminate is honoured ONLY when Block is set.
	Terminate bool
	Reason    string
	// Arguments, when non-nil, replaces Arguments. The interceptor may widen
	// as well as narrow.
	Arguments map[string]any
}

type BlockType string

type CacheRetention string

type Content []ContentBlock

type ContentBlock interface {
	BlockType() BlockType
	CloneBlock() ContentBlock
	// contains filtered or unexported methods
}

type Effort string

type ErrorEvent struct {
	Message string
	// Err is not serialized; the wire form carries Message.
	Err      error
	Terminal bool
}

type Event interface {
	EventType() EventType
	Class() EventClass
	// contains filtered or unexported methods
}

type EventClass uint8

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

type EventType string

type ExecutionMode uint8

type Message interface {
	Role() Role
	Clone() Message
	// contains filtered or unexported methods
}

type MessageEncoder func(Message) (json.RawMessage, error)

type MessageEndEvent struct{ Message AssistantMessage }

type MessageStartEvent struct{ Message AssistantMessage }

type MessageUpdateEvent struct{ Message AssistantMessage }

type Messages []Message

type Model struct {
	ID              string
	ContextWindow   int
	MaxOutputTokens int

	InputCostPerMillion      float64
	OutputCostPerMillion     float64
	CacheReadCostPerMillion  float64
	CacheWriteCostPerMillion float64

	// ThinkingKind is how the model takes extended thinking.
	ThinkingKind ThinkingKind
	// Efforts is the wire value of each effort the model takes: a token
	// budget on a budget model, an effort name on an adaptive one. With a map,
	// an effort absent from it (or nil) is not sent; with no map at all, the
	// effort is sent by its own name.
	Efforts map[Effort]*string
	// Compat is the catalog row's capability object, as JSON (for example
	// {"supports_sampling": false}).
	Compat json.RawMessage
}

type NestedCaller interface {
	Call(ctx context.Context, calls ...ToolUseBlock) ([]ToolResult, error)
}

type NoToolsMode string

type PreparedArguments struct {
	Raw  json.RawMessage
	Args map[string]any

	// Coercions records what step 3 changed, for diagnostics.
	Coercions []schema.Coercion
}

type ProviderClient interface {
	Stream(ctx context.Context, req Request) (<-chan StreamEvent, error)
}

type Request struct {
	System []ContentBlock
	// Prefix is sent after the system prompt and before Messages on every
	// request, with a cache breakpoint on its last block.
	Prefix   Messages
	Messages Messages
	// Tools is []ToolWire, not []Tool, so no provider can reach a handler or
	// any other field a request body must not carry.
	Tools         []ToolWire
	ToolChoice    ToolChoice
	MaxTokens     *int     // upper bound; capped at the model's output cap
	Temperature   *float64 // nil is absent; an explicit 0 is sent
	TopP          *float64
	StopSequences []string
	// Effort is the thinking effort; empty sends none.
	Effort Effort
}

type ResultHandler func(ctx context.Context, input json.RawMessage) ToolResult

type Role string

type RunResult struct {
	Messages   Messages
	StopReason RunStopReason
	// LastReason is the final assistant message's canonical reason, kept
	// because RunStopReason and StopReason are different vocabularies.
	LastReason StopReason
	Usage      Usage
	TurnCount  int
	Error      error
}

type RunStopReason string

type StopReason string

type StreamEvent struct {
	Event Event
	Err   error
}

type StreamOptions struct {
	// MaxPendingBytes bounds queued-but-unread payload. Zero is unbounded (the
	// default). A non-zero value below MinMaxPendingBytes is raised to it.
	// Exceeding it drops the CONSUMER (Next returns false, Err returns
	// ErrStreamOverrun) and lets the run finish with the result still
	// available — it never drops events.
	MaxPendingBytes int64
}

type StreamResult struct {
	// Message is non-nil once the stream has ended, always — including on a
	// pre-flight failure: partial content plus the failure must be one value.
	Message *AssistantMessage
	// Result is set on agent-level streams and nil on provider-level ones.
	Result *RunResult
	Err    error
}

type TextBlock struct{ Text string }

type TextDeltaEvent struct {
	BlockIndex int
	Delta      string
}

type TextEndEvent struct {
	BlockIndex int
	Text       string
}

type TextStartEvent struct{ BlockIndex int }

type ThinkingBlock struct {
	Thinking string
	// Signature is provider-issued and opaque; it may be empty on an aborted
	// stream, and transcript repair downgrades an unsigned block to text.
	// Never inspected.
	Signature string
	Redacted  bool
}

type ThinkingDeltaEvent struct {
	BlockIndex int
	Delta      string
}

type ThinkingEndEvent struct {
	BlockIndex int
	Thinking   string
	Signature  string
	Redacted   bool
}

type ThinkingKind string

type ThinkingStartEvent struct{ BlockIndex int }

type Tool struct {
	Name        string
	Description string
	InputSchema *schema.Schema
	// OutputSchema describes ToolResult.Data on success, for programmatic
	// callers (a script runner binding results, a wrapper tool, generated
	// documentation). It is optional and never enforced at runtime: a nil
	// schema means the tool makes no promise. It is NOT part of ToolWire, so
	// no provider request body carries it.
	OutputSchema *schema.Schema

	// ReachableTools are the tools this tool can call on the model's behalf
	// through CallNested — a wrapper such as a script runner. A tool that
	// declares none reaches none. Every call it makes goes through the same
	// interceptor, audit and event pipeline as a direct call, and only to a
	// tool listed here (after ToolPolicy filtering). Not part of ToolWire.
	ReachableTools []Tool
	// Terminating marks a tool whose purpose is to end the run (finish,
	// submit_answer). No wrapper may reach one: a run ends on a decision the
	// model or the embedder made, never on one a wrapper made for it. Not
	// part of ToolWire.
	Terminating bool

	Handler ToolHandler
	Execute ResultHandler

	Label string // display name, never sent
	// Builtin marks a first-party tool. It exists so ToolPolicy.NoTools can
	// mean "builtin" without the resolver keeping a hardcoded name list that
	// silently stops matching when a tool is renamed.
	Builtin          bool
	ExecutionMode    ExecutionMode
	PrepareArguments func(map[string]any) map[string]any
	PromptGuidelines []string
}

type ToolCallEndEvent struct {
	BlockIndex int
	Block      ToolUseBlock
}

type ToolCallStartEvent struct {
	BlockIndex int
	ToolUseID  string
	Name       string
}

type ToolChoice string

type ToolExecutionEndEvent struct {
	ToolUseID       string
	Name            string
	Result          Content
	IsError         bool
	ElapsedMS       int64
	ParentToolUseID string
}

type ToolExecutionStartEvent struct {
	ToolUseID       string
	Name            string
	ParentToolUseID string
}

type ToolExecutionUpdateEvent struct {
	ToolUseID       string
	Name            string
	Chunk           string
	ParentToolUseID string
}

type ToolHandler func(ctx context.Context, input json.RawMessage) (json.RawMessage, error)

type ToolInputDeltaEvent struct {
	BlockIndex int
	ToolUseID  string
	Delta      string // partial argument JSON, as received
}

type ToolMetadata struct {
	Truncated   bool   `json:"truncated,omitzero"`
	TruncatedBy string `json:"truncated_by,omitzero"` // "lines" | "bytes"
	TotalBytes  int64  `json:"total_bytes,omitzero"`
	TotalLines  int64  `json:"total_lines,omitzero"`
	SpillPath   string `json:"spill_path,omitzero"`
	DurationMS  int64  `json:"duration_ms,omitzero"`
	ExitCode    *int   `json:"exit_code,omitzero"`
	Outcome     string `json:"outcome,omitzero"` // ok|exit|signal|timeout|abort
	LineEnding  string `json:"line_ending,omitzero"`
}

type ToolPolicy struct {
	// Tools, when non-nil (INCLUDING empty), is used verbatim and bypasses
	// everything below. Non-nil-but-empty is distinct from nil.
	Tools        []Tool
	ToolNames    []string // nil means the default built-in set
	ExcludeTools []string
	NoTools      NoToolsMode
	CustomTools  []Tool
}

type ToolResult struct {
	OK     bool           `json:"ok"`
	Data   map[string]any `json:"data"`
	Error  string         `json:"error,omitzero"`
	Detail string         `json:"detail,omitzero"`
	// Terminate never reaches the model; it is this result's vote to end the
	// run (see BatchTerminates).
	Terminate bool          `json:"-"`
	Metadata  *ToolMetadata `json:"metadata,omitzero"`
	// Blocks are extra content blocks appended after the text the model
	// reads, each its own block in the result.
	Blocks []ContentBlock `json:"-"`

	// Text is the MODEL-FACING rendering of the result. When non-empty it is
	// the text block the model reads, verbatim, in place of the JSON envelope;
	// Data, Error and Detail stay populated for programmatic consumers
	// (interceptors, the audit trail, an MCP server bridging the tool) and are
	// unaffected.
	//
	// It exists because the envelope is the wrong shape for the results that
	// dominate an agent's context. A source file inside a JSON string pays for
	// every newline, tab and quote twice (`\n`, `\t`, `\"`) — 9–13% more
	// bytes and, because escape sequences tokenize badly, an estimated 15–30%
	// more tokens on indented code — and the model reads code through a layer
	// of escaping it then has to undo when it writes an edit. Every built-in
	// tool sets Text on success; an error result leaves it empty and the
	// envelope is used.
	Text string `json:"-"`
}

type ToolResultEvent struct{ Message ToolResultMessage }

type ToolResultMessage struct {
	ToolUseID string
	ToolName  string
	Content   Content
	IsError   bool
	Timestamp time.Time
	// AddedToolNames marks tools that became available at this point in the
	// transcript. Opaque to the loop.
	AddedToolNames []string
	Usage          *Usage // optional; a pointer, never omitempty
	// Metadata is the producing handler's structured metadata (exit code,
	// outcome, truncation, spill path, totals, duration, line ending).
	// Persisted by the session codec, never sent to a provider. Nil for
	// handler-less results (unknown tool, invalid arguments, blocked,
	// aborted, max_tokens synthesis, repair synthesis).
	Metadata *ToolMetadata
}

type ToolUseBlock struct {
	ID   string
	Name string
	// Input is the provider's own argument bytes, verbatim and AUTHORITATIVE
	// for every replay, fingerprint and serialization path.
	// Invariant: always syntactically valid JSON object bytes; NewToolUse
	// normalizes nil/empty to {}.
	Input json.RawMessage
	// ThoughtSignature is opaque and provider-issued; transcript repair strips
	// it on cross-model replay. Never inspected.
	ThoughtSignature string
}

type ToolWire struct {
	Name        string
	Description string
	InputSchema *schema.Schema
}

type TurnEndEvent struct {
	TurnIndex int
	Message   AssistantMessage
	// ToolResults is always non-nil; [] for a no-tool turn.
	ToolResults []ToolResultMessage
	Usage       Usage
}

type TurnStartEvent struct{ TurnIndex int }

type Usage struct {
	// InputTokens is NET of cache reads and writes.
	InputTokens  int64
	OutputTokens int64
	// ReasoningTokens is a SUBSET of OutputTokens, not an addend.
	ReasoningTokens  int64
	CacheReadTokens  int64
	CacheWriteTokens int64
	// CacheWrite1hTokens is a SUBSET of CacheWriteTokens.
	CacheWrite1hTokens int64
	TotalTokens        int64
	// Requests is how many model requests the usage covers.
	Requests int64
	CostUSD  float64
	// BilledModel is the model that actually served the request.
	BilledModel string
	// Unpriced is true when at least one request the usage covers had a cost
	// that neither the vendor reported nor the catalog priced, so CostUSD
	// counts that request as zero. The cost bit cannot say this: Add ORs it.
	Unpriced bool

	// Set records which fields the provider actually reported, so an explicit
	// 0 beats an SDK fallback and a wholly unreported usage is
	// distinguishable from a reported all-zero one.
	Set UsageField
}

type UsageField uint32

type UsageJSON struct {
	InputTokens        int64   `json:"input_tokens"`
	OutputTokens       int64   `json:"output_tokens"`
	ReasoningTokens    int64   `json:"reasoning_tokens"`
	CacheReadTokens    int64   `json:"cache_read_tokens"`
	CacheWriteTokens   int64   `json:"cache_write_tokens"`
	CacheWrite1hTokens int64   `json:"cache_write_1h_tokens"`
	TotalTokens        int64   `json:"total_tokens"`
	CostUSD            float64 `json:"cost_usd"`
	BilledModel        string  `json:"billed_model"`
	Reported           bool    `json:"reported"`
	Unpriced           bool    `json:"unpriced"`
}

type UsageWire struct {
	InputTokens        *int64
	OutputTokens       *int64
	ReasoningTokens    *int64
	CacheReadTokens    *int64
	CacheWriteTokens   *int64
	CacheWrite1hTokens *int64
	TotalTokens        *int64
}

type UserMessage struct {
	Content   Content
	Timestamp time.Time
}