actions.ts

/*---------------------------------------------------------------------------------------------
 *  Copyright (c) Microsoft Corporation. All rights reserved.
 *  Licensed under the MIT License. See License.txt in the project root for license information.
 *--------------------------------------------------------------------------------------------*/

// allow-any-unicode-comment-file
// DO NOT EDIT -- auto-generated by scripts/sync-agent-host-protocol.ts

import { ToolCallConfirmationReason, ToolCallCancellationReason, PendingMessageKind, type URI, type StringOrMarkdown, type AgentInfo, type ErrorInfo, type ModelSelection, type UserMessage, type ResponsePart, type ToolCallResult, type ToolResultContent, type ToolDefinition, type SessionActiveClient, type UsageInfo, type SessionCustomization, type FileEdit, type SessionInputAnswer, type SessionInputRequest, type TerminalInfo, type TerminalClaim, type SessionInputResponseKind, type ConfirmationOption } from './state.js';


// ─── Action Type Enum ────────────────────────────────────────────────────────

/**
 * Discriminant values for all state actions.
 *
 * @category Actions
 */
export const enum ActionType {
	RootAgentsChanged = 'root/agentsChanged',
	RootActiveSessionsChanged = 'root/activeSessionsChanged',
	SessionReady = 'session/ready',
	SessionCreationFailed = 'session/creationFailed',
	SessionTurnStarted = 'session/turnStarted',
	SessionDelta = 'session/delta',
	SessionResponsePart = 'session/responsePart',
	SessionToolCallStart = 'session/toolCallStart',
	SessionToolCallDelta = 'session/toolCallDelta',
	SessionToolCallReady = 'session/toolCallReady',
	SessionToolCallConfirmed = 'session/toolCallConfirmed',
	SessionToolCallComplete = 'session/toolCallComplete',
	SessionToolCallResultConfirmed = 'session/toolCallResultConfirmed',
	SessionToolCallContentChanged = 'session/toolCallContentChanged',
	SessionTurnComplete = 'session/turnComplete',
	SessionTurnCancelled = 'session/turnCancelled',
	SessionError = 'session/error',
	SessionTitleChanged = 'session/titleChanged',
	SessionUsage = 'session/usage',
	SessionReasoning = 'session/reasoning',
	SessionModelChanged = 'session/modelChanged',
	SessionServerToolsChanged = 'session/serverToolsChanged',
	SessionActiveClientChanged = 'session/activeClientChanged',
	SessionActiveClientToolsChanged = 'session/activeClientToolsChanged',
	SessionPendingMessageSet = 'session/pendingMessageSet',
	SessionPendingMessageRemoved = 'session/pendingMessageRemoved',
	SessionQueuedMessagesReordered = 'session/queuedMessagesReordered',
	SessionInputRequested = 'session/inputRequested',
	SessionInputAnswerChanged = 'session/inputAnswerChanged',
	SessionInputCompleted = 'session/inputCompleted',
	SessionCustomizationsChanged = 'session/customizationsChanged',
	SessionCustomizationToggled = 'session/customizationToggled',
	SessionTruncated = 'session/truncated',
	SessionIsReadChanged = 'session/isReadChanged',
	SessionIsArchivedChanged = 'session/isArchivedChanged',
	SessionActivityChanged = 'session/activityChanged',
	SessionDiffsChanged = 'session/diffsChanged',
	SessionConfigChanged = 'session/configChanged',
	SessionMetaChanged = 'session/metaChanged',
	RootTerminalsChanged = 'root/terminalsChanged',
	RootConfigChanged = 'root/configChanged',
	TerminalData = 'terminal/data',
	TerminalInput = 'terminal/input',
	TerminalResized = 'terminal/resized',
	TerminalClaimed = 'terminal/claimed',
	TerminalTitleChanged = 'terminal/titleChanged',
	TerminalCwdChanged = 'terminal/cwdChanged',
	TerminalExited = 'terminal/exited',
	TerminalCleared = 'terminal/cleared',
	TerminalCommandDetectionAvailable = 'terminal/commandDetectionAvailable',
	TerminalCommandExecuted = 'terminal/commandExecuted',
	TerminalCommandFinished = 'terminal/commandFinished',
}

