core

type AgentEvent struct {
	Type string

	// Populated per type:
	Message        AgentMessage       // message_start, message_end, user_message
	AssistantEvent *AssistantEvent    // message_update (streaming deltas)
	Text           string             // steer, user_message (plain-text prompt)
	SteerID        string             // steer
	MsgID          string             // steer, user_message (MsgID of the user message, for client dedup)
	AttachmentIDs  []string           // steers_canceled
	ToolCallID     string             // tool_execution_*
	ToolName       string             // tool_execution_*
	Args           map[string]any     // tool_execution_start
	Result         *Result            // tool_execution_end/update
	IsError        bool               // tool_execution_end
	Rejected       bool               // tool_execution_end (true only for permission denial)
	Messages       []AgentMessage     // agent_end (full conversation)
	Compaction     *CompactionPayload // compaction_end
	Error          error              // agent_error, compaction_end (non-fatal)
}

type AgentMessage struct {
	Message
	Custom map[string]any `json:"custom,omitempty"`
}

type AssistantEvent struct {
	Type         string   `json:"type"`
	ContentIndex int      `json:"content_index,omitempty"`
	Delta        string   `json:"delta,omitempty"`
	Partial      *Message `json:"partial,omitempty"`
	Message      *Message `json:"message,omitempty"`
	Error        error    `json:"-"`

	// Tool call metadata — populated for toolcall_start, toolcall_delta, toolcall_end events.
	ToolCallID  string         `json:"tool_call_id,omitempty"`
	ToolName    string         `json:"tool_name,omitempty"`
	PartialArgs map[string]any `json:"partial_args,omitempty"`

	// RateLimit — populated for the "ratelimit" event, emitted once at stream
	// start from the response headers (independent of message success).
	RateLimit *RateLimit `json:"rate_limit,omitempty"`
}

type CompactionPayload struct {
	Summary        string   `json:"summary"`
	TokensBefore   int      `json:"tokens_before"`
	TokensAfter    int      `json:"tokens_after"`
	ReadFiles      []string `json:"read_files,omitempty"`
	ModifiedFiles  []string `json:"modified_files,omitempty"`
	SummaryMsgID   string   `json:"summary_msg_id,omitempty"`
	FirstKeptMsgID string   `json:"first_kept_msg_id,omitempty"`
	Usage          *Usage   `json:"usage,omitempty"`
}

type CompactionSettings struct {
	Enabled       bool `json:"enabled"`
	ReserveTokens int  `json:"reserve_tokens"`       // keep free for model output + thinking
	KeepRecent    int  `json:"keep_recent"`          // tokens of recent context to keep verbatim
	CompactAt     int  `json:"compact_at,omitempty"` // soft threshold in tokens; 0 = use the model window
}

type Content struct {
	Type string `json:"type"`

	// text
	Text string `json:"text,omitempty"`
	// TextSignature carries provider round-trip metadata for a text/message
	// block so the exact item can be replayed on the next request. For the
	// OpenAI Responses API this is a small JSON blob {id, phase} — the model's
	// output message id and its phase ("commentary"/"final_answer"). OpenAI
	// warns that dropping the phase when replaying manually causes "early
	// stopping and other misbehavior", which manifests as empty/stalled turns.
	// Opaque to everything except the provider that produced it.
	TextSignature string `json:"text_signature,omitempty"`

	// thinking
	Thinking          string `json:"thinking,omitempty"`
	ThinkingSignature string `json:"thinking_signature,omitempty"`
	Redacted          bool   `json:"redacted,omitempty"`

	// image/document
	Data     string `json:"data,omitempty"`
	MimeType string `json:"mime_type,omitempty"`
	Filename string `json:"filename,omitempty"`
	// attachment reference (image/document stored out-of-line in the blob store).
	// When AttachmentID is set, Data is empty in persisted/in-memory history and is
	// rehydrated only at request time by the materializer. Size is the decoded byte
	// size, kept so budgeting/sizing works without reading the blob.
	AttachmentID   string `json:"attachment_id,omitempty"`
	AttachmentSize int64  `json:"attachment_size,omitempty"`

	// tool_call
	ToolCallID string         `json:"tool_call_id,omitempty"`
	ToolName   string         `json:"tool_name,omitempty"`
	Arguments  map[string]any `json:"arguments,omitempty"`
	// ToolCallItemID is the provider's output-item id for a tool_call (OpenAI
	// Responses: the "fc_..." id, distinct from ToolCallID which is the
	// "call_id" that pairs the call with its function_call_output). Preserved
	// so the function_call item can be replayed with its original id, matching
	// how the reasoning item that preceded it was paired. Empty for providers
	// that don't use a separate item id.
	ToolCallItemID string `json:"tool_call_item_id,omitempty"`
}

