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

type ApprovalResponse struct {
	Approved bool
	Mode     ApprovalMode
}

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

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

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

type WebDoneData struct {
	Error string `json:"error,omitempty"`
}

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

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

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

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

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