control

type AnswerPermission struct {
	SessionID ids.SessionID `json:"sessionId"`
	CallID    ids.CallID    `json:"callId"`
	Decision  Decision      `json:"decision"`
	Scope     PermitScope   `json:"scope,omitempty"` // for argv-glob/tool/session allow buttons
}

type AttachSession struct {
	SessionID ids.SessionID `json:"sessionId"`
}

type CancelTurn struct {
	SessionID ids.SessionID `json:"sessionId"`
}

type Cancelled struct {
	Turn   int          `json:"turn"`
	By     ids.ClientID `json:"by"`
	Reason string       `json:"reason"`
}

type Client interface {
	// ID returns the client's stable identifier for the lifetime of
	// the attach. Cross-references the OriginatorID embedded in
	// event envelopes the engine emits for turns this client started.
	ID() ids.ClientID

	// IdentityClass distinguishes human-driven clients from
	// agent-driven ones. Permission middleware honors this.
	IdentityClass() IdentityClass

	// Subscribe returns a receive-only channel of events broadcast
	// to this client. The channel is closed when the client is
	// detached or the context is done.
	Subscribe(ctx context.Context) <-chan EventEnvelope

	// Send delivers a command from the client to the multiplexer.
	// Returns an error if the transport is closed or the command
	// fails wire-format validation.
	Send(ctx context.Context, cmd Command) error

	// Close detaches the client. Detach is non-destructive at the
	// engine level — see § Multi-client semantics.
	Close() error
}

type Command interface {

	// CommandKind returns the kind discriminator used on the wire
	// (matches handshake.command_kinds entries).
	CommandKind() string
	// contains filtered or unexported methods
}

type CompactionTriggered struct {
	BeforeTokens int `json:"beforeTokens"`
	AfterTokens  int `json:"afterTokens"`
}

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

	// Type-specific fields. Only the field matching Type is meaningful.
	Text       string          `json:"text,omitempty"`
	ToolUse    *ToolUse        `json:"tool_use,omitempty"`
	ToolResult *ToolResultBlk  `json:"tool_result,omitempty"`
	Thinking   json.RawMessage `json:"thinking,omitempty"` // opaque, provider-stamped
	Image      *ImageBlock     `json:"image,omitempty"`
	Yield      *YieldBlock     `json:"yield,omitempty"` // explicit end-turn signal
}

type CostIncremented struct {
	Provider     string  `json:"provider"`
	Model        string  `json:"model"`
	InputTokens  int     `json:"inputTokens"`
	OutputTokens int     `json:"outputTokens"`
	CacheTokens  int     `json:"cacheTokens,omitempty"`
	USD          float64 `json:"usd"`
}

type CreateSession struct {
	Profile string `json:"profile"`
	// Resume, when non-nil, attaches the new EngineRun to an existing LogID.
	Resume *ids.LogID `json:"resume,omitempty"`
}

type CustomCommand struct {
	SessionID ids.SessionID   `json:"sessionId"`
	Namespace string          `json:"namespace"` // matches a claimed slash-command namespace
	Verb      string          `json:"verb"`
	Payload   json.RawMessage `json:"payload"`
}

type CustomEvent struct {
	Namespace string          `json:"namespace"`
	Kind      string          `json:"kind"`
	Payload   json.RawMessage `json:"payload"`
}

type Decision string

type DetachSession struct {
	SessionID ids.SessionID `json:"sessionId"`
}

type EnterPlanMode struct {
	SessionID ids.SessionID `json:"sessionId"`
}

type Error struct {
	Reason  string          `json:"reason"`  // stable error code
	Message string          `json:"message"` // human-friendly text
	Details json.RawMessage `json:"details,omitempty"`
}

type Event interface {
	EventKind() string
	// contains filtered or unexported methods
}

type EventEnvelope struct {
	ID         uint64          `json:"id"`   // monotonic per SessionID
	Kind       string          `json:"kind"` // matches handshake.event_kinds
	Session    ids.SessionID   `json:"session"`
	Originator ids.ClientID    `json:"originator,omitempty"`
	TS         time.Time       `json:"ts"`
	Payload    json.RawMessage `json:"payload"`
}

type ExitPlanMode struct {
	SessionID ids.SessionID `json:"sessionId"`
	Approve   bool          `json:"approve"`
}

