tools

type ApprovalManager interface {
	// RequestApproval asks the user to approve a tool execution.
	// Returns an ApprovalResult with the outcome and optional context.
	RequestApproval(requestID, toolName, riskLevel, prompt string, extras map[string]string) ApprovalResult
}

type ApprovalResult struct {
	Approved    bool   `json:"approved"`
	Reason      string `json:"reason,omitempty"`       // "rejected", "timed_out", "cancelled"
	UserComment string `json:"user_comment,omitempty"` // Optional feedback from user
}

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

type AskUserOption struct {
	Label       string `json:"label"`
	Value       string `json:"value,omitempty"`
	Description string `json:"description,omitempty"`
}

type AskUserRequest struct {
	Question    string          `json:"question"`
	Header      string          `json:"header,omitempty"`
	Options     []AskUserOption `json:"options,omitempty"`
	MultiSelect bool            `json:"multi_select,omitempty"`
	Default     string          `json:"default,omitempty"`
}

type AskUserService interface {
	// Ask presents req to the user and returns their response.
	Ask(ctx context.Context, req AskUserRequest) (string, error)
}

type AuditEntry struct {
	Timestamp time.Time `json:"timestamp"`
	Tool      string    `json:"tool"`
	Args      string    `json:"args,omitempty"`
	RiskLevel string    `json:"risk_level"`
	Category  string    `json:"category"`
	Action    string    `json:"action"` // "allowed", "denied", "prompted", "allowed_path_hit"
	Reasoning string    `json:"reasoning,omitempty"`
	Source    string    `json:"source,omitempty"` // "classifier", "policy", "user_override"
	SessionID string    `json:"session_id,omitempty"`
	Workspace string    `json:"workspace,omitempty"`

	// PathTier is the filesystem path-tier when the tool operates on a file
	// (e.g. "workspace", "external", "sensitive"). Empty for non-file tools.
	// SP-068 SP-127 synergy: enables consumers to distinguish path-tier
	// elevation from risk-tier without parsing reasoning strings.
	PathTier string `json:"path_tier,omitempty"`

	// FileMode is "read" or "write" for file operations. Empty for
	// non-file operations.
	FileMode string `json:"file_mode,omitempty"`
}

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

type BackgroundNotifier interface {
	NotifyCompletion(sessionID, kind, content string)
}

type BackgroundProcess struct {
	ID         string    // "bg-<sanitized-prefix>-<random-hex>"
	Cmd        *exec.Cmd // the running process (nil after exit)
	Process    *os.Process
	OutputPath string // path to accumulated output temp file
	Dir        string // working directory
	Command    string // original command string
	Kind       string // "shell" (default), "automate", etc.
	StartedAt  time.Time
	LastPolled time.Time
	// contains filtered or unexported fields
}

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

type BatchVisionRequest struct {
	Images  [][]byte
	Prompts []string
	Mode    string // prompt template mode; ignored if Prompts is non-empty
}

type BatchVisionResult struct {
	Results       []VisionAnalysis
	CombinedUsage *VisionUsageInfo
}

type BinaryFetchResult struct {
	Images       []api.ImageData // Populated for image URLs (and scanned PDFs)
	Text         string          // Populated for text-based PDFs
	Source       string          // Description of how content was obtained
	EffectiveURL string          // Post-redirect URL (differs from input if redirected)
}

type ChainedClassification struct {
	Subcommand string // the subcommand text (trimmed, not normalized)
	Risk       SecurityRisk
	Reasoning  string // human-readable why
	Category   RiskCategory
}

type ConflictResult struct {
	// Path is the original file path that had the conflict.
	Path string `json:"path"`
	// TheirsPath is the <path>.theirs sibling file location.
	TheirsPath string `json:"theirs_path"`
	// HashContainer is the SHA-256 hex digest of the container's content.
	HashContainer string `json:"hash_container"`
	// HashBrowser is the SHA-256 hex digest of the browser's current content.
	HashBrowser string `json:"hash_browser"`
	// Message is a human-readable explanation.
	Message string `json:"message"`
}

