@codingame/monaco-vscode-api 31.0.0 → 32.0.0

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

@@ -0,0 +1,957 @@
+import type { URI, Snapshot, SessionConfigSchema, SessionSummary, ModelSelection, Turn, TerminalClaim, SessionActiveClient, MessageAttachment } from "./state.js";
+import type { ActionEnvelope, StateAction } from "@codingame/monaco-vscode-xterm-common/vscode/vs/platform/agentHost/common/state/protocol/actions";
+export type { ConfigPropertySchema, ConfigSchema, SessionConfigPropertySchema, SessionConfigSchema } from "./state.js";
+/**
+ * Establishes a new connection and negotiates the protocol version.
+ * This MUST be the first message sent by the client.
+ *
+ * @category Commands
+ * @method initialize
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @see {@link /specification/lifecycle | Lifecycle} for the full handshake flow.
+ */
+export interface InitializeParams {
+    /**
+     * Protocol versions the client is willing to speak, ordered from most
+     * preferred to least preferred. Each entry is a [SemVer](https://semver.org)
+     * `MAJOR.MINOR.PATCH` string (e.g. `"0.1.0"`).
+     *
+     * The server selects one entry and returns it as `InitializeResult.protocolVersion`.
+     * If the server cannot speak any of the offered versions, it MUST return
+     * error code `-32005` (`UnsupportedProtocolVersion`).
+     */
+    protocolVersions: string[];
+    /** Unique client identifier */
+    clientId: string;
+    /** URIs to subscribe to during handshake */
+    initialSubscriptions?: URI[];
+    /**
+     * IETF BCP 47 language tag indicating the client's preferred locale
+     * (e.g. `"en-US"`, `"ja"`). The server SHOULD use this to localise
+     * user-facing strings such as confirmation option labels.
+     */
+    locale?: string;
+}
+/**
+ * Result of the `initialize` command.
+ *
+ * `protocolVersion` is the version the server has selected from the client's
+ * `protocolVersions` list. The client and server MUST use this version for
+ * the rest of the connection. If the server cannot speak any of the offered
+ * versions it MUST return error code `-32005` (`UnsupportedProtocolVersion`)
+ * instead of a result.
+ */
+export interface InitializeResult {
+    /**
+     * Protocol version selected by the server. MUST be one of the entries in
+     * `InitializeParams.protocolVersions`. Formatted as a [SemVer](https://semver.org)
+     * `MAJOR.MINOR.PATCH` string (e.g. `"0.1.0"`).
+     */
+    protocolVersion: string;
+    /** Current server sequence number */
+    serverSeq: number;
+    /** Snapshots for each `initialSubscriptions` URI */
+    snapshots: Snapshot[];
+    /** Suggested default directory for remote filesystem browsing */
+    defaultDirectory?: URI;
+    /**
+     * Characters that, when typed in a {@link UserMessage} input, SHOULD cause
+     * the client to issue a `completions` request with
+     * {@link CompletionItemKind.UserMessage}. Typically includes characters like
+     * `'@'` or `'/'`.
+     */
+    completionTriggerCharacters?: string[];
+}
+/**
+ * Discriminant for reconnect result types.
+ *
+ * @category Commands
+ */
+export declare enum ReconnectResultType {
+    Replay = "replay",
+    Snapshot = "snapshot"
+}
+/**
+ * Re-establishes a dropped connection. The server replays missed actions or
+ * provides fresh snapshots.
+ *
+ * @category Commands
+ * @method reconnect
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @see {@link /specification/lifecycle | Lifecycle} for details.
+ */
+export interface ReconnectParams {
+    /** Client identifier from the original connection */
+    clientId: string;
+    /** Last `serverSeq` the client received */
+    lastSeenServerSeq: number;
+    /** URIs the client was subscribed to */
+    subscriptions: URI[];
+}
+/**
+ * Reconnect result when the server can replay from the requested sequence.
+ *
+ * The server MUST include all replayed data in the response.
+ */
+export interface ReconnectReplayResult {
+    /** Discriminant */
+    type: ReconnectResultType.Replay;
+    /** Missed action envelopes since `lastSeenServerSeq` */
+    actions: ActionEnvelope[];
+    /**
+     * URIs from `ReconnectParams.subscriptions` that the server cannot resume.
+     * This includes resources that no longer exist (e.g. disposed sessions or
+     * terminals) as well as resources the client is no longer permitted to
+     * observe. Clients SHOULD drop these from their local subscription set.
+     */
+    missing: URI[];
+}
+/**
+ * Reconnect result when the gap exceeds the replay buffer.
+ */
+export interface ReconnectSnapshotResult {
+    /** Discriminant */
+    type: ReconnectResultType.Snapshot;
+    /** Fresh snapshots for each subscription */
+    snapshots: Snapshot[];
+}
+/** Result of the `reconnect` command. */
+export type ReconnectResult = ReconnectReplayResult | ReconnectSnapshotResult;
+/**
+ * Subscribe to a URI-identified state resource.
+ *
+ * @category Commands
+ * @method subscribe
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @see {@link /specification/subscriptions | Subscriptions}
+ */
+export interface SubscribeParams {
+    /** URI to subscribe to */
+    resource: URI;
+}
+/**
+ * Result of the `subscribe` command.
+ */
+export interface SubscribeResult {
+    /** Snapshot of the subscribed resource */
+    snapshot: Snapshot;
+}
+/**
+ * Creates a new session with the specified agent provider.
+ *
+ * If the session URI already exists, the server MUST return an error with code
+ * `-32003` (`SessionAlreadyExists`).
+ *
+ * After creation, the client should subscribe to the session URI to receive state
+ * updates. The server also broadcasts a `notify/sessionAdded` notification to all
+ * clients.
+ *
+ * @category Commands
+ * @method createSession
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @example
+ * ```jsonc
+ * // Client → Server
+ * { "jsonrpc": "2.0", "id": 2, "method": "createSession",
+ *   "params": { "session": "copilot:/<uuid>", "provider": "copilot", "model": "gpt-4o" } }
+ *
+ * // Server → Client (success)
+ * { "jsonrpc": "2.0", "id": 2, "result": null }
+ *
+ * // Server → Client (failure — provider not found)
+ * { "jsonrpc": "2.0", "id": 2, "error": { "code": -32002, "message": "No agent for provider" } }
+ *
+ * // Server → Client (failure — session already exists)
+ * { "jsonrpc": "2.0", "id": 2, "error": { "code": -32003, "message": "Session already exists" } }
+ * ```
+ */
+/**
+ * Identifies a source session and turn to fork from.
+ *
+ * When provided in `createSession`, the server populates the new session with
+ * content from the source session up to and including the response of the
+ * specified turn.
+ */
+export interface SessionForkSource {
+    /** URI of the existing session to fork from */
+    session: URI;
+    /** Turn ID in the source session; content up to and including this turn's response is copied */
+    turnId: string;
+}
+export interface CreateSessionParams {
+    /** Session URI (client-chosen, e.g. `copilot:/<uuid>`) */
+    session: URI;
+    /** Agent provider ID */
+    provider?: string;
+    /** Model selection (ID and optional model-specific configuration) */
+    model?: ModelSelection;
+    /** Working directory for the session */
+    workingDirectory?: URI;
+    /**
+     * Fork from an existing session. The new session is populated with content
+     * from the source session up to and including the specified turn's response.
+     */
+    fork?: SessionForkSource;
+    /**
+     * Agent-specific configuration values collected via `resolveSessionConfig`.
+     * Keys and values correspond to the schema returned by the server.
+     */
+    config?: Record<string, unknown>;
+    /**
+     * Eagerly claim the active client role for the new session.
+     *
+     * When provided, the server initializes the session with this client as the
+     * active client, equivalent to dispatching a `session/activeClientChanged`
+     * action immediately after creation. The `clientId` MUST match the
+     * `clientId` the creating client supplied in `initialize`.
+     */
+    activeClient?: SessionActiveClient;
+}
+/**
+ * Disposes a session and cleans up server-side resources.
+ *
+ * The server broadcasts a `notify/sessionRemoved` notification to all clients.
+ *
+ * @category Commands
+ * @method disposeSession
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ */
+export interface DisposeSessionParams {
+    /** Session URI to dispose */
+    session: URI;
+}
+/**
+ * Creates a new terminal on the server.
+ *
+ * After creation, the client should subscribe to the terminal URI to receive
+ * state updates. The server dispatches `root/terminalsChanged` to update the
+ * root terminal list.
+ *
+ * @category Commands
+ * @method createTerminal
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ */
+export interface CreateTerminalParams {
+    /** Terminal URI (client-chosen) */
+    terminal: URI;
+    /** Initial owner of the terminal */
+    claim: TerminalClaim;
+    /** Human-readable terminal name */
+    name?: string;
+    /** Initial working directory URI */
+    cwd?: URI;
+    /** Initial terminal width in columns */
+    cols?: number;
+    /** Initial terminal height in rows */
+    rows?: number;
+}
+/**
+ * Disposes a terminal and kills its process if still running.
+ *
+ * The server dispatches `root/terminalsChanged` to remove the terminal from
+ * the root terminal list.
+ *
+ * @category Commands
+ * @method disposeTerminal
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ */
+export interface DisposeTerminalParams {
+    /** Terminal URI to dispose */
+    terminal: URI;
+}
+/**
+ * Returns a list of session summaries. Used to populate session lists and sidebars.
+ *
+ * The session list is **not** part of the state tree because it can be arbitrarily
+ * large. Clients fetch it imperatively and maintain a local cache updated by
+ * `notify/sessionAdded` and `notify/sessionRemoved` notifications.
+ *
+ * @category Commands
+ * @method listSessions
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ */
+export interface ListSessionsParams {
+    /** Optional filter criteria */
+    filter?: object;
+}
+/** Result of the `listSessions` command. */
+export interface ListSessionsResult {
+    /** The list of session summaries. */
+    items: SessionSummary[];
+}
+/**
+ * Encoding of fetched content data.
+ *
+ * @category Commands
+ */
+export declare enum ContentEncoding {
+    Base64 = "base64",
+    Utf8 = "utf-8"
+}
+/**
+ * Reads the content of a resource by URI.
+ *
+ * Content references keep the state tree small by storing large data (images,
+ * long tool outputs) by reference rather than inline.
+ *
+ * Binary content (images, etc.) MUST use `base64` encoding. Text content MAY
+ * use `utf-8` encoding.
+ *
+ * @category Commands
+ * @method resourceRead
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @throws `NotFound` (`-32008`) if the URI does not exist.
+ * @throws `PermissionDenied` (`-32009`) if the client is not permitted to read the URI.
+ * @example
+ * ```jsonc
+ * // Client → Server
+ * { "jsonrpc": "2.0", "id": 10, "method": "resourceRead",
+ *   "params": { "uri": "copilot:/<uuid>/content/img-1" } }
+ *
+ * // Server → Client
+ * { "jsonrpc": "2.0", "id": 10, "result": {
+ *   "data": "iVBORw0KGgo...",
+ *   "encoding": "base64",
+ *   "contentType": "image/png"
+ * }}
+ * ```
+ */
+export interface ResourceReadParams {
+    /** Content URI from a `ContentRef` */
+    uri: string;
+    /** Preferred encoding for the returned data (default: server-chosen) */
+    encoding?: ContentEncoding;
+}
+/**
+ * Result of the `resourceRead` command.
+ *
+ * The server SHOULD honor the `encoding` requested in the params. If the
+ * server cannot provide the requested encoding, it MUST fall back to either
+ * `base64` or `utf-8`.
+ */
+export interface ResourceReadResult {
+    /** Content encoded as a string */
+    data: string;
+    /** How `data` is encoded */
+    encoding: ContentEncoding;
+    /** Content type (e.g. `"image/png"`, `"text/plain"`) */
+    contentType?: string;
+}
+/**
+ * Writes content to a file on the server's filesystem.
+ *
+ * Binary content (images, etc.) MUST use `base64` encoding. Text content MAY
+ * use `utf-8` encoding.
+ *
+ * If the file does not exist, it is created. If the file already exists, it is
+ * overwritten unless `createOnly` is set.
+ *
+ * @category Commands
+ * @method resourceWrite
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @throws `NotFound` (`-32008`) if the parent directory does not exist.
+ * @throws `PermissionDenied` (`-32009`) if the client is not permitted to write to the path.
+ * @throws `AlreadyExists` (`-32010`) if `createOnly` is set and the file already exists.
+ * @example
+ * ```jsonc
+ * // Client → Server
+ * { "jsonrpc": "2.0", "id": 11, "method": "resourceWrite",
+ *   "params": { "uri": "file:///workspace/hello.txt", "data": "SGVsbG8=",
+ *              "encoding": "base64", "contentType": "text/plain" } }
+ *
+ * // Server → Client
+ * { "jsonrpc": "2.0", "id": 11, "result": {} }
+ * ```
+ */
+export interface ResourceWriteParams {
+    /** Target file URI on the server filesystem */
+    uri: URI;
+    /** Content encoded as a string */
+    data: string;
+    /** How `data` is encoded */
+    encoding: ContentEncoding;
+    /** Content type (e.g. `"text/plain"`, `"image/png"`) */
+    contentType?: string;
+    /**
+     * If `true`, the server MUST fail if the file already exists instead of
+     * overwriting it. Useful for safe creation of new files.
+     */
+    createOnly?: boolean;
+}
+/**
+ * Result of the `resourceWrite` command.
+ *
+ * An empty object on success.
+ */
+export interface ResourceWriteResult {
+}
+/**
+ * Lists directory entries at a file URI on the server's filesystem.
+ *
+ * This is intended for remote folder pickers and similar UI that needs to let
+ * users navigate the server's local filesystem.
+ *
+ * The server MUST return success only if the target exists and is a directory.
+ * If the target does not exist, is not a directory, or cannot be accessed, the
+ * server MUST return a JSON-RPC error.
+ *
+ * @category Commands
+ * @method resourceList
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @throws `NotFound` (`-32008`) if the directory does not exist.
+ * @throws `PermissionDenied` (`-32009`) if the client is not permitted to browse the directory.
+ */
+export interface ResourceListParams {
+    /** Directory URI on the server filesystem */
+    uri: URI;
+}
+/**
+ * Directory entry returned by `resourceList`.
+ */
+export interface DirectoryEntry {
+    /** Base name of the entry */
+    name: string;
+    /** Whether the entry is a file or directory */
+    type: "file" | "directory";
+}
+/**
+ * Result of the `resourceList` command.
+ */
+export interface ResourceListResult {
+    /** Entries directly contained in the requested directory */
+    entries: DirectoryEntry[];
+}
+/**
+ * Fetches historical turns for a session. Used for lazy loading of conversation
+ * history.
+ *
+ * @category Commands
+ * @method fetchTurns
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @example
+ * ```jsonc
+ * // Client → Server (fetch the 20 most recent turns)
+ * { "jsonrpc": "2.0", "id": 8, "method": "fetchTurns",
+ *   "params": { "session": "copilot:/<uuid>", "limit": 20 } }
+ *
+ * // Server → Client
+ * { "jsonrpc": "2.0", "id": 8, "result": {
+ *   "turns": [ { "id": "t1", ... }, { "id": "t2", ... } ],
+ *   "hasMore": true
+ * }}
+ *
+ * // Client → Server (fetch 20 turns before t1)
+ * { "jsonrpc": "2.0", "id": 9, "method": "fetchTurns",
+ *   "params": { "session": "copilot:/<uuid>", "before": "t1", "limit": 20 } }
+ * ```
+ */
+export interface FetchTurnsParams {
+    /** Session URI */
+    session: URI;
+    /** Turn ID to fetch before (exclusive). Omit to fetch from the most recent turn. */
+    before?: string;
+    /** Maximum number of turns to return. Server MAY impose its own upper bound. */
+    limit?: number;
+}
+/**
+ * Result of the `fetchTurns` command.
+ */
+export interface FetchTurnsResult {
+    /** The requested turns, ordered oldest-first */
+    turns: Turn[];
+    /** Whether more turns exist before the returned range */
+    hasMore: boolean;
+}
+/**
+ * Stop receiving updates for a URI.
+ *
+ * @category Commands
+ * @method unsubscribe
+ * @direction Client → Server
+ * @messageType Notification
+ * @version 1
+ * @see {@link /specification/subscriptions | Subscriptions}
+ */
+export interface UnsubscribeParams {
+    /** URI to unsubscribe from */
+    resource: URI;
+}
+/**
+ * Fire-and-forget action dispatch (write-ahead). The client applies actions
+ * optimistically to local state.
+ *
+ * @category Commands
+ * @method dispatchAction
+ * @direction Client → Server
+ * @messageType Notification
+ * @version 1
+ * @see {@link /guide/actions | Actions} for the full list of client-dispatchable actions.
+ */
+export interface DispatchActionParams {
+    /** Client sequence number */
+    clientSeq: number;
+    /** The action to dispatch */
+    action: StateAction;
+}
+/**
+ * Copies a resource from one URI to another on the server's filesystem.
+ *
+ * If the destination already exists, it is overwritten unless `failIfExists`
+ * is set.
+ *
+ * @category Commands
+ * @method resourceCopy
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @throws `NotFound` (`-32008`) if the source does not exist.
+ * @throws `PermissionDenied` (`-32009`) if the client is not permitted to read the source or write to the destination.
+ * @throws `AlreadyExists` (`-32010`) if `failIfExists` is set and the destination already exists.
+ */
+export interface ResourceCopyParams {
+    /** Source URI to copy from */
+    source: URI;
+    /** Destination URI to copy to */
+    destination: URI;
+    /**
+     * If `true`, the server MUST fail if the destination already exists instead
+     * of overwriting it.
+     */
+    failIfExists?: boolean;
+}
+/**
+ * Result of the `resourceCopy` command.
+ *
+ * An empty object on success.
+ */
+export interface ResourceCopyResult {
+}
+/**
+ * Deletes a resource at a URI on the server's filesystem.
+ *
+ * @category Commands
+ * @method resourceDelete
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @throws `NotFound` (`-32008`) if the resource does not exist.
+ * @throws `PermissionDenied` (`-32009`) if the client is not permitted to delete the resource.
+ */
+export interface ResourceDeleteParams {
+    /** URI of the resource to delete */
+    uri: URI;
+    /**
+     * If `true` and the target is a directory, delete it and all its contents
+     * recursively. If `false` (default), deleting a non-empty directory MUST fail.
+     */
+    recursive?: boolean;
+}
+/**
+ * Result of the `resourceDelete` command.
+ *
+ * An empty object on success.
+ */
+export interface ResourceDeleteResult {
+}
+/**
+ * Requests permission to access a resource on the receiver's filesystem.
+ *
+ * `resourceRequest` is symmetrical and MAY be sent in either direction: a
+ * client asks the server to grant access to a server-side resource, or a
+ * server asks the client to grant access to a client-side resource. The
+ * receiver decides whether to allow, deny, or prompt the user for the
+ * requested access.
+ *
+ * If the receiver denies access, it MUST respond with `PermissionDenied`
+ * (-32009). The error data MAY include a `ResourceRequestParams` value
+ * describing the access the caller would need to be granted for the
+ * operation to succeed; see `PermissionDeniedErrorData` in
+ * `types/errors.ts`.
+ *
+ * After a successful `resourceRequest`, the caller MAY use the corresponding
+ * `resource*` commands (e.g. `resourceRead`, `resourceWrite`) to perform the
+ * operation. Receivers MAY rescind access at any time by returning
+ * `PermissionDenied` on subsequent operations.
+ *
+ * Either `read`, `write`, or both SHOULD be set to `true`. A request with
+ * neither flag set is treated as `read: true` by receivers.
+ *
+ * @category Commands
+ * @method resourceRequest
+ * @direction Client ↔ Server
+ * @messageType Request
+ * @version 1
+ * @throws `PermissionDenied` (`-32009`) if access is denied.
+ */
+export interface ResourceRequestParams {
+    /**
+     * Resource URI being requested. Typically a `file:` URI on the receiver's
+     * filesystem, but any URI scheme that the receiver mediates access to is
+     * allowed.
+     */
+    uri: URI;
+    /** Whether the caller needs read access to the resource. */
+    read?: boolean;
+    /** Whether the caller needs write access to the resource. */
+    write?: boolean;
+}
+/**
+ * Result of the `resourceRequest` command.
+ *
+ * An empty object on success.
+ */
+export interface ResourceRequestResult {
+}
+/**
+ * Moves (renames) a resource from one URI to another on the server's filesystem.
+ *
+ * If the destination already exists, it is overwritten unless `failIfExists`
+ * is set.
+ *
+ * @category Commands
+ * @method resourceMove
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @throws `NotFound` (`-32008`) if the source does not exist.
+ * @throws `PermissionDenied` (`-32009`) if the client is not permitted to move the resource.
+ * @throws `AlreadyExists` (`-32010`) if `failIfExists` is set and the destination already exists.
+ */
+export interface ResourceMoveParams {
+    /** Source URI to move from */
+    source: URI;
+    /** Destination URI to move to */
+    destination: URI;
+    /**
+     * If `true`, the server MUST fail if the destination already exists instead
+     * of overwriting it.
+     */
+    failIfExists?: boolean;
+}
+/**
+ * Result of the `resourceMove` command.
+ *
+ * An empty object on success.
+ */
+export interface ResourceMoveResult {
+}
+/**
+ * Pushes a Bearer token for a protected resource. The `resource` field MUST
+ * match a `ProtectedResourceMetadata.resource` value declared by an agent
+ * in `AgentInfo.protectedResources`.
+ *
+ * Tokens are delivered using [RFC 6750](https://datatracker.ietf.org/doc/html/rfc6750)
+ * (Bearer Token Usage) semantics. The client obtains the token from the
+ * authorization server(s) listed in the resource's metadata and pushes it
+ * to the server via this command.
+ *
+ * @category Commands
+ * @method authenticate
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @see {@link /specification/authentication | Authentication}
+ * @example
+ * ```jsonc
+ * // Client → Server
+ * { "jsonrpc": "2.0", "id": 3, "method": "authenticate",
+ *   "params": { "resource": "https://api.github.com", "token": "gho_xxxx" } }
+ *
+ * // Server → Client (success)
+ * { "jsonrpc": "2.0", "id": 3, "result": {} }
+ *
+ * // Server → Client (failure — invalid token)
+ * { "jsonrpc": "2.0", "id": 3, "error": { "code": -32007, "message": "Invalid token" } }
+ * ```
+ */
+export interface AuthenticateParams {
+    /**
+     * The protected resource identifier. MUST match a `resource` value from
+     * `ProtectedResourceMetadata` declared in `AgentInfo.protectedResources`.
+     */
+    resource: string;
+    /** Bearer token obtained from the resource's authorization server */
+    token: string;
+}
+/**
+ * Result of the `authenticate` command.
+ *
+ * An empty object on success. If the token is invalid or the resource is
+ * unrecognized, the server MUST return a JSON-RPC error (e.g. `AuthRequired`
+ * `-32007` or `InvalidParams` `-32602`).
+ */
+export interface AuthenticateResult {
+}
+/**
+ * Iteratively resolves the session configuration schema. The client sends the
+ * current partial session config and any user-filled metadata values. The server
+ * returns a property schema describing what additional metadata is needed,
+ * contextual to the current selections.
+ *
+ * The client calls this command whenever the user changes a significant input
+ * (e.g. picks a working directory, toggles a property). Each response returns
+ * the full current property set (not a delta). The returned `values` contain
+ * server-resolved defaults to pass to `createSession`.
+ *
+ * @category Commands
+ * @method resolveSessionConfig
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @example
+ * ```jsonc
+ * // Step 1: Client picks a working directory
+ * // Client → Server
+ * { "jsonrpc": "2.0", "id": 5, "method": "resolveSessionConfig",
+ *   "params": { "workingDirectory": "file:///home/user/my-project" } }
+ *
+ * // Server → Client (git repo detected, offers worktree option)
+ * { "jsonrpc": "2.0", "id": 5, "result": {
+ *   "schema": {
+ *     "type": "object",
+ *     "properties": {
+ *       "target": { "type": "string", "title": "Target", "enum": ["workspace", "worktree"] }
+ *     }
+ *   },
+ *   "values": {}
+ * }}
+ *
+ * // Step 2: User enables worktree
+ * // Client → Server
+ * { "jsonrpc": "2.0", "id": 6, "method": "resolveSessionConfig",
+ *   "params": { "workingDirectory": "file:///home/user/my-project",
+ *               "config": { "target": "worktree" } } }
+ *
+ * // Server → Client (now requires branch selection)
+ * { "jsonrpc": "2.0", "id": 6, "result": {
+ *   "schema": {
+ *     "type": "object",
+ *     "properties": {
+ *       "target": { "type": "string", "title": "Target", "enum": ["workspace", "worktree"] },
+ *       "baseBranch": { "type": "string", "title": "Base Branch",
+ *                       "enum": ["main", "develop"],
+ *                       "enumLabels": ["main", "develop"] }
+ *     },
+ *     "required": ["baseBranch"]
+ *   },
+ *   "values": { "target": "worktree" }
+ * }}
+ * ```
+ */
+export interface ResolveSessionConfigParams {
+    /** Agent provider ID */
+    provider?: string;
+    /** Working directory for the session */
+    workingDirectory?: URI;
+    /** Current user-filled configuration values */
+    config?: Record<string, unknown>;
+}
+/**
+ * Result of the `resolveSessionConfig` command.
+ */
+export interface ResolveSessionConfigResult {
+    /** JSON Schema describing available configuration properties given the current context */
+    schema: SessionConfigSchema;
+    /** Current configuration values (echoed back with server-resolved defaults applied) */
+    values: Record<string, unknown>;
+}
+/**
+ * A single value item returned by `sessionConfigCompletions`.
+ *
+ * @category Commands
+ */
+export interface SessionConfigValueItem {
+    /** The value to store in config */
+    value: string;
+    /** Human-readable display label */
+    label: string;
+    /** Optional secondary description */
+    description?: string;
+}
+/**
+ * Queries the server for allowed values of a dynamic session config property.
+ *
+ * Used when a property in the schema returned by `resolveSessionConfig` has
+ * `enumDynamic: true`. The client sends a search query and receives matching
+ * values with display metadata.
+ *
+ * @category Commands
+ * @method sessionConfigCompletions
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @example
+ * ```jsonc
+ * // Client → Server (user types "ma" in branch picker)
+ * { "jsonrpc": "2.0", "id": 7, "method": "sessionConfigCompletions",
+ *   "params": { "workingDirectory": "file:///home/user/my-project",
+ *               "config": { "target": "worktree" },
+ *               "property": "baseBranch", "query": "ma" } }
+ *
+ * // Server → Client
+ * { "jsonrpc": "2.0", "id": 7, "result": {
+ *   "items": [
+ *     { "value": "main", "label": "main", "icon": "git-branch" },
+ *     { "value": "main-v2", "label": "main-v2", "icon": "git-branch" }
+ *   ]
+ * }}
+ * ```
+ */
+export interface SessionConfigCompletionsParams {
+    /** Agent provider ID */
+    provider?: string;
+    /** Working directory for the session */
+    workingDirectory?: URI;
+    /** Current user-filled configuration values (provides context for the query) */
+    config?: Record<string, unknown>;
+    /** Property id from the schema to query values for */
+    property: string;
+    /** Search filter text (empty or omitted returns default/recent values) */
+    query?: string;
+}
+/**
+ * Result of the `sessionConfigCompletions` command.
+ */
+export interface SessionConfigCompletionsResult {
+    /** Matching value items */
+    items: SessionConfigValueItem[];
+}
+/**
+ * The kind of completion items being requested.
+ *
+ * @category Commands
+ */
+export declare enum CompletionItemKind {
+    /**
+     * Completions for the text of a {@link UserMessage} the user is composing.
+     * Each returned item carries an attachment that gets associated with the
+     * message when accepted.
+     */
+    UserMessage = "userMessage"
+}
+/**
+ * Requests completion items for a partially-typed input (e.g. a user message
+ * the user is currently composing). Used to power `@`-mention pickers,
+ * file/symbol references, and similar inline-completion experiences.
+ *
+ * Servers SHOULD treat this command as best-effort and return promptly. The
+ * client SHOULD debounce calls to avoid flooding the server with requests on
+ * every keystroke.
+ *
+ * @category Commands
+ * @method completions
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @example
+ * ```jsonc
+ * // User has typed "look at @foo" and the cursor is just after "@foo".
+ * // Client → Server
+ * { "jsonrpc": "2.0", "id": 12, "method": "completions",
+ *   "params": { "kind": "userMessage", "session": "copilot:/<uuid>",
+ *               "text": "look at @foo", "offset": 12 } }
+ *
+ * // Server → Client
+ * { "jsonrpc": "2.0", "id": 12, "result": {
+ *   "items": [
+ *     {
+ *       "insertText": "@foo.ts",
+ *       "rangeStart": 8,
+ *       "rangeEnd": 12,
+ *       "attachment": {
+ *         "type": "resource",
+ *         "label": "foo.ts",
+ *         "displayKind": "document",
+ *         "uri": "file:///workspace/foo.ts"
+ *       }
+ *     }
+ *   ]
+ * }}
+ * ```
+ */
+export interface CompletionsParams {
+    /** What kind of completion is being requested. */
+    kind: CompletionItemKind;
+    /** The session URI the completion is being requested for. */
+    session: URI;
+    /**
+     * The complete text of the input being completed (e.g. the full user
+     * message text typed so far).
+     */
+    text: string;
+    /**
+     * The character offset within `text` at which the completion is requested,
+     * measured in UTF-16 code units. MUST satisfy `0 <= offset <= text.length`.
+     */
+    offset: number;
+}
+/**
+ * A single completion item returned by the `completions` command.
+ *
+ * When the user accepts an item, the client SHOULD:
+ * 1. Replace the range `[rangeStart, rangeEnd)` in the input with `insertText`
+ *    (or insert `insertText` at the cursor when the range is omitted).
+ * 2. Associate the item's `attachment` with the resulting {@link UserMessage}.
+ *
+ * @category Commands
+ */
+export interface CompletionItem {
+    /**
+     * The text inserted into the input when this item is accepted.
+     */
+    insertText: string;
+    /**
+     * If defined, the start of the range in the input's `text` that is replaced
+     * by `insertText`. The range is the half-open interval
+     * `[rangeStart, rangeEnd)` of character offsets, measured in UTF-16 code
+     * units.
+     *
+     * When omitted, the client SHOULD insert `insertText` at the cursor.
+     *
+     * Note: this range refers to positions in the *current* input. The
+     * attachment's own `rangeStart`/`rangeEnd` (when present) refer to
+     * positions in the final {@link UserMessage.text} after the item is
+     * accepted.
+     */
+    rangeStart?: number;
+    /**
+     * The end of the range in the input's `text` that is replaced by
+     * `insertText`. See {@link rangeStart}.
+     */
+    rangeEnd?: number;
+    /**
+     * The attachment associated with this completion item.
+     */
+    attachment: MessageAttachment;
+}
+/**
+ * Result of the `completions` command.
+ */
+export interface CompletionsResult {
+    /** The completion items, in the order the server suggests displaying them. */
+    items: CompletionItem[];
+}