event

type ApprovalNeededPayload struct {
	// RequestID is the Broker correlation key; the TUI passes it back to
	// Broker.Respond when forwarding the user's choice.
	RequestID string
	// ToolName is the wire name of the tool whose call is being gated.
	ToolName string
	// ToolInput is the raw JSON the LLM passed to the tool.
	ToolInput json.RawMessage
	// InputDescription is the model-supplied `description` field from
	// ToolInput; "" when the tool's input has no such field.
	InputDescription string
	// Mode is the permission mode active when the gate fired.
	Mode string
	// Reason is the gate's explanation for asking (e.g. "matches dangerous prefix").
	Reason string
	// RiskHint is non-empty for Bash (the classifier's risk label);
	// empty for other tools.
	RiskHint string
	// Matched is the rule fragment that triggered the prompt, if any.
	Matched string
	// PlanContent is non-empty only for ExitPlanMode — carries the
	// markdown plan body so the approval overlay can render it inline.
	PlanContent string
}

type BgResultPayload struct {
	// TaskID is the wire-stable id (e.g. "b4x9z1kp") the model received
	// from the original `bash run_in_background:true` call.
	TaskID string
	// Status is the terminal lifecycle state: completed / failed / killed.
	Status string
	// ExitCode is the process exit code (0 for completed; non-zero for
	// failed; -1 or os-defined for killed).
	ExitCode int
	// Output is the captured stdout+stderr, capped at the bg path's
	// output ceiling (~64 KiB).
	Output string
	// AgentID is the spawning agent — copied so subagent bubble-up can
	// label rows without inferring from event metadata.
	AgentID string
}

type BubbleUp struct {
	Parent   Sink
	ParentID string
}

type CompactingEndPayload struct {
	// Type matches the prior CompactingPayload.Type — "micro" or "full".
	Type string
	// OK reports success or failure; false means the TUI should swap
	// the spinner for an error line rather than removing it silently.
	OK bool
	// BriefTokens is the size of the full-compact brief; updated UIs use
	// this to replace the percent estimate they painted at start.
	BriefTokens int
	// Err is the failure reason when OK is false; empty otherwise.
	Err string
}

type CompactingPayload struct {
	// Type is "micro" (elide old tool results) or "full" (summarise).
	Type string
	// UsageRatio is the input/budget ratio that triggered the compaction.
	UsageRatio float64
}

type DrainBackgroundTaskPayload struct {
	// TaskIDs are the ids drained on this iteration boundary, in
	// completion order.
	TaskIDs []string
}

type DrainMonitorEventsPayload struct {
	// EventCount is the total number of monitor events folded into the
	// session on this iteration boundary.
	EventCount int
	// MonitorIDs are the unique monitor ids the drained events came
	// from, in first-occurrence order.
	MonitorIDs []string
}

type ErrorPayload struct {
	// Stage tags where in the loop the failure occurred:
	// "llm" | "tool:<name>" | "loop".
	Stage string
	// Err is the underlying Go error. Use Message for the rendered
	// string form when you only need text (covers the nil case too).
	Err error
	// Message is err.Error() captured at emit time, or "" when Err is nil.
	// Convenience for consumers that don't want to nil-check + stringify
	// (UIs, JSON serialisers).
	Message string
}

type Event struct {
	Kind     Kind
	AgentID  string
	ParentID string
	Time     time.Time

	RunStart       *RunStartPayload       `json:",omitempty"`
	RunResume      *RunResumePayload      `json:",omitempty"`
	RunEnd         *RunEndPayload         `json:",omitempty"`
	IterLimit      *IterLimitPayload      `json:",omitempty"`
	Turn           *TurnPayload           `json:",omitempty"`
	Thinking       *TextPayload           `json:",omitempty"`
	Text           *TextPayload           `json:",omitempty"`
	ToolUseStart   *ToolUseStartPayload   `json:",omitempty"`
	ToolUseResult  *ToolUseResultPayload  `json:",omitempty"`
	ApprovalNeeded *ApprovalNeededPayload `json:",omitempty"`
	QuestionNeeded *QuestionNeededPayload `json:",omitempty"`
	Error          *ErrorPayload          `json:",omitempty"`
	StoreUpdate    *StoreUpdatePayload    `json:",omitempty"`
	Usage          *UsagePayload          `json:",omitempty"`
	Compacting     *CompactingPayload     `json:",omitempty"`
	CompactingEnd  *CompactingEndPayload  `json:",omitempty"`
	ModeChanged    *ModeChangedPayload    `json:",omitempty"`

	BgResult            *BgResultPayload            `json:",omitempty"`
	MonitorEvent        *MonitorEventPayload        `json:",omitempty"`
	DrainBackgroundTask *DrainBackgroundTaskPayload `json:",omitempty"`
	DrainMonitorEvents  *DrainMonitorEventsPayload  `json:",omitempty"`
}