type EventPublisher interface {
	Publish(eventType string, data any)
}

type FileAccessClassifier interface {
	// ClassifyFileAccess returns the Gate 1 verdict for a file path:
	// "allow" (proceed), "prompt" (fall through to gate), "deny" (error).
	ClassifyFileAccess(ctx context.Context, filePath, resolvedPath, mode string) string

	// IsFolderSessionAllowed reports whether absPath sits under a folder
	// the user has allowlisted for the rest of the session.
	IsFolderSessionAllowed(absPath string) bool
}

type FileAccessPrompter interface {
	// PromptFileAccess asks the user to approve out-of-workspace access.
	// toolName is the calling tool; filePath is the user-supplied path;
	// resolvedPath is the canonical target ("" when unresolvable); mode
	// is "read" or "write". Returns a context carrying the security
	// bypass token and true when approved, or the original context and
	// false on deny or when no prompt surface is available.
	PromptFileAccess(ctx context.Context, toolName, filePath, resolvedPath, mode string) (context.Context, bool)
}

type FileMetadata struct {
	// BrowserSeq is the latest browser-originated sequence number for this file.
	// Bumped each time the user makes an edit in the browser editor.
	BrowserSeq int64 `json:"browser_seq"`

	// ContainerSeq is the latest container-originated sequence number for this file.
	// Bumped each time the agent writes to this file via a tool call.
	ContainerSeq int64 `json:"container_seq"`

	// LastSyncedBrowser is the browser_seq value that the container has last
	// observed. When BrowserSeq > LastSyncedBrowser, the browser has unsynced
	// edits from the container's perspective.
	LastSyncedBrowser int64 `json:"last_synced_browser"`

	// LastSyncedContainer is the container_seq value that the browser has last
	// observed. When ContainerSeq > LastSyncedContainer, the container has
	// unsynced writes from the browser's perspective.
	LastSyncedContainer int64 `json:"last_synced_container"`

	// ModifiedAt is the last time any sync-relevant change occurred for this file.
	ModifiedAt time.Time `json:"modified_at"`
}

type GitApprovalPrompter interface {
	PromptForApproval(command string) (bool, error)
}

type GitCommitFlowExecutor interface {
	ExecuteGitCommitFlow() (string, error)
}

type GitOperation struct {
	Operation GitOperationType `json:"operation"`
	Args      string           `json:"args,omitempty"`
}

type GitOperationType string

type HeartbeatLostError struct {
	SessionID     string
	LastHeartbeat time.Time
}

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

type HeartbeatPayload struct {
	// Timestamp is the server-side or client-side time of the heartbeat.
	Timestamp string `json:"timestamp"`
}

type ImageAnalysisResponse struct {
	Success         bool                   `json:"success"`
	ToolInvoked     bool                   `json:"tool_invoked"`
	InputResolved   bool                   `json:"input_resolved"`
	OCRAttempted    bool                   `json:"ocr_attempted"`
	InputType       string                 `json:"input_type"` // "local_file", "remote_url", "unknown"
	InputPath       string                 `json:"input_path"`
	ErrorCode       string                 `json:"error_code,omitempty"`
	ErrorMessage    string                 `json:"error_message,omitempty"`
	ExtractedText   string                 `json:"extracted_text,omitempty"`
	OutputTruncated bool                   `json:"output_truncated,omitempty"`
	OriginalChars   int                    `json:"original_chars,omitempty"`
	ReturnedChars   int                    `json:"returned_chars,omitempty"`
	FullOutputPath  string                 `json:"full_output_path,omitempty"` // Path to full OCR/analysis text when truncated
	Analysis        *VisionAnalysis        `json:"analysis,omitempty"`
	SupportedInput  ImageAnalysisSupported `json:"supported_input"`
}

