@codingame/monaco-vscode-chat-service-override 28.4.0 → 29.0.0

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

@@ -0,0 +1,424 @@
+import type { URI, ISnapshot, ISessionSummary, ITurn } from "./state.js";
+import type { IActionEnvelope, IStateAction } from "./actions.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 IInitializeParams {
+    /** Protocol version the client speaks */
+    protocolVersion: number;
+    /** Unique client identifier */
+    clientId: string;
+    /** URIs to subscribe to during handshake */
+    initialSubscriptions?: URI[];
+}
+/**
+ * Result of the `initialize` command.
+ *
+ * If the server does not support the client's protocol version, it MUST return
+ * error code `-32005` (`UnsupportedProtocolVersion`).
+ */
+export interface IInitializeResult {
+    /** Protocol version the server speaks */
+    protocolVersion: number;
+    /** Current server sequence number */
+    serverSeq: number;
+    /** Snapshots for each `initialSubscriptions` URI */
+    snapshots: ISnapshot[];
+    /** Suggested default directory for remote filesystem browsing */
+    defaultDirectory?: URI;
+}
+/**
+ * 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 IReconnectParams {
+    /** 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 IReconnectReplayResult {
+    /** Discriminant */
+    type: ReconnectResultType.Replay;
+    /** Missed action envelopes since `lastSeenServerSeq` */
+    actions: IActionEnvelope[];
+}
+/**
+ * Reconnect result when the gap exceeds the replay buffer.
+ */
+export interface IReconnectSnapshotResult {
+    /** Discriminant */
+    type: ReconnectResultType.Snapshot;
+    /** Fresh snapshots for each subscription */
+    snapshots: ISnapshot[];
+}
+/** Result of the `reconnect` command. */
+export type IReconnectResult = IReconnectReplayResult | IReconnectSnapshotResult;
+/**
+ * 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 ISubscribeParams {
+    /** URI to subscribe to */
+    resource: URI;
+}
+/**
+ * Result of the `subscribe` command.
+ */
+export interface ISubscribeResult {
+    /** Snapshot of the subscribed resource */
+    snapshot: ISnapshot;
+}
+/**
+ * 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" } }
+ * ```
+ */
+export interface ICreateSessionParams {
+    /** Session URI (client-chosen, e.g. `copilot:/<uuid>`) */
+    session: URI;
+    /** Agent provider ID */
+    provider?: string;
+    /** Model ID to use */
+    model?: string;
+    /** Working directory for the session */
+    workingDirectory?: URI;
+}
+/**
+ * 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 IDisposeSessionParams {
+    /** Session URI to dispose */
+    session: 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 IListSessionsParams {
+    /** Optional filter criteria */
+    filter?: object;
+}
+/** Result of the `listSessions` command. */
+export interface IListSessionsResult {
+    /** The list of session summaries. */
+    items: ISessionSummary[];
+}
+/**
+ * Encoding of fetched content data.
+ *
+ * @category Commands
+ */
+export declare enum ContentEncoding {
+    Base64 = "base64",
+    Utf8 = "utf-8"
+}
+/**
+ * Fetches large content referenced by a `ContentRef` in the state tree.
+ *
+ * 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 fetchContent
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ * @example
+ * ```jsonc
+ * // Client → Server
+ * { "jsonrpc": "2.0", "id": 10, "method": "fetchContent",
+ *   "params": { "uri": "copilot:/<uuid>/content/img-1" } }
+ *
+ * // Server → Client
+ * { "jsonrpc": "2.0", "id": 10, "result": {
+ *   "data": "iVBORw0KGgo...",
+ *   "encoding": "base64",
+ *   "contentType": "image/png"
+ * }}
+ * ```
+ */
+export interface IFetchContentParams {
+    /** Content URI from a `ContentRef` */
+    uri: string;
+    /** Preferred encoding for the returned data (default: server-chosen) */
+    encoding?: ContentEncoding;
+}
+/**
+ * Result of the `fetchContent` 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 IFetchContentResult {
+    /** Content encoded as a string */
+    data: string;
+    /** How `data` is encoded */
+    encoding: ContentEncoding;
+    /** Content type (e.g. `"image/png"`, `"text/plain"`) */
+    contentType?: string;
+}
+/**
+ * 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 browseDirectory
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ */
+export interface IBrowseDirectoryParams {
+    /** Directory URI on the server filesystem */
+    uri: URI;
+}
+/**
+ * Directory entry returned by `browseDirectory`.
+ */
+export interface IDirectoryEntry {
+    /** Base name of the entry */
+    name: string;
+    /** Whether the entry is a file or directory */
+    type: "file" | "directory";
+}
+/**
+ * Result of the `browseDirectory` command.
+ */
+export interface IBrowseDirectoryResult {
+    /** Entries directly contained in the requested directory */
+    entries: IDirectoryEntry[];
+}
+/**
+ * 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 IFetchTurnsParams {
+    /** 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 IFetchTurnsResult {
+    /** The requested turns, ordered oldest-first */
+    turns: ITurn[];
+    /** 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 IUnsubscribeParams {
+    /** 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 IDispatchActionParams {
+    /** Client sequence number */
+    clientSeq: number;
+    /** The action to dispatch */
+    action: IStateAction;
+}
+/**
+ * Lists the contents of a directory on the server. Used by clients to
+ * present directory pickers or file browsers.
+ *
+ * @category Commands
+ * @method browseDirectory
+ * @direction Client → Server
+ * @messageType Request
+ * @version 1
+ */
+export interface IBrowseDirectoryParams {
+    /** Directory path to browse. Omit to list the default/root directory. */
+    directory?: string;
+}
+/**
+ * A single entry in a directory listing.
+ */
+export interface IBrowseDirectoryEntry {
+    /** Entry name (not a full path) */
+    name: string;
+    /** Whether this entry is a directory */
+    isDirectory: boolean;
+}
+/**
+ * Pushes a Bearer token for a protected resource. The `resource` field MUST
+ * match an `IProtectedResourceMetadata.resource` value declared by an agent
+ * in `IAgentInfo.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 IAuthenticateParams {
+    /**
+     * The protected resource identifier. MUST match a `resource` value from
+     * `IProtectedResourceMetadata` declared in `IAgentInfo.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 IAuthenticateResult {
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Standard JSON-RPC 2.0 error codes.
+ *
+ * @category Standard JSON-RPC Codes
+ */
+export declare const JsonRpcErrorCodes: {
+    /** Invalid JSON */
+    readonly ParseError: -32700;
+    /** Not a valid JSON-RPC request */
+    readonly InvalidRequest: -32600;
+    /** Unknown method name */
+    readonly MethodNotFound: -32601;
+    /** Invalid method parameters */
+    readonly InvalidParams: -32602;
+    /** Unspecified server error */
+    readonly InternalError: -32603;
+};
+/**
+ * AHP application-specific error codes.
+ *
+ * @category AHP Application Codes
+ * @version 1
+ */
+export declare const AhpErrorCodes: {
+    /** The referenced session URI does not exist */
+    readonly SessionNotFound: -32001;
+    /** The requested agent provider is not registered */
+    readonly ProviderNotFound: -32002;
+    /** A session with the given URI already exists */
+    readonly SessionAlreadyExists: -32003;
+    /** The operation requires no active turn, but one is in progress */
+    readonly TurnInProgress: -32004;
+    /** The client's protocol version is not supported by the server */
+    readonly UnsupportedProtocolVersion: -32005;
+    /** The requested content URI does not exist */
+    readonly ContentNotFound: -32006;
+    /**
+     * A command failed because the client has not authenticated for a required
+     * protected resource. The `data` field of the JSON-RPC error SHOULD contain
+     * an `IProtectedResourceMetadata[]` array describing the resources that
+     * require authentication.
+     *
+     * @see {@link /specification/authentication | Authentication}
+     */
+    readonly AuthRequired: -32007;
+};
+/** Union type of all AHP application error codes. */
+export type AhpErrorCode = (typeof AhpErrorCodes)[keyof typeof AhpErrorCodes];
+/** Union type of all JSON-RPC error codes. */
+export type JsonRpcErrorCode = (typeof JsonRpcErrorCodes)[keyof typeof JsonRpcErrorCodes];

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