// ─── Action Envelope ─────────────────────────────────────────────────────────

/**
 * Identifies the client that originally dispatched an action.
 */
export interface ActionOrigin {
	clientId: string;
	clientSeq: number;
}

/**
 * Every action is wrapped in an `ActionEnvelope`.
 */
export interface ActionEnvelope {
	readonly action: StateAction;
	readonly serverSeq: number;
	readonly origin: ActionOrigin | undefined;
	readonly rejectionReason?: string;
}

// ─── Root Actions ────────────────────────────────────────────────────────────

/**
 * Base interface for all tool-call-scoped actions, carrying the common
 * session, turn, and tool call identifiers.
 *
 * @category Session Actions
 */
interface ToolCallActionBase {
	/** Session URI */
	session: URI;
	/** Turn identifier */
	turnId: string;
	/** Tool call identifier */
	toolCallId: string;
	/**
	 * Additional provider-specific metadata for this tool call.
	 *
	 * Clients MAY look for well-known keys here to provide enhanced UI.
	 * For example, a `ptyTerminal` key with `{ input: string; output: string }`
	 * indicates the tool operated on a terminal (both `input` and `output` may
	 * contain escape sequences).
	 */
	_meta?: Record<string, unknown>;
}

/**
 * Fired when available agent backends or their models change.
 *
 * @category Root Actions
 * @version 1
 */
export interface RootAgentsChangedAction {
	type: ActionType.RootAgentsChanged;
	/** Updated agent list */
	agents: AgentInfo[];
}

/**
 * Fired when the number of active sessions changes.
 *
 * @category Root Actions
 * @version 1
 */
export interface RootActiveSessionsChangedAction {
	type: ActionType.RootActiveSessionsChanged;
	/** Current count of active sessions */
	activeSessions: number;
}

/**
 * Fired when the list of known terminals changes.
 *
 * Full-replacement semantics: the `terminals` array replaces the previous
 * `terminals` entirely.
 *
 * @category Root Actions
 * @version 1
 */
export interface RootTerminalsChangedAction {
	type: ActionType.RootTerminalsChanged;
	/** Updated terminal list (full replacement) */
	terminals: TerminalInfo[];
}

/**
 * Fired when agent-host configuration values change.
 *
 * By default, the reducer merges the new values into `state.config.values`.
 * Set `replace` to `true` to replace all values instead of merging.
 *
 * @category Root Actions
 * @version 1
 * @clientDispatchable
 */
export interface RootConfigChangedAction {
	type: ActionType.RootConfigChanged;
	/** Updated config values */
	config: Record<string, unknown>;
	/** When `true`, replaces all config values instead of merging */
	replace?: boolean;
}

// ─── Session Actions ─────────────────────────────────────────────────────────

/**
 * Session backend initialized successfully.
 *
 * @category Session Actions
 * @version 1
 */
export interface SessionReadyAction {
	type: ActionType.SessionReady;
	/** Session URI */
	session: URI;
}

/**
 * Session backend failed to initialize.
 *
 * @category Session Actions
 * @version 1
 */
export interface SessionCreationFailedAction {
	type: ActionType.SessionCreationFailed;
	/** Session URI */
	session: URI;
	/** Error details */
	error: ErrorInfo;
}

/**
 * User sent a message; server starts agent processing.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionTurnStartedAction {
	type: ActionType.SessionTurnStarted;
	/** Session URI */
	session: URI;
	/** Turn identifier */
	turnId: string;
	/** User's message */
	userMessage: UserMessage;
	/** If this turn was auto-started from a queued message, the ID of that message */
	queuedMessageId?: string;
}

/**
 * Streaming text chunk from the assistant, appended to a specific response part.
 *
 * The server MUST first emit a `session/responsePart` to create the target
 * part (markdown or reasoning), then use this action to append text to it.
 *
 * @category Session Actions
 * @version 1
 */
export interface SessionDeltaAction {
	type: ActionType.SessionDelta;
	/** Session URI */
	session: URI;
	/** Turn identifier */
	turnId: string;
	/** Identifier of the response part to append to */
	partId: string;
	/** Text chunk */
	content: string;
}

/**
 * Structured content appended to the response.
 *
 * @category Session Actions
 * @version 1
 */
