core

type APIEvent struct {
	Time      time.Time `json:"time"`
	Type      string    `json:"type"` // "thought", "chunk", "reply", "thread_started", "thread_done", "error"
	ThreadID  string    `json:"thread_id"`
	Message   string    `json:"message,omitempty"`
	Iteration int       `json:"iteration,omitempty"`
	Duration  string    `json:"duration,omitempty"`
}

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

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

type AudioFormat string

type AudioURL struct {
	URL      string `json:"url"`                 // https:// or data:audio/...;base64,...
	MimeType string `json:"mime_type,omitempty"` // "audio/mp3", "audio/wav", etc. (auto-detected if empty)
}

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

type BuiltinTool struct {
	Type string `json:"type"` // e.g. "code_execution_20250825", "code_interpreter"
	Name string `json:"name"` // e.g. "code_execution", "code_interpreter"
}

type ChatReply struct {
	User    string
	Message string
}

type ChatResponse struct {
	Text          string                 // streamed text content
	Reasoning     string                 // accumulated chain-of-thought (Fireworks reasoning_content / OpenRouter reasoning); empty when the provider didn't emit any
	ToolCalls     []NativeToolCall       // structured tool calls WE need to execute
	ServerResults []ServerToolResult     // tools the PROVIDER already executed
	ProviderState *ProviderResponseState // opaque provider output items needed for stateless continuation
	Usage         TokenUsage
}

type Config struct {
	Directive       string  `json:"directive"`
	Mode            RunMode `json:"mode,omitempty"`
	Unconscious     bool    `json:"unconscious,omitempty"`      // enable background memory consolidation thread
	RealtimeEnabled bool    `json:"realtime_enabled,omitempty"` // master switch for realtime (voice/audio) threads; off = main never sees the capability and spawn rejects realtime=true
	RealtimeVoice   string  `json:"realtime_voice,omitempty"`   // dashboard/default realtime voice (provider validates at session open)
	// RealtimeVoiceMCP is the operator-selected subset of attached MCP
	// servers exposed to dashboard voice sessions. It is policy/config only;
	// realtime execution still uses the normal thread registry and gates.
	RealtimeVoiceMCP []string               `json:"realtime_voice_mcp,omitempty"`
	Providers        []ProviderConfig       `json:"providers,omitempty"` // multi-provider pool
	Provider         *ProviderConfig        `json:"provider,omitempty"`  // legacy single-provider (auto-migrated to Providers on load)
	Threads          []PersistentThread     `json:"threads,omitempty"`
	MCPServers       []MCPServerConfig      `json:"mcp_servers,omitempty"`
	Execution        ExecutionControlConfig `json:"execution_control,omitempty"`
	// contains filtered or unexported fields
}

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

type ContentPart struct {
	Type       string      `json:"type"`                  // "text", "image_url", "input_audio", "audio_url"
	Text       string      `json:"text,omitempty"`        // type=text
	ImageURL   *ImageURL   `json:"image_url,omitempty"`   // type=image_url
	InputAudio *InputAudio `json:"input_audio,omitempty"` // type=input_audio
	AudioURL   *AudioURL   `json:"audio_url,omitempty"`   // type=audio_url
}

type Delta struct {
	Content string `json:"content"`
}

type DirectiveChangeData struct {
	Old string `json:"old,omitempty"`
	New string `json:"new"`
}

type Event struct {
	Type string // one of the Event* constants
	From string // source: "main", thread ID, "tui", "api", "tool:name"
	To   string // target subscriber ID; "" = broadcast

	Text       string        // message payload
	ToolName   string        // tool name (for EventToolChunk)
	Parts      []ContentPart // optional media (images, audio) attached to this event
	ToolResult *ToolResult   // optional: structured tool result

	// Structured fields (populated for ThinkDone events)
	Iteration      int
	Duration       time.Duration
	ConsumedEvents []string
	Usage          TokenUsage
	ToolCalls      []string
	Replies        []string
	Rate           ThinkRate
	SleepDuration  time.Duration
	Model          ModelTier
	Reasoning      ReasoningLevel
	MemoryCount    int
	ThreadCount    int
	ContextMsgs    int // number of messages in context window
	ContextChars   int // approximate character count of context
	Error          error
}

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

type ExecutionCheckpointMeta struct {
	ID        string            `json:"id"`
	ThreadID  string            `json:"thread_id"`
	Iteration int               `json:"iteration"`
	Phase     string            `json:"phase"`
	Tool      string            `json:"tool,omitempty"`
	CallID    string            `json:"call_id,omitempty"`
	Summary   string            `json:"summary,omitempty"`
	Args      map[string]string `json:"args,omitempty"`
	CreatedAt time.Time         `json:"created_at"`
}

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

type ExecutionControlAction struct {
	Action       string               `json:"action"`
	ThreadID     string               `json:"thread_id,omitempty"`
	CheckpointID string               `json:"checkpoint_id,omitempty"`
	Mode         ExecutionControlMode `json:"mode,omitempty"`
}

type ExecutionControlConfig struct {
	Mode        ExecutionControlMode `json:"mode,omitempty"`
	Scope       string               `json:"scope,omitempty"`
	Breakpoints []string             `json:"breakpoints,omitempty"`
	Follow      string               `json:"follow,omitempty"`
}

