bridle

type AfterToolCallCtx struct {
	Call   ToolCall
	Result ToolCallResult
	Step   int
}

type BeforeModelCallCtx struct {
	Request *ProviderRequest
	Step    int
}

type BeforeToolCallCtx struct {
	Call ToolCall
	Step int

	// Deny, when set true by a BeforeToolCall hook, tells the harness to
	// SKIP executing this tool call and instead return Result/Err as the
	// tool_result, then continue the loop so the model can react. Use this
	// (with a returned HookContinue) for per-call permission denials —
	// HookAbort ends the whole turn, which is not what a single-call
	// denial wants. Defaults false: existing hooks are unaffected.
	Deny bool
	// Result is the tool_result JSON payload to hand back when Deny is
	// set. nil is treated as JSON null. Ignored unless Deny is true.
	Result json.RawMessage
	// Err, when non-empty and Deny is set, marks the tool_result as an
	// error string the model sees (mirrors a runner.Run error). Ignored
	// unless Deny is true.
	Err string
}

type ContextBudgetWarning struct {
	Assembled int       // estimated assembled-prompt token count
	Budget    int       // the ContextPolicy.PromptBudget that was met/exceeded
	TS        time.Time // stamped by the harness at emission; zero outside a harness turn
}

type ContextPolicy struct {
	// TargetWindow is the desired context window in tokens. 0 = no
	// preference (engine default / model-fixed window). Providers with a
	// per-request window knob (ollama num_ctx) map this; fixed-window
	// providers no-op it.
	TargetWindow int

	// PromptBudget is a soft cap, in tokens, on the assembled prompt
	// before bridle warns. 0 = no budget (no warning ever). Honored by
	// ALL providers — the warning is computed at the harness seam, not
	// in the provider.
	PromptBudget int
}

type DoneEvent struct{ StopReason StreamStopReason }

type ErrorClass string

type ErrorEvent struct {
	Class ErrorClass
	Err   error
}

type Event interface {
	// contains filtered or unexported methods
}

type EventSink interface {
	Emit(Event)
}

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

type Hook[T any] func(ctx context.Context, in T) (T, HookAction, error)

type HookAction int

type HookID uint64

type InboxItem struct {
	From    string
	Content string
	MsgID   int64
	RawJSON json.RawMessage

	// ThreadRoot is the canonical thread identity for the message
	// (linked-list root id; nexus task #226). The funnel uses it to
	// key per-thread session state so each thread gets its own
	// claude-code jsonl, preventing SessionTail bleed across threads.
	// Zero = legacy/non-chat synthetic item or pre-#226 row.
	ThreadRoot int64

	// Source identifies which trigger channel produced this item.
	// Empty defaults to "chat" (legacy / nexus-chat substrate).
	// agora-side callers set Source="tty" for operator-typed inputs,
	// allowing ReturnHandlers to branch routing (chat → bus reply,
	// tty → panel-only). Future trigger channels add new Source
	// values; consumers default-treat unknown values as "chat" for
	// backward compat.
	Source string
}

type JSONSchema struct {
	Name        string
	Description string
	Schema      json.RawMessage
	Strict      bool
}

type LaneID string

type MCPClientConfig struct {
	Servers []MCPServerSpec
}

type MCPServerFailed struct {
	Server string
	Err    error
	TS     time.Time // stamped by the harness at emission; zero outside a harness turn
}

type MCPServerSpec struct {
	Name      string            // local identifier, used in tool-call provenance
	Transport MCPTransport      // stdio | http_sse
	Command   []string          // argv to spawn the server (stdio only)
	URL       string            // server URL (http_sse only)
	Env       map[string]string // environment variables for spawned server (stdio only)
	Header    map[string]string // request headers (http_sse only)
}

type MCPTransport string

type MessageRole string

type ModelCapabilities struct {
	Tools            bool
	ParallelTools    bool
	Streaming        bool
	ReasoningEffort  bool
	StructuredOutput bool
	PromptCaching    bool
	Vision           bool

	// SystemPromptMode advertises which system-prompt application mode
	// this catalog row was authored against: SystemPromptFull ("full",
	// alias of Replace) or SystemPromptAppend ("append"). claude-code
	// genuinely supports BOTH — the catalog row's "append" is an
	// ADVISORY default recording agora policy (preserve claude-code's
	// built-in prompt), not a hard capability gate. Callers may still
	// pass either mode on TurnRequest/ProviderRequest; this field only
	// documents the lane's typical/recommended choice.
	SystemPromptMode SystemPromptMode
}