export interface SessionResponsePartAction {
	type: ActionType.SessionResponsePart;
	/** Session URI */
	session: URI;
	/** Turn identifier */
	turnId: string;
	/** Response part (markdown or content ref) */
	part: ResponsePart;
}

/**
 * A tool call begins — parameters are streaming from the LM.
 *
 * For client-provided tools, the server sets `toolClientId` to identify the
 * owning client. That client is responsible for executing the tool once it
 * reaches the `running` state and dispatching `session/toolCallComplete`.
 *
 * @category Session Actions
 * @version 1
 */
export interface SessionToolCallStartAction extends ToolCallActionBase {
	type: ActionType.SessionToolCallStart;
	/** Internal tool name (for debugging/logging) */
	toolName: string;
	/** Human-readable tool name */
	displayName: string;
	/**
	 * If this tool is provided by a client, the `clientId` of the owning client.
	 * Absent for server-side tools.
	 */
	toolClientId?: string;
}

/**
 * Streaming partial parameters for a tool call.
 *
 * @category Session Actions
 * @version 1
 */
export interface SessionToolCallDeltaAction extends ToolCallActionBase {
	type: ActionType.SessionToolCallDelta;
	/** Partial parameter content to append */
	content: string;
	/** Updated progress message */
	invocationMessage?: StringOrMarkdown;
}

/**
 * Tool call parameters are complete, or a running tool requires re-confirmation.
 *
 * When dispatched for a `streaming` tool call, transitions to `pending-confirmation`
 * or directly to `running` if `confirmed` is set.
 *
 * When dispatched for a `running` tool call (e.g. mid-execution permission needed),
 * transitions back to `pending-confirmation`. The `invocationMessage` and `_meta`
 * SHOULD be updated to describe the specific confirmation needed. Clients use the
 * standard `session/toolCallConfirmed` flow to approve or deny.
 *
 * For client-provided tools, the server typically sets `confirmed` to
 * `'not-needed'` so the tool transitions directly to `running`, where the
 * owning client can begin execution immediately.
 *
 * @category Session Actions
 * @version 1
 */
export interface SessionToolCallReadyAction extends ToolCallActionBase {
	type: ActionType.SessionToolCallReady;
	/** Message describing what the tool will do or what confirmation is needed */
	invocationMessage: StringOrMarkdown;
	/** Raw tool input */
	toolInput?: string;
	/** Short title for the confirmation prompt (e.g. `"Run in terminal"`, `"Write file"`) */
	confirmationTitle?: StringOrMarkdown;
	/** File edits that this tool call will perform, for preview before confirmation */
	edits?: { items: FileEdit[] };
	/** Whether the agent host allows the client to edit the tool's input parameters before confirming */
	editable?: boolean;
	/** If set, the tool was auto-confirmed and transitions directly to `running` */
	confirmed?: ToolCallConfirmationReason;
	/**
	 * Options the server offers for this confirmation. When present, the client
	 * SHOULD render these instead of a plain approve/deny UI. Each option
	 * belongs to a {@link ConfirmationOptionGroup} so the client can still
	 * categorise the choices.
	 */
	options?: ConfirmationOption[];
}

/**
 * Client approves a pending tool call. The tool transitions to `running`.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionToolCallApprovedAction extends ToolCallActionBase {
	type: ActionType.SessionToolCallConfirmed;
	/** The tool call was approved */
	approved: true;
	/** How the tool was confirmed */
	confirmed: ToolCallConfirmationReason;
	/** Edited tool input parameters, if the client modified them before confirming */
	editedToolInput?: string;
	/** ID of the selected confirmation option, if the server provided options */
	selectedOptionId?: string;
}

/**
 * Client denies a pending tool call. The tool transitions to `cancelled`.
 *
 * For client-provided tools, the owning client MUST dispatch this if it does
 * not recognize the tool or cannot execute it.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionToolCallDeniedAction extends ToolCallActionBase {
	type: ActionType.SessionToolCallConfirmed;
	/** The tool call was denied */
	approved: false;
	/** Why the tool was cancelled */
	reason: ToolCallCancellationReason.Denied | ToolCallCancellationReason.Skipped;
	/** What the user suggested doing instead */
	userSuggestion?: UserMessage;
	/** Optional explanation for the denial */
	reasonMessage?: StringOrMarkdown;
	/** ID of the selected confirmation option, if the server provided options */
	selectedOptionId?: string;
}

