agent

type Agent struct {
	*Config

	Messages []Message
	Usage    Usage
	Revision uint64
	// contains filtered or unexported fields
}

type Config struct {
	Model        func() string
	Effort       func() string
	Tools        func() []tool.Tool
	Instructions func() string

	// UtilityModel, when set and non-empty, handles internal utility calls
	// (compaction summaries, recaps) instead of the main model.
	UtilityModel func() string

	// SubagentModel resolves a model role for per-subagent overrides: "plan"
	// and "utility" name the session's role models, "" the currently
	// inherited model (consulted for effort clamping). ok=false or an empty
	// ID keep the inherited model. Nil disables overrides and clamping.
	SubagentModel func(role string) (ModelOption, bool)

	// CacheKey routes provider-side prompt caching; keep it stable per
	// conversation (e.g. the session ID) to maximize prefix-cache hits.
	CacheKey string

	Hooks hook.Hooks

	// MaxTurns caps successful model invocations in one Send run. Stream
	// retries and tool calls do not consume turns. Zero uses the default;
	// negative disables the safety bound.
	MaxTurns int

	// MaxParallelTools bounds concurrently executing read-only tool calls.
	// Zero uses the default; negative allows the whole emitted batch.
	MaxParallelTools int

	// ToolTimeout is a hard ceiling on every tool call. When zero, tools may
	// extend the default via tool.Tool.Timeout; negative disables deadlines.
	ToolTimeout time.Duration

	ContextWindow int

	// LargeContext compacts against the model's full hardware window instead
	// of stopping at the provider's long-context price threshold (e.g. 2x
	// input pricing on GPT-5.4/5.5 beyond 272k input tokens).
	LargeContext bool

	ReserveTokens int
	// contains filtered or unexported fields
}

type Content struct {
	Text string `json:"text,omitempty"`
	// TextID is source-local identity used to reconcile streamed and retained
	// UI content. It is metadata, not a provider payload to replay in requests.
	TextID string `json:"text_id,omitempty"`

	Refusal string `json:"refusal,omitempty"`

	// Hidden marks injected context (e.g. background-task notifications) that
	// the model must see but UIs must not render as user input. A user message
	// whose content is entirely hidden becomes a hidden message.
	Hidden bool `json:"hidden,omitempty"`

	File *File `json:"file,omitempty"`

	Reasoning *Reasoning `json:"reasoning,omitempty"`

	ToolCall   *ToolCall   `json:"tool_call,omitempty"`
	ToolResult *ToolResult `json:"tool_result,omitempty"`
}

type ContextStats struct {
	Model  string
	Window int

	InstructionsTokens int
	ToolsTokens        int
	ToolStats          []ToolStat
	MessagesTokens     int
	MessageCount       int

	LastInputTokens int64
}

type File struct {
	Name string `json:"name,omitempty"`
	Data string `json:"data,omitempty"`
}

type Message struct {
	Role MessageRole `json:"role"`

	Content []Content `json:"content"`
	Hidden  bool      `json:"hidden,omitempty"`
}

type MessageRole string

type ModelInfo struct {
	ID string
}

type ModelOption struct {
	ID        string
	MinEffort string
	MaxEffort string
}

type Reasoning struct {
	ID string `json:"id,omitempty"`

	Summary string `json:"summary,omitempty"`

	// Part indexes the summary part a streamed delta belongs to; renderers
	// separate parts however suits their medium.
	Part int `json:"part,omitempty"`

	// Content is the provider's opaque (encrypted) reasoning payload, only
	// replayable to the model that produced it. Model tags the producer so the
	// agent loop can purge stale payloads when the session model changes.
	Content string `json:"content,omitempty"`
	Model   string `json:"model,omitempty"`
}

type State struct {
	Usage    Usage     `json:"usage"`
	Messages []Message `json:"messages,omitempty"`
	Revision uint64    `json:"-"`
}

type StreamEvent uint8

type StreamEventHandlers struct {
	Reset  func()
	Commit func()
}

type ToolCall struct {
	ID string `json:"id"`

	Name string `json:"name"`
	Args string `json:"args,omitempty"`
}

type ToolResult struct {
	ID string `json:"id,omitempty"`

	Name string `json:"name"`
	Args string `json:"args,omitempty"`

	Content  string         `json:"content,omitempty"`
	IsError  bool           `json:"is_error,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type ToolStat struct {
	Name   string
	Tokens int
}

type Usage struct {
	InputTokens  int64 `json:"input_tokens"`
	CachedTokens int64 `json:"cached_tokens"`
	OutputTokens int64 `json:"output_tokens"`

	// LastInputTokens is the input size of the most recent request — the
	// current context occupancy, unlike the cumulative counters above.
	LastInputTokens int64 `json:"last_input_tokens,omitempty"`
	// ContextWindow is the provider-reported maximum context size when the
	// transport supplies it directly.
	ContextWindow int64 `json:"context_window,omitempty"`
}