type ExecutionControlMode string

type ExecutionControlStatus struct {
	Mode                ExecutionControlMode `json:"mode"`
	Scope               string               `json:"scope"`
	Breakpoints         []string             `json:"breakpoints"`
	Follow              string               `json:"follow"`
	Waiting             bool                 `json:"waiting"`
	Phase               string               `json:"phase,omitempty"`
	ActiveThreadID      string               `json:"active_thread_id,omitempty"`
	Iteration           int                  `json:"iteration,omitempty"`
	Tool                string               `json:"tool,omitempty"`
	CallID              string               `json:"call_id,omitempty"`
	Summary             string               `json:"summary,omitempty"`
	Args                map[string]string    `json:"args,omitempty"`
	WaitingCount        int                  `json:"waiting_count,omitempty"`
	CanRestore          bool                 `json:"can_restore,omitempty"`
	RestoreCheckpointID string               `json:"restore_checkpoint_id,omitempty"`
	RestoreSummary      string               `json:"restore_summary,omitempty"`
	RestorePhase        string               `json:"restore_phase,omitempty"`
}

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

type ExecutionGate struct {
	ThreadID  string
	Phase     ExecutionPhase
	Iteration int
	Tool      string
	CallID    string
	Summary   string
	Args      map[string]string
	Result    string
	ParentID  string
}

type ExecutionPhase string

type ExecutionPhaseData struct {
	ThreadID       string            `json:"thread_id"`
	Iteration      int               `json:"iteration"`
	Phase          string            `json:"phase"`
	Tool           string            `json:"tool,omitempty"`
	CallID         string            `json:"call_id,omitempty"`
	Summary        string            `json:"summary,omitempty"`
	Args           map[string]string `json:"args,omitempty"`
	ResultPreview  string            `json:"result_preview,omitempty"`
	ParentThreadID string            `json:"parent_thread_id,omitempty"`
}

type ExtraSystemBlock struct {
	Preview string `json:"preview"` // first ~60 chars, newlines stripped
	Bytes   int    `json:"bytes"`
}

type GoogleModel struct {
	ID              string
	InputPer1M      float64
	CachedPer1M     float64
	OutputPer1M     float64
	MaxOutputTokens int
}

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

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

type ImageURL struct {
	URL    string `json:"url"`              // https:// or data:image/...;base64,...
	Detail string `json:"detail,omitempty"` // "low", "high", "auto"
}

type IndexEntry struct {
	Server      string
	LocalName   string // raw MCP name (for example "send")
	Name        string // fully-qualified (e.g. "storage_files_upload")
	Description string
	NoSpawn     bool // sub-threads cannot see this tool in search
	LoadMode    ToolLoadMode
	// contains filtered or unexported fields
}

type InputAudio struct {
	Data   string `json:"data"`   // base64
	Format string `json:"format"` // "wav", "mp3"
}

type LLMChunkData struct {
	Text      string `json:"text"`
	Iteration int    `json:"iteration"`
}

type LLMDoneData struct {
	Model            string `json:"model"`
	Reasoning        string `json:"reasoning,omitempty"`
	TokensIn         int    `json:"tokens_in"`
	TokensCached     int    `json:"tokens_cached"`
	CacheWriteTokens int    `json:"cache_write_tokens,omitempty"`
	TokensOut        int    `json:"tokens_out"`
	DurationMs       int64  `json:"duration_ms"`
	// cost_usd is no longer populated by core — pricing lives in the
	// server, which enriches llm.done events with a canonical
	// cost_usd on ingest. Removing the field from the Go type keeps
	// core free of pricing data, but the wire format is still the
	// same map-of-strings consumed by dashboards and persisted by
	// the server.
	Iteration           int    `json:"iteration"`
	Rate                string `json:"rate"`
	ContextMsgs         int    `json:"context_msgs"`
	ContextChars        int    `json:"context_chars"`
	ContextTokensEst    int    `json:"context_tokens_est,omitempty"`
	RequestContextMsgs  int    `json:"request_context_msgs,omitempty"`
	RequestContextChars int    `json:"request_context_chars,omitempty"`
	RequestTokensEst    int    `json:"request_context_tokens_est,omitempty"`
	// MaxContextTokens is the model's advertised input-context window
	// (in tokens). Comes from a static lookup keyed on the model id —
	// see ModelContextWindow. 0 when the model isn't in the table; UI
	// should treat 0 as "unknown" and skip percentage rendering.
	MaxContextTokens             int    `json:"max_context_tokens,omitempty"`
	MemoryCount                  int    `json:"memory_count"`
	ThreadCount                  int    `json:"thread_count"`
	Message                      string `json:"message,omitempty"`
	NativeToolCount              int    `json:"native_tool_count,omitempty"`
	ActiveMCPCount               int    `json:"active_mcp_count,omitempty"`
	AlwaysMCPCount               int    `json:"always_mcp_count,omitempty"`
	DeferredMCPCount             int    `json:"deferred_mcp_count,omitempty"`
	ToolMode                     string `json:"tool_mode,omitempty"`
	PromptCacheEpoch             uint64 `json:"prompt_cache_epoch"`
	PromptCacheResetReason       string `json:"prompt_cache_reset_reason,omitempty"`
	PromptCacheIdentityHash      string `json:"prompt_cache_identity_hash,omitempty"`
	PromptCacheStablePrefixHash  string `json:"prompt_cache_stable_prefix_hash,omitempty"`
	PromptCacheRequestHash       string `json:"prompt_cache_request_hash,omitempty"`
	PromptCacheCommonPrefixBytes int    `json:"prompt_cache_common_prefix_bytes,omitempty"`
}