/**
 * Client confirms or denies a pending tool call.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export type SessionToolCallConfirmedAction =
	| SessionToolCallApprovedAction
	| SessionToolCallDeniedAction;

/**
 * Tool execution finished. Transitions to `completed` or `pending-result-confirmation`
 * if `requiresResultConfirmation` is `true`.
 *
 * For client-provided tools (where `toolClientId` is set on the tool call state),
 * the owning client dispatches this action with the execution result. The server
 * SHOULD reject this action if the dispatching client does not match `toolClientId`.
 *
 * Servers waiting on a client tool call MAY time out after a reasonable duration
 * if the implementing client disconnects or becomes unresponsive, and dispatch
 * this action with `result.success = false` and an appropriate error.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionToolCallCompleteAction extends ToolCallActionBase {
	type: ActionType.SessionToolCallComplete;
	/** Execution result */
	result: ToolCallResult;
	/** If true, the result requires client approval before finalizing */
	requiresResultConfirmation?: boolean;
}

/**
 * Client approves or denies a tool's result.
 *
 * If `approved` is `false`, the tool transitions to `cancelled` with reason `result-denied`.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionToolCallResultConfirmedAction extends ToolCallActionBase {
	type: ActionType.SessionToolCallResultConfirmed;
	/** Whether the result was approved */
	approved: boolean;
}

/**
 * Partial content produced while a tool is still executing.
 *
 * Replaces the `content` array on the running tool call state. Clients can
 * use this to display live feedback (e.g. a terminal reference) before the
 * tool completes.
 *
 * For client-provided tools (where `toolClientId` is set on the tool call state),
 * the owning client dispatches this action to stream intermediate content while
 * executing. The server SHOULD reject this action if the dispatching client does
 * not match `toolClientId`.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionToolCallContentChangedAction extends ToolCallActionBase {
	type: ActionType.SessionToolCallContentChanged;
	/** The current partial content for the running tool call */
	content: ToolResultContent[];
}

/**
 * Turn finished — the assistant is idle.
 *
 * @category Session Actions
 * @version 1
 */
export interface SessionTurnCompleteAction {
	type: ActionType.SessionTurnComplete;
	/** Session URI */
	session: URI;
	/** Turn identifier */
	turnId: string;
}

/**
 * Turn was aborted; server stops processing.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionTurnCancelledAction {
	type: ActionType.SessionTurnCancelled;
	/** Session URI */
	session: URI;
	/** Turn identifier */
	turnId: string;
}

/**
 * Error during turn processing.
 *
 * @category Session Actions
 * @version 1
 */
export interface SessionErrorAction {
	type: ActionType.SessionError;
	/** Session URI */
	session: URI;
	/** Turn identifier */
	turnId: string;
	/** Error details */
	error: ErrorInfo;
}

/**
 * Session title updated. Fired by the server when the title is auto-generated
 * from conversation, or dispatched by a client to rename a session.
 *
 * @category Session Actions
 * @clientDispatchable
 * @version 1
 */
export interface SessionTitleChangedAction {
	type: ActionType.SessionTitleChanged;
	/** Session URI */
	session: URI;
	/** New title */
	title: string;
}

/**
 * Token usage report for a turn.
 *
 * @category Session Actions
 * @version 1
 */
export interface SessionUsageAction {
	type: ActionType.SessionUsage;
	/** Session URI */
	session: URI;
	/** Turn identifier */
	turnId: string;
	/** Token usage data */
	usage: UsageInfo;
}

/**
 * Reasoning/thinking text from the model, appended to a specific reasoning response part.
 *
 * The server MUST first emit a `session/responsePart` to create the target
 * reasoning part, then use this action to append text to it.
 *
 * @category Session Actions
 * @version 1
 */
export interface SessionReasoningAction {
	type: ActionType.SessionReasoning;
	/** Session URI */
	session: URI;
	/** Turn identifier */
	turnId: string;
	/** Identifier of the reasoning response part to append to */
	partId: string;
	/** Reasoning text chunk */
	content: string;
}

