handler

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

type AgentEventHandler interface {

	// OnAgentText is called when the agent emits a text chunk (streaming).
	OnAgentText(text string)

	// OnToolCall is called at the beginning of a tool invocation.
	OnToolCall(ev ToolCallEvent)

	// OnToolResult is called when a tool execution completes.
	OnToolResult(ev ToolResultEvent)

	// OnTodoUpdate is called when the todo store is mutated.
	OnTodoUpdate()

	// OnAgentStart is called when the agent begins processing a user prompt,
	// before any LLM call is made. Use this to show a "thinking" / "working"
	// indicator immediately, rather than waiting for the first text chunk.
	OnAgentStart()

	// OnAgentDone is called when the agent loop finishes (err may be nil).
	OnAgentDone(err error)

	// OnTokenUpdate reports cumulative token usage after a run.
	OnTokenUpdate(info TokenUsage)

	// RequestApproval asks the UI for tool-execution permission.
	// It blocks until the user responds or ctx is cancelled.
	// Returns (approved, newMode, error).
	RequestApproval(ctx context.Context, req ApprovalRequest) (ApprovalResponse, error)
}

type ApprovalMode int

type ApprovalOption struct {
	ID          string `json:"id"`
	Label       string `json:"label"`
	Kind        string `json:"kind,omitempty"`
	Description string `json:"description,omitempty"`
}

type ApprovalRequest struct {
	ToolName        string
	ToolArgs        string
	ToolCallID      string // unique ID of this tool invocation (from the LLM)
	IsExternal      bool   // true when accessing paths outside workpath
	WorkerName      string // non-empty for teammate agents
	WorkerColor     string
	ApprovalClass   string
	OperationID     string
	CapabilityKey   string
	Provider        string
	Model           string
	BillableSummary *BillableApprovalSummary
	// Options are runner-issued opaque, one-shot decisions for a structured
	// approval. Transports must present and return these exact IDs; they must
	// never mint replacements or coerce the decision back to a boolean.
	Options []ApprovalOption
	// AllowApproveAll is false for billable/external operations whose grant
	// must be bounded to the exact immutable intent.
	AllowApproveAll bool
}

type ApprovalResponse struct {
	Approved         bool
	Mode             ApprovalMode
	ResolvedOptionID string
}

type ArtifactRef = toolstate.ArtifactRef

type BillableApprovalSummary struct {
	Capability   string `json:"capability,omitempty"`
	Provider     string `json:"provider,omitempty"`
	Model        string `json:"model,omitempty"`
	Size         string `json:"size,omitempty"`
	AspectRatio  string `json:"aspect_ratio,omitempty"`
	Resolution   string `json:"resolution,omitempty"`
	Count        int    `json:"count,omitempty"`
	Billable     bool   `json:"billable,omitempty"`
	HasReference bool   `json:"has_reference,omitempty"`
}

type ModelRetryEvent struct {
	Status      ModelRetryStatus
	Attempt     int
	MaxAttempts int
	RetryIn     time.Duration
}

type ModelRetryHandler interface {
	OnModelRetry(ModelRetryEvent)
}

type ModelRetryStatus string

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

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

type TokenUsage struct {
	TotalTokens       int64
	PromptTokens      int64
	CompletionTokens  int64
	CachedTokens      int64
	ReasoningTokens   int64
	CacheWriteTokens  int64
	CallCount         int64
	CacheHitRate      float64
	CacheSupported    bool
	ModelContextLimit int // 0 if unknown
}

type ToolCallEvent struct {
	Name        string
	Args        string
	ToolCallID  string
	Surface     ToolSurface
	Phase       ToolPhase
	OperationID string
	BatchID     string    // batch identity: one assistant message = one batch
	BatchIndex  int       // 0-based position inside the batch
	BatchSize   int       // number of tool calls in the batch
	StartedAt   time.Time // when the runner announced the call
}

