@codingame/monaco-vscode-api 34.1.3 → 35.0.1

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

@@ -0,0 +1,1157 @@
+import type { ModelSelection } from "../channels-root/state.js";
+import type { AgentSelection, SessionStatus } from "../channels-session/state.js";
+import type { ContentRef, ErrorInfo, FileEdit, StringOrMarkdown, TextRange, TextSelection, URI, UsageInfo } from "../common/state.js";
+/**
+ * Full state for a single chat, loaded when a client subscribes to the chat's
+ * URI.
+ *
+ * The lightweight catalog representation of a chat is {@link ChatSummary},
+ * carried in {@link SessionState.chats | `SessionState.chats`}. `ChatState`
+ * **denormalizes** every {@link ChatSummary} field directly onto itself so
+ * subscribers receive one flat object instead of having to merge a nested
+ * `summary` sub-object. Producers MUST keep the two representations
+ * consistent: any change to the inlined fields below SHOULD also be
+ * announced on the parent session via the matching
+ * {@link SessionChatUpdatedAction | `session/chatUpdated`} action.
+ *
+ * @category Chat State
+ */
+export interface ChatState {
+    /** Chat URI */
+    resource: URI;
+    /** Chat title */
+    title: string;
+    /** Current chat status (reuses SessionStatus shape) */
+    status: SessionStatus;
+    /** Human-readable description of what the chat is currently doing */
+    activity?: string;
+    /** Last modification timestamp (ISO 8601, e.g. `"2025-03-10T18:42:03.123Z"`) */
+    modifiedAt: string;
+    /** How this chat came into existence */
+    origin?: ChatOrigin;
+    /**
+     * How the user can interact with this chat. See {@link ChatInteractivity}.
+     *
+     * Supports agent-team patterns where worker chats are read-only or hidden.
+     * Absence defaults to {@link ChatInteractivity.Full} for backward
+     * compatibility.
+     */
+    interactivity?: ChatInteractivity;
+    /**
+     * Optional per-chat working directory.
+     *
+     * If absent, the chat inherits
+     * {@link SessionState.workingDirectory | the session's working directory}.
+     * Hosts MAY override this for individual chats — for example, to give a
+     * subordinate chat its own git worktree so multiple chats in a session can
+     * make independent edits that the orchestrator later merges back.
+     */
+    workingDirectory?: URI;
+    /** Completed turns */
+    turns: Turn[];
+    /** Currently in-progress turn */
+    activeTurn?: ActiveTurn;
+    /** Message to inject into the current turn at a convenient point */
+    steeringMessage?: PendingMessage;
+    /** Messages to send automatically as new turns after the current turn finishes */
+    queuedMessages?: PendingMessage[];
+    /** Requests for user input that are currently blocking or informing chat progress */
+    inputRequests?: ChatInputRequest[];
+    /**
+     * The user's in-progress draft input for this chat — the message they are
+     * composing but have not sent yet, including its
+     * {@link Message.model | model} / {@link Message.agent | agent} selection
+     * and attachments.
+     *
+     * Clients MAY periodically sync their local input state into this field so
+     * a draft 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. When presenting input UI for an existing
+     * chat, clients SHOULD use any `draft` to initialize their input state.
+     * Cleared (set to `undefined`) once the message is sent.
+     */
+    draft?: Message;
+    /**
+     * Additional provider-specific metadata for this chat.
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Lightweight catalog entry for a chat, carried in
+ * {@link SessionState.chats | `SessionState.chats`}. The full conversation
+ * lives in {@link ChatState}, which inlines (denormalizes) every field below.
+ *
+ * @category Chat State
+ */
+export interface ChatSummary {
+    /** Chat URI */
+    resource: URI;
+    /** Chat title */
+    title: string;
+    /** Current chat status (reuses SessionStatus shape) */
+    status: SessionStatus;
+    /** Human-readable description of what the chat is currently doing */
+    activity?: string;
+    /** Last modification timestamp (ISO 8601, e.g. `"2025-03-10T18:42:03.123Z"`) */
+    modifiedAt: string;
+    /** How this chat came into existence */
+    origin?: ChatOrigin;
+    /**
+     * How the user can interact with this chat. See {@link ChatInteractivity}.
+     *
+     * Supports agent-team patterns where worker chats are read-only or hidden.
+     * Absence defaults to {@link ChatInteractivity.Full} for backward
+     * compatibility.
+     */
+    interactivity?: ChatInteractivity;
+    /**
+     * Optional per-chat working directory.
+     *
+     * If absent, the chat inherits
+     * {@link SessionSummary.workingDirectory | the session's working directory}.
+     * See {@link ChatState.workingDirectory} for usage notes.
+     */
+    workingDirectory?: URI;
+}
+/**
+ * Discriminant for {@link ChatOrigin} — how a chat came into existence.
+ *
+ * @category Chat State
+ */
+export declare enum ChatOriginKind {
+    /** User created the chat explicitly (e.g. via the host UI). */
+    User = "user",
+    /** Forked from an existing chat at a specific turn. */
+    Fork = "fork",
+    /** Spawned by a tool call running in another chat (e.g. a sub-agent delegation). */
+    Tool = "tool"
+}
+/**
+ * How a chat came into existence. Clients MAY use it to render
+ * contextual UI (parent indicators, fork markers, "spawned by tool" badges).
+ *
+ * The `tool` variant records a tool-spawned worker from the worker's side: its
+ * `chat`/`toolCallId` identify the spawning tool call in the parent chat. This
+ * is the canonical record of the spawn relationship. The same edge is surfaced
+ * from the parent's side by {@link ToolResultSubagentContent}, whose `resource`
+ * is this chat's URI; hosts MUST keep the two consistent.
+ *
+ * @category Chat State
+ */
+export type ChatOrigin = {
+    kind: ChatOriginKind.User;
+} | {
+    kind: ChatOriginKind.Fork;
+    chat: URI;
+    turnId: string;
+} | {
+    kind: ChatOriginKind.Tool;
+    chat: URI;
+    toolCallId: string;
+};
+/**
+ * How a user can interact with a chat.
+ *
+ * - `Full` — user can send messages and watch (default when absent)
+ * - `ReadOnly` — user can watch but not send messages (e.g. agent team workers)
+ * - `Hidden` — internal worker not shown in UI at all
+ *
+ * Supports the agent-team pattern where a lead chat is fully interactive and
+ * worker chats are read-only (visible for observability) or hidden (internal
+ * implementation detail). The harness sets this based on the chat's role;
+ * the UI uses it to show appropriate controls.
+ *
+ * @category Chat State
+ */
+export declare enum ChatInteractivity {
+    /** User can send messages and watch (default when absent) */
+    Full = "full",
+    /** User can watch but not send messages */
+    ReadOnly = "read-only",
+    /** Internal worker not shown in UI at all */
+    Hidden = "hidden"
+}
+/**
+ * Discriminant for pending message kinds.
+ *
+ * @category Pending Message Types
+ */
+export declare enum PendingMessageKind {
+    /** Injected into the current turn at a convenient point */
+    Steering = "steering",
+    /** Sent automatically as a new turn after the current turn finishes */
+    Queued = "queued"
+}
+/**
+ * A message queued for future delivery to the agent.
+ *
+ * Steering messages are injected into the current turn mid-flight.
+ * Queued messages are automatically started as new turns after the
+ * current turn naturally finishes.
+ *
+ * @category Pending Message Types
+ */
+export interface PendingMessage {
+    /** Unique identifier for this pending message */
+    id: string;
+    /** The message that will start the next turn */
+    message: Message;
+}
+/**
+ * How a client completed an input request.
+ *
+ * @category Chat Input Types
+ */
+export declare enum ChatInputResponseKind {
+    Accept = "accept",
+    Decline = "decline",
+    Cancel = "cancel"
+}
+/**
+ * Question/input control kind.
+ *
+ * @category Chat Input Types
+ */
+export declare enum ChatInputQuestionKind {
+    Text = "text",
+    Number = "number",
+    Integer = "integer",
+    Boolean = "boolean",
+    SingleSelect = "single-select",
+    MultiSelect = "multi-select"
+}
+/**
+ * A choice in a select-style question.
+ *
+ * @category Chat Input Types
+ */
+export interface ChatInputOption {
+    /** Stable option identifier; for MCP enum values this is the enum string */
+    id: string;
+    /** Display label */
+    label: string;
+    /** Optional secondary text */
+    description?: string;
+    /** Whether this option is the recommended/default choice */
+    recommended?: boolean;
+}
+interface ChatInputQuestionBase {
+    /** Stable question identifier used as the key in `answers` */
+    id: string;
+    /** Short display title */
+    title?: string;
+    /** Prompt shown to the user */
+    message: string;
+    /** Whether the user must answer this question to accept the request */
+    required?: boolean;
+}
+/** Text question within a chat input request. */
+export interface ChatInputTextQuestion extends ChatInputQuestionBase {
+    kind: ChatInputQuestionKind.Text;
+    /** Format hint for text questions, such as `email`, `uri`, `date`, or `date-time` */
+    format?: string;
+    /** Minimum string length */
+    min?: number;
+    /** Maximum string length */
+    max?: number;
+    /** Default text */
+    defaultValue?: string;
+}
+/** Numeric question within a chat input request. */
+export interface ChatInputNumberQuestion extends ChatInputQuestionBase {
+    kind: ChatInputQuestionKind.Number | ChatInputQuestionKind.Integer;
+    /**
+     * Minimum value
+     * @format float
+     */
+    min?: number;
+    /**
+     * Maximum value
+     * @format float
+     */
+    max?: number;
+    /**
+     * Default numeric value
+     * @format float
+     */
+    defaultValue?: number;
+}
+/** Boolean question within a chat input request. */
+export interface ChatInputBooleanQuestion extends ChatInputQuestionBase {
+    kind: ChatInputQuestionKind.Boolean;
+    /** Default boolean value */
+    defaultValue?: boolean;
+}
+/** Single-select question within a chat input request. */
+export interface ChatInputSingleSelectQuestion extends ChatInputQuestionBase {
+    kind: ChatInputQuestionKind.SingleSelect;
+    /** Options the user may select from */
+    options: ChatInputOption[];
+    /** Whether the user may enter text instead of selecting an option */
+    allowFreeformInput?: boolean;
+}
+/** Multi-select question within a chat input request. */
+export interface ChatInputMultiSelectQuestion extends ChatInputQuestionBase {
+    kind: ChatInputQuestionKind.MultiSelect;
+    /** Options the user may select from */
+    options: ChatInputOption[];
+    /** Whether the user may enter text in addition to selecting options */
+    allowFreeformInput?: boolean;
+    /** Minimum selected item count */
+    min?: number;
+    /** Maximum selected item count */
+    max?: number;
+}
+/**
+ * One question within a chat input request.
+ *
+ * @category Chat Input Types
+ */
+export type ChatInputQuestion = ChatInputTextQuestion | ChatInputNumberQuestion | ChatInputBooleanQuestion | ChatInputSingleSelectQuestion | ChatInputMultiSelectQuestion;
+/**
+ * A live request for user input.
+ *
+ * The server creates or replaces requests with `chat/inputRequested`.
+ * Clients sync drafts with `chat/inputAnswerChanged` and complete requests
+ * with `chat/inputCompleted`.
+ *
+ * @category Chat Input Types
+ */
+export interface ChatInputRequest {
+    /** Stable request identifier */
+    id: string;
+    /** Display message for the request as a whole */
+    message?: string;
+    /** URL the user should review or open, for URL-style elicitations */
+    url?: URI;
+    /** Ordered questions to ask the user */
+    questions?: ChatInputQuestion[];
+    /** Current draft or submitted answers, keyed by question ID */
+    answers?: Record<string, ChatInputAnswer>;
+}
+/**
+ * Answer value kind.
+ *
+ * @category Chat Input Types
+ */
+export declare enum ChatInputAnswerValueKind {
+    Text = "text",
+    Number = "number",
+    Boolean = "boolean",
+    Selected = "selected",
+    SelectedMany = "selected-many"
+}
+/**
+ * Value captured for one answer.
+ *
+ * @category Chat Input Types
+ */
+export interface ChatInputTextAnswerValue {
+    kind: ChatInputAnswerValueKind.Text;
+    value: string;
+}
+export interface ChatInputNumberAnswerValue {
+    kind: ChatInputAnswerValueKind.Number;
+    /** @format float */
+    value: number;
+}
+export interface ChatInputBooleanAnswerValue {
+    kind: ChatInputAnswerValueKind.Boolean;
+    value: boolean;
+}
+export interface ChatInputSelectedAnswerValue {
+    kind: ChatInputAnswerValueKind.Selected;
+    value: string;
+    /** Free-form text entered instead of selecting an option */
+    freeformValues?: string[];
+}
+export interface ChatInputSelectedManyAnswerValue {
+    kind: ChatInputAnswerValueKind.SelectedMany;
+    value: string[];
+    /** Free-form text entered in addition to selected options */
+    freeformValues?: string[];
+}
+export type ChatInputAnswerValue = ChatInputTextAnswerValue | ChatInputNumberAnswerValue | ChatInputBooleanAnswerValue | ChatInputSelectedAnswerValue | ChatInputSelectedManyAnswerValue;
+export interface ChatInputAnswered {
+    /** Answer state */
+    state: ChatInputAnswerState.Draft | ChatInputAnswerState.Submitted;
+    /** Answer value */
+    value: ChatInputAnswerValue;
+}
+export interface ChatInputSkipped {
+    /** Answer state */
+    state: ChatInputAnswerState.Skipped;
+    /** Free-form reason or value captured while skipping, if any */
+    freeformValues?: string[];
+}
+/**
+ * Answer lifecycle state.
+ *
+ * @category Chat Input Types
+ */
+export declare enum ChatInputAnswerState {
+    Draft = "draft",
+    Submitted = "submitted",
+    Skipped = "skipped"
+}
+/**
+ * Draft, submitted, or skipped answer for one question.
+ *
+ * @category Chat Input Types
+ */
+export type ChatInputAnswer = ChatInputAnswered | ChatInputSkipped;
+/**
+ * How a turn ended.
+ *
+ * @category Turn Types
+ */
+export declare enum TurnState {
+    Complete = "complete",
+    Cancelled = "cancelled",
+    Error = "error"
+}
+/**
+ * Discriminant for {@link MessageAttachment} variants.
+ *
+ * @category Turn Types
+ */
+export declare enum MessageAttachmentKind {
+    /** A simple, opaque attachment whose representation is described by the producer. */
+    Simple = "simple",
+    /** An attachment whose data is embedded inline as a base64 string. */
+    EmbeddedResource = "embeddedResource",
+    /** An attachment that references a resource by URI. */
+    Resource = "resource",
+    /** An attachment that references annotations on an annotations channel. */
+    Annotations = "annotations"
+}
+/**
+ * A completed request/response cycle.
+ *
+ * @category Turn Types
+ */
+export interface Turn {
+    /** Turn identifier */
+    id: string;
+    /** The message that initiated the turn */
+    message: Message;
+    /**
+     * All response content in stream order: text, tool calls, reasoning, and content refs.
+     *
+     * Consumers should derive display text by concatenating markdown parts,
+     * and find tool calls by filtering for `ToolCall` parts.
+     */
+    responseParts: ResponsePart[];
+    /** Token usage info */
+    usage: UsageInfo | undefined;
+    /** How the turn ended */
+    state: TurnState;
+    /** Error details if state is `'error'` */
+    error?: ErrorInfo;
+}
+/**
+ * An in-progress turn — the assistant is actively streaming.
+ *
+ * @category Turn Types
+ */
+export interface ActiveTurn {
+    /** Turn identifier */
+    id: string;
+    /** The message that initiated the turn */
+    message: Message;
+    /**
+     * All response content in stream order: text, tool calls, reasoning, and content refs.
+     *
+     * Tool call parts include `pendingPermissions` when permissions are awaiting user approval.
+     */
+    responseParts: ResponsePart[];
+    /** Token usage info */
+    usage: UsageInfo | undefined;
+}
+/**
+ * Discriminant for {@link MessageOrigin} — identifies who produced a message.
+ *
+ * @category Turn Types
+ */
+export declare enum MessageKind {
+    /** Sent directly by the user. */
+    User = "user",
+    /**
+     * Produced by the agent itself rather than the user — for example, an agent
+     * that seeds the first message of a chat it spawned.
+     */
+    Agent = "agent",
+    /**
+     * Produced by a tool rather than the user — for example, a tool that spawns a
+     * worker chat whose first message carries a seed prompt.
+     */
+    Tool = "tool",
+    /** A system-generated notification rather than a direct user message. */
+    SystemNotification = "systemNotification"
+}
+/**
+ * Identifies the origin of a {@link Message} — who produced it. For the message
+ * that initiates a turn ({@link Turn.message}), this is also the origin of the
+ * turn; for steering or queued messages it is just the origin of that message.
+ *
+ * @category Turn Types
+ */
+export interface MessageOrigin {
+    /** The kind of actor that produced the message. */
+    kind: MessageKind;
+}
+/**
+ * A message that initiates or steers a turn. Messages can originate from the
+ * user, the agent, a tool, or be system-generated (see {@link MessageOrigin}).
+ *
+ * Attachments MAY be referenced inside {@link Message.text} via their
+ * {@link MessageAttachmentBase.range} field. Attachments without a range are
+ * still associated with the message but do not correspond to a specific span
+ * in the text.
+ *
+ * @category Turn Types
+ */
+export interface Message {
+    /** Message text */
+    text: string;
+    /** The origin of the message */
+    origin: MessageOrigin;
+    /** File/selection attachments */
+    attachments?: MessageAttachment[];
+    /**
+     * The model this message was, or will be, sent with.
+     *
+     * For historic user/agent messages this records the model actually used, so
+     * a client editing or resending the message can retain that selection. For a
+     * {@link ChatState.draft | draft} it carries the model the user picked for
+     * the message they are composing. Absent means the agent host's default
+     * model applies.
+     */
+    model?: ModelSelection;
+    /**
+     * The custom agent this message was, or will be, sent with.
+     *
+     * For historic messages this records the agent actually used; for a
+     * {@link ChatState.draft | draft} it carries the agent the user picked.
+     * Absent means no custom agent — the provider's default behavior applies.
+     */
+    agent?: AgentSelection;
+    /**
+     * Additional provider-specific metadata for this message.
+     *
+     * Clients MAY look for well-known keys here to provide enhanced UI, and
+     * agent hosts MAY use it to carry context that does not fit any other
+     * field. Mirrors the MCP `_meta` convention.
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Common fields shared by all {@link MessageAttachment} variants.
+ *
+ * @category Turn Types
+ */
+export interface MessageAttachmentBase {
+    /**
+     * A human-readable label for the attachment (e.g. the filename of a file
+     * attachment). Used for display in UI.
+     */
+    label: string;
+    /**
+     * If defined, the range in {@link Message.text} that references this
+     * attachment. This is a text range, not a byte range.
+     */
+    range?: TextRange;
+    /**
+     * Advisory display hint for clients rendering this attachment. Recognized
+     * values include:
+     *
+     * - `'image'`: the attachment is an image
+     * - `'document'`: the attachment is a textual document
+     * - `'symbol'`: the attachment is a code symbol (e.g. a function or class)
+     * - `'directory'`: the attachment is a folder
+     * - `'selection'`: the attachment is a selection within a document
+     *
+     * Implementations MAY provide additional values; clients SHOULD fall back
+     * to a reasonable default when an unknown value is encountered.
+     */
+    displayKind?: string;
+    /**
+     * Additional implementation-defined metadata for the attachment.
+     *
+     * If the attachment was produced by the `completions` command, the client
+     * MUST preserve every property of `_meta` originally returned by the agent
+     * host when sending the user message containing the accepted completion.
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * A simple, opaque attachment whose model representation is described by
+ * the producer.
+ *
+ * @category Turn Types
+ */
+export interface SimpleMessageAttachment extends MessageAttachmentBase {
+    /** Discriminant */
+    type: MessageAttachmentKind.Simple;
+    /**
+     * Representation of the attachment as it should be shown to the model.
+     *
+     * If the attachment was produced by the client, this property MUST be
+     * defined so the agent host can correctly interpret the attachment. This
+     * property MAY be omitted when the attachment originated from a
+     * `completions` response.
+     */
+    modelRepresentation?: string;
+}
+/**
+ * An attachment whose data is embedded inline as a base64 string.
+ *
+ * Use this for small binary payloads (e.g. a pasted image) that should be
+ * delivered with the user message itself rather than fetched separately.
+ *
+ * @category Turn Types
+ */
+export interface MessageEmbeddedResourceAttachment extends MessageAttachmentBase {
+    /** Discriminant */
+    type: MessageAttachmentKind.EmbeddedResource;
+    /** Base64-encoded binary data */
+    data: string;
+    /** Content MIME type (e.g. `"image/png"`, `"application/pdf"`) */
+    contentType: string;
+    /**
+     * Optional selection within the attached textual resource.
+     *
+     * Only meaningful for textual resources.
+     */
+    selection?: TextSelection;
+}
+/**
+ * An attachment that references a resource by URI. The content is not
+ * delivered inline; consumers can fetch it via `resourceRead` when needed.
+ *
+ * @category Turn Types
+ */
+export interface MessageResourceAttachment extends MessageAttachmentBase, ContentRef {
+    /** Discriminant */
+    type: MessageAttachmentKind.Resource;
+    /**
+     * Optional selection within the referenced textual resource.
+     *
+     * Only meaningful for textual resources.
+     */
+    selection?: TextSelection;
+}
+/**
+ * An attachment that references annotations on a session's annotations
+ * channel (see {@link AnnotationsState}).
+ *
+ * When {@link annotationIds} is omitted the attachment references every
+ * annotation on the channel; when present it references only the listed
+ * {@link Annotation.id | annotation ids}.
+ *
+ * @category Turn Types
+ */
+export interface MessageAnnotationsAttachment extends MessageAttachmentBase {
+    /** Discriminant */
+    type: MessageAttachmentKind.Annotations;
+    /**
+     * The annotations channel URI (typically `ahp-session:/<uuid>/annotations`).
+     * Matches {@link AnnotationsSummary.resource}.
+     */
+    resource: URI;
+    /**
+     * Specific {@link Annotation.id | annotation ids} to reference. When
+     * omitted, the attachment references all annotations on the channel.
+     */
+    annotationIds?: string[];
+}
+/**
+ * An attachment associated with a {@link Message}.
+ *
+ * @category Turn Types
+ */
+export type MessageAttachment = SimpleMessageAttachment | MessageEmbeddedResourceAttachment | MessageResourceAttachment | MessageAnnotationsAttachment;
+/**
+ * Discriminant for response part types.
+ *
+ * @category Response Parts
+ */
+export declare enum ResponsePartKind {
+    Markdown = "markdown",
+    ContentRef = "contentRef",
+    ToolCall = "toolCall",
+    Reasoning = "reasoning",
+    SystemNotification = "systemNotification"
+}
+/**
+ * @category Response Parts
+ */
+export interface MarkdownResponsePart {
+    /** Discriminant */
+    kind: ResponsePartKind.Markdown;
+    /** Part identifier, used by `chat/delta` to target this part for content appends */
+    id: string;
+    /** Markdown content */
+    content: string;
+}
+/**
+ * A content part that's a reference to large content stored outside the state tree.
+ *
+ * @category Response Parts
+ */
+export interface ResourceReponsePart extends ContentRef {
+    /** Discriminant */
+    kind: ResponsePartKind.ContentRef;
+}
+/**
+ * A tool call represented as a response part.
+ *
+ * Tool calls are part of the response stream, interleaved with text and
+ * reasoning. The `toolCall.toolCallId` serves as the part identifier for
+ * actions that target this part.
+ *
+ * @category Response Parts
+ */
+export interface ToolCallResponsePart {
+    /** Discriminant */
+    kind: ResponsePartKind.ToolCall;
+    /** Full tool call lifecycle state */
+    toolCall: ToolCallState;
+}
+/**
+ * Reasoning/thinking content from the model.
+ *
+ * @category Response Parts
+ */
+export interface ReasoningResponsePart {
+    /** Discriminant */
+    kind: ResponsePartKind.Reasoning;
+    /** Part identifier, used by `chat/reasoning` to target this part for content appends */
+    id: string;
+    /** Accumulated reasoning text */
+    content: string;
+}
+/**
+ * @category Response Parts
+ */
+export type ResponsePart = MarkdownResponsePart | ResourceReponsePart | ToolCallResponsePart | ReasoningResponsePart | SystemNotificationResponsePart;
+/**
+ * A system notification surfaced as part of the response stream.
+ *
+ * System notifications are messages authored by the agent harness
+ * that need to be visible to both the agent (for situational awareness) and
+ * the user (for transcript continuity). Examples include "background subagent
+ * X completed" or "task Y was cancelled".
+ *
+ * @category Response Parts
+ */
+export interface SystemNotificationResponsePart {
+    /** Discriminant */
+    kind: ResponsePartKind.SystemNotification;
+    /** The text of the system notification */
+    content: StringOrMarkdown;
+}
+/**
+ * Status of a tool call in the lifecycle state machine.
+ *
+ * @category Tool Call Types
+ */
+export declare enum ToolCallStatus {
+    Streaming = "streaming",
+    PendingConfirmation = "pending-confirmation",
+    Running = "running",
+    PendingResultConfirmation = "pending-result-confirmation",
+    Completed = "completed",
+    Cancelled = "cancelled"
+}
+/**
+ * How a tool call was confirmed for execution.
+ *
+ * - `NotNeeded` — No confirmation required (auto-approved)
+ * - `UserAction` — User explicitly approved
+ * - `Setting` — Approved by a persistent user setting
+ *
+ * @category Tool Call Types
+ */
+export declare enum ToolCallConfirmationReason {
+    NotNeeded = "not-needed",
+    UserAction = "user-action",
+    Setting = "setting"
+}
+/**
+ * Why a tool call was cancelled.
+ *
+ * @category Tool Call Types
+ */
+export declare enum ToolCallCancellationReason {
+    Denied = "denied",
+    Skipped = "skipped",
+    ResultDenied = "result-denied"
+}
+/**
+ * Whether a confirmation option represents an approval or denial action.
+ *
+ * @category Tool Call Types
+ */
+export declare enum ConfirmationOptionKind {
+    Approve = "approve",
+    Deny = "deny"
+}
+/**
+ * A confirmation option that the server offers for a tool call awaiting
+ * approval. Allows richer choices beyond simple approve/deny — for example,
+ * "Approve in this Session" or "Deny with reason."
+ *
+ * @category Tool Call Types
+ */
+export interface ConfirmationOption {
+    /** Unique identifier for the option, returned in the confirmed action */
+    id: string;
+    /** Human-readable label displayed to the user */
+    label: string;
+    /** Whether this option represents an approval or denial */
+    kind: ConfirmationOptionKind;
+    /**
+     * Logical group number for visual categorisation.
+     *
+     * Clients SHOULD display options in the order they are defined and MAY
+     * use differing group numbers to insert dividers between logical clusters
+     * of options.
+     */
+    group?: number;
+}
+export declare enum ToolCallContributorKind {
+    Client = "client",
+    MCP = "mcp"
+}
+export interface ToolCallClientContributor {
+    kind: ToolCallContributorKind.Client;
+    /**
+     * If this tool is provided by a client, the `clientId` of the owning client.
+     * Absent for server-side tools.
+     *
+     * When set, the identified client is responsible for executing the tool and
+     * dispatching `chat/toolCallComplete` with the result.
+     */
+    clientId: string;
+}
+export interface ToolCallMcpContributor {
+    kind: ToolCallContributorKind.MCP;
+    /**
+     * Customization ID of the corresponding MCP server in {@link SessionState.customizations}.
+     */
+    customizationId: string;
+}
+export type ToolCallContributor = ToolCallClientContributor | ToolCallMcpContributor;
+/**
+ * Metadata common to all tool call states.
+ *
+ * @category Tool Call Types
+ * @remarks
+ * Fields like `toolName` carry agent-specific identifiers on the wire despite the
+ * agent-agnostic design principle. These exist for debugging and logging purposes.
+ * A future version may move these to a separate diagnostic channel or namespace them
+ * more clearly.
+ */
+interface ToolCallBase {
+    /** Unique tool call identifier */
+    toolCallId: string;
+    /** 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.
+     */
+    contributor?: ToolCallContributor;
+    /**
+     * Additional provider-specific metadata for this tool call.
+     *
+     * This MAY include a `ui` field corresponding to the MCP Apps (SEP-1865)
+     * `McpUiToolMeta` found in MCP tool calls, which may be used in combination
+     * with the {@link contributor} to serve MCP Apps.
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Properties available once tool call parameters are fully received.
+ *
+ * @category Tool Call Types
+ */
+interface ToolCallParameterFields {
+    /** Message describing what the tool will do */
+    invocationMessage: StringOrMarkdown;
+    /** Raw tool input */
+    toolInput?: string;
+}
+/**
+ * Tool execution result details, available after execution completes.
+ *
+ * @category Tool Call Types
+ */
+export interface ToolCallResult {
+    /** Whether the tool succeeded */
+    success: boolean;
+    /** Past-tense description of what the tool did */
+    pastTenseMessage: StringOrMarkdown;
+    /**
+     * Unstructured result content blocks.
+     *
+     * This mirrors the `content` field of MCP `CallToolResult`.
+     */
+    content?: ToolResultContent[];
+    /**
+     * Optional structured result object.
+     *
+     * This mirrors the `structuredContent` field of MCP `CallToolResult`.
+     */
+    structuredContent?: Record<string, unknown>;
+    /** Error details if the tool failed */
+    error?: {
+        message: string;
+        code?: string;
+    };
+}
+/**
+ * LM is streaming the tool call parameters.
+ *
+ * @category Tool Call Types
+ */
+export interface ToolCallStreamingState extends ToolCallBase {
+    status: ToolCallStatus.Streaming;
+    /** Partial parameters accumulated so far */
+    partialInput?: string;
+    /** Progress message shown while parameters are streaming */
+    invocationMessage?: StringOrMarkdown;
+}
+/**
+ * Parameters are complete, or a running tool requires re-confirmation
+ * (e.g. a mid-execution permission check).
+ *
+ * @category Tool Call Types
+ */
+export interface ToolCallPendingConfirmationState extends ToolCallBase, ToolCallParameterFields {
+    status: ToolCallStatus.PendingConfirmation;
+    /** 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;
+    /**
+     * 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[];
+}
+/**
+ * Tool is actively executing.
+ *
+ * @category Tool Call Types
+ */
+export interface ToolCallRunningState extends ToolCallBase, ToolCallParameterFields {
+    status: ToolCallStatus.Running;
+    /** How the tool was confirmed for execution */
+    confirmed: ToolCallConfirmationReason;
+    /** The confirmation option the user selected, if confirmation options were provided */
+    selectedOption?: ConfirmationOption;
+    /**
+     * Partial content produced while the tool is still executing.
+     *
+     * For example, a terminal content block lets clients subscribe to live
+     * output before the tool completes.
+     */
+    content?: ToolResultContent[];
+}
+/**
+ * Tool finished executing, waiting for client to approve the result.
+ *
+ * @category Tool Call Types
+ */
+export interface ToolCallPendingResultConfirmationState extends ToolCallBase, ToolCallParameterFields, ToolCallResult {
+    status: ToolCallStatus.PendingResultConfirmation;
+    /** How the tool was confirmed for execution */
+    confirmed: ToolCallConfirmationReason;
+    /** The confirmation option the user selected, if confirmation options were provided */
+    selectedOption?: ConfirmationOption;
+}
+/**
+ * Tool completed successfully or with an error.
+ *
+ * @category Tool Call Types
+ */
+export interface ToolCallCompletedState extends ToolCallBase, ToolCallParameterFields, ToolCallResult {
+    status: ToolCallStatus.Completed;
+    /** How the tool was confirmed for execution */
+    confirmed: ToolCallConfirmationReason;
+    /** The confirmation option the user selected, if confirmation options were provided */
+    selectedOption?: ConfirmationOption;
+}
+/**
+ * Tool call was cancelled before execution.
+ *
+ * @category Tool Call Types
+ */
+export interface ToolCallCancelledState extends ToolCallBase, ToolCallParameterFields {
+    status: ToolCallStatus.Cancelled;
+    /** Why the tool was cancelled */
+    reason: ToolCallCancellationReason;
+    /** Optional message explaining the cancellation */
+    reasonMessage?: StringOrMarkdown;
+    /** What the user suggested doing instead */
+    userSuggestion?: Message;
+    /** The confirmation option the user selected, if confirmation options were provided */
+    selectedOption?: ConfirmationOption;
+}
+/**
+ * Discriminated union of all tool call lifecycle states.
+ *
+ * See the [state model guide](/guide/state-model.html#tool-call-lifecycle)
+ * for the full state machine diagram.
+ *
+ * @category Tool Call Types
+ */
+export type ToolCallState = ToolCallStreamingState | ToolCallPendingConfirmationState | ToolCallRunningState | ToolCallPendingResultConfirmationState | ToolCallCompletedState | ToolCallCancelledState;
+/**
+ * The two tool-call states that block on a client confirmation: parameter
+ * confirmation before execution ({@link ToolCallPendingConfirmationState}) and
+ * result confirmation after execution
+ * ({@link ToolCallPendingResultConfirmationState}).
+ *
+ * Surfaced at the session level by {@link SessionToolConfirmationRequest}.
+ *
+ * @category Tool Call Types
+ */
+export type ToolCallConfirmationState = ToolCallPendingConfirmationState | ToolCallPendingResultConfirmationState;
+/**
+ * Discriminant for tool result content types.
+ *
+ * @category Tool Result Content
+ */
+export declare enum ToolResultContentType {
+    Text = "text",
+    EmbeddedResource = "embeddedResource",
+    Resource = "resource",
+    FileEdit = "fileEdit",
+    Terminal = "terminal",
+    ShellExit = "shell_exit",
+    Subagent = "subagent"
+}
+/**
+ * Text content in a tool result.
+ *
+ * Mirrors MCP `TextContent`.
+ *
+ * @category Tool Result Content
+ */
+export interface ToolResultTextContent {
+    type: ToolResultContentType.Text;
+    /** The text content */
+    text: string;
+}
+/**
+ * Base64-encoded binary content embedded in a tool result.
+ *
+ * Mirrors MCP `EmbeddedResource` for inline binary data.
+ *
+ * @category Tool Result Content
+ */
+export interface ToolResultEmbeddedResourceContent {
+    type: ToolResultContentType.EmbeddedResource;
+    /** Base64-encoded data */
+    data: string;
+    /** Content type (e.g. `"image/png"`, `"application/pdf"`) */
+    contentType: string;
+}
+/**
+ * A reference to a resource stored outside the tool result.
+ *
+ * Wraps {@link ContentRef} for lazy-loading large results.
+ *
+ * @category Tool Result Content
+ */
+export interface ToolResultResourceContent extends ContentRef {
+    type: ToolResultContentType.Resource;
+}
+/**
+ * Describes a file modification performed by a tool.
+ *
+ * @category Tool Result Content
+ */
+export interface ToolResultFileEditContent extends FileEdit {
+    type: ToolResultContentType.FileEdit;
+}
+/**
+ * A reference to a terminal whose output is relevant to this tool result.
+ *
+ * Clients can subscribe to the terminal's URI to stream its output in real
+ * time, providing live feedback while a tool is executing.
+ *
+ * @category Tool Result Content
+ */
+export interface ToolResultTerminalContent {
+    type: ToolResultContentType.Terminal;
+    /** Terminal URI (subscribable for full terminal state) */
+    resource: URI;
+    /** Display title for the terminal content */
+    title: string;
+}
+/**
+ * Shell command exit metadata emitted by the Copilot SDK shell tool.
+ *
+ * @category Tool Result Content
+ */
+export interface ToolResultShellExitContent {
+    type: ToolResultContentType.ShellExit;
+    /** Shell id, as assigned by Copilot runtime */
+    shellId: string;
+    /** Exit code from the completed shell command */
+    exitCode: number;
+    /** Working directory where the shell command was executed */
+    cwd?: string;
+    /** Output preview associated with the shell command, if available */
+    outputPreview?: string;
+    /** Whether outputPreview is known to be incomplete or truncated */
+    outputTruncated?: boolean;
+}
+/**
+ * A reference, embedded in a tool result, to a worker chat spawned by the tool
+ * call (a sub-agent delegation), referenced by a chat URI (`ahp-chat:/...`).
+ *
+ * This is the spawning tool call's forward view of the worker. The worker chat
+ * records the same edge in reverse via its {@link ChatOrigin} (`kind: 'tool'`),
+ * whose `toolCallId` identifies the tool call that emitted this content.
+ *
+ * @category Tool Result Content
+ */
+export interface ToolResultSubagentContent {
+    type: ToolResultContentType.Subagent;
+    /** Worker chat URI (subscribable for full chat state) */
+    resource: URI;
+    /** Display title for the subagent */
+    title: string;
+    /** Internal agent name */
+    agentName?: string;
+    /** Human-readable description of the subagent's task */
+    description?: string;
+}
+/**
+ * Content block in a tool result.
+ *
+ * Mirrors the content blocks in MCP `CallToolResult.content`, plus
+ * `ToolResultResourceContent` for lazy-loading large results,
+ * `ToolResultFileEditContent` for file edit diffs,
+ * `ToolResultTerminalContent` for live terminal output,
+ * `ToolResultShellExitContent` for shell command exit metadata, and
+ * `ToolResultSubagentContent` for tool-spawned worker chats (AHP extensions).
+ *
+ * @category Tool Result Content
+ */
+export type ToolResultContent = ToolResultTextContent | ToolResultEmbeddedResourceContent | ToolResultResourceContent | ToolResultFileEditContent | ToolResultTerminalContent | ToolResultShellExitContent | ToolResultSubagentContent;
+export {};