type ModelChunk struct {
	Text string
	TS   time.Time // stamped by the harness at emission; zero outside a harness turn
}

type ModelHandle struct {
	Lane     string
	Provider ProviderID
	Model    string
	Info     ModelInfo
}

type ModelInfo struct {
	ID              string
	Lane            LaneID
	Provider        ProviderID
	Aliases         []string
	ContextWindow   int // tokens — required; the skills 2% catalog budget + context-manager depend on it
	MaxOutputTokens int
	Capabilities    ModelCapabilities
	Pricing         *ModelPricing    // nil = unknown/unset
	Prompt          *ModelPromptMeta // nil = no prompt-presentation metadata authored yet
}

type ModelPricing struct {
	In     float64
	Out    float64
	Cached float64
}

type ModelPromptMeta struct {
	Dialect      *PromptDialect
	RenditionRef string
}

type NormalizedSessionEvent struct {
	Role    SessionRole
	Content string // human-readable text representation
}

type OnStepBoundaryCtx struct {
	Step int
}

type OnTurnDoneCtx struct {
	Result *TurnResult
}

type PromptDialect struct {
	ToolIdiom string
	Format    string
	Thinking  string
}

type Provider interface {
	Name() ProviderID
	Capabilities() ProviderCapabilities
	RunTurn(ctx context.Context, req ProviderRequest, sink EventSink) (ProviderResult, error)
}

type ProviderCapabilities struct {
	Category               ProviderCategory
	SupportsCustomTools    bool // funnel can pass arbitrary Tools via TurnRequest
	SupportsBeforeToolCall bool // BeforeToolCall hook fires
	SupportsAfterToolCall  bool // AfterToolCall hook fires
	SupportsMCP            bool // provider consumes TurnRequest.MCP (direct-api only)
}

type ProviderCategory string

type ProviderError struct {
	Kind    ProviderErrorKind
	Message string
	Err     error // underlying error (may be nil)
}

type ProviderErrorKind string

type ProviderID string

type ProviderMessage struct {
	Role       string // "user" | "assistant" | "tool_result" | "system"
	Content    string
	ToolCallID string           // links a tool_result back to the call that produced it
	ToolName   string           // function-declaration name; required for tool_result on Gemini
	ToolCalls  []ToolInvocation // tool_use blocks for assistant turns; nil on other roles

	// ThinkingBlocks (NEX-320) preserves Claude extended-thinking
	// content blocks across turns. Required by the Anthropic API:
	// subsequent turns whose conversation history is missing the
	// thinking blocks from prior assistant turns get rejected with
	// 400 ("content[].thinking in the thinking mode must be passed
	// back to the API"). Providers without thinking-mode support
	// (OpenAI, Gemini, claudecode subprocess) ignore this field;
	// nil/empty when thinking wasn't engaged or for non-assistant
	// roles. Order is preserved — Anthropic requires thinking blocks
	// appear BEFORE text/tool_use blocks in the reconstructed turn.
	ThinkingBlocks []ThinkingBlock

	// ReasoningContent (NEX-340) is the openai-shape parallel of
	// ThinkingBlocks for DeepSeek reasoner-style models. DeepSeek's
	// `/v1` returns an assistant message with a `reasoning_content`
	// string field (extension to OpenAI Chat Completions wire) on
	// reasoning models like deepseek-v4-pro. Subsequent turns whose
	// assistant history is missing this field get rejected with
	// 400 ("The reasoning_content in the thinking mode must be
	// passed back to the API").
	//
	// Providers without reasoning_content support (vanilla OpenAI,
	// Anthropic, Gemini, claudecode) ignore this field. Empty when
	// the prior turn was a non-reasoning model or for non-assistant
	// roles.
	ReasoningContent string
}