type ToolDisplayInfo struct {
	Title       string `json:"title"`              // Human-readable tool name (e.g. "Read", "Edit", "Shell")
	Subtitle    string `json:"subtitle,omitempty"` // Context info (file path, command description, pattern)
	Icon        string `json:"icon,omitempty"`     // Icon identifier
	Category    string `json:"category,omitempty"` // "context" (read-only), "mutation", "execution"
	Kind        string `json:"kind,omitempty"`     // presentation kind: read|search|list|shell|edit|agent|other
	Collapsible bool   `json:"collapsible,omitempty"`
}

type ToolOutcome = toolstate.Outcome

type ToolPhase = toolstate.Phase

type ToolProgressEvent = toolstate.ProgressEvent

type ToolProgressHandler interface {
	OnToolProgress(ToolProgressEvent)
}

type ToolResultEvent struct {
	Name       string
	Output     string
	ToolCallID string
	Err        error
	// Duration is result arrival minus call announcement, with any time spent
	// blocked on user approval subtracted (pure execution latency); 0 when
	// unknown.
	Duration time.Duration
	// Denied is true when the user rejected this tool call at the approval
	// prompt. UIs should render this as "declined" (e.g. strikethrough), not
	// as an execution error.
	Denied      bool
	Surface     ToolSurface
	Phase       ToolPhase
	OperationID string
	Outcome     ToolOutcome
	ErrorCode   string
	Provider    string
	Model       string
	Artifacts   []ArtifactRef
}

type ToolSurface = toolstate.Surface

type WebApprovalRequestData struct {
	ID              string                   `json:"id"`
	ToolName        string                   `json:"tool_name"`
	ToolArgs        string                   `json:"tool_args"`
	ToolCallID      string                   `json:"tool_call_id,omitempty"`
	IsExternal      bool                     `json:"is_external"`
	ApprovalClass   string                   `json:"approval_class,omitempty"`
	OperationID     string                   `json:"operation_id,omitempty"`
	CapabilityKey   string                   `json:"capability_key,omitempty"`
	Provider        string                   `json:"provider,omitempty"`
	Model           string                   `json:"model,omitempty"`
	AllowApproveAll bool                     `json:"allow_approve_all"`
	Options         []ApprovalOption         `json:"options,omitempty"`
	BillableSummary *BillableApprovalSummary `json:"billable_summary,omitempty"`
}

type WebAskUserRequestData struct {
	ID        string                  `json:"id"`
	Questions []tools.AskUserQuestion `json:"questions"`
}

type WebDoneData struct {
	Error     string `json:"error,omitempty"`
	Detail    string `json:"detail,omitempty"`
	Stopped   bool   `json:"stopped,omitempty"`
	Code      string `json:"code,omitempty"`
	ErrorKind string `json:"error_kind,omitempty"`
	Kind      string `json:"kind,omitempty"`
	Phase     string `json:"phase,omitempty"`
	Retryable *bool  `json:"retryable,omitempty"`
}

type WebEvent struct {
	Event string `json:"event"`
	Data  any    `json:"data"`
}

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

type WebModelRetryData struct {
	Status      ModelRetryStatus `json:"status"`
	Attempt     int              `json:"attempt"`
	MaxAttempts int              `json:"max_attempts"`
	RetryInMS   int64            `json:"retry_in_ms,omitempty"`
}

type WebSubagentData struct {
	Name      string `json:"name"`
	AgentType string `json:"agent_type"`
	Done      bool   `json:"done"`
	Result    string `json:"result,omitempty"`
	Error     string `json:"error,omitempty"`
}

type WebSubagentProgressData struct {
	AgentName string `json:"agent_name"`
	Event     string `json:"event"` // "tool_call" or "tool_result"
	ToolName  string `json:"tool_name"`
	Detail    string `json:"detail"`
}

type WebTextData struct {
	Text string `json:"text"`
}

type WebTokenData struct {
	TotalTokens       int64   `json:"total_tokens"`
	PromptTokens      int64   `json:"prompt_tokens"`
	CompletionTokens  int64   `json:"completion_tokens"`
	CachedTokens      int64   `json:"cached_tokens"`
	ReasoningTokens   int64   `json:"reasoning_tokens"`
	CacheWriteTokens  int64   `json:"cache_write_tokens"`
	CallCount         int64   `json:"call_count"`
	CacheHitRate      float64 `json:"cache_hit_rate"`
	CacheSupported    bool    `json:"cache_supported"`
	ModelContextLimit int     `json:"model_context_limit"`
}