type LLMErrorData struct {
	Model     string `json:"model"`
	Error     string `json:"error"`
	Iteration int    `json:"iteration"`
}

type LLMProvider interface {
	// Chat sends messages and streams the response.
	// ctx is propagated to the underlying HTTP request so cancellation
	// (user abort, shutdown) unblocks an in-flight stream cleanly.
	// tools: native tool definitions to include in the request (nil = no tools).
	// onChunk is called for each text token chunk as it arrives.
	// onThinking is called for each reasoning/thinking token (separate from output).
	// onToolChunk is called for each tool argument chunk as it streams
	// (toolName, callID, argChunk). callID disambiguates two parallel
	// calls of the same tool in one response — providers pass their own
	// stable per-call id (tc.Index for OpenAI, content_block id for
	// Anthropic). Empty string is acceptable.
	// Returns ChatResponse with text, tool calls, and usage.
	Chat(ctx context.Context, messages []Message, model string, tools []NativeTool, onChunk func(string), onThinking func(string), onToolChunk func(toolName, callID, chunk string)) (ChatResponse, error)

	// Models returns model IDs for each tier.
	Models() map[ModelTier]string

	// Name returns the provider name for display/telemetry.
	Name() string

	// CostPer1M returns pricing per 1M tokens: (input, cached, output).
	CostPer1M() (float64, float64, float64)

	// SupportsNativeTools returns true if this provider handles structured tool calling.
	SupportsNativeTools() bool

	// AvailableBuiltinTools returns built-in tools this provider supports.
	AvailableBuiltinTools() []BuiltinTool

	// SetBuiltinTools enables specific built-in tools.
	SetBuiltinTools(tools []string)

	// WithBuiltins returns a shallow clone of this provider with only the specified builtins enabled.
	// If builtins is nil, returns the provider unchanged (inherit all).
	WithBuiltins(builtins []string) LLMProvider
}

type MCPConn interface {
	GetName() string
	ListTools() ([]mcpToolDef, error)
	CallTool(name string, args map[string]string) (ToolResponse, error)
	Close()
}

type MCPHTTPServer struct {
	Name string
	// contains filtered or unexported fields
}

type MCPServer struct {
	Name string
	// contains filtered or unexported fields
}

type MCPServerConfig struct {
	Name      string            `json:"name"`
	Command   string            `json:"command,omitempty"`   // stdio transport
	Args      []string          `json:"args,omitempty"`      // stdio transport
	Env       map[string]string `json:"env,omitempty"`       // stdio transport
	Transport string            `json:"transport,omitempty"` // "stdio" (default) or "http"
	URL       string            `json:"url,omitempty"`       // http transport
	// ToolLoading controls prompt-schema availability independently from
	// connection and authorization. Always-loaded tools are present on every
	// authorized model request; deferred tools require search/preload; auto
	// preserves the global eager/discovery threshold behavior.
	ToolLoading *MCPToolLoadingConfig `json:"tool_loading,omitempty"`
	// NoSpawn, when true, hides this server's tools from sub-thread
	// search_tools results and refuses sub-thread spawn(mcps=[...])
	// attachments. Used for infrastructure-level servers the host
	// wires in for main-thread-only responsibilities (management
	// gateway, outbound channel bridges) where letting a worker
	// invoke them would be a privilege escalation. Core has no
	// knowledge of which names are "system" — the host sets this
	// flag when registering those entries. The privileged HTTP spawn
	// path (POST /threads/{id}) sets SpawnOpts.BypassNoSpawn to
	// punch through this filter for system-initiated workers
	// (channelchat's chat-handling thread needs `channels`).
	NoSpawn bool `json:"no_spawn,omitempty"`
}

type MCPServerInfo struct {
	Name          string
	ToolCount     int
	AlwaysCount   int
	AutoCount     int
	DeferredCount int
}

type MCPToolLoadingConfig struct {
	Default ToolLoadMode            `json:"default,omitempty"`
	Tools   map[string]ToolLoadMode `json:"tools,omitempty"`
}

type MemoryRecallMatch struct {
	Record MemoryRecord
	Score  float64
	Signal float64
}

type MemoryRecord struct {
	ID         string    `json:"id"`
	TS         time.Time `json:"ts"`
	Content    string    `json:"content,omitempty"`
	Tags       []string  `json:"tags,omitempty"`
	Weight     float64   `json:"weight,omitempty"`
	Supersedes string    `json:"supersedes,omitempty"`
	Embedding  []float64 `json:"embedding,omitempty"`

	// Tombstone bits.
	Tombstone bool   `json:"tombstone,omitempty"`
	IDTarget  string `json:"id_target,omitempty"`
	Reason    string `json:"reason,omitempty"`
}

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