type ProviderRequest struct {
	AspectID           string
	AppendSystemPrompt string
	Session            SessionHandle // for subprocess-stream: resume key; for direct-api: may be empty
	Messages           []ProviderMessage
	Tools              []ToolDef
	ToolChoice         string           // see TurnRequest.ToolChoice
	MCP                *MCPClientConfig // nil = no MCP tools
	MaxSteps           int
	Model              string

	// Cwd is the working directory for subprocess-style providers (see
	// TurnRequest.Cwd). Empty falls through to bridle's host cwd. Direct-
	// API providers ignore this field.
	Cwd string

	// ProviderEnv is per-turn auth/routing env (see TurnRequest.ProviderEnv).
	// Subprocess providers overlay it onto the spawned process's env;
	// direct-API providers read it as auth/base-url config. Empty/nil =
	// provider uses its own default config.
	ProviderEnv map[string]string

	// ToolExecutor is harness-owned (bridle spec NEX-745 §4): the
	// harness's own ToolRunner-backed tool-execution pipeline, wired in
	// for subprocess-stream providers whose agentic loop runs mid-
	// RunTurn and therefore can't wait for run.go's per-round tool loop
	// to service a custom tool call (claudesdk today). Nil for every
	// other provider — direct-api providers already own the loop in
	// run.go and ignore this field; subprocess-stream providers that
	// don't support custom tools (claudecode) never receive one.
	ToolExecutor ToolExecutor

	// Sampling + output control — see TurnRequest field docs.
	// NEX-299 Pass 2. Providers honour what their wire format supports
	// and silently ignore the rest (e.g. Seed openai-only, TopK
	// claude-only).
	Temperature     *float64
	TopP            *float64
	TopK            *int
	Seed            *int
	MaxOutputTokens int
	StopSequences   []string
	ResponseFormat  *ResponseFormat

	// ThinkingBudgetTokens requests Anthropic extended-thinking with this token
	// budget. Anthropic requires it be >= 1024 and < the request's max_tokens.
	// 0 = unset/disabled (provider default, no thinking). Claude-only; other
	// providers ignore it, same as Seed/TopK precedent.
	ThinkingBudgetTokens int

	// Effort mirrors TurnRequest.Effort (see its doc comment for the
	// ladder). Providers translate it to their own reasoning-effort knob
	// where they have one, and silently drop it otherwise.
	Effort string

	// ToolCallStrictness mirrors TurnRequest.ToolCallStrictness so the
	// harness's post-provider tool-call contract step (NEX-581) can read
	// the per-aspect knob from the lowered request. Providers themselves
	// ignore it — the contract lives in run.go's round loop.
	ToolCallStrictness ToolCallStrictness
	// ContextPolicy is the lowered per-aspect context-window policy (the
	// context contract, NEX-581). Providers read ContextPolicy.TargetWindow
	// and map it to their engine knob in applyContextPolicy (ollama →
	// num_ctx); fixed-window providers no-op it. PromptBudget is enforced
	// at the harness seam, not here. Zero value = no policy.
	ContextPolicy ContextPolicy

	// SystemPromptMode selects how AppendSystemPrompt is applied: replace (replaces the
	// base prompt entirely, like --system-prompt); or append (the default).
	//
	// Default/append mode appends to bridle's built-in base prompt; replace mode replaces it.
	// Claude-code v2.1.177 supports both modes — `--system-prompt` / `--append-system-prompt`
	// with the same spill logic as AppendSystemPrompt. Field is zero value (default) = append.
	SystemPromptMode SystemPromptMode
}

type ProviderResult struct {
	FinalText    string
	ToolCalls    []ToolInvocation
	StepCount    int
	Usage        Usage
	StopReason   StopReason
	SessionDelta []SessionEvent
	// ResolvedModel is the model id the upstream API actually returned
	// (e.g. "claude-3-5-sonnet-20241022"). May differ from
	// ProviderRequest.Model when per-turn ProviderEnv routed the call
	// elsewhere. Empty when the provider doesn't surface a model id.
	// Flows into TurnResult.ResolvedModel.
	ResolvedModel string
	// ThinkingBlocks (NEX-320) carries Claude extended-thinking content
	// blocks from this turn. The harness threads them into the next
	// turn's ProviderMessage so toClaudeMessages can re-emit them —
	// the Anthropic API requires they survive multi-turn round-trip.
	// Nil/empty when the provider doesn't support thinking mode OR
	// when this turn produced none.
	ThinkingBlocks []ThinkingBlock

	// ReasoningContent (NEX-340) is the openai-shape parallel of
	// ThinkingBlocks for DeepSeek reasoner-style models. The harness
	// threads this into the next IN-TURN step's reconstructed
	// assistant ProviderMessage (run.go tool-loop) so toOpenAIMessages
	// can re-emit it on step 2+. DeepSeek's API rejects in-turn
	// follow-up calls whose assistant{tool_call} reconstruction is
	// missing this field with 400 ("The reasoning_content in the
	// thinking mode must be passed back to the API"). Cross-turn
	// replay flows through SessionDelta instead — see SessionEvent.
	ReasoningContent string
}