type ContextEstimate struct {
	Tokens         int // total estimated context tokens
	UsageTokens    int // from provider-reported usage (0 if none valid)
	TrailingTokens int // estimated tokens for messages after last valid usage
	OverheadTokens int // system prompt + tool specs
}

type DocumentCapableProvider interface {
	SupportsDocuments() bool
}

type EmptyResponseError struct {
	// Provider is the provider name (e.g. "openai").
	Provider string
	// Usage carries the token usage the provider reported for the empty
	// response, if any. An empty completed response can still bill input
	// tokens; the loop must account for this before retrying so a stall can't
	// silently bypass the budget. nil when the provider reported no usage.
	Usage *Usage
}

type ExecuteFunc func(ctx context.Context, params map[string]any, onUpdate func(Result)) (Result, error)

type LoadedMoaConfig struct {
	Config      MoaConfig
	MCPDisabled MCPDisableSources
}

type LockKeyFunc func(args map[string]any) string

type MCPDisablePolicy struct {
	Global  map[string]struct{}
	Project map[string]struct{}
	Session map[string]struct{}
}

type MCPDisableResolution struct {
	// Disabled is true if any scope vetoes the server.
	Disabled bool
	// Scopes lists every scope that vetoes it, in stable order (global,
	// project, session). Empty when the server is enabled.
	Scopes []MCPDisableScope
}

type MCPDisableScope string

type MCPDisableSources struct {
	// Global lists names vetoed by the global config.
	Global []string
	// Project lists names vetoed by the project config. It is populated only
	// when ProjectTrusted is true; an untrusted project's preference is never
	// silently applied.
	Project []string
	// ProjectTrusted reports whether <cwd>/.moa/config.json is trusted, i.e.
	// whether the project scope is writable/applicable at all.
	ProjectTrusted bool
}

type MCPServer struct {
	Command string            `json:"command"`
	Args    []string          `json:"args"`
	Env     map[string]string `json:"env"`
	// URL is the streamable-HTTP endpoint of a remote MCP server. Only http and
	// https are accepted. It is an outbound connection to an endpoint the
	// operator configured, so it carries the same trust as the rest of the file.
	URL string `json:"url"`
	// Headers are extra HTTP headers sent on every request to URL (typically
	// Authorization). Ignored for command-based servers.
	Headers map[string]string `json:"headers"`
}

type Message struct {
	MsgID     string    `json:"msg_id,omitempty"`
	Role      string    `json:"role"`
	Content   []Content `json:"content"`
	Timestamp int64     `json:"timestamp"`

	// assistant-only
	Provider     string `json:"provider,omitempty"`
	Model        string `json:"model,omitempty"`
	Usage        *Usage `json:"usage,omitempty"`
	StopReason   string `json:"stop_reason,omitempty"`
	ErrorMessage string `json:"error_message,omitempty"`

	// tool_result-only
	ToolCallID string `json:"tool_call_id,omitempty"`
	ToolName   string `json:"tool_name,omitempty"`
	IsError    bool   `json:"is_error,omitempty"`
}