/**
 * Model changed for this session.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionModelChangedAction {
	type: ActionType.SessionModelChanged;
	/** Session URI */
	session: URI;
	/** New model selection */
	model: ModelSelection;
}

/**
 * The read state of the session changed.
 *
 * Dispatched by a client to mark a session as read (e.g. after viewing it)
 * or unread (e.g. after new activity since the client last looked at it).
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionIsReadChangedAction {
	type: ActionType.SessionIsReadChanged;
	/** Session URI */
	session: URI;
	/** Whether the session has been read */
	isRead: boolean;
}

/**
 * The archived state of the session changed.
 *
 * Dispatched by a client to archive a session (e.g. the task is
 * complete) or to unarchive it.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionIsArchivedChangedAction {
	type: ActionType.SessionIsArchivedChanged;
	/** Session URI */
	session: URI;
	/** Whether the session is archived */
	isArchived: boolean;
}

/**
 * The activity description of the session changed.
 *
 * Dispatched by the server to indicate what the session is currently doing
 * (e.g. running a tool, thinking). Clear activity by setting it to `undefined`.
 *
 * @category Session Actions
 * @version 1
 */
export interface SessionActivityChangedAction {
	type: ActionType.SessionActivityChanged;
	/** Session URI */
	session: URI;
	/** Human-readable description of current activity, or `undefined` to clear */
	activity: string | undefined;
}

/**
 * The file diffs for the session changed.
 *
 * Full-replacement semantics: the `diffs` array replaces the previous
 * `summary.diffs` entirely.
 *
 * @category Session Actions
 * @version 1
 */
export interface SessionDiffsChangedAction {
	type: ActionType.SessionDiffsChanged;
	/** Session URI */
	session: URI;
	/** Updated file diffs for the session */
	diffs: FileEdit[];
}

/**
 * Server tools for this session have changed.
 *
 * Full-replacement semantics: the `tools` array replaces the previous `serverTools` entirely.
 *
 * @category Session Actions
 * @version 1
 */
export interface SessionServerToolsChangedAction {
	type: ActionType.SessionServerToolsChanged;
	/** Session URI */
	session: URI;
	/** Updated server tools list (full replacement) */
	tools: ToolDefinition[];
}

/**
 * The active client for this session has changed.
 *
 * A client dispatches this action with its own `SessionActiveClient` to claim
 * the active role, or with `null` to release it. The server SHOULD reject if
 * another client is already active. The server SHOULD automatically dispatch
 * this action with `activeClient: null` when the active client disconnects.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionActiveClientChangedAction {
	type: ActionType.SessionActiveClientChanged;
	/** Session URI */
	session: URI;
	/** The new active client, or `null` to unset */
	activeClient: SessionActiveClient | null;
}

/**
 * The active client's tool list has changed.
 *
 * Full-replacement semantics: the `tools` array replaces the active client's
 * previous tools entirely. The server SHOULD reject if the dispatching client
 * is not the current active client.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionActiveClientToolsChangedAction {
	type: ActionType.SessionActiveClientToolsChanged;
	/** Session URI */
	session: URI;
	/** Updated client tools list (full replacement) */
	tools: ToolDefinition[];
}

// ─── Customization Actions ───────────────────────────────────────────────────

/**
 * The session's customizations have changed.
 *
 * Full-replacement semantics: the `customizations` array replaces the
 * previous `customizations` entirely.
 *
 * @category Session Actions
 * @version 1
 */
export interface SessionCustomizationsChangedAction {
	type: ActionType.SessionCustomizationsChanged;
	/** Session URI */
	session: URI;
	/** Updated customization list (full replacement) */
	customizations: SessionCustomization[];
}

/**
 * A client toggled a customization on or off.
 *
 * The server locates the customization by `uri` in the session's
 * customization list and sets its `enabled` flag.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionCustomizationToggledAction {
	type: ActionType.SessionCustomizationToggled;
	/** Session URI */
	session: URI;
	/** The URI of the customization to toggle */
	uri: URI;
	/** Whether to enable or disable the customization */
	enabled: boolean;
}

// ─── Config Actions ──────────────────────────────────────────────────────────