type Message struct {
	Role          string                 `json:"role"`
	Content       string                 `json:"content"`
	Parts         []ContentPart          `json:"parts,omitempty"`          // multimodal content
	ToolCalls     []NativeToolCall       `json:"tool_calls,omitempty"`     // assistant messages: structured tool calls
	ToolResults   []ToolResult           `json:"tool_results,omitempty"`   // user messages: results for prior tool calls
	ProviderState *ProviderResponseState `json:"provider_state,omitempty"` // opaque state for exact provider replay
	// RequestContext marks transient retrieval context. It is carried only in
	// the prepared provider request and is never written to session history.
	RequestContext bool `json:"-"`
	// Reasoning is the model's chain-of-thought from the turn that
	// produced this message. We replay it back to the provider on
	// subsequent turns because Moonshot (Kimi K2.6 via OpenCode Go)
	// requires `reasoning_content` to be present on assistant
	// tool_call messages when thinking mode is enabled — without it
	// every multi-turn tool flow 400s. Other providers ignore it.
	Reasoning string `json:"reasoning,omitempty"`
}

type ModelCapabilities struct {
	ContextWindow                 int                        `json:"context_window,omitempty"`
	MaxContextWindow              int                        `json:"max_context_window,omitempty"`
	EffectiveContextWindowPercent int                        `json:"effective_context_window_percent,omitempty"`
	DefaultReasoningLevel         string                     `json:"default_reasoning_level,omitempty"`
	SupportedReasoningLevels      []ModelReasoningCapability `json:"supported_reasoning_levels,omitempty"`
	InputModalities               []string                   `json:"input_modalities,omitempty"`
	SupportsParallelToolCalls     *bool                      `json:"supports_parallel_tool_calls,omitempty"`
	SupportsReasoningSummaries    *bool                      `json:"supports_reasoning_summaries,omitempty"`
	SupportsImageDetailOriginal   *bool                      `json:"supports_image_detail_original,omitempty"`
	SupportsSearchTool            *bool                      `json:"supports_search_tool,omitempty"`
}

type ModelReasoningCapability struct {
	Effort      string `json:"effort"`
	Description string `json:"description,omitempty"`
}

type ModelTier int

type NativeTool struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Parameters  map[string]any `json:"parameters"` // JSON Schema
}

type NativeToolCall struct {
	ID               string            `json:"id"`                       // provider call ID for matching results
	OutputItemID     string            `json:"output_item_id,omitempty"` // Responses output item ID (fc_...), distinct from call ID
	Status           string            `json:"status,omitempty"`         // Responses output item status for exact replay/debugging
	Name             string            `json:"name"`
	Args             map[string]string `json:"args"`
	ThoughtSignature string            `json:"thought_signature,omitempty"` // Gemini: encrypted reasoning state
}

type NativeToolSize struct {
	Name  string `json:"name"`
	Kind  string `json:"kind"` // "core" | "mcp" | "local"
	Bytes int    `json:"bytes"`
}

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

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

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

type PersistentThread struct {
	ID        string   `json:"id"`
	Name      string   `json:"name,omitempty"`      // human-readable label; empty = display as ID
	ParentID  string   `json:"parent_id,omitempty"` // empty = child of main
	Depth     int      `json:"depth,omitempty"`     // 0 = main's direct child
	System    bool     `json:"system,omitempty"`    // system thread (can't be killed by LLM)
	Directive string   `json:"directive"`
	Tools     []string `json:"tools"`
	MCPNames  []string `json:"mcp_names,omitempty"` // MCP servers to connect on respawn
	Model     string   `json:"model,omitempty"`     // starting model tier: large, medium, small
	Reasoning string   `json:"reasoning,omitempty"` // starting reasoning effort: auto, low, medium, high, ...
	Provider  string   `json:"provider,omitempty"`  // provider selected for this thread
	Realtime  bool     `json:"realtime,omitempty"`  // spawn as a realtime (voice/audio) thread
	Voice     string   `json:"voice,omitempty"`     // realtime voice id (e.g. "marin"); empty = provider default
}

type Phase struct {
	Name    string
	Setup   func(t *testing.T, dir string)                   // optional: inject data before this phase
	Wait    func(t *testing.T, dir string, th *Thinker) bool // poll condition (return true when done)
	Verify  func(t *testing.T, dir string, th *Thinker)      // optional: assertions after Wait succeeds
	Timeout time.Duration
}

type PromptComposition struct {
	System         SystemBreakdown    `json:"system"`
	NativeTools    []NativeToolSize   `json:"native_tools"`
	NativeBytes    int                `json:"native_bytes"`
	ExtraSystem    []ExtraSystemBlock `json:"extra_system"` // role=system msgs after messages[0]
	ExtraBytes     int                `json:"extra_bytes"`
	ConvBytes      int                `json:"conv_bytes"` // user/assistant/tool/other messages
	GrandTotal     int                `json:"grand_total"`
	ModelMaxTokens int                `json:"model_max_tokens,omitempty"`
}