type MoaConfig struct {
	DisableSandbox         bool                 `json:"disable_sandbox"`                         // Deprecated: use PathScope. YOLO mode: allow any file path
	AllowedPaths           []string             `json:"allowed_paths"`                           // Additional directories accessible outside workspace
	PathScope              string               `json:"path_scope"`                              // "workspace", "unrestricted", or "" (derive from permission mode)
	Permissions            PermissionsConfig    `json:"permissions"`                             // Tool execution permission policy
	PinnedModels           []string             `json:"pinned_models"`                           // Model IDs pinned for Ctrl+P cycling
	BraveAPIKey            string               `json:"brave_api_key"`                           // Brave Search API key for web_search tool
	MCPServers             map[string]MCPServer `json:"mcp_servers"`                             // MCP tool server connections
	DisabledMCPServers     []string             `json:"disabled_mcp_servers,omitempty"`          // MCP server names vetoed at this config level (server stays configured but is not started)
	TrustedMCPPaths        []string             `json:"trusted_mcp_paths"`                       // Project paths trusted for .mcp.json auto-load
	TrustedProjectPaths    []string             `json:"trusted_project_paths"`                   // Project paths trusted for .moa/config.json + .moa/tools/* auto-load
	PlanReviewModel        string               `json:"plan_review_model"`                       // Model for plan reviewer (default: current model)
	PlanReviewThinking     string               `json:"plan_review_thinking"`                    // Thinking level for plan reviewer (default: "low")
	CodeReviewModel        string               `json:"code_review_model,omitempty"`             // Model for code reviewer (default: plan review model)
	CodeReviewThinking     string               `json:"code_review_thinking,omitempty"`          // Thinking level for code reviewer (default: plan review thinking)
	MaxBudget              float64              `json:"max_budget"`                              // Max USD per agent run. 0 = unlimited.
	MaxTurns               int                  `json:"max_turns,omitempty"`                     // Max agent turns per run. 0 = unlimited.
	MaxToolCallsPerTurn    int                  `json:"max_tool_calls_per_turn,omitempty"`       // Max tool calls per turn. 0 = unlimited.
	MaxRunDurationStr      string               `json:"max_run_duration,omitempty"`              // Max run duration as Go duration string (e.g. "30m"). Empty = unlimited.
	MemoryEnabled          *bool                `json:"memory_enabled,omitempty"`                // nil = true (enabled by default)
	AutoVerify             *bool                `json:"auto_verify,omitempty"`                   // nil = false (disabled by default)
	PersistentShell        *bool                `json:"persistent_shell,omitempty"`              // nil = true (enabled by default)
	UpdateCheck            *bool                `json:"update_check,omitempty"`                  // nil = true (check stable releases at most every 6h)
	CacheTTL               string               `json:"cache_ttl,omitempty"`                     // Interactive prompt-cache TTL: "5m" (default) or "1h". Only "1h" changes behavior.
	STTLanguage            string               `json:"stt_language,omitempty"`                  // Speech-to-text language as ISO-639-1 (e.g. "es", "en"). Empty = "en"; "auto" lets the model detect.
	STTModel               string               `json:"stt_model,omitempty"`                     // Speech-to-text model id. Empty = "gpt-transcribe".
	STTVocabulary          []string             `json:"stt_vocabulary,omitempty"`                // Words the transcriber tends to get wrong (names, jargon). Keep it short: long lists hurt accuracy.
	SubagentMaxTurns       int                  `json:"subagent_max_turns,omitempty"`            // Max turns per subagent run. 0 = use package default.
	SubagentMaxRunDuration string               `json:"subagent_max_run_duration,omitempty"`     // Max subagent run duration as Go duration string. Empty = use package default.
	SubagentMaxConcurrent  int                  `json:"subagent_max_concurrent_async,omitempty"` // Max concurrent async subagents. 0 = use package default.
}

type Model struct {
	ID        string   `json:"id"`
	Provider  string   `json:"provider"`
	API       string   `json:"api"`
	Name      string   `json:"name"`
	MaxInput  int      `json:"max_input"`
	MaxOutput int      `json:"max_output"`
	Pricing   *Pricing `json:"pricing,omitempty"`
}

type ModelEntry struct {
	Model Model
	Alias string // shortest alias, empty if none
}

type PermissionsConfig struct {
	Mode  string   `json:"mode"`  // "yolo", "ask", or "auto" (default: "yolo")
	Allow []string `json:"allow"` // Glob patterns auto-approved in ask mode: "Bash(npm:*)", "edit"
	Deny  []string `json:"deny"`  // Glob patterns always denied (checked before allow)
	Model string   `json:"model"` // Model for auto mode evaluator (e.g. "haiku")
	Rules []string `json:"rules"` // Natural language rules for auto mode
}

type Pricing struct {
	Input      float64 `json:"input"`       // $/M input tokens
	Output     float64 `json:"output"`      // $/M output tokens
	CacheRead  float64 `json:"cache_read"`  // $/M cached input tokens
	CacheWrite float64 `json:"cache_write"` // $/M cache write tokens

	// Tiers holds additional pricing tiers keyed by a context-length
	// threshold, for providers that charge more once the prompt exceeds a
	// given size. Must be sorted ascending by Threshold.
	Tiers []PricingTier `json:"tiers,omitempty"`
}

type PricingTier struct {
	Threshold  int     `json:"threshold"`   // tier applies when Input+CacheRead >= this
	Input      float64 `json:"input"`       // $/M input tokens
	Output     float64 `json:"output"`      // $/M output tokens
	CacheRead  float64 `json:"cache_read"`  // $/M cached input tokens
	CacheWrite float64 `json:"cache_write"` // $/M cache write tokens
}

type Provider interface {
	Stream(ctx context.Context, req Request) (<-chan AssistantEvent, error)
}

type ProviderUnwrapper interface {
	Unwrap() Provider
}