/**
 * Client changed a mutable config value mid-session.
 *
 * Only properties with `sessionMutable: true` in the config schema may be
 * changed. The server validates and broadcasts the action; the reducer merges
 * the new values into `state.config.values`.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionConfigChangedAction {
	type: ActionType.SessionConfigChanged;
	/** Session URI */
	session: URI;
	/** Updated config values */
	config: Record<string, unknown>;
	/** When `true`, replaces all config values instead of merging */
	replace?: boolean;
}

/**
 * The session's `_meta` side-channel changed. Replaces `state._meta`
 * entirely (full-replacement semantics). Producers SHOULD merge any
 * keys they wish to preserve into the new value before dispatching.
 *
 * @category Session Actions
 * @version 1
 */
export interface SessionMetaChangedAction {
	type: ActionType.SessionMetaChanged;
	/** Session URI */
	session: URI;
	/** New `_meta` payload, or `undefined` to clear it */
	_meta: Record<string, unknown> | undefined;
}

// ─── Truncation ──────────────────────────────────────────────────────────────

/**
 * Truncates a session's history. If `turnId` is provided, all turns after that
 * turn are removed and the specified turn is kept. If `turnId` is omitted, all
 * turns are removed.
 *
 * If there is an active turn it is silently dropped and the session status
 * returns to `idle`.
 *
 * Common use-case: truncate old data then dispatch a new
 * `session/turnStarted` with an edited message.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionTruncatedAction {
	type: ActionType.SessionTruncated;
	/** Session URI */
	session: URI;
	/** Keep turns up to and including this turn. Omit to clear all turns. */
	turnId?: string;
}

// ─── Pending Message Actions ─────────────────────────────────────────────────

/**
 * A pending message was set (upsert semantics: creates or replaces).
 *
 * For steering messages, this always replaces the single steering message.
 * For queued messages, if a message with the given `id` already exists it is
 * updated in place; otherwise it is appended to the queue. If the session is
 * idle when a queued message is set, the server SHOULD immediately consume it
 * and start a new turn.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionPendingMessageSetAction {
	type: ActionType.SessionPendingMessageSet;
	/** Session URI */
	session: URI;
	/** Whether this is a steering or queued message */
	kind: PendingMessageKind;
	/** Unique identifier for this pending message */
	id: string;
	/** The message content */
	userMessage: UserMessage;
}

/**
 * A pending message was removed (steering or queued).
 *
 * Dispatched by clients to cancel a pending message, or by the server when
 * it consumes a message (e.g. starting a turn from a queued message or
 * injecting a steering message into the current turn).
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionPendingMessageRemovedAction {
	type: ActionType.SessionPendingMessageRemoved;
	/** Session URI */
	session: URI;
	/** Whether this is a steering or queued message */
	kind: PendingMessageKind;
	/** Identifier of the pending message to remove */
	id: string;
}

/**
 * Reorder the queued messages.
 *
 * The `order` array contains the IDs of queued messages in their new
 * desired order. IDs not present in the current queue are ignored.
 * Queued messages whose IDs are absent from `order` are appended at
 * the end in their original relative order (so a client with a stale
 * view of the queue never silently drops messages).
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionQueuedMessagesReorderedAction {
	type: ActionType.SessionQueuedMessagesReordered;
	/** Session URI */
	session: URI;
	/** Queued message IDs in the desired order */
	order: string[];
}

// ─── Session Input Actions ──────────────────────────────────────────────────

/**
 * A session requested input from the user.
 *
 * Full-request upsert semantics: the `request` replaces any existing request
 * with the same `id`, or is appended if it is new. Answer drafts are preserved
 * unless `request.answers` is provided.
 *
 * @category Session Actions
 * @version 1
 */
export interface SessionInputRequestedAction {
	type: ActionType.SessionInputRequested;
	/** Session URI */
	session: URI;
	/** Input request to create or replace */
	request: SessionInputRequest;
}

/**
 * A client updated, submitted, skipped, or removed a single in-progress answer.
 *
 * Dispatching with `answer: undefined` removes that question's answer draft.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionInputAnswerChangedAction {
	type: ActionType.SessionInputAnswerChanged;
	/** Session URI */
	session: URI;
	/** Input request identifier */
	requestId: string;
	/** Question identifier within the input request */
	questionId: string;
	/** Updated answer, or `undefined` to clear an answer draft */
	answer?: SessionInputAnswer;
}