@@ -0,0 +1,202 @@
+import type { IInitializeParams, IInitializeResult, IReconnectParams, IReconnectResult, ISubscribeParams, ISubscribeResult, ICreateSessionParams, IDisposeSessionParams, IListSessionsParams, IListSessionsResult, IFetchContentParams, IFetchContentResult, IBrowseDirectoryParams, IBrowseDirectoryResult, IFetchTurnsParams, IFetchTurnsResult, IUnsubscribeParams, IDispatchActionParams, IAuthenticateParams, IAuthenticateResult } from "./commands.js";
+import type { IActionEnvelope } from "./actions.js";
+import type { IProtocolNotification } from "./notifications.js";
+/** A JSON-RPC request: has both `method` and `id`. */
+export interface IJsonRpcRequest {
+    readonly jsonrpc: "2.0";
+    readonly id: number;
+    readonly method: string;
+    readonly params?: unknown;
+}
+/** A JSON-RPC success response. */
+export interface IJsonRpcSuccessResponse {
+    readonly jsonrpc: "2.0";
+    readonly id: number;
+    readonly result: unknown;
+}
+/** A JSON-RPC error response. */
+export interface IJsonRpcErrorResponse {
+    readonly jsonrpc: "2.0";
+    readonly id: number;
+    readonly error: {
+        readonly code: number;
+        readonly message: string;
+        readonly data?: unknown;
+    };
+}
+/** A JSON-RPC response (success or error). */
+export type IJsonRpcResponse = IJsonRpcSuccessResponse | IJsonRpcErrorResponse;
+/** A JSON-RPC notification: has `method` but no `id`. */
+export interface IJsonRpcNotification {
+    readonly jsonrpc: "2.0";
+    readonly method: string;
+    readonly params?: unknown;
+}
+/**
+ * Registry mapping each command method name to its params and result types.
+ *
+ * @category Commands
+ */
+export interface ICommandMap {
+    "initialize": {
+        params: IInitializeParams;
+        result: IInitializeResult;
+    };
+    "reconnect": {
+        params: IReconnectParams;
+        result: IReconnectResult;
+    };
+    "subscribe": {
+        params: ISubscribeParams;
+        result: ISubscribeResult;
+    };
+    "createSession": {
+        params: ICreateSessionParams;
+        result: null;
+    };
+    "disposeSession": {
+        params: IDisposeSessionParams;
+        result: null;
+    };
+    "listSessions": {
+        params: IListSessionsParams;
+        result: IListSessionsResult;
+    };
+    "fetchContent": {
+        params: IFetchContentParams;
+        result: IFetchContentResult;
+    };
+    "browseDirectory": {
+        params: IBrowseDirectoryParams;
+        result: IBrowseDirectoryResult;
+    };
+    "fetchTurns": {
+        params: IFetchTurnsParams;
+        result: IFetchTurnsResult;
+    };
+    "authenticate": {
+        params: IAuthenticateParams;
+        result: IAuthenticateResult;
+    };
+}
+/** Params for the server → client `notification` method. */
+export interface INotificationMethodParams {
+    notification: IProtocolNotification;
+}
+/**
+ * Registry mapping each client → server notification method to its params type.
+ *
+ * @category Notifications
+ */
+export interface IClientNotificationMap {
+    "unsubscribe": {
+        params: IUnsubscribeParams;
+    };
+    "dispatchAction": {
+        params: IDispatchActionParams;
+    };
+}
+/**
+ * Registry mapping each server → client notification method to its params type.
+ *
+ * @category Notifications
+ */
+export interface IServerNotificationMap {
+    "action": {
+        params: IActionEnvelope;
+    };
+    "notification": {
+        params: INotificationMethodParams;
+    };
+}
+/** Combined notification map for all directions. */
+export type INotificationMap = IClientNotificationMap & IServerNotificationMap;
+/**
+ * A fully typed JSON-RPC request for a specific AHP command.
+ *
+ * When used as a union (default generic), narrowing on `method` gives typed `params`:
+ *
+ * ```ts
+ * function handle(req: IAhpRequest) {
+ *   if (req.method === 'fetchTurns') {
+ *     req.params.session; // typed as URI
+ *   }
+ * }
+ * ```
+ */
+export type IAhpRequest<M extends keyof ICommandMap = keyof ICommandMap> = M extends unknown ? {
+    readonly jsonrpc: "2.0";
+    readonly id: number;
+    readonly method: M;
+    readonly params: ICommandMap[M]["params"];
+} : never;
+/**
+ * A fully typed JSON-RPC success response for a specific AHP command.
+ *
+ * Since JSON-RPC responses do not carry `method`, use this with an explicit
+ * generic parameter when you know the method from the associated request:
+ *
+ * ```ts
+ * const result: IAhpSuccessResponse<'fetchTurns'> = ...;
+ * result.result.turns; // typed as ITurn[]
+ * ```
+ */
+export type IAhpSuccessResponse<M extends keyof ICommandMap = keyof ICommandMap> = M extends unknown ? {
+    readonly jsonrpc: "2.0";
+    readonly id: number;
+    readonly result: ICommandMap[M]["result"];
+} : never;
+/** Typed JSON-RPC response (success with known result type, or error). */
+export type IAhpResponse<M extends keyof ICommandMap = keyof ICommandMap> = IAhpSuccessResponse<M> | IJsonRpcErrorResponse;
+/**
+ * A fully typed JSON-RPC notification for a specific AHP notification method.
+ *
+ * When used as a union (default generic), narrowing on `method` gives typed `params`:
+ *
+ * ```ts
+ * function handle(notif: IAhpNotification) {
+ *   if (notif.method === 'action') {
+ *     notif.params.serverSeq; // typed as number
+ *   }
+ * }
+ * ```
+ */
+export type IAhpNotification<M extends keyof INotificationMap = keyof INotificationMap> = M extends unknown ? {
+    readonly jsonrpc: "2.0";
+    readonly method: M;
+    readonly params: INotificationMap[M]["params"];
+} : never;
+/** A client → server notification. */
+export type IAhpClientNotification<M extends keyof IClientNotificationMap = keyof IClientNotificationMap> = M extends unknown ? {
+    readonly jsonrpc: "2.0";
+    readonly method: M;
+    readonly params: IClientNotificationMap[M]["params"];
+} : never;
+/** A server → client notification. */
+export type IAhpServerNotification<M extends keyof IServerNotificationMap = keyof IServerNotificationMap> = M extends unknown ? {
+    readonly jsonrpc: "2.0";
+    readonly method: M;
+    readonly params: IServerNotificationMap[M]["params"];
+} : never;
+/**
+ * Discriminated union of all AHP protocol messages.
+ *
+ * Narrow using standard JSON-RPC structure:
+ * - Has `method` + `id` → request ({@link IAhpRequest})
+ * - Has `method`, no `id` → notification ({@link IAhpNotification})
+ * - Has `result` or `error` + `id` → response ({@link IAhpResponse})
+ *
+ * Then narrow on `method` for fully typed params:
+ *
+ * ```ts
+ * function dispatch(msg: IProtocolMessage) {
+ *   if ('method' in msg && 'id' in msg) {
+ *     // msg is IAhpRequest
+ *     if (msg.method === 'fetchTurns') {
+ *       msg.params.session; // URI
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export type IProtocolMessage = IAhpRequest | IAhpSuccessResponse | IJsonRpcErrorResponse | IAhpNotification;