vscode/src/vs/platform/agentHost/common/state/protocol/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 IAgentInfo, type IErrorInfo, type IUserMessage, type IResponsePart, type IToolCallResult, type IToolDefinition, type ISessionActiveClient, type IUsageInfo, type ISessionCustomization } 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',
	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',
	SessionCustomizationsChanged = 'session/customizationsChanged',
	SessionCustomizationToggled = 'session/customizationToggled',
}

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

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

/**
 * Every action is wrapped in an `ActionEnvelope`.
 */
export interface IActionEnvelope {
	readonly action: IStateAction;
	readonly serverSeq: number;
	readonly origin: IActionOrigin | 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 IToolCallActionBase {
	/** 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 IRootAgentsChangedAction {
	type: ActionType.RootAgentsChanged;
	/** Updated agent list */
	agents: IAgentInfo[];
}

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

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

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

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

/**
 * User sent a message; server starts agent processing.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface ISessionTurnStartedAction {
	type: ActionType.SessionTurnStarted;
	/** Session URI */
	session: URI;
	/** Turn identifier */
	turnId: string;
	/** User's message */
	userMessage: IUserMessage;
	/** 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 ISessionDeltaAction {
	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 ISessionResponsePartAction {
	type: ActionType.SessionResponsePart;
	/** Session URI */
	session: URI;
	/** Turn identifier */
	turnId: string;
	/** Response part (markdown or content ref) */
	part: IResponsePart;
}

/**
 * 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 ISessionToolCallStartAction extends IToolCallActionBase {
	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 ISessionToolCallDeltaAction extends IToolCallActionBase {
	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 ISessionToolCallReadyAction extends IToolCallActionBase {
	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;
	/** If set, the tool was auto-confirmed and transitions directly to `running` */
	confirmed?: ToolCallConfirmationReason;
}

/**
 * Client approves a pending tool call. The tool transitions to `running`.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export interface ISessionToolCallApprovedAction extends IToolCallActionBase {
	type: ActionType.SessionToolCallConfirmed;
	/** The tool call was approved */
	approved: true;
	/** How the tool was confirmed */
	confirmed: ToolCallConfirmationReason;
}

/**
 * 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 ISessionToolCallDeniedAction extends IToolCallActionBase {
	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?: IUserMessage;
	/** Optional explanation for the denial */
	reasonMessage?: StringOrMarkdown;
}

/**
 * Client confirms or denies a pending tool call.
 *
 * @category Session Actions
 * @version 1
 * @clientDispatchable
 */
export type ISessionToolCallConfirmedAction =
	| ISessionToolCallApprovedAction
	| ISessionToolCallDeniedAction;

/**
 * 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 ISessionToolCallCompleteAction extends IToolCallActionBase {
	type: ActionType.SessionToolCallComplete;
	/** Execution result */
	result: IToolCallResult;
	/** 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 ISessionToolCallResultConfirmedAction extends IToolCallActionBase {
	type: ActionType.SessionToolCallResultConfirmed;
	/** Whether the result was approved */
	approved: boolean;
}

/**
 * Turn finished — the assistant is idle.
 *
 * @category Session Actions
 * @version 1
 */
export interface ISessionTurnCompleteAction {
	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 ISessionTurnCancelledAction {
	type: ActionType.SessionTurnCancelled;
	/** Session URI */
	session: URI;
	/** Turn identifier */
	turnId: string;
}

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

/**
 * 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 ISessionTitleChangedAction {
	type: ActionType.SessionTitleChanged;
	/** Session URI */
	session: URI;
	/** New title */
	title: string;
}

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

/**
 * 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 ISessionReasoningAction {
	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 ISessionModelChangedAction {
	type: ActionType.SessionModelChanged;
	/** Session URI */
	session: URI;
	/** New model ID */
	model: string;
}

/**
 * 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 ISessionServerToolsChangedAction {
	type: ActionType.SessionServerToolsChanged;
	/** Session URI */
	session: URI;
	/** Updated server tools list (full replacement) */
	tools: IToolDefinition[];
}

/**
 * The active client for this session has changed.
 *
 * A client dispatches this action with its own `ISessionActiveClient` 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 ISessionActiveClientChangedAction {
	type: ActionType.SessionActiveClientChanged;
	/** Session URI */
	session: URI;
	/** The new active client, or `null` to unset */
	activeClient: ISessionActiveClient | 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 ISessionActiveClientToolsChangedAction {
	type: ActionType.SessionActiveClientToolsChanged;
	/** Session URI */
	session: URI;
	/** Updated client tools list (full replacement) */
	tools: IToolDefinition[];
}

// ─── 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 ISessionCustomizationsChangedAction {
	type: ActionType.SessionCustomizationsChanged;
	/** Session URI */
	session: URI;
	/** Updated customization list (full replacement) */
	customizations: ISessionCustomization[];
}

/**
 * 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 ISessionCustomizationToggledAction {
	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;
}

// ─── 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 ISessionPendingMessageSetAction {
	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: IUserMessage;
}

/**
 * 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 ISessionPendingMessageRemovedAction {
	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 ISessionQueuedMessagesReorderedAction {
	type: ActionType.SessionQueuedMessagesReordered;
	/** Session URI */
	session: URI;
	/** Queued message IDs in the desired order */
	order: string[];
}

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

/**
 * Discriminated union of all state actions.
 */
export type IStateAction =
	| IRootAgentsChangedAction
	| IRootActiveSessionsChangedAction
	| ISessionReadyAction
	| ISessionCreationFailedAction
	| ISessionTurnStartedAction
	| ISessionDeltaAction
	| ISessionResponsePartAction
	| ISessionToolCallStartAction
	| ISessionToolCallDeltaAction
	| ISessionToolCallReadyAction
	| ISessionToolCallConfirmedAction
	| ISessionToolCallCompleteAction
	| ISessionToolCallResultConfirmedAction
	| ISessionTurnCompleteAction
	| ISessionTurnCancelledAction
	| ISessionErrorAction
	| ISessionTitleChangedAction
	| ISessionUsageAction
	| ISessionReasoningAction
	| ISessionModelChangedAction
	| ISessionServerToolsChangedAction
	| ISessionActiveClientChangedAction
	| ISessionActiveClientToolsChangedAction
	| ISessionPendingMessageSetAction
	| ISessionPendingMessageRemovedAction
	| ISessionQueuedMessagesReorderedAction
	| ISessionCustomizationsChangedAction
	| ISessionCustomizationToggledAction;