/**
 * A client accepted, declined, or cancelled a session input request.
 *
 * If accepted, the server uses `answers` (when provided) plus the request's
 * synced answer state to resume the blocked operation.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface SessionInputCompletedAction {
	type: ActionType.SessionInputCompleted;
	/** Session URI */
	session: URI;
	/** Input request identifier */
	requestId: string;
	/** Completion outcome */
	response: SessionInputResponseKind;
	/** Optional final answer replacement, keyed by question ID */
	answers?: Record<string, SessionInputAnswer>;
}

// ─── Terminal Actions ────────────────────────────────────────────────────────

/**
 * Terminal output data (pty → client direction).
 *
 * Appends `data` to the terminal's `content` in the reducer.
 *
 * `terminal/data` and `terminal/input` are intentionally separate actions
 * because standard write-ahead reconciliation is not safe for terminal I/O.
 * A pty is a stateful, mutable process — optimistically applying input or
 * predicting output would produce incorrect state. Instead, `terminal/input`
 * is a side-effect-only action (client → server → pty), and `terminal/data`
 * is server-authoritative output (pty → server → client).
 *
 * @category Terminal Actions
 * @version 1
 */
export interface TerminalDataAction {
	type: ActionType.TerminalData;
	/** Terminal URI */
	terminal: URI;
	/** Output data (may contain ANSI escape sequences) */
	data: string;
}

/**
 * Keyboard input sent to the terminal process (client → pty direction).
 *
 * This is a side-effect-only action: the server forwards the data to the
 * terminal's pty. The reducer treats this as a no-op since `terminal/data`
 * actions will reflect any resulting output.
 *
 * See `terminal/data` for why these two actions are kept separate.
 *
 * @category Terminal Actions
 * @version 1
 * @clientDispatchable
 */
export interface TerminalInputAction {
	type: ActionType.TerminalInput;
	/** Terminal URI */
	terminal: URI;
	/** Input data to send to the pty */
	data: string;
}

/**
 * Terminal dimensions changed.
 *
 * Dispatchable by clients to request a resize, or by the server to inform
 * clients of the actual terminal dimensions.
 *
 * @category Terminal Actions
 * @version 1
 * @clientDispatchable
 */
export interface TerminalResizedAction {
	type: ActionType.TerminalResized;
	/** Terminal URI */
	terminal: URI;
	/** Terminal width in columns */
	cols: number;
	/** Terminal height in rows */
	rows: number;
}

/**
 * Terminal claim changed. A client or session transfers ownership of the terminal.
 *
 * The server SHOULD reject if the dispatching client does not currently hold
 * the claim.
 *
 * @category Terminal Actions
 * @version 1
 * @clientDispatchable
 */
export interface TerminalClaimedAction {
	type: ActionType.TerminalClaimed;
	/** Terminal URI */
	terminal: URI;
	/** The new claim */
	claim: TerminalClaim;
}

/**
 * Terminal title changed.
 *
 * Fired by the server when the terminal process updates its title (e.g. via
 * escape sequences), or dispatched by a client to rename a terminal.
 *
 * @category Terminal Actions
 * @version 1
 * @clientDispatchable
 */
export interface TerminalTitleChangedAction {
	type: ActionType.TerminalTitleChanged;
	/** Terminal URI */
	terminal: URI;
	/** New terminal title */
	title: string;
}

/**
 * Terminal working directory changed.
 *
 * @category Terminal Actions
 * @version 1
 */
export interface TerminalCwdChangedAction {
	type: ActionType.TerminalCwdChanged;
	/** Terminal URI */
	terminal: URI;
	/** New working directory */
	cwd: URI;
}

/**
 * Terminal process exited.
 *
 * @category Terminal Actions
 * @version 1
 */
export interface TerminalExitedAction {
	type: ActionType.TerminalExited;
	/** Terminal URI */
	terminal: URI;
	/** Process exit code. `undefined` if the process was killed without an exit code. */
	exitCode?: number;
}

/**
 * Terminal scrollback buffer cleared.
 *
 * @category Terminal Actions
 * @version 1
 * @clientDispatchable
 */