type PromptTokensDetails struct {
	CachedTokens     int `json:"cached_tokens"`
	CacheWriteTokens int `json:"cache_write_tokens"`
}

type ProviderConfig struct {
	Name              string                       `json:"name"`                         // "google", "openai", "anthropic", "fireworks", "xai", "ollama", or a "*-realtime" companion
	Default           bool                         `json:"default,omitempty"`            // true = default provider (first match wins)
	Models            map[string]string            `json:"models,omitempty"`             // "large" → model ID, "medium" → ..., "small" → ...
	ModelCapabilities map[string]ModelCapabilities `json:"model_capabilities,omitempty"` // selected model metadata keyed by model ID
	BuiltinTools      []string                     `json:"builtin_tools,omitempty"`      // e.g. ["code_execution"]
	RealtimeVoice     string                       `json:"realtime_voice,omitempty"`     // default voice for realtime providers (e.g. "marin")
}

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

type ProviderResponseState struct {
	Provider string            `json:"provider"`
	Items    []json.RawMessage `json:"items,omitempty"`
}

type RealtimeEvent struct {
	Type RealtimeEventType

	// Audio (RealtimeEventAudioOut)
	Audio []byte

	// Transcript (RealtimeEventTranscript*)
	Transcript string
	Final      bool // true = end-of-utterance, false = partial

	// Tool call (RealtimeEventToolCall)
	ToolCallID string
	ToolName   string
	ToolArgs   string // raw JSON string

	// Response/audio item metadata. ItemID + AudioEndMS let the caller
	// truncate unplayed audio correctly on barge-in.
	ResponseID   string
	ItemID       string
	AudioStartMS int
	AudioEndMS   int
	Usage        RealtimeUsage
	DroppedAudio uint64

	// Error (RealtimeEventError)
	Err error
}

type RealtimeEventType string

type RealtimePricing struct {
	TextInput        float64
	TextCachedInput  float64
	TextOutput       float64
	AudioInput       float64
	AudioCachedInput float64
	AudioOutput      float64

	// Some realtime vendors bill connection media by duration and text
	// conversation items by count rather than by tokens. These optional
	// dimensions coexist with token pricing so provider adapters do not
	// leak billing rules into the generic thread runtime.
	AudioInputPerMinute  float64
	AudioOutputPerMinute float64
	TextInputPerMessage  float64
}

type RealtimeProvider interface {
	Name() string
	Models() map[ModelTier]string
	// Pricing returns the model-specific text and audio rates. Realtime
	// providers report input/output audio separately, and cached audio has
	// its own rate, so the ordinary three-number LLM price tuple is not
	// expressive enough here.
	Pricing(model string) RealtimePricing

	// DefaultVoice returns the provider's preferred voice when the
	// caller doesn't specify one. Empty string is acceptable for
	// providers that pick a voice server-side.
	DefaultVoice() string

	// DefaultTranscriptionModel returns the provider-native streaming
	// transcription model to request for input captions. Providers that
	// do not support a separate transcription model may return empty.
	DefaultTranscriptionModel() string

	// Open establishes a session. ctx propagates to the underlying
	// connection; cancelling ctx closes the session cleanly. The
	// returned session is bound to ctx for its lifetime.
	Open(ctx context.Context, opts RealtimeSessionOpts) (RealtimeSession, error)
}

type RealtimeSession interface {
	// SendAudio pushes a chunk of input audio in the configured
	// AudioInFmt to the model. Non-blocking on the model side — the
	// session buffers and the network does its own back-pressure.
	SendAudio(pcm []byte) error

	// SendText injects a text message into the conversation. role is
	// one of "user", "system", "assistant". Used by main to deliver
	// out-of-band context to the realtime worker without speaking it
	// into the call (e.g. "[from:main] caller is VIP, be warm").
	SendText(role, text string) error

	// SendToolResult delivers one tool result without starting the next model
	// response. This separation lets the generic thinker submit every result
	// from a parallel tool batch before requesting one continuation.
	SendToolResult(callID, result string, isError bool) error

	// RequestResponse asks the provider to continue after text or tool items
	// have been added to its conversation.
	RequestResponse() error

	// UpdateConfiguration replaces mutable instructions and tools while
	// preserving the provider-side conversation.
	UpdateConfiguration(instructions string, tools []NativeTool) error

	// RestoreConversation appends bounded transcript history without
	// triggering a response. It is used after a provider-enforced session
	// renewal so the worker can continue rather than becoming a blank agent.
	RestoreConversation(messages []Message) error

	// Interrupt cancels the model's current utterance. Used when new
	// user audio arrives during model speech, or when main sends a
	// course-correction the worker decides to act on immediately.
	Interrupt() error

	// Truncate removes the unplayed suffix of an assistant audio item after
	// client-managed WebSocket playback is interrupted.
	Truncate(itemID string, audioEndMS int) error

	// Events returns the unified event stream from the session:
	// audio out, transcript fragments, tool calls, lifecycle events,
	// errors. Channel closes when the session ends.
	Events() <-chan RealtimeEvent

	// Close terminates the session and releases resources. Safe to
	// call multiple times.
	Close() error
}