type IterLimitPayload struct {
	// Iters is the iteration count the loop hit before pausing — matches
	// RunEndPayload.Iters naming so callers can read iteration counts
	// from either payload without remembering two field names.
	Iters int
}

type Kind string

type ModeChangedPayload struct {
	// PrevMode is the mode that was active before the change. Empty on the
	// very first initialization.
	PrevMode string
	// Mode is the new mode the agent has transitioned into.
	Mode string
}

type Multi struct {
	Sinks []Sink
}

type QuestionItem struct {
	// Question is the prompt body.
	Question string
	// Header is the short chip label (max 12 chars in the canonical UI).
	Header string
	// MultiSelect controls whether the user may pick more than one option.
	MultiSelect bool
	// Options are the offered choices.
	Options []QuestionOption
}

type QuestionNeededPayload struct {
	// RequestID is the question.Broker correlation key; the TUI passes
	// it back via Controller.RespondQuestion.
	RequestID string
	// AgentID is the agent that invoked AskUserQuestion (relevant when
	// subagent question routing lands).
	AgentID string
	// Questions are the items rendered in the overlay.
	Questions []QuestionItem
}

type QuestionOption struct {
	// Label is the choice text shown to the user.
	Label string
	// Description is the optional explanation rendered alongside.
	Description string
	// Preview is the optional code/diagram block shown in side-by-side mode.
	Preview string
}

type RunEndPayload struct {
	// Iters is the number of iterations the loop consumed before ending.
	Iters int
	// Content is the assistant's final text for the Run.
	Content string
	// Thinking is the assistant's reasoning text (if any).
	Thinking string
}

type RunResumePayload struct {
	// FromMessageIndex is the position in the session transcript where
	// Continue picked up.
	FromMessageIndex int
}

type RunStartPayload struct {
	// Prompt is the user message that opened this Run.
	Prompt string
}

type Sink interface {
	Emit(Event)
}

type SinkFunc func(Event)

type StoreUpdatePayload struct {
	// Domain identifies the emitting store ("task", "subagent", …).
	Domain string
	// Op is the verb: "created" / "updated" / "removed" / "phase" / "done" / "crushed".
	Op string
	// ID is the store-local identifier (task ID, subagent ID, …).
	ID string
	// Payload is the store's domain-typed snapshot; consumers type-assert
	// based on Domain.
	Payload any
	// Time is the emit timestamp.
	Time time.Time
}

type TextPayload struct {
	// Text is the assistant text content (a full block, or one streaming
	// delta when the event Kind is KindTextChunk / KindThinkingChunk).
	Text string
}

type ToolUseResultPayload struct {
	// ToolID correlates this result with the prior ToolUseStart.
	ToolID string
	// Content is the LLM-facing text summary the tool produced.
	Content string
	// IsError is true when the tool itself returned an error result.
	// Distinct from a Go-level failure (which surfaces via KindError).
	IsError bool
	// Metadata is an optional tool-specific structured payload (e.g. a
	// *fs.FileDiff for write/edit). UIs type-assert to render rich views.
	Metadata any
	// ContentBlocks carries multimodal output (text + images). Empty for
	// text-only tool results.
	ContentBlocks []tools.ContentBlock
}

type ToolUseStartPayload struct {
	// Name is the tool's wire name (matches tools.ToolName).
	Name string
	// Input is the raw JSON the LLM passed to the tool — UIs typically
	// summarise one field rather than dumping the whole blob.
	Input json.RawMessage
	// ToolID correlates this dispatch with its eventual ToolUseResult.
	ToolID string
}

type TurnPayload struct {
	// Iteration is the zero-based loop iteration index.
	Iteration int
}

type UsagePayload struct {
	// Turn is usage for the just-completed LLM call.
	Turn llm.Usage
	// Cumulative is the running session total after Turn is folded in.
	Cumulative llm.Usage
}