type ImageAnalysisSupported struct {
	RemoteURL     bool   `json:"remote_url"`
	LocalFile     bool   `json:"local_file"`
	ImageFormats  bool   `json:"image_formats"`  // jpg, png, gif, webp, etc.
	PDFSupport    bool   `json:"pdf_support"`    // PDF support status
	PDFWorkaround string `json:"pdf_workaround"` // Instructions for PDF handling
	MaxFileSizeMB int    `json:"max_file_size_mb"`
}

type ImageData struct {
	// URI is the path or data URI of the image
	URI string `json:"uri"`
	// Base64 is the base64-encoded image data (for inline multimodal attachment)
	Base64 string `json:"base64,omitempty"`
	// MIMEType is the image MIME type (e.g., "image/png")
	MIMEType string `json:"mime_type"`
}

type MemorySearchResult struct {
	Name    string
	Preview string
	Score   float64
	Content string
}

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

type PDFPipelineResult struct {
	Text   string
	Images []api.ImageData
	Source string
}

type ParameterDef struct {
	Name        string `json:"name"`
	Type        string `json:"type"`
	Required    bool   `json:"required"`
	Description string `json:"description"`

	// Items is the JSON schema for this parameter's elements; only used
	// when Type is "array". It is serialized into the outgoing
	// function-calling schema as the `items` key.
	//
	// Every array parameter MUST declare Items: Gemini 3.x strict
	// function-calling validation rejects the entire request (HTTP 400 via
	// OpenRouter) when any array property lacks `items`. Gemini 2.5 and
	// other providers tolerated the omission. Enforced by
	// TestToolSchemas_ArrayParametersHaveItems.
	Items map[string]any `json:"items,omitempty"`
}

type PasswordPrompter interface {
	// Prompt asks the user to type a password and returns it without a
	// trailing newline. The reason is a human-readable description shown to
	// the user (e.g., "sudo apt update needs your password").
	//
	// Returns ErrNoInteractiveSurface when there is no way to prompt the
	// user (non-TTY stdin, no WebUI client, etc.).
	Prompt(ctx context.Context, reason string) (string, error)
}

type PatchEvent struct {
	// Path is the workspace-relative file path (e.g. "pkg/foo/bar.go").
	Path string `json:"path"`

	// ContainerSeq is the new container sequence number for this file after the
	// agent's write.
	ContainerSeq int64 `json:"container_seq"`

	// Content is the full file content after the agent's write. For the first
	// pass, patches are whole-file replaces.
	Content string `json:"content"`

	// BaseBrowserSeq is the browser_seq value the container observed before
	// applying this write. Used for staleness detection.
	BaseBrowserSeq int64 `json:"base_browser_seq"`
}

type PatchInPayload struct {
	// Path is the workspace-relative file path (e.g. "pkg/foo/bar.go").
	Path string `json:"path"`

	// Content is the full file content after the browser edit.
	Content string `json:"content"`

	// BrowserSeq is the browser's sequence number after this edit.
	BrowserSeq int64 `json:"browser_seq"`

	// LastSyncedContainer is the last container_seq the browser has seen for
	// this file. Used for staleness detection on the server side.
	LastSyncedContainer int64 `json:"last_synced_container"`
}

type ResponseKind int

type RetryOptions struct {
	MaxAttempts int              // total attempts (including first); 1 disables; 0 falls back to default
	BaseDelay   time.Duration    // base for exponential backoff (200ms default)
	MaxDelay    time.Duration    // cap on backoff (1600ms default)
	JitterPct   int              // ± jitter percent (20 default)
	IsRetryable func(error) bool // optional classifier; uses default if nil
	OpName      string           // for logging
	// Stats is an optional output pointer. If non-nil, DoVisionRetry
	// populates it with per-call retry statistics (retry count, total
	// sleep time, last error). Safe for use by callers that need per-call
	// metrics for JSONL records.
	Stats *RetryStats
}