type RealtimeSessionOpts struct {
	Model              string       // provider-specific model id
	Voice              string       // empty = provider default
	Instructions       string       // complete thread system prompt
	Tools              []NativeTool // tool schemas to expose to the model
	AudioInFmt         AudioFormat
	AudioOutFmt        AudioFormat
	AudioInRate        int    // Hz; 0 = provider default
	AudioOutRate       int    // Hz; 0 = provider default
	Reasoning          string // provider-supported reasoning effort; empty/auto = default
	SafetyIdentifier   string // stable privacy-preserving end-user/session identifier
	TranscribeInput    bool
	TranscriptionModel string // empty = provider default
}

type RealtimeThinker struct {
	*Thinker
	// contains filtered or unexported fields
}

type RealtimeUsage struct {
	TotalTokens       int
	InputTokens       int
	OutputTokens      int
	TextInputTokens   int
	TextCachedTokens  int
	TextOutputTokens  int
	AudioInputTokens  int
	AudioCachedTokens int
	AudioOutputTokens int

	AudioInputSeconds  float64
	AudioOutputSeconds float64
	TextInputMessages  int
}

type ReasoningLevel string

type ReasoningProvider interface {
	WithReasoning(settings ReasoningSettings) LLMProvider
}

type ReasoningSettings struct {
	Level ReasoningLevel
}

type Request struct {
	Model    string    `json:"model"`
	Messages []Message `json:"messages"`
	Stream   bool      `json:"stream"`
}

type RunMode string

type Scenario struct {
	Name       string
	Directive  string
	MCPServers []MCPServerConfig // {{dataDir}} in Env values is replaced at runtime
	Providers  []ProviderConfig  // multi-provider pool config (optional)
	DataSetup  func(t *testing.T, dir string)
	Phases     []Phase
	Timeout    time.Duration // hard cap for entire scenario
}

type ScenarioAuditEntry struct {
	Time string            `json:"time"`
	Tool string            `json:"tool"`
	Args map[string]string `json:"args"`
}

type ServerToolResult struct {
	ToolName string `json:"tool_name"`
	Code     string `json:"code,omitempty"`   // code that was executed
	Output   string `json:"output,omitempty"` // stdout/result
	Error    string `json:"error,omitempty"`  // stderr if any
}

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

type SessionEntry struct {
	// Sequence is a per-session, monotonically increasing cursor. It makes the
	// durable history safe for consumers that need to observe a running thread:
	// unlike the in-memory context window, this cursor does not move when old
	// messages are trimmed from the model prompt.
	Sequence      int64                  `json:"seq,omitempty"`
	Timestamp     time.Time              `json:"ts"`
	Role          string                 `json:"role"` // "system", "user", "assistant", "tool_result", "_compacted"
	Content       string                 `json:"content"`
	Parts         []ContentPart          `json:"parts,omitempty"`
	ToolCalls     []NativeToolCall       `json:"tool_calls,omitempty"`
	ToolResults   []ToolResult           `json:"tool_results,omitempty"`
	Reasoning     string                 `json:"reasoning,omitempty"`
	ProviderState *ProviderResponseState `json:"provider_state,omitempty"`
	Summary       string                 `json:"summary,omitempty"`        // for _compacted entries
	OrigCount     int                    `json:"original_count,omitempty"` // how many messages were compacted
	TokensIn      int                    `json:"tokens_in,omitempty"`
	TokensOut     int                    `json:"tokens_out,omitempty"`
	Iteration     int                    `json:"iteration,omitempty"`
}

