bridle

type AfterModelChunkCtx struct {
	Chunk ModelChunk
	Step  int
}

type AfterToolCallCtx struct {
	Call   ToolCall
	Result ToolCallResult
	Step   int
}

type BeforeModelCallCtx struct {
	Request TurnRequest
	Step    int
}

type BeforeToolCallCtx struct {
	Call ToolCall
	Step int
}

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 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 MCPClientConfig struct {
	Servers []MCPServerSpec
}

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 ModelChunk struct {
	Text string
}

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

type OnStepBoundaryCtx struct {
	Step int
}

type OnTurnDoneCtx struct {
	Result *TurnResult
}

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
}

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
}

type ProviderResult struct {
	FinalText    string
	ToolCalls    []ToolInvocation
	StepCount    int
	Usage        Usage
	StopReason   StopReason
	SessionDelta []SessionEvent
}

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

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
}

type StopReason string

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

type ToolCallResult struct {
	ID     string
	Result json.RawMessage
	Err    string // non-empty if the tool runner returned an error
}

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

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

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

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

type TurnDone struct {
	Result TurnResult
}

type TurnError struct {
	Err   error
	Stage string // "provider", "tool", "harness-recover", etc.
}

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
	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 | ollama-local | openai-api | claude-code
	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

	// Cwd is the working directory for subprocess-style providers
	// (currently claude-code). 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 —
	// 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. Direct-API providers (claude-api, ollama, openai)
	// 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 (claude-code) 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
}

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
	SessionDelta []SessionEvent // events to propose to the funnel-owned JSONL
}

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
}