@github/copilot-sdk 0.2.1-preview.0 → 0.2.1-preview.2

package/dist/client.js

@@ -10,7 +10,7 @@ import {
   StreamMessageReader,
   StreamMessageWriter
 } from "vscode-jsonrpc/node.js";
-import { createServerRpc } from "./generated/rpc.js";
+import { createServerRpc, registerClientSessionApiHandlers } from "./generated/rpc.js";
 import { getSdkProtocolVersion } from "./sdkProtocolVersion.js";
 import { CopilotSession, NO_RESULT_PERMISSION_V2_ERROR } from "./session.js";
 import { getTraceContext } from "./telemetry.js";
@@ -96,6 +96,8 @@ class CopilotClient {
   processExitPromise = null;
   // Rejects when CLI process exits
   negotiatedProtocolVersion = null;
+  /** Connection-level session filesystem config, set via constructor option. */
+  sessionFsConfig = null;
   /**
    * Typed server-scoped RPC methods.
    * @throws Error if the client is not connected
@@ -155,8 +157,10 @@ class CopilotClient {
     }
     this.onListModels = options.onListModels;
     this.onGetTraceContext = options.onGetTraceContext;
+    this.sessionFsConfig = options.sessionFs ?? null;
+    const effectiveEnv = options.env ?? process.env;
     this.options = {
-      cliPath: options.cliUrl ? void 0 : options.cliPath || getBundledCliPath(),
+      cliPath: options.cliUrl ? void 0 : options.cliPath || effectiveEnv.COPILOT_CLI_PATH || getBundledCliPath(),
       cliArgs: options.cliArgs ?? [],
       cwd: options.cwd ?? process.cwd(),
       port: options.port || 0,
@@ -167,7 +171,7 @@ class CopilotClient {
       logLevel: options.logLevel || "debug",
       autoStart: options.autoStart ?? true,
       autoRestart: false,
-      env: options.env ?? process.env,
+      env: effectiveEnv,
       githubToken: options.githubToken,
       // Default useLoggedInUser to false when githubToken is provided, otherwise true
       useLoggedInUser: options.useLoggedInUser ?? (options.githubToken ? false : true),
@@ -225,6 +229,13 @@ class CopilotClient {
       }
       await this.connectToServer();
       await this.verifyProtocolVersion();
+      if (this.sessionFsConfig) {
+        await this.connection.sendRequest("sessionFs.setProvider", {
+          initialCwd: this.sessionFsConfig.initialCwd,
+          sessionStatePath: this.sessionFsConfig.sessionStatePath,
+          conventions: this.sessionFsConfig.conventions
+        });
+      }
       this.state = "connected";
     } catch (error) {
       this.state = "error";
@@ -436,6 +447,9 @@ class CopilotClient {
     if (config.onUserInputRequest) {
       session.registerUserInputHandler(config.onUserInputRequest);
     }
+    if (config.onElicitationRequest) {
+      session.registerElicitationHandler(config.onElicitationRequest);
+    }
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
@@ -449,6 +463,15 @@ class CopilotClient {
       session.on(config.onEvent);
     }
     this.sessions.set(sessionId, session);
+    if (this.sessionFsConfig) {
+      if (config.createSessionFsHandler) {
+        session.clientSessionApis.sessionFs = config.createSessionFsHandler(session);
+      } else {
+        throw new Error(
+          "createSessionFsHandler is required in session config when sessionFs is enabled in client options."
+        );
+      }
+    }
     try {
       const response = await this.connection.sendRequest("session.create", {
         ...await getTraceContext(this.onGetTraceContext),
@@ -473,6 +496,7 @@ class CopilotClient {
         provider: config.provider,
         requestPermission: true,
         requestUserInput: !!config.onUserInputRequest,
+        requestElicitation: !!config.onElicitationRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
         streaming: config.streaming,
@@ -543,6 +567,9 @@ class CopilotClient {
     if (config.onUserInputRequest) {
       session.registerUserInputHandler(config.onUserInputRequest);
     }
+    if (config.onElicitationRequest) {
+      session.registerElicitationHandler(config.onElicitationRequest);
+    }
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
@@ -556,6 +583,15 @@ class CopilotClient {
       session.on(config.onEvent);
     }
     this.sessions.set(sessionId, session);
+    if (this.sessionFsConfig) {
+      if (config.createSessionFsHandler) {
+        session.clientSessionApis.sessionFs = config.createSessionFsHandler(session);
+      } else {
+        throw new Error(
+          "createSessionFsHandler is required in session config when sessionFs is enabled in client options."
+        );
+      }
+    }
     try {
       const response = await this.connection.sendRequest("session.resume", {
         ...await getTraceContext(this.onGetTraceContext),
@@ -580,6 +616,7 @@ class CopilotClient {
         provider: config.provider,
         requestPermission: true,
         requestUserInput: !!config.onUserInputRequest,
+        requestElicitation: !!config.onElicitationRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
         configDir: config.configDir,
@@ -791,16 +828,50 @@ class CopilotClient {
     if (!this.connection) {
       throw new Error("Client not connected");
     }
-    const response = await this.connection.sendRequest("session.list", { filter });
+    const response = await this.connection.sendRequest("session.list", {
+      filter
+    });
     const { sessions } = response;
-    return sessions.map((s) => ({
-      sessionId: s.sessionId,
-      startTime: new Date(s.startTime),
-      modifiedTime: new Date(s.modifiedTime),
-      summary: s.summary,
-      isRemote: s.isRemote,
-      context: s.context
-    }));
+    return sessions.map(CopilotClient.toSessionMetadata);
+  }
+  /**
+   * Gets metadata for a specific session by ID.
+   *
+   * This provides an efficient O(1) lookup of a single session's metadata
+   * instead of listing all sessions. Returns undefined if the session is not found.
+   *
+   * @param sessionId - The ID of the session to look up
+   * @returns A promise that resolves with the session metadata, or undefined if not found
+   * @throws Error if the client is not connected
+   *
+   * @example
+   * ```typescript
+   * const metadata = await client.getSessionMetadata("session-123");
+   * if (metadata) {
+   *   console.log(`Session started at: ${metadata.startTime}`);
+   * }
+   * ```
+   */
+  async getSessionMetadata(sessionId) {
+    if (!this.connection) {
+      throw new Error("Client not connected");
+    }
+    const response = await this.connection.sendRequest("session.getMetadata", { sessionId });
+    const { session } = response;
+    if (!session) {
+      return void 0;
+    }
+    return CopilotClient.toSessionMetadata(session);
+  }
+  static toSessionMetadata(raw) {
+    return {
+      sessionId: raw.sessionId,
+      startTime: new Date(raw.startTime),
+      modifiedTime: new Date(raw.modifiedTime),
+      summary: raw.summary,
+      isRemote: raw.isRemote,
+      context: raw.context
+    };
   }
   /**
    * Gets the foreground session ID in TUI+server mode.
@@ -1130,6 +1201,12 @@ stderr: ${stderrOutput}`
       "systemMessage.transform",
       async (params) => await this.handleSystemMessageTransform(params)
     );
+    const sessions = this.sessions;
+    registerClientSessionApiHandlers(this.connection, (sessionId) => {
+      const session = sessions.get(sessionId);
+      if (!session) throw new Error(`No session found for sessionId: ${sessionId}`);
+      return session.clientSessionApis;
+    });
     this.connection.onClose(() => {
       this.state = "disconnected";
     });

package/dist/generated/rpc.d.ts

@@ -171,6 +171,165 @@ export interface AccountGetQuotaResult {
         };
     };
 }
+export interface McpConfigListResult {
+    /**
+     * All MCP servers from user config, keyed by name
+     */
+    servers: {
+        /**
+         * MCP server configuration (local/stdio or remote/http)
+         */
+        [k: string]: {
+            /**
+             * Tools to include. Defaults to all tools if not specified.
+             */
+            tools?: string[];
+            type?: "local" | "stdio";
+            isDefaultServer?: boolean;
+            filterMapping?: {
+                [k: string]: "none" | "markdown" | "hidden_characters";
+            } | ("none" | "markdown" | "hidden_characters");
+            timeout?: number;
+            command: string;
+            args: string[];
+            cwd?: string;
+            env?: {
+                [k: string]: string;
+            };
+        } | {
+            /**
+             * Tools to include. Defaults to all tools if not specified.
+             */
+            tools?: string[];
+            type: "http" | "sse";
+            isDefaultServer?: boolean;
+            filterMapping?: {
+                [k: string]: "none" | "markdown" | "hidden_characters";
+            } | ("none" | "markdown" | "hidden_characters");
+            timeout?: number;
+            url: string;
+            headers?: {
+                [k: string]: string;
+            };
+            oauthClientId?: string;
+            oauthPublicClient?: boolean;
+        };
+    };
+}
+export interface McpConfigAddParams {
+    /**
+     * Unique name for the MCP server
+     */
+    name: string;
+    /**
+     * MCP server configuration (local/stdio or remote/http)
+     */
+    config: {
+        /**
+         * Tools to include. Defaults to all tools if not specified.
+         */
+        tools?: string[];
+        type?: "local" | "stdio";
+        isDefaultServer?: boolean;
+        filterMapping?: {
+            [k: string]: "none" | "markdown" | "hidden_characters";
+        } | ("none" | "markdown" | "hidden_characters");
+        timeout?: number;
+        command: string;
+        args: string[];
+        cwd?: string;
+        env?: {
+            [k: string]: string;
+        };
+    } | {
+        /**
+         * Tools to include. Defaults to all tools if not specified.
+         */
+        tools?: string[];
+        type: "http" | "sse";
+        isDefaultServer?: boolean;
+        filterMapping?: {
+            [k: string]: "none" | "markdown" | "hidden_characters";
+        } | ("none" | "markdown" | "hidden_characters");
+        timeout?: number;
+        url: string;
+        headers?: {
+            [k: string]: string;
+        };
+        oauthClientId?: string;
+        oauthPublicClient?: boolean;
+    };
+}
+export interface McpConfigUpdateParams {
+    /**
+     * Name of the MCP server to update
+     */
+    name: string;
+    /**
+     * MCP server configuration (local/stdio or remote/http)
+     */
+    config: {
+        /**
+         * Tools to include. Defaults to all tools if not specified.
+         */
+        tools?: string[];
+        type?: "local" | "stdio";
+        isDefaultServer?: boolean;
+        filterMapping?: {
+            [k: string]: "none" | "markdown" | "hidden_characters";
+        } | ("none" | "markdown" | "hidden_characters");
+        timeout?: number;
+        command: string;
+        args: string[];
+        cwd?: string;
+        env?: {
+            [k: string]: string;
+        };
+    } | {
+        /**
+         * Tools to include. Defaults to all tools if not specified.
+         */
+        tools?: string[];
+        type: "http" | "sse";
+        isDefaultServer?: boolean;
+        filterMapping?: {
+            [k: string]: "none" | "markdown" | "hidden_characters";
+        } | ("none" | "markdown" | "hidden_characters");
+        timeout?: number;
+        url: string;
+        headers?: {
+            [k: string]: string;
+        };
+        oauthClientId?: string;
+        oauthPublicClient?: boolean;
+    };
+}
+export interface McpConfigRemoveParams {
+    /**
+     * Name of the MCP server to remove
+     */
+    name: string;
+}
+export interface SessionFsSetProviderResult {
+    /**
+     * Whether the provider was set successfully
+     */
+    success: boolean;
+}
+export interface SessionFsSetProviderParams {
+    /**
+     * Initial working directory for sessions
+     */
+    initialCwd: string;
+    /**
+     * Path within each session's SessionFs where the runtime stores files for that session
+     */
+    sessionStatePath: string;
+    /**
+     * Path conventions used by this filesystem
+     */
+    conventions: "windows" | "posix";
+}
 export interface SessionModelGetCurrentResult {
     /**
      * Currently active model identifier
@@ -543,9 +702,9 @@ export interface SessionMcpListResult {
          */
         name: string;
         /**
-         * Connection status: connected, failed, pending, disabled, or not_configured
+         * Connection status: connected, failed, needs-auth, pending, disabled, or not_configured
          */
-        status: "connected" | "failed" | "pending" | "disabled" | "not_configured";
+        status: "connected" | "failed" | "needs-auth" | "pending" | "disabled" | "not_configured";
         /**
          * Configuration source: user, workspace, plugin, or builtin
          */
@@ -867,6 +1026,37 @@ export interface SessionUiElicitationParams {
         required?: string[];
     };
 }