type RetryStats struct {
	RetryCount    int           // number of retry attempts (0 = first attempt succeeded)
	SleepDuration time.Duration // total time spent sleeping between retries
	LastError     error         // last error (nil on success)
}

type RetryableHTTPError struct {
	StatusCode int
	Status     string
	Method     string
	URL        string
	RetryAfter time.Duration // 0 means server didn't provide one
	Err        error         // underlying cause (for HTTP errors wrapping a network failure)
}

type RiskCategory string

type RollbackResult struct {
	Output   string
	Metadata map[string]interface{}
	Success  bool
}

type SearchEngine interface {
	// Search runs a web search query and returns formatted results.
	Search(ctx context.Context, query string) (string, error)
}

type SecurityResult struct {
	Risk         SecurityRisk
	Reasoning    string
	ShouldBlock  bool
	ShouldPrompt bool
	IsHardBlock  bool
	RiskType     string       // Deprecated: Use Category instead. Risk category for user-facing messages
	Category     RiskCategory // Granular risk category for the classified operation

	// IntentConfirmation marks a tool call as requiring explicit user
	// confirmation before proceeding, but NOT because it's dangerous.
	// Used for operations that are safe but consequential — like launching
	// a long-running autonomous workflow. The approval prompt uses
	// intent-focused framing instead of security-warning framing.
	IntentConfirmation bool
}

type SecurityRisk int

type SessionHeartbeat struct {
	// SessionID is the unique identifier for this session.
	SessionID string
	// LastHeartbeat is the timestamp of the most recent heartbeat received.
	LastHeartbeat time.Time
	// JobTerminated is called when the heartbeat threshold is exceeded.
	// It receives the sessionID so the caller can clean up resources.
	// If nil, no action is taken on timeout.
	JobTerminated func(sessionID string)
}

type SkillInfo struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Path        string `json:"path"`
	Content     string `json:"content"`
	Source      string `json:"source"` // "builtin", "user", or "project"
}

type SkillLoader interface {
	// LoadSkill resolves a skill ID and returns its metadata and content.
	LoadSkill(skillID string) (*SkillInfo, error)
}

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

type StartOptions struct {
	EventBus *events.EventBus // non-nil to enable output-chunk streaming for automate sessions
}

type SymbolEntry struct {
	Name string
	Line int
}

type SymbolWithEdges struct {
	Symbols []SymbolEntry
	Edges   []codegraph.Edge
}

type SyncEnvelope struct {
	// Type is one of the EnvelopeType* constants.
	Type string `json:"type"`

	// Seq is a monotonic sequence number for this direction. The browser and
	// container each maintain their own counters; the counter increments with
	// every envelope sent.
	Seq int64 `json:"seq"`

	// Payload is the structured payload, whose shape depends on Type. For
	// patch_in, it is a PatchInPayload. For patch_out, it is a PatchEvent.
	// For heartbeat, it may be nil or a HeartbeatPayload.
	Payload any `json:"payload"`

	// Error is non-empty when the envelope carries an error response.
	Error string `json:"error,omitempty"`
}

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

type TerminalAccess interface {
	// ExecuteCommandInHidden runs a command synchronously on a hidden PTY session
	// and returns the output and exit code.
	ExecuteCommandInHidden(ctx context.Context, sessionID string, command string) (output string, exitCode int, err error)

	// GetOrCreateHiddenSessionForChat returns the session ID of an existing hidden session
	// for the given chat, or creates a new one. Returns the session ID.
	GetOrCreateHiddenSessionForChat(ctx context.Context, chatID string) (sessionID string, err error)

	// ExecuteCommandInBackground writes a command to a new hidden PTY session
	// and returns immediately with the session ID. Does NOT wait for completion.
	// Background sessions get a descriptive name and longer cleanup timeout.
	ExecuteCommandInBackground(ctx context.Context, chatID, command string) (sessionID string, err error)

	// GetBackgroundOutput returns accumulated output for a background session.
	GetBackgroundOutput(sessionID string) (output string, err error)

	// StopBackgroundSession terminates a background session by session ID.
	// Sends Ctrl+C to the PTY and closes the session. Returns an error if the
	// session is not found or is not a background session.
	StopBackgroundSession(sessionID string) error

	// IsSessionActive checks whether a session (by ID) is still active.
	// Returns false if the session doesn't exist or has terminated.
	IsSessionActive(sessionID string) bool
}