type RateLimit struct {
	// Status is the provider's own coarse verdict: "allowed",
	// "allowed_warning", or "rejected" — cheaper for a caller to react to
	// than deriving a threshold from Utilization itself.
	Status string
	// WindowType names which window this reading is for — e.g.
	// "five_hour", "seven_day", "seven_day_opus", "seven_day_sonnet",
	// "seven_day_overage_included", "overage" — or "" when the provider
	// did not specify one.
	WindowType string
	// Utilization is 0-100. 0 covers both "just reset" and "not
	// reported" — the provider does not distinguish them either
	// (agora-spec-bridle's usage convention: a floor, not a
	// billing-grade count).
	Utilization int
	// ResetsAt is when this window resets; the zero Time when unknown.
	ResetsAt time.Time
	// UsingOverage is true once the session has started drawing on paid
	// overage credits rather than the plan's included allowance.
	UsingOverage bool
	TS           time.Time // stamped by the harness at emission; zero outside a harness turn
}

type ReasoningChunk struct {
	Text string
	TS   time.Time // stamped by the harness at emission; zero outside a harness turn
}

type ReasoningDeltaEvent struct{ Text string }

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

type Request struct {
	Messages []RoleMessage
	Tools    []ToolDef

	// Effort is the agora reasoning-effort ladder value: low | medium |
	// high | xhigh | max (agora-spec-bridle §3), lowered into
	// ProviderRequest.Effort and translated per-provider (T2). Empty is
	// equivalent to unset (provider/model default).
	Effort string

	MaxTokens int

	// Structured requests schema-constrained output. T1/T7 threads the
	// field through but does not enforce it (see JSONSchema doc) — T4
	// follow-up work.
	Structured *JSONSchema

	// CacheHints marks the stable prefix (system + tools + skills
	// catalog) for provider-side prompt-cache control (agora-spec-bridle
	// §3). T1/T7 threads the field through but does not yet apply any
	// provider cache-control wiring from it — follow-up work.
	CacheHints []string

	// ProviderEnv is per-call auth/routing config, same contract as
	// TurnRequest.ProviderEnv / ProviderRequest.ProviderEnv.
	ProviderEnv map[string]string
}

type ResponseFormat struct {
	// Type is one of: "text" | "json_object" | "json_schema". Empty
	// defaults to "text" (provider default, free-form).
	Type string

	// Name identifies the schema for the "json_schema" type. OpenAI
	// requires it (max 64 chars, a-z/A-Z/0-9/_/-).
	Name string

	// Description is optional context for the model on what the
	// schema is for. Only used for "json_schema".
	Description string

	// Schema is a JSON Schema describing the expected response.
	// Required when Type == "json_schema". Ignored otherwise.
	Schema json.RawMessage

	// Strict, when Type == "json_schema", turns on OpenAI's strict
	// structured-outputs mode (response is GUARANTEED to match
	// schema). Recommended on for classifier paths where
	// parse-failure costs more than rejection.
	Strict bool
}

type RoleMessage struct {
	Role    MessageRole
	Content string
}

type RoundTiming struct {
	AssemblySecs            float64 // request assembly + BeforeModelCall hooks
	StartupToFirstEventSecs float64 // provider call -> first sink event (CLI lane: spawn+startup+TTFT)
	StreamSecs              float64 // first event -> provider call return
	PromptBytes             int     // marshaled request messages size
	MessageCount            int
	ToolDefCount            int
}

