agent

type Agent struct {
	*Config

	// Events is the canonical append-only runtime ledger. Messages is its
	// materialized conversation projection and remains exported for source
	// compatibility; provider context is maintained separately.
	Events   []RuntimeEvent
	Messages []Message
	Usage    Usage
	Revision uint64

	// Recorder is instance-scoped on purpose: derived subagent configs must not
	// accidentally append child events to their parent's journal.
	Recorder EventRecorder

	ContextRevision uint64
	// contains filtered or unexported fields
}

type Config struct {

	// Telemetry instruments agent, model, and tool operations. DefaultConfig
	// initializes it when standard OTEL exporter variables are present. Library
	// callers may inject a separately configured pipeline instead.
	Telemetry *telemetry.Telemetry

	Model        func() string
	Effort       func() string
	Tools        func() []tool.Tool
	Instructions func() string

	// RoleModel resolves "main", "plan", and "utility" role models. An empty
	// role names the currently inherited model and is used for effort clamping.
	// ok=false or an empty ID keeps the inherited model. Nil disables role
	// overrides.
	RoleModel 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

	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 EventRecorder interface {
	AppendEvents(events []RuntimeEvent) error
}

type EventRecorderFunc func(events []RuntimeEvent) error

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

type GenerateOptions struct {
	Model           string
	Effort          string
	Instructions    string
	Input           string
	OutputSchema    map[string]any
	MaxOutputTokens int64
}

type GenerateResult struct {
	Text  string
	Usage Usage
}

type Message struct {
	InputID string      `json:"input_id,omitempty"`
	Role    MessageRole `json:"role"`

	// Phase distinguishes assistant progress updates from final answers and
	// must survive persistence and replay in subsequent provider requests.
	Phase MessagePhase `json:"phase,omitempty"`

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

type MessagePhase string

type MessageRole string

type ModelInfo struct {
	ID string
}

type ModelOption struct {
	ID      string
	Efforts []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 RuntimeEvent struct {
	Sequence uint64           `json:"sequence"`
	ID       string           `json:"id"`
	Type     RuntimeEventType `json:"type"`
	At       time.Time        `json:"at"`

	TurnID      string `json:"turn_id,omitempty"`
	RunID       string `json:"run_id,omitempty"`
	OperationID string `json:"operation_id,omitempty"`
	Model       string `json:"model,omitempty"`

	Message       *Message         `json:"message,omitempty"`
	Context       []Message        `json:"context,omitempty"`
	ContextReason string           `json:"context_reason,omitempty"`
	Usage         *Usage           `json:"usage,omitempty"`
	Terminal      *RuntimeTerminal `json:"terminal,omitempty"`
	Tool          *RuntimeTool     `json:"tool,omitempty"`
}

type RuntimeEventType string

type RuntimeStatus string

type RuntimeTerminal struct {
	Status           RuntimeStatus `json:"status"`
	Error            string        `json:"error,omitempty"`
	OutcomeUncertain bool          `json:"outcome_uncertain,omitempty"`
}

type RuntimeTool struct {
	CallID  string `json:"call_id,omitempty"`
	Name    string `json:"name"`
	Args    string `json:"args,omitempty"`
	Effect  string `json:"effect,omitempty"`
	IsError bool   `json:"is_error,omitempty"`
}

type State struct {
	Events          []RuntimeEvent `json:"events,omitempty"`
	Usage           Usage          `json:"usage"`
	Messages        []Message      `json:"messages,omitempty"`
	Context         []Message      `json:"context,omitempty"`
	ContextSet      bool           `json:"context_set,omitempty"`
	Revision        uint64         `json:"-"`
	ContextRevision uint64         `json:"context_revision,omitempty"`
}

type StreamEvent uint8

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

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

	Name         string            `json:"name"`
	Kind         string            `json:"kind,omitempty"`
	Args         string            `json:"args,omitempty"`
	Locations    []ToolLocation    `json:"locations,omitempty"`
	Presentation *ToolPresentation `json:"presentation,omitempty"`

	Partial bool `json:"partial,omitempty"`
}

type ToolLocation struct {
	Path string `json:"path"`
	Line int    `json:"line,omitempty"`
}

type ToolPresentation struct {
	Title     string         `json:"title"`
	Kind      string         `json:"kind,omitempty"`
	Args      string         `json:"args,omitempty"`
	Hint      string         `json:"hint,omitempty"`
	Locations []ToolLocation `json:"locations,omitempty"`
}

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

	Name         string            `json:"name"`
	Kind         string            `json:"kind,omitempty"`
	Args         string            `json:"args,omitempty"`
	Locations    []ToolLocation    `json:"locations,omitempty"`
	Presentation *ToolPresentation `json:"presentation,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 and OutputTokens are inclusive totals. Cache reads and cache
	// creation are subsets of InputTokens; reasoning is a subset of
	// OutputTokens. The JSON names retain session compatibility with earlier
	// versions of wingman-agent.
	InputTokens  int64 `json:"input_tokens"`
	OutputTokens int64 `json:"output_tokens"`

	ReasoningTokens int64 `json:"reasoning_tokens,omitempty"`

	CacheReadInputTokens     int64 `json:"cached_tokens"`
	CacheCreationInputTokens int64 `json:"cache_write_tokens,omitempty"`

	// 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"`
}