type TodoItem struct {
	ID         string `json:"id"`
	Content    string `json:"content"`
	Status     string `json:"status"`               // pending, in_progress, completed, cancelled
	Priority   string `json:"priority,omitempty"`   // high, medium, low
	ActiveForm string `json:"activeForm,omitempty"` // present-continuous phrasing
}

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

type ToolDefinition struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	Parameters  []ParameterDef `json:"parameters"`
	Required    []string       `json:"required,omitempty"` // Required parameter names

	// Hidden keeps the tool callable but omits it from the roster advertised
	// to the model. Use it for superseded tools: existing callers keep
	// working without the schema costing context on every turn.
	Hidden bool `json:"-"`

	// RequiresEmbeddings marks a tool that has no useful behavior without an
	// embedding index. The registration path filters these out when the
	// agent has no EmbeddingManager, so the model never sees a tool that
	// would fail at execution time.
	RequiresEmbeddings bool `json:"-"`
}

type ToolEnv struct {
	// EventBus for publishing events (tool_start, tool_end, etc.)
	EventBus *events.EventBus
	// WorkspaceRoot is the working directory root for path resolution
	WorkspaceRoot string
	// OutputWriter for writing tool output (stdout, logs, etc.)
	OutputWriter io.Writer
	// ApprovalManager for security approvals; nil if approvals are not supported
	ApprovalManager ApprovalManager
	// FileAccessClassifier provides Gate 1's path-tier verdict before
	// a file operation runs. Nil means no classifier is available.
	FileAccessClassifier FileAccessClassifier
	// FileAccessPrompter restores the interactive off-workspace approval
	// flow for "prompt" verdicts. When set, handlers consult it before
	// failing with the raw off-workspace error; when nil (no agent
	// context, or a surface that cannot prompt), handlers keep the
	// SP-127 M4 behavior of returning the raw filesystem error.
	FileAccessPrompter FileAccessPrompter // MaxTokensFunc returns the current token budget limit
	MaxTokensFunc      func() int
	// ConfigManager provides configuration access for tools that need it (e.g., API keys for web fetching)
	ConfigManager *configuration.Manager
	// EmbeddingMgr is the agent's long-lived embedding manager. When set,
	// tools must reuse it instead of constructing their own.
	EmbeddingMgr *embedding.EmbeddingManager
	// AskUser routes ask_user prompts through the active interactive channel
	// (WebUI dialog when a browser is connected, terminal stdin otherwise).
	// Nil means the tool must fall back to the CLI prompt directly.
	AskUser AskUserService
	// TodoManager is the conversation-scoped todo list. When nil, tools
	// should fall back to the package-default scope via ManagerForChat("").
	TodoManager *TodoManager
	// IsInteractiveCLI reports whether the agent is running with a controlling
	// TTY (no WebUI client). Tools use this to decide whether to render
	// rich CLI output (boxes, colors) for the user.
	IsInteractiveCLI bool
	// VisionProcessor, when set, lets vision-dependent tools analyze
	// images and UI screenshots without holding an *Agent reference.
	// Nil means the tool must report "vision unavailable".
	VisionProcessor *VisionProcessor
	// WebBrowser runs headless browser navigation (Playwright/rod wrapper).
	// Nil means the tool must report "browser unavailable".
	WebBrowser WebBrowser
	// SkillLoader resolves skill IDs to their on-disk instructions.
	// Nil means skill loading is not available.
	SkillLoader SkillLoader
	// SearchEngine performs Google Custom Search API queries.
	// Nil means web search is not available.
	SearchEngine SearchEngine
	// SubagentDepth is the nesting depth of subagents (0 = primary agent, 1 = first-level
	// subagent, 2 = second-level, etc.). Used by memory gate and other subagent-specific
	// tool behaviors. Default 0 means not in subagent context.
	SubagentDepth int
	// Gate1AutoApproved reports whether Gate 1 already auto-approved this
	// tool call (--unsafe mode or elevated risk profile). When true,
	// handlers skip their interactive approval prompt to avoid double-prompting.
	// Hard blocks are NEVER bypassed regardless of this flag.
	Gate1AutoApproved bool
	// RawArgsJSON is the raw JSON string of the tool arguments as sent by the
	// LLM. When set, handlers can parse this to recover the original key
	// insertion order of nested maps (e.g., the "data" field in
	// write_structured_file) before Go's map iteration randomizes it.
	RawArgsJSON string
	// RepoMapDefaultDepth overrides the repo_map tool's default depth when
	// the caller doesn't specify one. Zero means use the tool's built-in
	// default (3 = full symbols). Low-Context Mode sets this to 1.
	RepoMapDefaultDepth int
	Notifier            BackgroundNotifier
	// LifetimeCtx is a process-scoped context that outlives any single
	// turn. Background goroutines must use this instead of the per-turn
	// ctx so they survive turn boundaries. Cancelled when the agent shuts down.
	LifetimeCtx context.Context
	// ToolFuncs carries the agent-dependent tool dispatch closures for the
	// specific agent this env belongs to. When nil, ResolveToolFuncs falls
	// back to the package-level vars (the legacy single-agent path).
	ToolFuncs *ToolFuncSet
	// Agent is the *pkg/agent.Agent instance. Only set for tools that
	// explicitly need agent access (e.g., run_subagent). Nil for all others.
	Agent interface{} `json:"-"`
}