type SpawnOpts struct {
	MediaParts      []ContentPart
	ProviderName    string // override provider from pool (empty = inherit parent)
	Model           string // starting model tier (empty = default large)
	Reasoning       ReasoningLevel
	InitialMessages []string
	ParentID        string   // "main" or parent thread ID (empty = "main")
	Depth           int      // depth in the spawn tree (0 = child of main)
	MCPNames        []string // MCP servers whose tools preload into the child's activeTools at boot
	// Tools, when set, preloads specific tool names (across any server)
	// into the child's activeTools at boot. Complements MCPNames:
	// MCPNames = "give me everything from these servers", Tools =
	// "give me exactly these names". Both are additive. Used by the
	// privileged HTTP spawn endpoint (POST /threads/{id}) for system
	// callers that know which tools they need; the LLM-driven spawn
	// tool path leaves this nil and uses mcps=[…] instead.
	Tools        []string
	BuiltinTools []string // provider builtin overrides (nil = inherit, empty = none)
	DeferRun     bool     // if true, don't start Run() — call StartAll() later
	System       bool     // true for platform-owned system threads such as unconscious
	Ephemeral    bool     // temporary caller-owned thread; cleanup also removes session history
	// Paused: if true, the thread spawns in paused state. Run() loop
	// blocks at the top of its first iteration until either an inbox
	// event arrives (an explicit `send` from the leader) OR the
	// thinker is unpaused via PauseAll(false). Useful for
	//   - "configure-then-launch" patterns where the leader spawns
	//     several workers atomically before any of them think
	//   - cautious/learn modes that want children to wait for explicit
	//     instruction rather than acting on the directive alone
	//   - debugging — inspect the worker before it does anything
	Paused bool
	// BypassNoSpawn skips the no_spawn MCP filter. Set by the
	// authenticated HTTP spawn endpoint (POST /threads/{id}) where
	// the caller has the core API key — the system itself is asking
	// for a privileged sub-thread (e.g. channelchat's chat thread
	// needs the `channels` MCP to reply to users). The LLM-driven
	// spawn tool path never sets this, so an in-agent worker still
	// can't escalate by attaching a no_spawn MCP.
	BypassNoSpawn bool
	// Realtime: if true, construct a realtime (voice/audio) thread
	// driven by a RealtimeProvider session instead of the standard
	// request/response Thinker. ProviderName must resolve to a
	// registered RealtimeProvider (e.g. "openai-realtime"); when
	// empty, the pool's RealtimeDefault is used. SpawnWithOpts will
	// refuse with a clear error if no realtime provider is available.
	Realtime bool
	// Voice: realtime voice id (e.g. "alloy"). Empty = provider's
	// default. Ignored when Realtime is false.
	Voice string
	// AudioIn: PCM audio chunks pushed by the caller (telephony
	// bridge, browser WebRTC, mic source). The realtime thread reads
	// these and forwards to session.SendAudio. nil = no inbound audio
	// (text-only realtime — useful for tests). Ignored when
	// Realtime is false.
	AudioIn chan []byte
	// AudioOut: PCM audio chunks the realtime thread writes when the
	// model speaks. Caller plays/streams them. nil = audio output
	// silently dropped. Ignored when Realtime is false.
	AudioOut chan []byte
	// AudioControl carries low-volume playback controls such as "interrupt"
	// to the WebSocket bridge so telephony clients can clear queued audio.
	AudioControl chan string
	// BridgeDisconnectTTL asks core to stop this realtime thread if its audio
	// bridge remains disconnected for the duration. Zero disables cleanup.
	BridgeDisconnectTTL time.Duration
	// InitialMessage is sent to the realtime provider after the first audio
	// bridge connects, then immediately requests a response.
	InitialMessage string
}

type StreamChoice struct {
	Delta Delta `json:"delta"`
}

type StreamEvent struct {
	Choices []StreamChoice `json:"choices"`
	Usage   *Usage         `json:"usage,omitempty"`
}

type Subscription struct {
	ID      string
	C       chan Event
	Wake    chan struct{} // signaled on every new event delivery
	Dropped uint64        // atomic
	// contains filtered or unexported fields
}

type SystemBreakdown struct {
	Base            int `json:"base"`             // up to "CORE TOOLS — always available:"
	CoreTools       int `json:"core_tools"`       // "CORE TOOLS — always available:" to next [ marker
	RetrievedTools  int `json:"retrieved_tools"`  // [available tools — matched to your current context] block (RAG per-turn)
	MCPServers      int `json:"mcp_servers"`      // [AVAILABLE MCP SERVERS] block
	MCPToolDocs     int `json:"mcp_tool_docs"`    // [MCP TOOLS — available for sub-threads] block
	Providers       int `json:"providers"`        // [AVAILABLE PROVIDERS] block
	ActiveThreads   int `json:"active_threads"`   // [ACTIVE THREADS] block
	SafetyMode      int `json:"safety_mode"`      // [SAFETY MODE: ...] block
	Skills          int `json:"skills"`           // [LEARNED SKILLS] block
	BlobHint        int `json:"blob_hint"`        // [FILE HANDLES] block
	PreviousContext int `json:"previous_context"` // [PREVIOUS CONTEXT] block (from session load)
	Directive       int `json:"directive"`        // [DIRECTIVE — EXECUTE ON STARTUP] block
	Other           int `json:"other"`            // text not matching any known marker
	Total           int `json:"total"`
}

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

type TelemetryEvent struct {
	ID         string          `json:"id"`
	InstanceID int64           `json:"instance_id,omitempty"`
	ThreadID   string          `json:"thread_id"`
	Type       string          `json:"type"`
	Time       time.Time       `json:"time"`
	Data       json.RawMessage `json:"data"`
}

type ThinkRate int

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

type Thread struct {
	ID     string
	Name   string // human-readable label, separate from ID. ID is immutable;
	System bool   // platform-managed thread, not an agent-addressable worker
	// Name can be edited via update without touching parent_id
	// references or session storage. Empty means "use ID for display".
	ParentID     string   // "main" or parent thread ID
	Depth        int      // 0 = child of main, 1 = grandchild, etc.
	Directive    string   // original directive before tool docs
	MCPNames     []string // MCP server names this thread connected to
	Thinker      *Thinker
	Realtime     *RealtimeThinker // non-nil for realtime (voice/audio) threads; runs in place of Thinker.Run
	IsRealtime   bool
	Voice        string
	ProviderName string
	Ephemeral    bool

	// BridgeDisconnectTTL is set only for caller-owned realtime sessions
	// (the dashboard currently uses it). A zero value preserves the existing
	// sidecar/telephony behaviour: losing the audio bridge does not kill the
	// realtime worker.
	BridgeDisconnectTTL time.Duration

	Parent   *Thinker
	Children *ThreadManager // non-nil if this thread can spawn (depth < MaxSpawnDepth)
	Tools    map[string]bool
	Started  time.Time
	// contains filtered or unexported fields
}