type WebToolCallData struct {
	Name        string           `json:"name"`
	Args        string           `json:"args"`
	ToolCallID  string           `json:"tool_call_id,omitempty"`
	DisplayInfo *ToolDisplayInfo `json:"display_info,omitempty"`
	BatchID     string           `json:"batch_id,omitempty"`
	BatchIndex  int              `json:"batch_index,omitempty"`
	BatchSize   int              `json:"batch_size,omitempty"`
	StartedAt   int64            `json:"started_at,omitempty"`
	Surface     ToolSurface      `json:"surface,omitempty"`
	Phase       ToolPhase        `json:"phase,omitempty"`
	OperationID string           `json:"operation_id,omitempty"`
	// ApprovalID binds this released call to the exact host-generated approval
	// occurrence. Model tool-call IDs are not trusted to be unique. When set,
	// ApprovalGranted is the decision for that gate (false means denied).
	ApprovalID      string `json:"approval_id,omitempty"`
	ApprovalGranted bool   `json:"approval_granted,omitempty"`
}

type WebToolProgressData struct {
	Name        string        `json:"name"`
	ToolCallID  string        `json:"tool_call_id,omitempty"`
	Surface     ToolSurface   `json:"surface,omitempty"`
	Phase       ToolPhase     `json:"phase"`
	OperationID string        `json:"operation_id,omitempty"`
	ErrorCode   string        `json:"error_code,omitempty"`
	Provider    string        `json:"provider,omitempty"`
	Model       string        `json:"model,omitempty"`
	Artifacts   []ArtifactRef `json:"artifacts,omitempty"`
}

type WebToolResultData struct {
	Name          string                     `json:"name"`
	Output        string                     `json:"output"`
	DisplayOutput string                     `json:"display_output,omitempty"` // clean output for UI display
	Error         string                     `json:"error,omitempty"`
	ToolCallID    string                     `json:"tool_call_id,omitempty"`
	ApprovalID    string                     `json:"approval_id,omitempty"`
	Streams       *WebToolResultStreams      `json:"streams,omitempty"`
	Meta          *WebToolResultMeta         `json:"meta,omitempty"`
	Presentation  *WebToolResultPresentation `json:"presentation,omitempty"`
	// DurationMs is the runner-measured call→result latency (approval wait
	// already subtracted), provided for all tools. It coexists with
	// Meta.DurationMs, which only execute-style tools report (in-sandbox
	// execution time).
	DurationMs int64 `json:"duration_ms,omitempty"`
	// Denied is true when the user rejected this call at the approval prompt.
	// The UI renders it struck-through/muted (declined), not as an error.
	Denied      bool          `json:"denied,omitempty"`
	Surface     ToolSurface   `json:"surface,omitempty"`
	Phase       ToolPhase     `json:"phase,omitempty"`
	OperationID string        `json:"operation_id,omitempty"`
	Outcome     ToolOutcome   `json:"outcome,omitempty"`
	ErrorCode   string        `json:"error_code,omitempty"`
	Provider    string        `json:"provider,omitempty"`
	Model       string        `json:"model,omitempty"`
	Artifacts   []ArtifactRef `json:"artifacts,omitempty"`
}

type WebToolResultMeta struct {
	ExitCode   int    `json:"exit_code"`
	DurationMs int64  `json:"duration_ms"`
	TimedOut   bool   `json:"timed_out,omitempty"`
	Truncated  bool   `json:"truncated,omitempty"`
	SpillPath  string `json:"spill_path,omitempty"`
}

type WebToolResultPresentation struct {
	Kind        string `json:"kind,omitempty"`
	Title       string `json:"title,omitempty"`
	Subtitle    string `json:"subtitle,omitempty"`
	Collapsible bool   `json:"collapsible,omitempty"`
}

type WebToolResultStreams struct {
	Stdout     string `json:"stdout,omitempty"`
	Stderr     string `json:"stderr,omitempty"`
	Aggregated string `json:"aggregated,omitempty"`
}