type SessionEvent struct {
	Provider ProviderID  `json:"provider,omitempty"` // who produced this event
	Role     SessionRole `json:"role"`
	Content  string      `json:"content,omitempty"`
	// RawJSON carries provider-specific blocks (tool_use, tool_result, etc.)
	// that don't fit the plain content field. Valid only in conjunction with Provider.
	RawJSON json.RawMessage `json:"raw,omitempty"`
	// ThinkingBlocks (NEX-320 cross-turn) preserves Claude extended-
	// thinking blocks across Deliberate calls — within a single Run the
	// blocks survive via ProviderResult.ThinkingBlocks, but the funnel's
	// SessionTail re-lowering path (run.go lowerRequest) erases them
	// without this field. Anthropic API rejects multi-turn requests
	// whose assistant history is missing thinking blocks from prior
	// thinking-mode turns ("content[].thinking ... must be passed back").
	//
	// Attached to the FIRST assistant SessionEvent of each turn (text
	// or tool_use) — duplicating across all events in the same turn
	// would double-emit the blocks on the wire. lowerRequest carries
	// these onto the corresponding ProviderMessage.
	//
	// omitempty keeps existing JSONL session logs backward-compatible
	// (old entries decode with empty slice; cross-turn replay no-ops
	// when nil).
	ThinkingBlocks []ThinkingBlock `json:"thinking_blocks,omitempty"`

	// ReasoningContent (NEX-340) is the openai-shape parallel of
	// ThinkingBlocks for DeepSeek reasoner-style models. Same shape
	// of requirement: subsequent turns whose assistant history loses
	// the reasoning_content field get rejected with 400
	// ("The reasoning_content in the thinking mode must be passed
	// back to the API"). Attached to the FIRST assistant SessionEvent
	// of each turn so lowerRequest can re-emit on the corresponding
	// ProviderMessage. omitempty preserves back-compat for non-
	// reasoning sessions and non-openai-shape providers.
	ReasoningContent string `json:"reasoning_content,omitempty"`

	// ToolCallID links a tool-result SessionEvent (Role==RoleTool)
	// back to the assistant tool_use that produced it. Required for
	// cross-turn replay through SessionTail: providers that use call-
	// id correlation (Anthropic, OpenAI, Ollama) need this on the
	// reconstructed tool_result ProviderMessage. Empty for non-tool
	// events. Without it, lowerRequest can't pair tool_results with
	// their tool_calls and the API rejects the rebuilt history.
	ToolCallID string `json:"tool_call_id,omitempty"`
}

type SessionHandle struct {
	ID  string // opaque to the funnel; meaningful to the provider
	New bool   // true on the first invocation for this ID; false on continuations
}

type SessionRole string

type StepBoundary struct {
	Step int
	TS   time.Time // stamped by the harness at emission; zero outside a harness turn
}

type StopReason string

type StreamEvent interface {
	// contains filtered or unexported methods
}

type StreamStopReason string

type StreamUsage struct {
	Input     int
	Output    int
	Cached    int
	Reasoning int
}

type SystemPromptMode string

type TextDeltaEvent struct{ Text string }

type ThinkingBlock struct {
	// Type is "thinking" or "redacted_thinking".
	Type string
	// Thinking is the plaintext reasoning content (Type=="thinking" only).
	Thinking string
	// Signature is the server-provided cryptographic signature; must
	// be sent back verbatim. (Type=="thinking" only.)
	Signature string
	// Data is the opaque encrypted payload (Type=="redacted_thinking"
	// only). Anthropic's safety filter swaps in a redacted block when
	// it judges the plaintext shouldn't reach the caller; the API
	// still requires it on round-trip.
	Data string
}

type ToolCall struct {
	ID   string
	Name string
	Args json.RawMessage
}

type ToolCallEvent struct {
	ID       string
	Name     string
	ArgsJSON json.RawMessage
}

type ToolCallRepaired struct {
	// Stage names the contract action: "detected", "repaired", or "retried".
	Stage string
	// Detail is a short label (which token leaked, what repair did).
	Detail string
	TS     time.Time // stamped by the harness at emission; zero outside a harness turn
}

type ToolCallResult struct {
	ID     string
	Result json.RawMessage
	Err    string    // non-empty if the tool runner returned an error
	TS     time.Time // stamped by the harness at emission; zero outside a harness turn
}

type ToolCallStart struct {
	ID   string
	Name string
	Args json.RawMessage
	TS   time.Time // stamped by the harness at emission; zero outside a harness turn
}

type ToolCallStrictness string

type ToolDef struct {
	Name        string
	Description string
	// InputSchema is a JSON Schema object describing the expected arguments.
	InputSchema json.RawMessage
}

type ToolExecutor interface {
	Execute(ctx context.Context, call ToolCall) (ToolResult, error)
}

type ToolInvocation struct {
	ID     string
	Name   string
	Args   json.RawMessage
	Result json.RawMessage
	Err    string
}