export interface TerminalClearedAction {
	type: ActionType.TerminalCleared;
	/** Terminal URI */
	terminal: URI;
}

/**
 * Shell integration has loaded and the terminal now supports command
 * detection. The server dispatches this when shell integration becomes
 * available (which may happen asynchronously after the terminal is created).
 *
 * Clients MUST NOT assume command detection is available until this action
 * (or `terminal/commandExecuted`) has been received.
 *
 * @category Terminal Actions
 * @version 1
 */
export interface TerminalCommandDetectionAvailableAction {
	type: ActionType.TerminalCommandDetectionAvailable;
	/** Terminal URI */
	terminal: URI;
}

/**
 * A command has been submitted to the shell and is now executing.
 * All subsequent `terminal/data` actions (until the matching
 * `terminal/commandFinished`) constitute this command's output.
 *
 * @category Terminal Actions
 * @version 1
 */
export interface TerminalCommandExecutedAction {
	type: ActionType.TerminalCommandExecuted;
	/** Terminal URI */
	terminal: URI;
	/**
	 * Stable identifier for this command, scoped to the terminal URI.
	 * Allows correlating `commandExecuted` → `commandFinished` pairs.
	 */
	commandId: string;
	/** The command line text that was submitted */
	commandLine: string;
	/**
	 * Unix timestamp (ms) of when the command started executing, as measured
	 * on the server.
	 */
	timestamp: number;
}

/**
 * A command has finished executing.
 *
 * The sequence of `terminal/data` actions between the preceding
 * `terminal/commandExecuted` (same `commandId`) and this action constitutes
 * the complete output of the command.
 *
 * @category Terminal Actions
 * @version 1
 */
export interface TerminalCommandFinishedAction {
	type: ActionType.TerminalCommandFinished;
	/** Terminal URI */
	terminal: URI;
	/** Matches the `commandId` from the corresponding `commandExecuted` */
	commandId: string;
	/** Shell exit code. `undefined` if the shell did not report one. */
	exitCode?: number;
	/**
	 * Wall-clock duration of the command in milliseconds, as measured by the
	 * shell integration script on the server side.
	 */
	durationMs?: number;
}

// ─── Discriminated Union ─────────────────────────────────────────────────────

/**
 * Discriminated union of all state actions.
 */
export type StateAction =
	| RootAgentsChangedAction
	| RootActiveSessionsChangedAction
	| RootTerminalsChangedAction
	| RootConfigChangedAction
	| SessionReadyAction
	| SessionCreationFailedAction
	| SessionTurnStartedAction
	| SessionDeltaAction
	| SessionResponsePartAction
	| SessionToolCallStartAction
	| SessionToolCallDeltaAction
	| SessionToolCallReadyAction
	| SessionToolCallConfirmedAction
	| SessionToolCallCompleteAction
	| SessionToolCallResultConfirmedAction
	| SessionToolCallContentChangedAction
	| SessionTurnCompleteAction
	| SessionTurnCancelledAction
	| SessionErrorAction
	| SessionTitleChangedAction
	| SessionUsageAction
	| SessionReasoningAction
	| SessionModelChangedAction
	| SessionServerToolsChangedAction
	| SessionActiveClientChangedAction
	| SessionActiveClientToolsChangedAction
	| SessionPendingMessageSetAction
	| SessionPendingMessageRemovedAction
	| SessionQueuedMessagesReorderedAction
	| SessionInputRequestedAction
	| SessionInputAnswerChangedAction
	| SessionInputCompletedAction
	| SessionCustomizationsChangedAction
	| SessionCustomizationToggledAction
	| SessionTruncatedAction
	| SessionIsReadChangedAction
	| SessionIsArchivedChangedAction
	| SessionActivityChangedAction
	| SessionDiffsChangedAction
	| SessionConfigChangedAction
	| SessionMetaChangedAction
	| TerminalDataAction
	| TerminalInputAction
	| TerminalResizedAction
	| TerminalClaimedAction
	| TerminalTitleChangedAction
	| TerminalCwdChangedAction
	| TerminalExitedAction
	| TerminalClearedAction
	| TerminalCommandDetectionAvailableAction
	| TerminalCommandExecutedAction
	| TerminalCommandFinishedAction;