type Handshake struct {
	ProtocolVersion         string   `json:"protocol_version"`
	CanonicalFormVersion    int      `json:"canonical_form_version"`
	SchemaVersionTokenClaim int      `json:"schema_version_token_claim"`
	SchemaVersionProfile    int      `json:"schema_version_profile"`
	SchemaVersionSessionLog int      `json:"schema_version_session_log"`
	CommandKinds            []string `json:"command_kinds"`
	EventKinds              []string `json:"event_kinds"`
	Features                []string `json:"features"`
	ResourceURIScheme       string   `json:"resource_uri_scheme"`
}

type HookError struct {
	Event    string `json:"event"`
	Command  string `json:"command"`
	ExitCode int    `json:"exitCode"`
	Output   string `json:"output,omitempty"`
}

type HookTimeout struct {
	Event   string        `json:"event"`
	Command string        `json:"command"`
	After   time.Duration `json:"after"`
}

type IdentityClass uint8

type ImageBlock struct {
	MediaType string `json:"media_type"`
	Data      string `json:"data"`
}

type MCPServerDown struct {
	Name     string `json:"name"`
	Reason   string `json:"reason"`
	Attempts int    `json:"attempts"`
}

type PermissionRequested struct {
	CallID     ids.CallID      `json:"callId"`
	Tool       string          `json:"tool"`
	Args       json.RawMessage `json:"args"`
	Originator ids.ClientID    `json:"originator"`
	Reason     string          `json:"reason,omitempty"` // e.g. why this is being asked
}

type PermitScope string

type SendInput struct {
	SessionID ids.SessionID  `json:"sessionId"`
	Content   []ContentBlock `json:"content"`
	// Wait controls REST/MCP synchronous vs streaming behavior.
	// "" / "none" → returns immediately; "turn" → blocks until TurnEnded.
	Wait string `json:"wait,omitempty"`
}

type SessionEnded struct {
	Reason string `json:"reason"` // "idle" | "user" | "error" | "binary-shutdown"
}

type SetModel struct {
	SessionID ids.SessionID `json:"sessionId"`
	Model     string        `json:"model"`
}

type StreamGap struct {
	From   uint64 `json:"from"`
	To     uint64 `json:"to"`
	Reason string `json:"reason"` // "ttl" | "compaction"
}

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

type ThinkingDelta struct {
	Block json.RawMessage `json:"block"` // opaque, provider-stamped
}

type TokenExpiring struct {
	JTI   ids.JTI   `json:"jti"`
	ExpAt time.Time `json:"expAt"`
}

type ToolCallProgress struct {
	CallID  ids.CallID `json:"callId"`
	Partial string     `json:"partial"`
}

type ToolCallStarted struct {
	CallID   ids.CallID      `json:"callId"`
	Tool     string          `json:"tool"`
	Args     json.RawMessage `json:"args"`
	Mutating bool            `json:"mutating"`
}

type ToolResult struct {
	CallID  ids.CallID     `json:"callId"`
	Content []ContentBlock `json:"content"`
	IsError bool           `json:"isError,omitempty"`
}

type ToolResultBlk struct {
	ToolUseID string         `json:"tool_use_id"`
	Content   []ContentBlock `json:"content"`
	IsError   bool           `json:"is_error,omitempty"`
}

type ToolTimingEntry struct {
	CallID   ids.CallID    `json:"callId"`
	Tool     string        `json:"tool"`
	Duration time.Duration `json:"duration"`
}

type ToolUse struct {
	ID    string          `json:"id"`    // matches a tool_use id later in ToolResultBlk
	Name  string          `json:"name"`  // tool name
	Input json.RawMessage `json:"input"` // tool-call arguments
}

type TurnEnded struct {
	Turn   int    `json:"turn"`
	Reason string `json:"reason"` // "complete" | "cancelled" | "error" | "yield"
}

type TurnStarted struct {
	Turn       int          `json:"turn"`
	Originator ids.ClientID `json:"originator"`
	// Content is the input that started this turn. Lets non-originator
	// clients (browser sidecar attached to the same session as the TUI,
	// or vice-versa) render the user message without round-tripping
	// through a separate "echo" event. Optional for backwards
	// compatibility — older publishers may omit it.
	Content []ContentBlock `json:"content,omitempty"`
}

type TurnTiming struct {
	Turn       int                      `json:"turn"`
	Components map[string]time.Duration `json:"components"`
	ToolCalls  []ToolTimingEntry        `json:"toolCalls,omitempty"`
}

type YieldBlock struct {
	Reason string `json:"reason,omitempty"`
}