type ToolResult struct {
	Result json.RawMessage
	Err    string
}

type ToolRunner interface {
	Run(ctx context.Context, call ToolCall) (json.RawMessage, error)
}

type ToolTiming struct {
	ID   string
	Name string
	Secs float64
}

type TurnDone struct {
	Result TurnResult
	TS     time.Time // stamped by the harness at emission; zero outside a harness turn
}

type TurnError struct {
	Err   error
	Stage TurnErrorStage
	TS    time.Time // stamped by the harness at emission; zero outside a harness turn
}

type TurnErrorStage string

type TurnRequest struct {
	// Identity & framing
	AspectID           string           // who's running (cost/triage/identity attribution)
	AppendSystemPrompt string           // composed by funnel: NEXUS.md + SOUL.md + PRIMER + harness rules
	SystemPromptMode   SystemPromptMode // how AppendSystemPrompt is applied: append (default, zero value) extends claude-code's base prompt; replace swaps it entirely
	Session            SessionHandle    // opaque handle for provider-side state (subprocess-stream: resume key)
	SessionTail        []SessionEvent   // recent events for direct-api providers to lower into the request

	// This turn
	UserMessage string      // the prompt that opens this turn (may be empty for autonomous)
	Inbox       []InboxItem // mid-turn comms accumulated since last turn

	// Tool surface
	Tools []ToolDef        // explicit in-process tool defs
	MCP   *MCPClientConfig // MCP-loaded tools; nil = no MCP tools this turn

	// Provider
	Provider ProviderID // claude-api | openai-api | bedrock | gemini-api | ollama-local | claude-code | gemini-cli | codex-cli | claude-pty
	Model    string     // REQUIRED — provider-specific model id; RunTurn returns ErrModelRequired if empty
	MaxSteps int        // hard cap on tool-call rounds; 0 = unlimited

	// ToolChoice optionally constrains how the model picks tools.
	// Empty string → provider default (typically "auto").
	// "auto" → model decides whether to call a tool.
	// "any" → model must call exactly one tool, free choice of which.
	// "none" → no tools may be called this turn (text only).
	// Any other value → name of a specific tool that must be called.
	// Not all providers honour all values; unsupported values fall back to "auto".
	ToolChoice string

	// Sampling controls (NEX-299 Pass 2). Pointer types so "unset" is
	// distinguishable from "explicitly zero" — providers fall through
	// to their own default when nil.
	//
	//   Temperature: lower = more deterministic. 0 for classifier
	//                tasks (cheap judge); higher for creative.
	//   TopP:        nucleus sampling. Standard across providers.
	//   TopK:        claude-only; openai silently ignores.
	//   Seed:        openai-only deterministic sampling seed;
	//                claude silently ignores. Pair with Temperature=0
	//                for full reproducibility.
	Temperature *float64
	TopP        *float64
	TopK        *int
	Seed        *int

	// ThinkingBudgetTokens requests Anthropic extended-thinking with this token
	// budget. Anthropic requires it be >= 1024 and < the request's max_tokens.
	// 0 = unset/disabled (provider default, no thinking). Claude-only; other
	// providers ignore it, same as Seed/TopK precedent.
	ThinkingBudgetTokens int

	// Effort is the agora reasoning-effort ladder value: low | medium |
	// high | xhigh | max (agora-spec-bridle §3). Empty = provider
	// default (no translation attempted). Providers that can't express
	// a tier at all drop it silently, same as Seed/TopK precedent.
	Effort string

	// MaxOutputTokens caps generation length. 0 = provider default
	// (claude internally falls back to 4096; openai uses its own
	// account-level default). Set non-zero for cost-bounded paths
	// like cheap-judge classifier where verdicts are tiny.
	MaxOutputTokens int

	// StopSequences halt generation on first match. Maps to openai
	// `stop` and claude `stop_sequences`. Empty = no stop sequences.
	StopSequences []string

	// ResponseFormat constrains the model's output shape — most
	// usefully for json_schema strict mode, which guarantees the
	// response matches Schema. Providers that don't support this
	// (claude as of writing) silently ignore. Callers wanting
	// portability should also encode schema requirements in the
	// system prompt. Nil = free-form text (provider default).
	ResponseFormat *ResponseFormat

	// ToolCallStrictness is the per-aspect tool-call contract knob
	// (NEX-581). It controls how hard bridle works to deliver a clean
	// tool call or clean text when an engine leaks raw protocol tokens.
	// Empty = repair-then-retry (the default): builders should keep it
	// strict and never ship a degraded tool call; research aspects can
	// set "tolerant" to accept structurally-repaired text without a
	// retry round.
	ToolCallStrictness ToolCallStrictness

	// Cwd is the working directory for subprocess-style providers.
	// Empty falls through to the bridle host process's cwd. Per-request
	// rather than per-Harness because different aspects sharing one
	// Harness need distinct cwds. For example, claude-code derives its
	// session jsonl path AND its .mcp.json discovery from cwd, so two
	// aspects with the same Harness but overlapping cwds collide
	// sessions and leak MCP identity from one into the other. Codex CLI
	// receives the same value as both process cwd and `codex --cd`.
	// Direct-API providers ignore this field — they have no subprocess
	// to anchor.
	Cwd string

	// ProviderEnv is per-call environment for the provider. Direct-API
	// providers read it as their auth/routing config (commonly
	// ANTHROPIC_API_KEY, ANTHROPIC_BASE_URL, OPENAI_API_KEY,
	// OPENAI_BASE_URL); subprocess providers propagate it into the
	// spawned process's env so the same per-turn override pattern
	// applies. nil/empty = use whatever the provider already has on its
	// own (process env, --bare-style flags, etc).
	//
	// Per-call rather than per-process so a single funnel can mix
	// credentials across turns — e.g. main turn against the operator's
	// Anthropic credit pool, judge turn against a DeepSeek-via-
	// Anthropic-shape credential, eval turn against OpenAI. The
	// credential store wires this from aspects.default_*_credential
	// per task #218.
	ProviderEnv map[string]string

	// ContextPolicy is the per-aspect context-window policy (the context
	// contract, NEX-581): a desired window (TargetWindow) and a soft
	// prompt-size budget (PromptBudget), expressed once here and mapped
	// by each provider to its engine knob — or warned on engine-
	// agnostically. Zero value = no policy (engine defaults, no budget
	// warning). See ContextPolicy.
	ContextPolicy ContextPolicy
}