type ToolFuncSet struct {
	RunSubagent          func(ctx context.Context, args map[string]any) (string, error)
	RunParallelSubagents func(ctx context.Context, args map[string]any) (string, error)
	RequestClarification func(ctx context.Context, args map[string]any) (string, error)
	RespondClarification func(ctx context.Context, args map[string]any) (string, error)
	ListChanges          func(ctx context.Context, args map[string]any) (string, error)
	RecoverFile          func(ctx context.Context, args map[string]any) (string, error)
	RevertMyChanges      func(ctx context.Context, args map[string]any) (string, error)
	MCPRefresh           func(ctx context.Context, args map[string]any) (string, error)
	RunAutomate          func(ctx context.Context, args map[string]any) (string, error)
	CreatePullRequest    func(ctx context.Context, args map[string]any) (string, error)
}

type ToolHandler interface {
	// Name returns the unique tool identifier (e.g., "read_file").
	Name() string
	// Definition returns the JSON schema definition for the LLM to understand the tool.
	Definition() ToolDefinition
	// Validate checks arguments before execution. Returns error if invalid.
	Validate(args map[string]any) error
	// Execute runs the tool with the given context, environment, and arguments.
	Execute(ctx context.Context, env ToolEnv, args map[string]any) (ToolResult, error)

	// Metadata — all optional with sensible defaults. When a metadata method
	// returns its zero value, the ToolRegistry falls back to its own
	// registry-wide defaults for timeout and max result size.
	Aliases() []string      // default: nil (no aliases)
	Timeout() time.Duration // default: 0 (use registry default)
	MaxResultSize() int     // default: 0 (use registry default)
	SafeForParallel() bool  // default: false
	Interactive() bool      // default: false
}

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