type ThreadDoneData struct {
	ParentID string `json:"parent_id"`
	Result   string `json:"result,omitempty"`
}

type ThreadInfo struct {
	ID           string
	Name         string // human-readable display label; empty = render id
	System       bool   // platform-managed; hidden from and immutable by agent tools
	ParentID     string // "main" or parent thread ID
	Depth        int
	Directive    string
	Tools        []string
	MCPNames     []string
	Running      bool
	Iteration    int
	Rate         ThinkRate
	Model        ModelTier
	Reasoning    ReasoningLevel
	Provider     string // active provider name
	Realtime     bool
	Voice        string
	Started      time.Time
	ContextMsgs  int
	ContextChars int
	SubThreads   int // number of direct children
}

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

type ThreadMessageData struct {
	From    string `json:"from"`
	To      string `json:"to"`
	Message string `json:"message"`
}

type ThreadRenamedData struct {
	OldID    string `json:"old_id"`
	NewID    string `json:"new_id"`
	Name     string `json:"name,omitempty"`
	ParentID string `json:"parent_id,omitempty"`
}

type ThreadSpawnData struct {
	ParentID  string   `json:"parent_id"`
	Directive string   `json:"directive"`
	Tools     []string `json:"tools"`
	MCP       []string `json:"mcp,omitempty"`
	Realtime  bool     `json:"realtime,omitempty"`
	Voice     string   `json:"voice,omitempty"`
	Provider  string   `json:"provider,omitempty"`
}

type TokenUsage struct {
	PromptTokens     int
	CachedTokens     int
	CacheWriteTokens int
	CompletionTokens int
	AudioTokens      int // realtime providers only; billed at a separate rate
}

type ToolCallData struct {
	ID     string            `json:"id,omitempty"`
	Name   string            `json:"name"`
	Args   map[string]string `json:"args,omitempty"`
	Reason string            `json:"reason,omitempty"`
}

type ToolDef struct {
	Name        string
	Description string                                    // human-readable
	Syntax      string                                    // example usage
	Rules       string                                    // usage rules for the prompt
	Core        bool                                      // always in prompt (pace, send, done, evolve, search_tools)
	MainOnly    bool                                      // only for main thread (spawn, kill)
	ThreadOnly  bool                                      // only for sub-threads, not main (reply)
	SystemOnly  bool                                      // only for system threads (unconscious)
	MCP         bool                                      // provided by an MCP server — hidden from the per-turn tool list until activated (search_tools / spawn preload / BM25 preload)
	MCPServer   string                                    // name of the MCP server that provides this tool
	Handler     func(args map[string]string) ToolResponse // nil = handled inline by tool handler
	InputSchema map[string]any                            // JSON Schema for native tool calling (nil = auto-generated from Syntax)
	// WakeOnResult controls whether an async tool result wakes the thinker.
	// Default is always. MCP tools may override this via
	// _meta["io.apteva/wakeOnResult"] = "on_error".
	WakeOnResult WakeOnResultPolicy
}

type ToolHandler func(t *Thinker, calls []toolCall, consumed []string) (replies []string, toolNames []string, results []ToolResult)

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

type ToolLoadMode string

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

type ToolResponse struct {
	Text    string // text result (always present)
	Image   []byte // optional image (screenshot etc.) — sent as part of tool result to LLM
	IsError bool   // true when the tool returned an MCP-level isError result
}

type ToolResult struct {
	CallID             string `json:"call_id"`
	ToolName           string `json:"tool_name,omitempty"`
	Content            string `json:"content"`         // full text for first consumption; bounded archive preview thereafter
	Image              []byte `json:"image,omitempty"` // optional image (screenshot etc.)
	IsError            bool   `json:"is_error,omitempty"`
	OriginalChars      int    `json:"original_chars,omitempty"`
	OriginalBytes      int    `json:"original_bytes,omitempty"`
	OriginalImageBytes int    `json:"original_image_bytes,omitempty"`
	SHA256             string `json:"sha256,omitempty"`
	ArchiveRef         string `json:"archive_ref,omitempty"`
	ContentIsPreview   bool   `json:"content_is_preview,omitempty"`
}

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

type ToolResultData struct {
	ID                  string `json:"id,omitempty"`
	Name                string `json:"name"`
	DurationMs          int64  `json:"duration_ms"`
	Success             bool   `json:"success"`
	Result              string `json:"result,omitempty"`
	ResultOriginalBytes int    `json:"result_original_bytes"`
	ResultContextBytes  int    `json:"result_context_bytes"`
	ResultPreviewBytes  int    `json:"result_preview_bytes"`
	ResultImageBytes    int    `json:"result_image_bytes,omitempty"`
	ResultTruncated     bool   `json:"result_truncated"`
}

type Usage struct {
	PromptTokens        int                  `json:"prompt_tokens"`
	CompletionTokens    int                  `json:"completion_tokens"`
	TotalTokens         int                  `json:"total_tokens"`
	PromptTokensDetails *PromptTokensDetails `json:"prompt_tokens_details,omitempty"`
}

type WakeOnResultPolicy string

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

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