type TurnResult struct {
	FinalText     string           // model's last assistant text (may be empty for tool-only turns)
	ToolCalls     []ToolInvocation // ordered list of what the model actually did
	StepCount     int
	Usage         Usage
	StopReason    StopReason
	ResolvedModel string         // model id the upstream API reported; empty when unknown
	SessionDelta  []SessionEvent // events to propose to the funnel-owned JSONL
	Timing        TurnTiming     // per-turn timing instrumentation; zero value = not recorded
}

type TurnTiming struct {
	Rounds    []RoundTiming
	Tools     []ToolTiming
	TotalSecs float64
}

type Usage struct {
	InputTokens              int
	OutputTokens             int
	CacheReadInputTokens     int     // Anthropic prompt-cache hit count
	CacheCreationInputTokens int     // tokens written into the prompt cache this turn
	CostUSD                  float64 // provider-reported or estimated; 0 if unknown

	// Estimated is set true when the token counts in this Usage were
	// NOT reported by the engine — they were estimated by bridle's
	// tokenizer as a last-resort floor (the usage contract, NEX-581).
	// A provider that reports real usage leaves this false. The flag
	// rides through addUsage: if ANY round of a turn was estimated, the
	// turn total is flagged Estimated. Consumers (cost accounting) can
	// treat estimated counts as approximate. The guarantee is that a
	// completed turn never has silently-zero usage — it has real
	// counts, or a flagged estimate, never nothing.
	Estimated bool

	// ReasoningTokens is the count of extended-thinking/reasoning
	// tokens the provider billed for this round, when it reports the
	// breakdown separately from OutputTokens (agora-spec-bridle §2
	// usage{input, output, cached, reasoning}). Additive field; 0 for
	// providers/rounds that don't report it (not necessarily "no
	// reasoning happened" — it may just be folded into OutputTokens
	// instead, e.g. Anthropic bills thinking tokens as output tokens
	// today).
	ReasoningTokens int
}

type UsageEvent struct{ Usage StreamUsage }

type Warning struct {
	Kind    string
	Message string
	TS      time.Time // stamped by the harness at emission; zero outside a harness turn
}

type WarningEvent struct {
	Kind    string
	Message string
}