type ToolResult struct {
	// Output is the primary text result of the tool execution.
	Output string `json:"output"`
	// StructuredOut holds optional structured data (maps, slices, etc.)
	StructuredOut any `json:"structured_out,omitempty"`
	// Images contains optional image data for vision-capable tools.
	Images []ImageData `json:"images,omitempty"`
	// TokenUsage tracks tokens consumed during execution.
	TokenUsage int64 `json:"token_usage"`
	// IsError indicates whether this result represents an error state.
	IsError bool `json:"is_error"`
}

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

type UIElement struct {
	Type        string `json:"type"`             // button, input, text, etc.
	Description string `json:"description"`      // what it looks like
	Position    string `json:"position"`         // approximate location
	Issues      string `json:"issues,omitempty"` // any problems noted
}

type ViewHistoryResult struct {
	Output   string
	Metadata map[string]interface{}
}

type VisionAnalysis struct {
	ImagePath   string      `json:"image_path"`
	Description string      `json:"description"`
	Elements    []UIElement `json:"elements,omitempty"`
	Issues      []string    `json:"issues,omitempty"`
	Suggestions []string    `json:"suggestions,omitempty"`
}

type VisionCacheStats struct {
	Hits       atomic.Uint64
	Misses     atomic.Uint64
	Evictions  atomic.Uint64
	Size       atomic.Int64
	Insertions atomic.Uint64
}

type VisionCacheStatsSnapshot struct {
	Hits       uint64
	Misses     uint64
	Evictions  uint64
	Size       int64
	Insertions uint64
}

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

type VisionMetrics struct {
	// ImageTokensTotal is the cumulative count of input prompt image tokens
	// billed across all vision calls (including cached reads).
	ImageTokensTotal atomic.Int64

	// ImageTokensCachedTotal is the cumulative count of cached image
	// tokens — a subset of ImageTokensTotal that hit the cache and so
	// cost only the discounted cached rate.
	ImageTokensCachedTotal atomic.Int64

	// EmbedCallsTotal counts every call to embed a multimodal image into
	// a chat message (processImagesAsMultimodal result).
	EmbedCallsTotal atomic.Int64

	// OCRCallsTotal counts calls to the OCR-via-tool path.
	OCRCallsTotal atomic.Int64

	// ResizeEvents counts every image we resized down to the 1568px cap
	// before embedding (SP-103-B2).
	ResizeEvents atomic.Int64

	// CacheHits and CacheMisses mirror the cache stats on a separate
	// atomic surface so callers can poll metrics cheaply.
	CacheHits   atomic.Int64
	CacheMisses atomic.Int64

	// RetryCount tracks the total number of retry attempts across all
	// vision calls (i.e., the number of times DoVisionRetry re-entered
	// the loop after a failed attempt).
	RetryCount atomic.Int64

	// OCRFallbackTotal counts the number of times OCR fallback was attempted.
	OCRFallbackTotal atomic.Int64

	// OCRFallbackSuccess counts the number of times OCR fallback returned
	// a successful result. The fallback success rate is
	// OCRFallbackSuccess / OCRFallbackTotal.
	OCRFallbackSuccess atomic.Int64

	// LatencyRequestMS accumulates wall-clock time (ms) spent in the
	// provider's SendVisionRequest call (per attempt, not including retries).
	LatencyRequestMS atomic.Int64

	// LatencyRetrySleepMS accumulates wall-clock time (ms) spent sleeping
	// between retry attempts.
	LatencyRetrySleepMS atomic.Int64

	// LatencyFallbackMS accumulates wall-clock time (ms) spent in the
	// OCR fallback path (from entry to result).
	LatencyFallbackMS atomic.Int64

	// LatencyParseMS accumulates wall-clock time (ms) spent parsing the
	// provider response into a VisionAnalysis struct.
	LatencyParseMS atomic.Int64

	FailuresByReason map[string]int64

	// BatchAttempts counts the number of times batched vision analysis was
	// attempted (N>1 images sent together in one provider call).
	BatchAttempts atomic.Int64

	// BatchHits counts the number of times a batched result was served
	// from the cache without a provider call.
	BatchHits atomic.Int64

	// BatchMisses counts the number of times a batched result was NOT in
	// the cache and required a provider call.
	BatchMisses atomic.Int64

	// BatchPartialFailures counts the number of times a batched provider
	// call returned but one or more per-image sections were missing/failed,
	// requiring per-image fallback processing.
	BatchPartialFailures atomic.Int64
	// contains filtered or unexported fields
}

