@codingame/monaco-vscode-xterm-common 30.0.1 → 31.0.1

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

@@ -0,0 +1,1418 @@
+/** A URI string (e.g. `agenthost:/root` or `copilot:/<uuid>`). */
+export type URI = string;
+/**
+ * A string that may optionally be rendered as Markdown.
+ *
+ * - A plain `string` is rendered as-is (no Markdown processing).
+ * - An object with `{ markdown: string }` is rendered with Markdown formatting.
+ */
+export type StringOrMarkdown = string | {
+    markdown: string;
+};
+/**
+ * An optionally-sized icon that can be displayed in a user interface.
+ *
+ * @category Common Types
+ */
+export interface Icon {
+    /**
+     * A standard URI pointing to an icon resource. May be an HTTP/HTTPS URL or a
+     * `data:` URI with Base64-encoded image data.
+     *
+     * Consumers SHOULD take steps to ensure URLs serving icons are from the
+     * same domain as the client/server or a trusted domain.
+     *
+     * Consumers SHOULD take appropriate precautions when consuming SVGs as they can contain
+     * executable JavaScript.
+     */
+    src: URI;
+    /**
+     * Optional MIME type override if the source MIME type is missing or generic.
+     * For example: `"image/png"`, `"image/jpeg"`, or `"image/svg+xml"`.
+     */
+    contentType?: string;
+    /**
+     * Optional array of strings that specify sizes at which the icon can be used.
+     * Each string should be in WxH format (e.g., `"48x48"`, `"96x96"`) or `"any"` for scalable formats like SVG.
+     *
+     * If not provided, the client should assume that the icon can be used at any size.
+     */
+    sizes?: string[];
+    /**
+     * Optional specifier for the theme this icon is designed for. `"light"` indicates
+     * the icon is designed to be used with a light background, and `"dark"` indicates
+     * the icon is designed to be used with a dark background.
+     *
+     * If not provided, the client should assume the icon can be used with any theme.
+     */
+    theme?: "light" | "dark";
+}
+/**
+ * Describes a protected resource's authentication requirements using
+ * [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) (OAuth 2.0
+ * Protected Resource Metadata) semantics.
+ *
+ * Field names use snake_case to match the RFC 9728 JSON format.
+ *
+ * @category Authentication
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc9728 | RFC 9728}
+ */
+export interface IProtectedResourceMetadata {
+    /**
+     * REQUIRED. The protected resource's resource identifier, a URL using the
+     * `https` scheme with no fragment component (e.g. `"https://api.github.com"`).
+     */
+    resource: string;
+    /** OPTIONAL. Human-readable name of the protected resource. */
+    resource_name?: string;
+    /** OPTIONAL. JSON array of OAuth authorization server identifier URLs. */
+    authorization_servers?: string[];
+    /** OPTIONAL. URL of the protected resource's JWK Set document. */
+    jwks_uri?: string;
+    /** RECOMMENDED. JSON array of OAuth 2.0 scope values used in authorization requests. */
+    scopes_supported?: string[];
+    /** OPTIONAL. JSON array of Bearer Token presentation methods supported. */
+    bearer_methods_supported?: string[];
+    /** OPTIONAL. JSON array of JWS signing algorithms supported. */
+    resource_signing_alg_values_supported?: string[];
+    /** OPTIONAL. JSON array of JWE encryption algorithms (alg) supported. */
+    resource_encryption_alg_values_supported?: string[];
+    /** OPTIONAL. JSON array of JWE encryption algorithms (enc) supported. */
+    resource_encryption_enc_values_supported?: string[];
+    /** OPTIONAL. URL of human-readable documentation for the resource. */
+    resource_documentation?: string;
+    /** OPTIONAL. URL of the resource's data-usage policy. */
+    resource_policy_uri?: string;
+    /** OPTIONAL. URL of the resource's terms of service. */
+    resource_tos_uri?: string;
+    /**
+     * AHP extension. Whether authentication is required for this resource.
+     *
+     * - `true` (default) — the agent cannot be used without a valid token.
+     *   The server SHOULD return `AuthRequired` (`-32007`) if the client
+     *   attempts to use the agent without authenticating.
+     * - `false` — the agent works without authentication but MAY offer
+     *   enhanced capabilities when a token is provided.
+     *
+     * Clients SHOULD treat an absent field the same as `true`.
+     */
+    required?: boolean;
+}
+/**
+ * Policy configuration state for a model.
+ *
+ * @category Root State
+ */
+export declare enum PolicyState {
+    Enabled = "enabled",
+    Disabled = "disabled",
+    Unconfigured = "unconfigured"
+}
+/**
+ * Global state shared with every client subscribed to `agenthost:/root`.
+ *
+ * @category Root State
+ */
+export interface IRootState {
+    /** Available agent backends and their models */
+    agents: IAgentInfo[];
+    /** Number of active (non-disposed) sessions on the server */
+    activeSessions?: number;
+    /** Known terminals on the server. Subscribe to individual terminal URIs for full state. */
+    terminals?: ITerminalInfo[];
+}
+/**
+ * @category Root State
+ */
+export interface IAgentInfo {
+    /** Agent provider ID (e.g. `'copilot'`) */
+    provider: string;
+    /** Human-readable name */
+    displayName: string;
+    /** Description string */
+    description: string;
+    /** Available models for this agent */
+    models: ISessionModelInfo[];
+    /**
+     * Protected resources this agent requires authentication for.
+     *
+     * Each entry describes an OAuth 2.0 protected resource using
+     * [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) semantics.
+     * Clients should obtain tokens from the declared `authorization_servers`
+     * and push them via the `authenticate` command before creating sessions
+     * with this agent.
+     *
+     * @see {@link /specification/authentication | Authentication}
+     */
+    protectedResources?: IProtectedResourceMetadata[];
+    /**
+     * Customizations (Open Plugins) associated with this agent.
+     *
+     * Each entry is a reference to an [Open Plugins](https://open-plugins.com/)
+     * plugin that the agent host can activate for sessions using this agent.
+     */
+    customizations?: ICustomizationRef[];
+}
+/**
+ * @category Root State
+ */
+export interface ISessionModelInfo {
+    /** Model identifier */
+    id: string;
+    /** Provider this model belongs to */
+    provider: string;
+    /** Human-readable model name */
+    name: string;
+    /** Maximum context window size */
+    maxContextWindow?: number;
+    /** Whether the model supports vision */
+    supportsVision?: boolean;
+    /** Policy configuration state */
+    policyState?: PolicyState;
+    /**
+     * Configuration schema describing model-specific options (e.g. thinking
+     * level). Clients present this as a form and pass the resolved values in
+     * {@link IModelSelection.config} when creating or changing sessions.
+     */
+    configSchema?: IConfigSchema;
+}
+/**
+ * A model selection: the chosen model ID together with any model-specific
+ * configuration values whose keys correspond to the model's
+ * {@link ISessionModelInfo.configSchema}.
+ *
+ * @category Root State
+ */
+export interface IModelSelection {
+    /** Model identifier */
+    id: string;
+    /** Model-specific configuration values */
+    config?: Record<string, string>;
+}
+/**
+ * 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 IPendingMessage {
+    /** Unique identifier for this pending message */
+    id: string;
+    /** The message content */
+    userMessage: IUserMessage;
+}
+/**
+ * Session initialization state.
+ *
+ * @category Session State
+ */
+export declare enum SessionLifecycle {
+    Creating = "creating",
+    Ready = "ready",
+    CreationFailed = "creationFailed"
+}
+/**
+ * Bitset of summary-level session status flags.
+ *
+ * Use bitwise checks instead of equality for non-terminal activity. For example,
+ * `status & SessionStatus.InProgress` matches both ordinary in-progress turns
+ * and turns that are paused waiting for input.
+ *
+ * @category Session State
+ */
+export declare enum SessionStatus {
+    Idle = 1,
+    Error = 2,
+    InProgress = 8,
+    InputNeeded = 24
+}
+/**
+ * Full state for a single session, loaded when a client subscribes to the session's URI.
+ *
+ * @category Session State
+ */
+export interface ISessionState {
+    /** Lightweight session metadata */
+    summary: ISessionSummary;
+    /** Session initialization state */
+    lifecycle: SessionLifecycle;
+    /** Error details if creation failed */
+    creationError?: IErrorInfo;
+    /** Tools provided by the server (agent host) for this session */
+    serverTools?: IToolDefinition[];
+    /** The client currently providing tools and interactive capabilities to this session */
+    activeClient?: ISessionActiveClient;
+    /** Completed turns */
+    turns: ITurn[];
+    /** Currently in-progress turn */
+    activeTurn?: IActiveTurn;
+    /** Message to inject into the current turn at a convenient point */
+    steeringMessage?: IPendingMessage;
+    /** Messages to send automatically as new turns after the current turn finishes */
+    queuedMessages?: IPendingMessage[];
+    /** Requests for user input that are currently blocking or informing session progress */
+    inputRequests?: ISessionInputRequest[];
+    /** Session configuration schema and current values */
+    config?: ISessionConfigState;
+    /**
+     * Server-provided customizations active in this session.
+     *
+     * Client-provided customizations are available on
+     * {@link ISessionActiveClient.customizations | activeClient.customizations}.
+     */
+    customizations?: ISessionCustomization[];
+}
+/**
+ * The client currently providing tools and interactive capabilities to a session.
+ *
+ * Only one client may be active per session at a time. The server SHOULD
+ * automatically unset the active client if that client disconnects.
+ *
+ * @category Session State
+ */
+export interface ISessionActiveClient {
+    /** Client identifier (matches `clientId` from `initialize`) */
+    clientId: string;
+    /** Human-readable client name (e.g. `"VS Code"`) */
+    displayName?: string;
+    /** Tools this client provides to the session */
+    tools: IToolDefinition[];
+    /** Customizations this client contributes to the session */
+    customizations?: ICustomizationRef[];
+}
+/**
+ * Server-owned project metadata for a session.
+ *
+ * @category Session State
+ */
+export interface IProjectInfo {
+    /** Project URI */
+    uri: URI;
+    /** Human-readable project name */
+    displayName: string;
+}
+/**
+ * @category Session State
+ */
+export interface ISessionSummary {
+    /** Session URI */
+    resource: URI;
+    /** Agent provider ID */
+    provider: string;
+    /** Session title */
+    title: string;
+    /** Current session status */
+    status: SessionStatus;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Last modification timestamp */
+    modifiedAt: number;
+    /** Server-owned project for this session */
+    project?: IProjectInfo;
+    /** Currently selected model */
+    model?: IModelSelection;
+    /** The working directory URI for this session */
+    workingDirectory?: URI;
+    /** Whether the client has viewed this session since its last modification */
+    isRead?: boolean;
+    /** Whether the session has been marked as done by the client */
+    isDone?: boolean;
+    /** Files changed during this session with diff statistics */
+    diffs?: IFileEdit[];
+}
+/**
+ * A JSON Schema-compatible string enum property descriptor with display extensions.
+ *
+ * Standard JSON Schema fields (`type`, `title`, `description`, `default`,
+ * `enum`) allow validators to process the schema. Display extensions
+ * (`enumLabels`, `enumDescriptions`) are parallel arrays that provide UI
+ * metadata for each `enum` value.
+ *
+ * This is the generic base type. See {@link ISessionConfigPropertySchema} for
+ * session-specific extensions.
+ *
+ * @category Config Schema Types
+ */
+export interface IConfigPropertySchema {
+    /** JSON Schema: property type. Only string enum properties are currently supported. */
+    type: "string";
+    /** JSON Schema: human-readable label for the property */
+    title: string;
+    /** JSON Schema: description / tooltip */
+    description?: string;
+    /** JSON Schema: default value */
+    default?: string;
+    /** JSON Schema: allowed values */
+    enum: string[];
+    /** Display extension: human-readable label per enum value (parallel array) */
+    enumLabels?: string[];
+    /** Display extension: description per enum value (parallel array) */
+    enumDescriptions?: string[];
+    /** JSON Schema: when `true`, the property is displayed but cannot be modified by the user */
+    readOnly?: boolean;
+}
+/**
+ * A JSON Schema object describing available configuration properties.
+ *
+ * This is the generic base type. See {@link ISessionConfigSchema} for
+ * session-specific usage.
+ *
+ * @category Config Schema Types
+ */
+export interface IConfigSchema {
+    /** JSON Schema: always `'object'` */
+    type: "object";
+    /** JSON Schema: property descriptors keyed by property id */
+    properties: Record<string, IConfigPropertySchema>;
+    /** JSON Schema: list of required property ids */
+    required?: string[];
+}
+/**
+ * A session configuration property descriptor.
+ *
+ * Extends the generic {@link IConfigPropertySchema} with session-specific
+ * display extensions.
+ *
+ * @category Session Config Types
+ */
+export interface ISessionConfigPropertySchema extends IConfigPropertySchema {
+    /**
+     * Display extension: when `true`, the full set of allowed values is too large
+     * to enumerate statically. The client SHOULD use `sessionConfigCompletions`
+     * to fetch matching values based on user input. Any values in `enum` are
+     * seed/recent values for initial display.
+     */
+    enumDynamic?: boolean;
+    /** When `true`, the user may change this property after session creation */
+    sessionMutable?: boolean;
+}
+/**
+ * A JSON Schema object describing available session configuration metadata.
+ *
+ * @category Session Config Types
+ */
+export interface ISessionConfigSchema {
+    /** JSON Schema: always `'object'` */
+    type: "object";
+    /** JSON Schema: property descriptors keyed by property id */
+    properties: Record<string, ISessionConfigPropertySchema>;
+    /** JSON Schema: list of required property ids */
+    required?: string[];
+}
+/**
+ * Live session configuration metadata.
+ *
+ * The schema describes the available configuration properties and the values
+ * contain the current value for each resolved property.
+ *
+ * @category Session Config Types
+ */
+export interface ISessionConfigState {
+    /** JSON Schema describing available configuration properties */
+    schema: ISessionConfigSchema;
+    /** Current configuration values */
+    values: Record<string, string>;
+}
+/**
+ * How a client completed an input request.
+ *
+ * @category Session Input Types
+ */
+export declare enum SessionInputResponseKind {
+    Accept = "accept",
+    Decline = "decline",
+    Cancel = "cancel"
+}
+/**
+ * Question/input control kind.
+ *
+ * @category Session Input Types
+ */
+export declare enum SessionInputQuestionKind {
+    Text = "text",
+    Number = "number",
+    Integer = "integer",
+    Boolean = "boolean",
+    SingleSelect = "single-select",
+    MultiSelect = "multi-select"
+}
+/**
+ * A choice in a select-style question.
+ *
+ * @category Session Input Types
+ */
+export interface ISessionInputOption {
+    /** 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 ISessionInputQuestionBase {
+    /** 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 session input request. */
+export interface ISessionInputTextQuestion extends ISessionInputQuestionBase {
+    kind: SessionInputQuestionKind.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 session input request. */
+export interface ISessionInputNumberQuestion extends ISessionInputQuestionBase {
+    kind: SessionInputQuestionKind.Number | SessionInputQuestionKind.Integer;
+    /** Minimum value */
+    min?: number;
+    /** Maximum value */
+    max?: number;
+    /** Default numeric value */
+    defaultValue?: number;
+}
+/** Boolean question within a session input request. */
+export interface ISessionInputBooleanQuestion extends ISessionInputQuestionBase {
+    kind: SessionInputQuestionKind.Boolean;
+    /** Default boolean value */
+    defaultValue?: boolean;
+}
+/** Single-select question within a session input request. */
+export interface ISessionInputSingleSelectQuestion extends ISessionInputQuestionBase {
+    kind: SessionInputQuestionKind.SingleSelect;
+    /** Options the user may select from */
+    options: ISessionInputOption[];
+    /** Whether the user may enter text instead of selecting an option */
+    allowFreeformInput?: boolean;
+}
+/** Multi-select question within a session input request. */
+export interface ISessionInputMultiSelectQuestion extends ISessionInputQuestionBase {
+    kind: SessionInputQuestionKind.MultiSelect;
+    /** Options the user may select from */
+    options: ISessionInputOption[];
+    /** 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 session input request.
+ *
+ * @category Session Input Types
+ */
+export type ISessionInputQuestion = ISessionInputTextQuestion | ISessionInputNumberQuestion | ISessionInputBooleanQuestion | ISessionInputSingleSelectQuestion | ISessionInputMultiSelectQuestion;
+/**
+ * A live request for user input.
+ *
+ * The server creates or replaces requests with `session/inputRequested`.
+ * Clients sync drafts with `session/inputAnswerChanged` and complete requests
+ * with `session/inputCompleted`.
+ *
+ * @category Session Input Types
+ */
+export interface ISessionInputRequest {
+    /** 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?: ISessionInputQuestion[];
+    /** Current draft or submitted answers, keyed by question ID */
+    answers?: Record<string, ISessionInputAnswer>;
+}
+/**
+ * Answer value kind.
+ *
+ * @category Session Input Types
+ */
+export declare enum SessionInputAnswerValueKind {
+    Text = "text",
+    Number = "number",
+    Boolean = "boolean",
+    Selected = "selected",
+    SelectedMany = "selected-many"
+}
+/**
+ * Value captured for one answer.
+ *
+ * @category Session Input Types
+ */
+export interface ISessionInputTextAnswerValue {
+    kind: SessionInputAnswerValueKind.Text;
+    value: string;
+}
+export interface ISessionInputNumberAnswerValue {
+    kind: SessionInputAnswerValueKind.Number;
+    value: number;
+}
+export interface ISessionInputBooleanAnswerValue {
+    kind: SessionInputAnswerValueKind.Boolean;
+    value: boolean;
+}
+export interface ISessionInputSelectedAnswerValue {
+    kind: SessionInputAnswerValueKind.Selected;
+    value: string;
+    /** Free-form text entered instead of selecting an option */
+    freeformValues?: string[];
+}
+export interface ISessionInputSelectedManyAnswerValue {
+    kind: SessionInputAnswerValueKind.SelectedMany;
+    value: string[];
+    /** Free-form text entered in addition to selected options */
+    freeformValues?: string[];
+}
+export type ISessionInputAnswerValue = ISessionInputTextAnswerValue | ISessionInputNumberAnswerValue | ISessionInputBooleanAnswerValue | ISessionInputSelectedAnswerValue | ISessionInputSelectedManyAnswerValue;
+export interface ISessionInputAnswered {
+    /** Answer state */
+    state: SessionInputAnswerState.Draft | SessionInputAnswerState.Submitted;
+    /** Answer value */
+    value: ISessionInputAnswerValue;
+}
+export interface ISessionInputSkipped {
+    /** Answer state */
+    state: SessionInputAnswerState.Skipped;
+    /** Free-form reason or value captured while skipping, if any */
+    freeformValues?: string[];
+}
+/**
+ * Answer lifecycle state.
+ *
+ * @category Session Input Types
+ */
+export declare enum SessionInputAnswerState {
+    Draft = "draft",
+    Submitted = "submitted",
+    Skipped = "skipped"
+}
+/**
+ * Draft, submitted, or skipped answer for one question.
+ *
+ * @category Session Input Types
+ */
+export type ISessionInputAnswer = ISessionInputAnswered | ISessionInputSkipped;
+/**
+ * How a turn ended.
+ *
+ * @category Turn Types
+ */
+export declare enum TurnState {
+    Complete = "complete",
+    Cancelled = "cancelled",
+    Error = "error"
+}
+/**
+ * Type of a message attachment.
+ *
+ * @category Turn Types
+ */
+export declare enum AttachmentType {
+    File = "file",
+    Directory = "directory",
+    Selection = "selection"
+}
+/**
+ * A completed request/response cycle.
+ *
+ * @category Turn Types
+ */
+export interface ITurn {
+    /** Turn identifier */
+    id: string;
+    /** The user's input */
+    userMessage: IUserMessage;
+    /**
+     * 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: IResponsePart[];
+    /** Token usage info */
+    usage: IUsageInfo | undefined;
+    /** How the turn ended */
+    state: TurnState;
+    /** Error details if state is `'error'` */
+    error?: IErrorInfo;
+}
+/**
+ * An in-progress turn — the assistant is actively streaming.
+ *
+ * @category Turn Types
+ */
+export interface IActiveTurn {
+    /** Turn identifier */
+    id: string;
+    /** The user's input */
+    userMessage: IUserMessage;
+    /**
+     * 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: IResponsePart[];
+    /** Token usage info */
+    usage: IUsageInfo | undefined;
+}
+/**
+ * @category Turn Types
+ */
+export interface IUserMessage {
+    /** Message text */
+    text: string;
+    /** File/selection attachments */
+    attachments?: IMessageAttachment[];
+}
+/**
+ * @category Turn Types
+ */
+export interface IMessageAttachment {
+    /** Attachment type */
+    type: AttachmentType;
+    /** File/directory path */
+    path: string;
+    /** Display name */
+    displayName?: string;
+}
+/**
+ * Discriminant for response part types.
+ *
+ * @category Response Parts
+ */
+export declare enum ResponsePartKind {
+    Markdown = "markdown",
+    ContentRef = "contentRef",
+    ToolCall = "toolCall",
+    Reasoning = "reasoning"
+}
+/**
+ * @category Response Parts
+ */
+export interface IMarkdownResponsePart {
+    /** Discriminant */
+    kind: ResponsePartKind.Markdown;
+    /** Part identifier, used by `session/delta` to target this part for content appends */
+    id: string;
+    /** Markdown content */
+    content: string;
+}
+/**
+ * A reference to large content stored outside the state tree.
+ */
+export interface IContentRef {
+    /** Content URI */
+    uri: URI;
+    /** Approximate size in bytes */
+    sizeHint?: number;
+    /** Content MIME type */
+    contentType?: string;
+}
+/**
+ * A content part that's a reference to large content stored outside the state tree.
+ *
+ * @category Response Parts
+ */
+export interface IResourceReponsePart extends IContentRef {
+    /** 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 IToolCallResponsePart {
+    /** Discriminant */
+    kind: ResponsePartKind.ToolCall;
+    /** Full tool call lifecycle state */
+    toolCall: IToolCallState;
+}
+/**
+ * Reasoning/thinking content from the model.
+ *
+ * @category Response Parts
+ */
+export interface IReasoningResponsePart {
+    /** Discriminant */
+    kind: ResponsePartKind.Reasoning;
+    /** Part identifier, used by `session/reasoning` to target this part for content appends */
+    id: string;
+    /** Accumulated reasoning text */
+    content: string;
+}
+/**
+ * @category Response Parts
+ */
+export type IResponsePart = IMarkdownResponsePart | IResourceReponsePart | IToolCallResponsePart | IReasoningResponsePart;
+/**
+ * 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"
+}
+/**
+ * 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 IToolCallBase {
+    /** Unique tool call identifier */
+    toolCallId: string;
+    /** 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.
+     *
+     * When set, the identified client is responsible for executing the tool and
+     * dispatching `session/toolCallComplete` with the result.
+     */
+    toolClientId?: 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>;
+}
+/**
+ * Properties available once tool call parameters are fully received.
+ *
+ * @category Tool Call Types
+ */
+interface IToolCallParameterFields {
+    /** 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 IToolCallResult {
+    /** 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?: IToolResultContent[];
+    /**
+     * 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 IToolCallStreamingState extends IToolCallBase {
+    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 IToolCallPendingConfirmationState extends IToolCallBase, IToolCallParameterFields {
+    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: IFileEdit[];
+    };
+    /** Whether the agent host allows the client to edit the tool's input parameters before confirming */
+    editable?: boolean;
+}
+/**
+ * Tool is actively executing.
+ *
+ * @category Tool Call Types
+ */
+export interface IToolCallRunningState extends IToolCallBase, IToolCallParameterFields {
+    status: ToolCallStatus.Running;
+    /** How the tool was confirmed for execution */
+    confirmed: ToolCallConfirmationReason;
+    /**
+     * 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?: IToolResultContent[];
+}
+/**
+ * Tool finished executing, waiting for client to approve the result.
+ *
+ * @category Tool Call Types
+ */
+export interface IToolCallPendingResultConfirmationState extends IToolCallBase, IToolCallParameterFields, IToolCallResult {
+    status: ToolCallStatus.PendingResultConfirmation;
+    /** How the tool was confirmed for execution */
+    confirmed: ToolCallConfirmationReason;
+}
+/**
+ * Tool completed successfully or with an error.
+ *
+ * @category Tool Call Types
+ */
+export interface IToolCallCompletedState extends IToolCallBase, IToolCallParameterFields, IToolCallResult {
+    status: ToolCallStatus.Completed;
+    /** How the tool was confirmed for execution */
+    confirmed: ToolCallConfirmationReason;
+}
+/**
+ * Tool call was cancelled before execution.
+ *
+ * @category Tool Call Types
+ */
+export interface IToolCallCancelledState extends IToolCallBase, IToolCallParameterFields {
+    status: ToolCallStatus.Cancelled;
+    /** Why the tool was cancelled */
+    reason: ToolCallCancellationReason;
+    /** Optional message explaining the cancellation */
+    reasonMessage?: StringOrMarkdown;
+    /** What the user suggested doing instead */
+    userSuggestion?: IUserMessage;
+}
+/**
+ * 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 IToolCallState = IToolCallStreamingState | IToolCallPendingConfirmationState | IToolCallRunningState | IToolCallPendingResultConfirmationState | IToolCallCompletedState | IToolCallCancelledState;
+/**
+ * Describes a tool available in a session, provided by either the server or the active client.
+ *
+ * @category Tool Definition Types
+ */
+export interface IToolDefinition {
+    /** Unique tool identifier */
+    name: string;
+    /** Human-readable display name */
+    title?: string;
+    /** Description of what the tool does */
+    description?: string;
+    /**
+     * JSON Schema defining the expected input parameters.
+     *
+     * Optional because client-provided tools may not have formal schemas.
+     * Mirrors MCP `Tool.inputSchema`.
+     */
+    inputSchema?: {
+        type: "object";
+        properties?: Record<string, object>;
+        required?: string[];
+    };
+    /**
+     * JSON Schema defining the structure of the tool's output.
+     *
+     * Mirrors MCP `Tool.outputSchema`.
+     */
+    outputSchema?: {
+        type: "object";
+        properties?: Record<string, object>;
+        required?: string[];
+    };
+    /** Behavioral hints about the tool. All properties are advisory. */
+    annotations?: IToolAnnotations;
+    /**
+     * Additional provider-specific metadata.
+     *
+     * Mirrors the MCP `_meta` convention.
+     */
+    _meta?: Record<string, unknown>;
+}
+/**
+ * Behavioral hints about a tool. All properties are advisory and not
+ * guaranteed to faithfully describe tool behavior.
+ *
+ * Mirrors MCP `ToolAnnotations` from the Model Context Protocol specification.
+ *
+ * @category Tool Definition Types
+ */
+export interface IToolAnnotations {
+    /** Alternate human-readable title */
+    title?: string;
+    /** Tool does not modify its environment (default: false) */
+    readOnlyHint?: boolean;
+    /** Tool may perform destructive updates (default: true) */
+    destructiveHint?: boolean;
+    /** Repeated calls with the same arguments have no additional effect (default: false) */
+    idempotentHint?: boolean;
+    /** Tool may interact with external entities (default: true) */
+    openWorldHint?: boolean;
+}
+/**
+ * Discriminant for tool result content types.
+ *
+ * @category Tool Result Content
+ */
+export declare enum ToolResultContentType {
+    Text = "text",
+    EmbeddedResource = "embeddedResource",
+    Resource = "resource",
+    FileEdit = "fileEdit",
+    Terminal = "terminal",
+    Subagent = "subagent"
+}
+/**
+ * Text content in a tool result.
+ *
+ * Mirrors MCP `TextContent`.
+ *
+ * @category Tool Result Content
+ */
+export interface IToolResultTextContent {
+    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 IToolResultEmbeddedResourceContent {
+    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 IContentRef} for lazy-loading large results.
+ *
+ * @category Tool Result Content
+ */
+export interface IToolResultResourceContent extends IContentRef {
+    type: ToolResultContentType.Resource;
+}
+/**
+ * Describes a file modification with before/after state and diff metadata.
+ *
+ * Supports creates (only `after`), deletes (only `before`), renames/moves
+ * (different `uri` in `before` and `after`), and edits (same `uri`, different content).
+ *
+ * @category Tool Result Content
+ */
+export interface IFileEdit {
+    /** The file state before the edit. Absent for file creations or for in-place file edits. */
+    before?: {
+        /** URI of the file before the edit */
+        uri: URI;
+        /** Reference to the file content before the edit */
+        content: IContentRef;
+    };
+    /** The file state after the edit. Absent for file deletions. */
+    after?: {
+        /** URI of the file after the edit */
+        uri: URI;
+        /** Reference to the file content after the edit */
+        content: IContentRef;
+    };
+    /** Optional diff display metadata */
+    diff?: {
+        /** Number of items added (e.g., lines for text files, cells for notebooks) */
+        added?: number;
+        /** Number of items removed (e.g., lines for text files, cells for notebooks) */
+        removed?: number;
+    };
+}
+/**
+ * Describes a file modification performed by a tool.
+ *
+ * @category Tool Result Content
+ */
+export interface IToolResultFileEditContent extends IFileEdit {
+    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 IToolResultTerminalContent {
+    type: ToolResultContentType.Terminal;
+    /** Terminal URI (subscribable for full terminal state) */
+    resource: URI;
+    /** Display title for the terminal content */
+    title: string;
+}
+/**
+ * A reference to a subagent session spawned by a tool.
+ *
+ * Clients can subscribe to the subagent's session URI to stream its
+ * progress in real time, including inner tool calls and responses.
+ *
+ * @category Tool Result Content
+ */
+export interface IToolResultSubagentContent {
+    type: ToolResultContentType.Subagent;
+    /** Subagent session URI (subscribable for full session 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
+ * `IToolResultResourceContent` for lazy-loading large results,
+ * `IToolResultFileEditContent` for file edit diffs,
+ * `IToolResultTerminalContent` for live terminal output, and
+ * `IToolResultSubagentContent` for subagent sessions (AHP extensions).
+ *
+ * @category Tool Result Content
+ */
+export type IToolResultContent = IToolResultTextContent | IToolResultEmbeddedResourceContent | IToolResultResourceContent | IToolResultFileEditContent | IToolResultTerminalContent | IToolResultSubagentContent;
+/**
+ * A reference to an [Open Plugins](https://open-plugins.com/) plugin.
+ *
+ * This is intentionally thin — AHP specifies plugin identity and metadata
+ * but not implementation details, which are defined by the Open Plugins spec.
+ *
+ * @category Customization Types
+ */
+export interface ICustomizationRef {
+    /** Plugin URI (e.g. an HTTPS URL or marketplace identifier) */
+    uri: URI;
+    /** Human-readable name */
+    displayName: string;
+    /** Description of what the plugin provides */
+    description?: string;
+    /** Icons for the plugin */
+    icons?: Icon[];
+    /**
+     * Opaque version token for this customization.
+     *
+     * Clients SHOULD include a nonce with every customization they provide.
+     * Consumers can compare nonces to detect whether a customization has
+     * changed since it was last seen, avoiding redundant reloads or copies.
+     */
+    nonce?: string;
+}
+/**
+ * Loading status for a server-managed customization.
+ *
+ * @category Customization Types
+ */
+export declare enum CustomizationStatus {
+    /** Plugin is being loaded */
+    Loading = "loading",
+    /** Plugin is fully operational */
+    Loaded = "loaded",
+    /** Plugin partially loaded but has warnings */
+    Degraded = "degraded",
+    /** Plugin was unable to load */
+    Error = "error"
+}
+/**
+ * A customization active in a session.
+ *
+ * Entries without a `clientId` are server-provided; entries with a `clientId`
+ * originate from that client.
+ *
+ * @category Customization Types
+ */
+export interface ISessionCustomization {
+    /** The plugin this customization refers to */
+    customization: ICustomizationRef;
+    /** Whether this customization is currently enabled */
+    enabled: boolean;
+    /** Server-reported loading status */
+    status?: CustomizationStatus;
+    /**
+     * Human-readable status detail (e.g. error message or degradation warning).
+     */
+    statusMessage?: string;
+}
+/**
+ * Lightweight terminal metadata exposed on the root state.
+ *
+ * @category Terminal Types
+ */
+export interface ITerminalInfo {
+    /** Terminal URI (subscribable for full terminal state) */
+    resource: URI;
+    /** Human-readable terminal title */
+    title: string;
+    /** Who currently holds this terminal */
+    claim: ITerminalClaim;
+    /** Process exit code, if the terminal process has exited */
+    exitCode?: number;
+}
+/**
+ * Discriminant for terminal claim kinds.
+ *
+ * @category Terminal Types
+ */
+export declare enum TerminalClaimKind {
+    Client = "client",
+    Session = "session"
+}
+/**
+ * A terminal claimed by a connected client.
+ *
+ * @category Terminal Types
+ */
+export interface ITerminalClientClaim {
+    /** Discriminant */
+    kind: TerminalClaimKind.Client;
+    /** The `clientId` of the claiming client */
+    clientId: string;
+}
+/**
+ * A terminal claimed by a session, optionally scoped to a specific turn or tool call.
+ *
+ * @category Terminal Types
+ */
+export interface ITerminalSessionClaim {
+    /** Discriminant */
+    kind: TerminalClaimKind.Session;
+    /** Session URI that claimed the terminal */
+    session: URI;
+    /** Optional turn identifier within the session */
+    turnId?: string;
+    /** Optional tool call identifier within the turn */
+    toolCallId?: string;
+}
+/**
+ * Describes who currently holds a terminal. A terminal may be claimed by
+ * either a connected client or a session (e.g. during a tool call).
+ *
+ * @category Terminal Types
+ */
+export type ITerminalClaim = ITerminalClientClaim | ITerminalSessionClaim;
+/**
+ * Full state for a single terminal, loaded when a client subscribes to the terminal's URI.
+ *
+ * @category Terminal Types
+ */
+export interface ITerminalState {
+    /** Human-readable terminal title */
+    title: string;
+    /** Current working directory of the terminal process */
+    cwd?: URI;
+    /** Terminal width in columns */
+    cols?: number;
+    /** Terminal height in rows */
+    rows?: number;
+    /**
+     * Typed content parts, replacing the flat `content: string`.
+     *
+     * Naive consumers that only need the raw VT stream can reconstruct it with:
+     *   `content.map(p => p.type === 'command' ? p.output : p.value).join('')`
+     *
+     * Consumers that need command boundaries can filter by part type.
+     */
+    content: ITerminalContentPart[];
+    /** Process exit code, set when the terminal process exits */
+    exitCode?: number;
+    /** Who currently holds this terminal */
+    claim: ITerminalClaim;
+    /**
+     * Whether this terminal emits `terminal/commandExecuted` and
+     * `terminal/commandFinished` actions and populates `command`-typed parts.
+     *
+     * Clients MUST check this flag before relying on command detection.
+     * Do NOT use the presence of a `command` part as a feature flag — parts
+     * are absent in the normal idle state.
+     */
+    supportsCommandDetection?: boolean;
+}
+/**
+ * A content part within terminal output.
+ *
+ * @category Terminal Types
+ */
+export type ITerminalContentPart = ITerminalUnclassifiedPart | ITerminalCommandPart;
+/**
+ * Unstructured terminal output — content before, between, or after commands,
+ * or from terminals that do not support command detection.
+ *
+ * @category Terminal Types
+ */
+export interface ITerminalUnclassifiedPart {
+    type: "unclassified";
+    /** Accumulated VT output. Appended to by `terminal/data` when no command is executing. */
+    value: string;
+}
+/**
+ * A single command: its command line and the output it produced.
+ *
+ * While `isComplete` is false the command is still executing; `output` grows
+ * as `terminal/data` actions arrive. At `terminal/commandFinished` the part
+ * is mutated in-place with `isComplete: true` and the completion metadata.
+ *
+ * @category Terminal Types
+ */
+export interface ITerminalCommandPart {
+    type: "command";
+    /**
+     * Stable id matching the `commandId` on the corresponding
+     * `terminal/commandExecuted` and `terminal/commandFinished` actions.
+     */
+    commandId: string;
+    /** The command line submitted to the shell. */
+    commandLine: string;
+    /**
+     * Accumulated VT output. Appended to by `terminal/data` while `isComplete`
+     * is false. Shell integration escape sequences are stripped by the server.
+     */
+    output: string;
+    /** Unix timestamp (ms) when execution started, as reported by the server. */
+    timestamp: number;
+    /** Whether the command has finished. */
+    isComplete: boolean;
+    /** Shell exit code. Set at completion. `undefined` if unknown. */
+    exitCode?: number;
+    /** Wall-clock duration in milliseconds. Set at completion. */
+    durationMs?: number;
+}
+/**
+ * @category Common Types
+ */
+export interface IUsageInfo {
+    /** Input tokens consumed */
+    inputTokens?: number;
+    /** Output tokens generated */
+    outputTokens?: number;
+    /** Model used */
+    model?: string;
+    /** Tokens read from cache */
+    cacheReadTokens?: number;
+}
+/**
+ * @category Common Types
+ */
+export interface IErrorInfo {
+    /** Error type identifier */
+    errorType: string;
+    /** Human-readable error message */
+    message: string;
+    /** Stack trace */
+    stack?: string;
+}
+/**
+ * A point-in-time snapshot of a subscribed resource's state, returned by
+ * `initialize`, `reconnect`, and `subscribe`.
+ *
+ * @category Common Types
+ */
+export interface ISnapshot {
+    /** The subscribed resource URI (e.g. `agenthost:/root` or `copilot:/<uuid>`) */
+    resource: URI;
+    /** The current state of the resource */
+    state: IRootState | ISessionState | ITerminalState;
+    /** The `serverSeq` at which this snapshot was taken. Subsequent actions will have `serverSeq > fromSeq`. */
+    fromSeq: number;
+}
+export {};