@codingame/monaco-vscode-api 34.1.2 → 35.0.0

package/vscode/src/vs/platform/agentHost/common/state/protocol/channels-chat/actions.d.ts

@@ -0,0 +1,584 @@
+import { ActionType } from "../common/actions.js";
+import type { StringOrMarkdown, ErrorInfo, FileEdit, UsageInfo } from "../common/state.js";
+import { ToolCallConfirmationReason, ToolCallCancellationReason, PendingMessageKind, type Message, type ResponsePart, type ToolCallResult, type ToolResultContent, type ChatInputAnswer, type ChatInputRequest, type ChatInputResponseKind, type ConfirmationOption, type ToolCallContributor } from "./state.js";
+/**
+ * Base interface for all tool-call-scoped actions, carrying the common turn
+ * and tool call identifiers. The owning chat URI is identified by the
+ * enclosing {@link ActionEnvelope}'s `channel` field.
+ *
+ * @category Chat Actions
+ */
+interface ToolCallActionBase {
+    /** 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>;
+}
+/**
+ * A new message has been sent to the agent, and a new turn starts.
+ *
+ * A client is only allowed to send {@link MessageKind.User} messages.
+ *
+ * @category Chat Actions
+ * @version 1
+ * @clientDispatchable
+ */
+export interface ChatTurnStartedAction {
+    type: ActionType.ChatTurnStarted;
+    /** Turn identifier */
+    turnId: string;
+    /** The new message */
+    message: Message;
+    /** If this turn was auto-started from a queued message, the ID of that message */
+    queuedMessageId?: string;
+    /**
+     * Additional provider-specific metadata for this action.
+     *
+     * Clients MAY look for well-known keys here to provide enhanced UI, and
+     * agent hosts MAY use it to carry per-event context that does not fit any
+     * other field — for example, attributing the event to a specific agent
+     * (such as a sub-agent acting within the turn). Mirrors the MCP `_meta`
+     * convention.
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Streaming text chunk from the assistant, appended to a specific response part.
+ *
+ * The server MUST first emit a `chat/responsePart` to create the target
+ * part (markdown or reasoning), then use this action to append text to it.
+ *
+ * @category Chat Actions
+ * @version 1
+ */
+export interface ChatDeltaAction {
+    type: ActionType.ChatDelta;
+    /** Turn identifier */
+    turnId: string;
+    /** Identifier of the response part to append to */
+    partId: string;
+    /** Text chunk */
+    content: string;
+    /**
+     * Additional provider-specific metadata for this action.
+     *
+     * Clients MAY look for well-known keys here to provide enhanced UI, and
+     * agent hosts MAY use it to carry per-event context that does not fit any
+     * other field — for example, attributing the event to a specific agent
+     * (such as a sub-agent acting within the turn). Mirrors the MCP `_meta`
+     * convention.
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Structured content appended to the response.
+ *
+ * @category Chat Actions
+ * @version 1
+ */
+export interface ChatResponsePartAction {
+    type: ActionType.ChatResponsePart;
+    /** Turn identifier */
+    turnId: string;
+    /** Response part (markdown or content ref) */
+    part: ResponsePart;
+    /**
+     * Additional provider-specific metadata for this action.
+     *
+     * Clients MAY look for well-known keys here to provide enhanced UI, and
+     * agent hosts MAY use it to carry per-event context that does not fit any
+     * other field — for example, attributing the event to a specific agent
+     * (such as a sub-agent acting within the turn). Mirrors the MCP `_meta`
+     * convention.
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * A tool call begins — parameters are streaming from the LM.
+ *
+ * The server sets {@link ToolCallContributor | `contributor`} to identify
+ * the origin of the tool. For client-provided tools, the named client is
+ * responsible for executing the tool once it reaches the `running` state
+ * and dispatching `chat/toolCallComplete`. For MCP-served tools, the
+ * server executes the call against the named `McpServerCustomization`.
+ *
+ * @category Chat Actions
+ * @version 1
+ */
+export interface ChatToolCallStartAction extends ToolCallActionBase {
+    type: ActionType.ChatToolCallStart;
+    /** Internal tool name (for debugging/logging) */
+    toolName: string;
+    /** Human-readable tool name */
+    displayName: string;
+    /** Human-readable description of what the tool invocation intends to do */
+    intention?: string;
+    /**
+     * Reference to the contributor of the tool being called. Absent for
+     * server-side tools that are not contributed by a client or MCP server.
+     */
+    contributor?: ToolCallContributor;
+}
+/**
+ * Streaming partial parameters for a tool call.
+ *
+ * @category Chat Actions
+ * @version 1
+ */
+export interface ChatToolCallDeltaAction extends ToolCallActionBase {
+    type: ActionType.ChatToolCallDelta;
+    /** 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 `chat/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 Chat Actions
+ * @version 1
+ */
+export interface ChatToolCallReadyAction extends ToolCallActionBase {
+    type: ActionType.ChatToolCallReady;
+    /** 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 Chat Actions
+ * @version 1
+ * @clientDispatchable
+ */
+export interface ChatToolCallApprovedAction extends ToolCallActionBase {
+    type: ActionType.ChatToolCallConfirmed;
+    /** 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 Chat Actions
+ * @version 1
+ * @clientDispatchable
+ */
+export interface ChatToolCallDeniedAction extends ToolCallActionBase {
+    type: ActionType.ChatToolCallConfirmed;
+    /** The tool call was denied */
+    approved: false;
+    /** Why the tool was cancelled */
+    reason: ToolCallCancellationReason.Denied | ToolCallCancellationReason.Skipped;
+    /** What the user suggested doing instead */
+    userSuggestion?: Message;
+    /** 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 Chat Actions
+ * @version 1
+ * @clientDispatchable
+ */
+export type ChatToolCallConfirmedAction = ChatToolCallApprovedAction | ChatToolCallDeniedAction;
+/**
+ * Tool execution finished. Transitions to `completed` or `pending-result-confirmation`
+ * if `requiresResultConfirmation` is `true`.
+ *
+ * For client-provided tools (whose tool call state carries a client
+ * `ToolCallContributor` with a `clientId`), the owning client dispatches this
+ * action with the execution result. The server SHOULD reject this action if the
+ * dispatching client does not match the contributor's `clientId`.
+ *
+ * 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 Chat Actions
+ * @version 1
+ * @clientDispatchable
+ */
+export interface ChatToolCallCompleteAction extends ToolCallActionBase {
+    type: ActionType.ChatToolCallComplete;
+    /** 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 Chat Actions
+ * @version 1
+ * @clientDispatchable
+ */
+export interface ChatToolCallResultConfirmedAction extends ToolCallActionBase {
+    type: ActionType.ChatToolCallResultConfirmed;
+    /** 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 (whose tool call state carries a client
+ * `ToolCallContributor` with a `clientId`), 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 the contributor's
+ * `clientId`.
+ *
+ * @category Chat Actions
+ * @version 1
+ * @clientDispatchable
+ */
+export interface ChatToolCallContentChangedAction extends ToolCallActionBase {
+    type: ActionType.ChatToolCallContentChanged;
+    /** The current partial content for the running tool call */
+    content: ToolResultContent[];
+}
+/**
+ * Turn finished — the assistant is idle.
+ *
+ * @category Chat Actions
+ * @version 1
+ */
+export interface ChatTurnCompleteAction {
+    type: ActionType.ChatTurnComplete;
+    /** Turn identifier */
+    turnId: string;
+    /**
+     * Additional provider-specific metadata for this action.
+     *
+     * Clients MAY look for well-known keys here to provide enhanced UI, and
+     * agent hosts MAY use it to carry per-event context that does not fit any
+     * other field — for example, attributing the event to a specific agent
+     * (such as a sub-agent acting within the turn). Mirrors the MCP `_meta`
+     * convention.
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Turn was aborted; server stops processing.
+ *
+ * @category Chat Actions
+ * @version 1
+ * @clientDispatchable
+ */
+export interface ChatTurnCancelledAction {
+    type: ActionType.ChatTurnCancelled;
+    /** Turn identifier */
+    turnId: string;
+    /**
+     * Additional provider-specific metadata for this action.
+     *
+     * Clients MAY look for well-known keys here to provide enhanced UI, and
+     * agent hosts MAY use it to carry per-event context that does not fit any
+     * other field — for example, attributing the event to a specific agent
+     * (such as a sub-agent acting within the turn). Mirrors the MCP `_meta`
+     * convention.
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Error during turn processing.
+ *
+ * @category Chat Actions
+ * @version 1
+ */
+export interface ChatErrorAction {
+    type: ActionType.ChatError;
+    /** Turn identifier */
+    turnId: string;
+    /** Error details */
+    error: ErrorInfo;
+    /**
+     * Additional provider-specific metadata for this action.
+     *
+     * Clients MAY look for well-known keys here to provide enhanced UI, and
+     * agent hosts MAY use it to carry per-event context that does not fit any
+     * other field — for example, attributing the event to a specific agent
+     * (such as a sub-agent acting within the turn). Mirrors the MCP `_meta`
+     * convention.
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * The activity description of this chat changed.
+ *
+ * Dispatched by the server to indicate what the chat is currently doing
+ * (e.g. running a tool, thinking). Clear activity by omitting it or setting it
+ * to `undefined`.
+ * Producers SHOULD also update the parent session's chat catalog with
+ * `session/chatUpdated` so `ChatSummary.activity` stays in sync.
+ *
+ * @category Chat Actions
+ * @version 1
+ */
+export interface ChatActivityChangedAction {
+    type: ActionType.ChatActivityChanged;
+    /** Human-readable description of current activity; omit or set `undefined` to clear */
+    activity?: string;
+}
+/**
+ * Token usage report for a turn.
+ *
+ * @category Chat Actions
+ * @version 1
+ */
+export interface ChatUsageAction {
+    type: ActionType.ChatUsage;
+    /** Turn identifier */
+    turnId: string;
+    /** Token usage data */
+    usage: UsageInfo;
+    /**
+     * Additional provider-specific metadata for this action.
+     *
+     * Clients MAY look for well-known keys here to provide enhanced UI, and
+     * agent hosts MAY use it to carry per-event context that does not fit any
+     * other field — for example, attributing the event to a specific agent
+     * (such as a sub-agent acting within the turn). Mirrors the MCP `_meta`
+     * convention.
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Reasoning/thinking text from the model, appended to a specific reasoning response part.
+ *
+ * The server MUST first emit a `chat/responsePart` to create the target
+ * reasoning part, then use this action to append text to it.
+ *
+ * @category Chat Actions
+ * @version 1
+ */
+export interface ChatReasoningAction {
+    type: ActionType.ChatReasoning;
+    /** Turn identifier */
+    turnId: string;
+    /** Identifier of the reasoning response part to append to */
+    partId: string;
+    /** Reasoning text chunk */
+    content: string;
+    /**
+     * Additional provider-specific metadata for this action.
+     *
+     * Clients MAY look for well-known keys here to provide enhanced UI, and
+     * agent hosts MAY use it to carry per-event context that does not fit any
+     * other field — for example, attributing the event to a specific agent
+     * (such as a sub-agent acting within the turn). Mirrors the MCP `_meta`
+     * convention.
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * 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 chat status
+ * returns to `idle`.
+ *
+ * Common use-case: truncate old data then dispatch a new
+ * `chat/turnStarted` with an edited message.
+ *
+ * @category Chat Actions
+ * @version 1
+ * @clientDispatchable
+ */
+export interface ChatTruncatedAction {
+    type: ActionType.ChatTruncated;
+    /** Keep turns up to and including this turn. Omit to clear all turns. */
+    turnId?: string;
+}
+/**
+ * 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 chat is
+ * idle when a queued message is set, the server SHOULD immediately consume it
+ * and start a new turn.
+ *
+ * A client is only allowed to send {@link MessageKind.User} messages.
+ *
+ * @category Chat Actions
+ * @version 1
+ * @clientDispatchable
+ */
+export interface ChatPendingMessageSetAction {
+    type: ActionType.ChatPendingMessageSet;
+    /** Whether this is a steering or queued message */
+    kind: PendingMessageKind;
+    /** Unique identifier for this pending message */
+    id: string;
+    /** The message content */
+    message: Message;
+}
+/**
+ * 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 Chat Actions
+ * @version 1
+ * @clientDispatchable
+ */
+export interface ChatPendingMessageRemovedAction {
+    type: ActionType.ChatPendingMessageRemoved;
+    /** 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 Chat Actions
+ * @version 1
+ * @clientDispatchable
+ */
+export interface ChatQueuedMessagesReorderedAction {
+    type: ActionType.ChatQueuedMessagesReordered;
+    /** Queued message IDs in the desired order */
+    order: string[];
+}
+/**
+ * The chat's draft input changed.
+ *
+ * Clients MAY periodically sync their local input state — the message the user
+ * is composing, including its {@link Message.model | model} /
+ * {@link Message.agent | agent} selection and attachments — into the chat's
+ * {@link ChatState.draft | `draft`} so it survives reloads and is visible to
+ * other clients viewing the same chat. Eager syncing is **not** required;
+ * clients SHOULD debounce and MAY sync only at convenient points. Set `draft`
+ * to `undefined` to clear it (e.g. once the message is sent).
+ *
+ * A client is only allowed to draft {@link MessageKind.User} messages.
+ *
+ * @category Chat Actions
+ * @version 1
+ * @clientDispatchable
+ */
+export interface ChatDraftChangedAction {
+    type: ActionType.ChatDraftChanged;
+    /** New draft message, or `undefined` to clear it */
+    draft?: Message;
+}
+/**
+ * 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 Chat Actions
+ * @version 1
+ */
+export interface ChatInputRequestedAction {
+    type: ActionType.ChatInputRequested;
+    /** Input request to create or replace */
+    request: ChatInputRequest;
+}
+/**
+ * A client updated, submitted, skipped, or removed a single in-progress answer.
+ *
+ * Dispatching with `answer: undefined` removes that question's answer draft.
+ *
+ * @category Chat Actions
+ * @version 1
+ * @clientDispatchable
+ */
+export interface ChatInputAnswerChangedAction {
+    type: ActionType.ChatInputAnswerChanged;
+    /** Input request identifier */
+    requestId: string;
+    /** Question identifier within the input request */
+    questionId: string;
+    /** Updated answer, or `undefined` to clear an answer draft */
+    answer?: ChatInputAnswer;
+}
+/**
+ * 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 Chat Actions
+ * @version 1
+ * @clientDispatchable
+ */
+export interface ChatInputCompletedAction {
+    type: ActionType.ChatInputCompleted;
+    /** Input request identifier */
+    requestId: string;
+    /** Completion outcome */
+    response: ChatInputResponseKind;
+    /** Optional final answer replacement, keyed by question ID */
+    answers?: Record<string, ChatInputAnswer>;
+}
+export type ChatAction = ChatTurnStartedAction | ChatDeltaAction | ChatResponsePartAction | ChatToolCallStartAction | ChatToolCallDeltaAction | ChatToolCallReadyAction | ChatToolCallConfirmedAction | ChatToolCallCompleteAction | ChatToolCallResultConfirmedAction | ChatToolCallContentChangedAction | ChatTurnCompleteAction | ChatTurnCancelledAction | ChatErrorAction | ChatActivityChangedAction | ChatUsageAction | ChatReasoningAction | ChatTruncatedAction | ChatPendingMessageSetAction | ChatPendingMessageRemovedAction | ChatQueuedMessagesReorderedAction | ChatDraftChangedAction | ChatInputRequestedAction | ChatInputAnswerChangedAction | ChatInputCompletedAction;
+export {};

package/vscode/src/vs/platform/agentHost/common/state/protocol/channels-chat/commands.d.ts

@@ -0,0 +1,42 @@
+import type { URI } from "../common/state.js";
+import type { BaseParams } from "../common/commands.js";
+import type { Message } from "./state.js";
+/**
+ * Identifies a source chat and turn to fork from.
+ */
+export interface ChatForkSource {
+    /** URI of the existing chat to fork from */
+    chat: URI;
+    /** Turn ID in the source chat; content up to and including this turn's response is copied */
+    turnId: string;
+}
+/**
+ * Creates a new chat within a session.
+ *
+ * @category Commands
+ * @method createChat
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ */
+export interface CreateChatParams extends BaseParams {
+    /** Session URI containing the new chat. */
+    channel: URI;
+    /** Chat URI (client-chosen, e.g. `ahp-chat:/<uuid>`). */
+    chat: URI;
+    /** Optional initial message for the new chat. */
+    initialMessage?: Message;
+    /** Optional source chat and turn to fork from. */
+    source?: ChatForkSource;
+}
+/**
+ * Disposes a chat and cleans up server-side resources.
+ *
+ * @category Commands
+ * @method disposeChat
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ */
+export interface DisposeChatParams extends BaseParams {
+}