type VisionMetricsRecord struct {
	Timestamp           string `json:"timestamp"` // RFC3339
	SessionID           string `json:"session_id,omitempty"`
	OpName              string `json:"op_name"`     // e.g. "analyze_image"
	ImageCount          int    `json:"image_count"` // number of images in this call
	Success             bool   `json:"success"`
	FailureReason       string `json:"failure_reason,omitempty"` // classified reason (empty if success)
	RetryCount          int    `json:"retry_count"`              // number of retry attempts (0 = first attempt succeeded)
	UsedOCRFallback     bool   `json:"used_ocr_fallback"`
	OCRFallbackSuccess  bool   `json:"ocr_fallback_success"`
	LatencyRequestMS    int64  `json:"latency_request_ms"`     // total provider call wall time (all attempts)
	LatencyRetrySleepMS int64  `json:"latency_retry_sleep_ms"` // time spent sleeping between retries
	LatencyFallbackMS   int64  `json:"latency_fallback_ms"`    // OCR fallback wall time (0 if not used)
	LatencyParseMS      int64  `json:"latency_parse_ms"`       // response parsing wall time
	ImageTokens         int    `json:"image_tokens"`           // prompt image tokens (including cached)
	ImageTokensCached   int    `json:"image_tokens_cached"`    // cached image tokens
}

type VisionMetricsSnapshot struct {
	ImageTokensTotal       int64 `json:"vision_image_tokens_total"`
	ImageTokensCachedTotal int64 `json:"vision_image_tokens_cached_total"`
	EmbedCallsTotal        int64 `json:"vision_embed_calls_total"`
	OCRCallsTotal          int64 `json:"vision_ocr_calls_total"`
	ResizeEvents           int64 `json:"vision_resize_events"`
	CacheHits              int64 `json:"vision_cache_hits"`
	CacheMisses            int64 `json:"vision_cache_misses"`
	// VISION-5: structured metrics
	RetryCount          int64            `json:"vision_retry_count"`
	OCRFallbackTotal    int64            `json:"vision_ocr_fallback_total"`
	OCRFallbackSuccess  int64            `json:"vision_ocr_fallback_success"`
	LatencyRequestMS    int64            `json:"vision_latency_request_ms"`
	LatencyRetrySleepMS int64            `json:"vision_latency_retry_sleep_ms"`
	LatencyFallbackMS   int64            `json:"vision_latency_fallback_ms"`
	LatencyParseMS      int64            `json:"vision_latency_parse_ms"`
	FailuresByReason    map[string]int64 `json:"vision_failures_by_reason"`
	// VISION-4: batch metrics
	BatchAttempts        int64 `json:"vision_batch_attempts"`
	BatchHits            int64 `json:"vision_batch_hits"`
	BatchMisses          int64 `json:"vision_batch_misses"`
	BatchPartialFailures int64 `json:"vision_batch_partial_failures"`
}

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

type VisionProgressFunc func(completed, total int)

type VisionUsageInfo struct {
	PromptTokens     int     `json:"prompt_tokens"`
	CompletionTokens int     `json:"completion_tokens"`
	TotalTokens      int     `json:"total_tokens"`
	EstimatedCost    float64 `json:"estimated_cost"`
}

type WebBrowser interface {
	BrowseURL(ctx context.Context, url string, opts map[string]any) (string, error)
}