+export interface SessionUiHandlePendingElicitationResult {
+    /**
+     * Whether the response was accepted. False if the request was already resolved by another client.
+     */
+    success: boolean;
+}
+export interface SessionUiHandlePendingElicitationParams {
+    /**
+     * Target session identifier
+     */
+    sessionId: string;
+    /**
+     * The unique request ID from the elicitation.requested event
+     */
+    requestId: string;
+    /**
+     * The elicitation response (accept with form values, decline, or cancel)
+     */
+    result: {
+        /**
+         * The user's response: accept (submitted), decline (rejected), or cancel (dismissed)
+         */
+        action: "accept" | "decline" | "cancel";
+        /**
+         * The form values submitted by the user (present when action is 'accept')
+         */
+        content?: {
+            [k: string]: string | number | boolean | string[];
+        };
+    };
+}
 export interface SessionPermissionsHandlePendingPermissionRequestResult {
     /**
      * Whether the permission request was handled successfully
@@ -967,6 +1157,197 @@ export interface SessionShellKillParams {
      */
     signal?: "SIGTERM" | "SIGKILL" | "SIGINT";
 }
+export interface SessionFsReadFileResult {
+    /**
+     * File content as UTF-8 string
+     */
+    content: string;
+}
+export interface SessionFsReadFileParams {
+    /**
+     * Target session identifier
+     */
+    sessionId: string;
+    /**
+     * Path using SessionFs conventions
+     */
+    path: string;
+}
+export interface SessionFsWriteFileParams {
+    /**
+     * Target session identifier
+     */
+    sessionId: string;
+    /**
+     * Path using SessionFs conventions
+     */
+    path: string;
+    /**
+     * Content to write
+     */
+    content: string;
+    /**
+     * Optional POSIX-style mode for newly created files
+     */
+    mode?: number;
+}
+export interface SessionFsAppendFileParams {
+    /**
+     * Target session identifier
+     */
+    sessionId: string;
+    /**
+     * Path using SessionFs conventions
+     */
+    path: string;
+    /**
+     * Content to append
+     */
+    content: string;
+    /**
+     * Optional POSIX-style mode for newly created files
+     */
+    mode?: number;
+}
+export interface SessionFsExistsResult {
+    /**
+     * Whether the path exists
+     */
+    exists: boolean;
+}
+export interface SessionFsExistsParams {
+    /**
+     * Target session identifier
+     */
+    sessionId: string;
+    /**
+     * Path using SessionFs conventions
+     */
+    path: string;
+}
+export interface SessionFsStatResult {
+    /**
+     * Whether the path is a file
+     */
+    isFile: boolean;
+    /**
+     * Whether the path is a directory
+     */
+    isDirectory: boolean;
+    /**
+     * File size in bytes
+     */
+    size: number;
+    /**
+     * ISO 8601 timestamp of last modification
+     */
+    mtime: string;
+    /**
+     * ISO 8601 timestamp of creation
+     */
+    birthtime: string;
+}
+export interface SessionFsStatParams {
+    /**
+     * Target session identifier
+     */
+    sessionId: string;
+    /**
+     * Path using SessionFs conventions
+     */
+    path: string;
+}
+export interface SessionFsMkdirParams {
+    /**
+     * Target session identifier
+     */
+    sessionId: string;
+    /**
+     * Path using SessionFs conventions
+     */
+    path: string;
+    /**
+     * Create parent directories as needed
+     */
+    recursive?: boolean;
+    /**
+     * Optional POSIX-style mode for newly created directories
+     */
+    mode?: number;
+}
+export interface SessionFsReaddirResult {
+    /**
+     * Entry names in the directory
+     */
+    entries: string[];
+}
+export interface SessionFsReaddirParams {
+    /**
+     * Target session identifier
+     */
+    sessionId: string;
+    /**
+     * Path using SessionFs conventions
+     */
+    path: string;
+}
+export interface SessionFsReaddirWithTypesResult {
+    /**
+     * Directory entries with type information
+     */
+    entries: {
+        /**
+         * Entry name
+         */
+        name: string;
+        /**
+         * Entry type
+         */
+        type: "file" | "directory";
+    }[];
+}
+export interface SessionFsReaddirWithTypesParams {
+    /**
+     * Target session identifier
+     */
+    sessionId: string;
+    /**
+     * Path using SessionFs conventions
+     */
+    path: string;
+}
+export interface SessionFsRmParams {
+    /**
+     * Target session identifier
+     */
+    sessionId: string;
+    /**
+     * Path using SessionFs conventions
+     */
+    path: string;
+    /**
+     * Remove directories and their contents recursively
+     */
+    recursive?: boolean;
+    /**
+     * Ignore errors if the path does not exist
+     */
+    force?: boolean;
+}
+export interface SessionFsRenameParams {
+    /**
+     * Target session identifier
+     */
+    sessionId: string;
+    /**
+     * Source path using SessionFs conventions
+     */
+    src: string;
+    /**
+     * Destination path using SessionFs conventions
+     */
+    dest: string;
+}
 /** Create typed server-scoped RPC methods (no session required). */
 export declare function createServerRpc(connection: MessageConnection): {
     ping: (params: PingParams) => Promise<PingResult>;
@@ -979,6 +1360,17 @@ export declare function createServerRpc(connection: MessageConnection): {
     account: {
         getQuota: () => Promise<AccountGetQuotaResult>;
     };
+    mcp: {
+        config: {
+            list: () => Promise<McpConfigListResult>;
+            add: (params: McpConfigAddParams) => Promise<void>;
+            update: (params: McpConfigUpdateParams) => Promise<void>;
+            remove: (params: McpConfigRemoveParams) => Promise<void>;
+        };
+    };
+    sessionFs: {
+        setProvider: (params: SessionFsSetProviderParams) => Promise<SessionFsSetProviderResult>;
+    };
 };
 /** Create typed session-scoped RPC methods. */
 export declare function createSessionRpc(connection: MessageConnection, sessionId: string): {
@@ -1049,6 +1441,7 @@ export declare function createSessionRpc(connection: MessageConnection, sessionI
     };
     ui: {
         elicitation: (params: Omit<SessionUiElicitationParams, "sessionId">) => Promise<SessionUiElicitationResult>;
+        handlePendingElicitation: (params: Omit<SessionUiHandlePendingElicitationParams, "sessionId">) => Promise<SessionUiHandlePendingElicitationResult>;
     };
     permissions: {
         handlePendingPermissionRequest: (params: Omit<SessionPermissionsHandlePendingPermissionRequestParams, "sessionId">) => Promise<SessionPermissionsHandlePendingPermissionRequestResult>;
@@ -1059,3 +1452,27 @@ export declare function createSessionRpc(connection: MessageConnection, sessionI
         kill: (params: Omit<SessionShellKillParams, "sessionId">) => Promise<SessionShellKillResult>;
     };
 };
+/** Handler for `sessionFs` client session API methods. */
+export interface SessionFsHandler {
+    readFile(params: SessionFsReadFileParams): Promise<SessionFsReadFileResult>;
+    writeFile(params: SessionFsWriteFileParams): Promise<void>;
+    appendFile(params: SessionFsAppendFileParams): Promise<void>;
+    exists(params: SessionFsExistsParams): Promise<SessionFsExistsResult>;
+    stat(params: SessionFsStatParams): Promise<SessionFsStatResult>;
+    mkdir(params: SessionFsMkdirParams): Promise<void>;
+    readdir(params: SessionFsReaddirParams): Promise<SessionFsReaddirResult>;
+    readdirWithTypes(params: SessionFsReaddirWithTypesParams): Promise<SessionFsReaddirWithTypesResult>;
+    rm(params: SessionFsRmParams): Promise<void>;
+    rename(params: SessionFsRenameParams): Promise<void>;
+}
+/** All client session API handler groups. */
+export interface ClientSessionApiHandlers {
+    sessionFs?: SessionFsHandler;
+}
+/**
+ * Register client session API handlers on a JSON-RPC connection.
+ * The server calls these methods to delegate work to the client.
+ * Each incoming call includes a `sessionId` in the params; the registration
+ * function uses `getHandlers` to resolve the session's handlers.
+ */
+export declare function registerClientSessionApiHandlers(connection: MessageConnection, getHandlers: (sessionId: string) => ClientSessionApiHandlers): void;