type QuotaExceededError struct {
	// Provider is the provider name (e.g. "openai", "anthropic").
	Provider string
	// Message is the human-readable message from the provider, if any.
	Message string
	// PlanType is the subscription plan reported by the provider (may be empty).
	PlanType string
	// ResetsIn is the time until the exhausted window resets (0 if unknown).
	ResetsIn time.Duration
	// ResetsAt is the wall-clock reset time (zero if unknown).
	ResetsAt time.Time
	// Window labels which limit was hit ("5h", "weekly", or "" if unknown).
	Window string
}

type RateLimit struct {
	Status              string  `json:"status,omitempty"`               // allowed / allowed_warning / rejected
	RepresentativeClaim string  `json:"representative_claim,omitempty"` // window that currently binds: five_hour / seven_day / overage / ...
	FiveHourUtil        float64 `json:"five_hour_util"`                 // [0,1], or -1 if unknown
	SevenDayUtil        float64 `json:"seven_day_util"`                 // [0,1], or -1 if unknown
	OverageStatus       string  `json:"overage_status,omitempty"`
	OverageUtil         float64 `json:"overage_util"` // [0,1], or -1 if unknown
}

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

type Request struct {
	Model    Model
	System   string     // System prompt
	Messages []Message  // Conversation history (user, assistant, tool_result)
	Tools    []ToolSpec // Available tools for tool_use
	Options  StreamOptions
}

type Result struct {
	Content []Content `json:"content"`
	IsError bool      `json:"is_error,omitempty"`
	// Custom annotates the recorded tool result with facts the UI needs but the
	// model does not — it is merged into the tool_result message's own Custom
	// map and never reaches the provider. The subagent tool uses it to record
	// which job a call spawned, a link that is otherwise lost on restart.
	Custom map[string]any `json:"custom,omitempty"`
}

type SteerItem struct {
	ID   string `json:"id"`
	Text string `json:"text"`
	// Content, when non-nil, is the full payload of a steer (text plus image or
	// other content blocks). It is injected with NewUserMessageWithContent. A
	// nil Content means a plain-text steer carried in Text.
	Content []Content `json:"content,omitempty"`
	// Command, when non-empty, marks this item as a queued command (a BARRIER):
	// it holds the raw normalized command line (e.g. "/compact", "/model sonnet").
	// A barrier item is never injected as a conversation message — it stops the
	// queue drain, and is executed at the next idle point (RunEnded) by the bus.
	// Invariant: a barrier carries no Content, and an Internal item is never a
	// barrier.
	Command string `json:"command,omitempty"`
	// Internal marks a system-generated steer (e.g. a subagent/bash completion
	// injected into the parent run) as opposed to a user-typed message. Internal
	// steers are delivered to the agent but excluded from the authoritative
	// queue snapshot, since their delivery event is suppressed and they must not
	// surface as user-visible "queued" chips.
	Internal bool `json:"-"`
}

type StreamOptions struct {
	Temperature    *float64 `json:"temperature,omitempty"`
	MaxTokens      *int     `json:"max_tokens,omitempty"`
	APIKey         string   `json:"-"`
	ThinkingLevel  string   `json:"thinking_level,omitempty"`
	CacheRetention string   `json:"cache_retention,omitempty"`
}

type Tool struct {
	Name        string          `json:"name"`
	Label       string          `json:"label"`
	Description string          `json:"description"`
	Parameters  json.RawMessage `json:"parameters"`
	Execute     ExecuteFunc     `json:"-"`
	Effect      ToolEffect      `json:"-"` // scheduling hint for conflict-aware execution
	LockKey     LockKeyFunc     `json:"-"` // required when Effect is EffectWritePath
}

type ToolCallDecision struct {
	Block  bool
	Reason string
	Kind   string // optional classification (e.g. permission, policy)
}

type ToolEffect int

type ToolSpec struct {
	Name        string          `json:"name"`
	Description string          `json:"description"`
	Parameters  json.RawMessage `json:"parameters"`
}

type TranscribeOptions struct {
	// Language is an ISO-639-1 hint (e.g. "es", "en"). Empty lets the provider
	// auto-detect. Setting it avoids mis-detection on short/ambiguous audio.
	Language string
	// Prompt biases the decoder toward specific vocabulary/spelling. Optional.
	Prompt string
	// Model is the provider's model id. Empty lets the provider pick its own
	// default, so callers that do not care keep working.
	Model string
}

type Transcriber interface {
	Transcribe(ctx context.Context, audio io.Reader, filename string, opts TranscribeOptions) (string, error)
}

type Usage struct {
	Input       int `json:"input"`
	Output      int `json:"output"`
	CacheRead   int `json:"cache_read"`
	CacheWrite  int `json:"cache_write"`
	TotalTokens int `json:"total_tokens"`
}