@github/copilot-sdk 0.3.0-preview.1 → 1.0.0-beta.1

package/README.md

@@ -88,6 +88,7 @@ new CopilotClient(options?: CopilotClientOptions)
 - `autoStart?: boolean` - Auto-start server (default: true)
 - `gitHubToken?: string` - GitHub token for authentication. When provided, takes priority over other auth methods.
 - `useLoggedInUser?: boolean` - Whether to use logged-in user for authentication (default: true, but false when `gitHubToken` is provided). Cannot be used with `cliUrl`.
+- `copilotHome?: string` - Base directory for Copilot data (session state, config, etc.). Sets `COPILOT_HOME` on the spawned CLI process. When not set, the CLI defaults to `~/.copilot`. Useful in restricted environments where only specific directories are writable. Ignored when using `cliUrl`.
 - `telemetry?: TelemetryConfig` - OpenTelemetry configuration for the CLI process. Providing this object enables telemetry — no separate flag needed. See [Telemetry](#telemetry) below.
 - `onGetTraceContext?: TraceContextProvider` - Advanced: callback for linking your application's own OpenTelemetry spans into the same distributed trace as the CLI's spans. Not needed for normal telemetry collection. See [Telemetry](#telemetry) below.
 

package/dist/cjs/client.js

@@ -109,6 +109,8 @@ class CopilotClient {
   options;
   isExternalServer = false;
   forceStopping = false;
+  /** Token sent in `connect`; auto-generated when the SDK spawns its own CLI in TCP mode. */
+  effectiveConnectionToken;
   onListModels;
   onGetTraceContext;
   modelsCache = null;
@@ -116,6 +118,7 @@ class CopilotClient {
   sessionLifecycleHandlers = /* @__PURE__ */ new Set();
   typedLifecycleHandlers = /* @__PURE__ */ new Map();
   _rpc = null;
+  _internalRpc = null;
   processExitPromise = null;
   // Rejects when CLI process exits
   negotiatedProtocolVersion = null;
@@ -134,6 +137,19 @@ class CopilotClient {
     }
     return this._rpc;
   }
+  /**
+   * Internal RPC surface (e.g. handshake helpers). Not part of the public API.
+   * @internal
+   */
+  get internalRpc() {
+    if (!this.connection) {
+      throw new Error("Client is not connected. Call start() first.");
+    }
+    if (!this._internalRpc) {
+      this._internalRpc = (0, import_rpc.createInternalServerRpc)(this.connection);
+    }
+    return this._internalRpc;
+  }
   /**
    * Creates a new CopilotClient instance.
    *
@@ -169,6 +185,17 @@ class CopilotClient {
         "gitHubToken and useLoggedInUser cannot be used with cliUrl (external server manages its own auth)"
       );
     }
+    if (options.tcpConnectionToken !== void 0) {
+      if (typeof options.tcpConnectionToken !== "string" || options.tcpConnectionToken.length === 0) {
+        throw new Error("tcpConnectionToken must be a non-empty string");
+      }
+      if (options.useStdio === true) {
+        throw new Error("tcpConnectionToken cannot be used with useStdio: true");
+      }
+    }
+    const willUseStdio = options.cliUrl ? false : options.useStdio ?? true;
+    const sdkSpawnsCli = !willUseStdio && !options.cliUrl && !options.isChildProcess;
+    this.effectiveConnectionToken = options.tcpConnectionToken ?? (sdkSpawnsCli ? (0, import_node_crypto.randomUUID)() : void 0);
     if (options.sessionFs) {
       this.validateSessionFsConfig(options.sessionFs);
     }
@@ -202,6 +229,7 @@ class CopilotClient {
       // Default useLoggedInUser to false when gitHubToken is provided, otherwise true
       useLoggedInUser: options.useLoggedInUser ?? (options.gitHubToken ? false : true),
       telemetry: options.telemetry,
+      copilotHome: options.copilotHome,
       sessionIdleTimeoutSeconds: options.sessionIdleTimeoutSeconds ?? 0
     };
   }
@@ -558,6 +586,7 @@ class CopilotClient {
         configDir: config.configDir,
         enableConfigDiscovery: config.enableConfigDiscovery,
         skillDirectories: config.skillDirectories,
+        instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         infiniteSessions: config.infiniteSessions,
         gitHubToken: config.gitHubToken
@@ -685,9 +714,11 @@ class CopilotClient {
         defaultAgent: config.defaultAgent,
         agent: config.agent,
         skillDirectories: config.skillDirectories,
+        instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         infiniteSessions: config.infiniteSessions,
         disableResume: config.disableResume,
+        continuePendingWork: config.continuePendingWork,
         gitHubToken: config.gitHubToken
       });
       const { workspacePath, capabilities } = response;
@@ -809,18 +840,29 @@ class CopilotClient {
     }
   }
   /**
-   * Verify that the server's protocol version is within the supported range
-   * and store the negotiated version.
+   * Send the `connect` handshake (carrying the optional token) and verify the
+   * server's protocol version. Falls back to `ping` against legacy servers
+   * that don't implement `connect`.
    */
   async verifyProtocolVersion() {
+    if (!this.connection) {
+      throw new Error("Client not connected");
+    }
     const maxVersion = (0, import_sdkProtocolVersion.getSdkProtocolVersion)();
-    let pingResult;
-    if (this.processExitPromise) {
-      pingResult = await Promise.race([this.ping(), this.processExitPromise]);
-    } else {
-      pingResult = await this.ping();
+    const raceAgainstExit = (p) => this.processExitPromise ? Promise.race([p, this.processExitPromise]) : p;
+    let serverVersion;
+    try {
+      const result = await raceAgainstExit(
+        this.internalRpc.connect({ token: this.effectiveConnectionToken })
+      );
+      serverVersion = result.protocolVersion;
+    } catch (err) {
+      if (err instanceof import_node.ResponseError && err.code === import_node.ErrorCodes.MethodNotFound) {
+        serverVersion = (await raceAgainstExit(this.ping())).protocolVersion;
+      } else {
+        throw err;
+      }
     }
-    const serverVersion = pingResult.protocolVersion;
     if (serverVersion === void 0) {
       throw new Error(
         `SDK protocol version mismatch: SDK supports versions ${MIN_PROTOCOL_VERSION}-${maxVersion}, but server does not report a protocol version. Please update your server to ensure compatibility.`
@@ -1055,6 +1097,12 @@ class CopilotClient {
       if (this.options.gitHubToken) {
         envWithoutNodeDebug.COPILOT_SDK_AUTH_TOKEN = this.options.gitHubToken;
       }
+      if (this.effectiveConnectionToken) {
+        envWithoutNodeDebug.COPILOT_CONNECTION_TOKEN = this.effectiveConnectionToken;
+      }
+      if (this.options.copilotHome) {
+        envWithoutNodeDebug.COPILOT_HOME = this.options.copilotHome;
+      }
       if (!this.options.cliPath) {
         throw new Error(
           "Path to Copilot CLI is required. Please provide it via the cliPath option, or use cliUrl to rely on a remote CLI."

package/dist/cjs/generated/rpc.js

@@ -18,6 +18,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var rpc_exports = {};
 __export(rpc_exports, {
+  createInternalServerRpc: () => createInternalServerRpc,
   createServerRpc: () => createServerRpc,
   createSessionRpc: () => createSessionRpc,
   registerClientSessionApiHandlers: () => registerClientSessionApiHandlers
@@ -61,8 +62,14 @@ function createServerRpc(connection) {
     }
   };
 }
+function createInternalServerRpc(connection) {
+  return {
+    connect: async (params) => connection.sendRequest("connect", params)
+  };
+}
 function createSessionRpc(connection, sessionId) {
   return {
+    suspend: async () => connection.sendRequest("session.suspend", { sessionId }),
     auth: {
       getStatus: async () => connection.sendRequest("session.auth.getStatus", { sessionId })
     },
@@ -105,6 +112,14 @@ function createSessionRpc(connection, sessionId) {
       reload: async () => connection.sendRequest("session.agent.reload", { sessionId })
     },
     /** @experimental */
+    tasks: {
+      startAgent: async (params) => connection.sendRequest("session.tasks.startAgent", { sessionId, ...params }),
+      list: async () => connection.sendRequest("session.tasks.list", { sessionId }),
+      promoteToBackground: async (params) => connection.sendRequest("session.tasks.promoteToBackground", { sessionId, ...params }),
+      cancel: async (params) => connection.sendRequest("session.tasks.cancel", { sessionId, ...params }),
+      remove: async (params) => connection.sendRequest("session.tasks.remove", { sessionId, ...params })
+    },
+    /** @experimental */
     skills: {
       list: async () => connection.sendRequest("session.skills.list", { sessionId }),
       enable: async (params) => connection.sendRequest("session.skills.enable", { sessionId, ...params }),
@@ -218,6 +233,7 @@ function registerClientSessionApiHandlers(connection, getHandlers) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  createInternalServerRpc,
   createServerRpc,
   createSessionRpc,
   registerClientSessionApiHandlers

package/dist/client.d.ts

@@ -47,6 +47,8 @@ export declare class CopilotClient {
     private options;
     private isExternalServer;
     private forceStopping;
+    /** Token sent in `connect`; auto-generated when the SDK spawns its own CLI in TCP mode. */
+    private effectiveConnectionToken?;
     private onListModels?;
     private onGetTraceContext?;
     private modelsCache;
@@ -54,6 +56,7 @@ export declare class CopilotClient {
     private sessionLifecycleHandlers;
     private typedLifecycleHandlers;
     private _rpc;
+    private _internalRpc;
     private processExitPromise;
     private negotiatedProtocolVersion;
     /** Connection-level session filesystem config, set via constructor option. */
@@ -63,6 +66,11 @@ export declare class CopilotClient {
      * @throws Error if the client is not connected
      */
     get rpc(): ReturnType<typeof createServerRpc>;
+    /**
+     * Internal RPC surface (e.g. handshake helpers). Not part of the public API.
+     * @internal
+     */
+    private get internalRpc();
     /**
      * Creates a new CopilotClient instance.
      *
@@ -267,8 +275,9 @@ export declare class CopilotClient {
      */
     listModels(): Promise<ModelInfo[]>;
     /**
-     * Verify that the server's protocol version is within the supported range
-     * and store the negotiated version.
+     * Send the `connect` handshake (carrying the optional token) and verify the
+     * server's protocol version. Falls back to `ping` against legacy servers
+     * that don't implement `connect`.
      */
     private verifyProtocolVersion;
     /**

package/dist/client.js

@@ -7,10 +7,16 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   createMessageConnection,
+  ErrorCodes,
+  ResponseError,
   StreamMessageReader,
   StreamMessageWriter
 } from "vscode-jsonrpc/node.js";
-import { createServerRpc, registerClientSessionApiHandlers } from "./generated/rpc.js";
+import {
+  createServerRpc,
+  createInternalServerRpc,
+  registerClientSessionApiHandlers
+} from "./generated/rpc.js";
 import { getSdkProtocolVersion } from "./sdkProtocolVersion.js";
 import { CopilotSession, NO_RESULT_PERMISSION_V2_ERROR } from "./session.js";
 import { createSessionFsAdapter } from "./sessionFsProvider.js";
@@ -89,6 +95,8 @@ class CopilotClient {
   options;
   isExternalServer = false;
   forceStopping = false;
+  /** Token sent in `connect`; auto-generated when the SDK spawns its own CLI in TCP mode. */
+  effectiveConnectionToken;
   onListModels;
   onGetTraceContext;
   modelsCache = null;
@@ -96,6 +104,7 @@ class CopilotClient {
   sessionLifecycleHandlers = /* @__PURE__ */ new Set();
   typedLifecycleHandlers = /* @__PURE__ */ new Map();
   _rpc = null;
+  _internalRpc = null;
   processExitPromise = null;
   // Rejects when CLI process exits
   negotiatedProtocolVersion = null;
@@ -114,6 +123,19 @@ class CopilotClient {
     }
     return this._rpc;
   }
+  /**
+   * Internal RPC surface (e.g. handshake helpers). Not part of the public API.
+   * @internal
+   */
+  get internalRpc() {
+    if (!this.connection) {
+      throw new Error("Client is not connected. Call start() first.");
+    }
+    if (!this._internalRpc) {
+      this._internalRpc = createInternalServerRpc(this.connection);
+    }
+    return this._internalRpc;
+  }
   /**
    * Creates a new CopilotClient instance.
    *
@@ -149,6 +171,17 @@ class CopilotClient {
         "gitHubToken and useLoggedInUser cannot be used with cliUrl (external server manages its own auth)"
       );
     }
+    if (options.tcpConnectionToken !== void 0) {
+      if (typeof options.tcpConnectionToken !== "string" || options.tcpConnectionToken.length === 0) {
+        throw new Error("tcpConnectionToken must be a non-empty string");
+      }
+      if (options.useStdio === true) {
+        throw new Error("tcpConnectionToken cannot be used with useStdio: true");
+      }
+    }
+    const willUseStdio = options.cliUrl ? false : options.useStdio ?? true;
+    const sdkSpawnsCli = !willUseStdio && !options.cliUrl && !options.isChildProcess;
+    this.effectiveConnectionToken = options.tcpConnectionToken ?? (sdkSpawnsCli ? randomUUID() : void 0);
     if (options.sessionFs) {
       this.validateSessionFsConfig(options.sessionFs);
     }
@@ -182,6 +215,7 @@ class CopilotClient {
       // Default useLoggedInUser to false when gitHubToken is provided, otherwise true
       useLoggedInUser: options.useLoggedInUser ?? (options.gitHubToken ? false : true),
       telemetry: options.telemetry,
+      copilotHome: options.copilotHome,
       sessionIdleTimeoutSeconds: options.sessionIdleTimeoutSeconds ?? 0
     };
   }
@@ -538,6 +572,7 @@ class CopilotClient {
         configDir: config.configDir,
         enableConfigDiscovery: config.enableConfigDiscovery,
         skillDirectories: config.skillDirectories,
+        instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         infiniteSessions: config.infiniteSessions,
         gitHubToken: config.gitHubToken
@@ -665,9 +700,11 @@ class CopilotClient {
         defaultAgent: config.defaultAgent,
         agent: config.agent,
         skillDirectories: config.skillDirectories,
+        instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         infiniteSessions: config.infiniteSessions,
         disableResume: config.disableResume,
+        continuePendingWork: config.continuePendingWork,
         gitHubToken: config.gitHubToken
       });
       const { workspacePath, capabilities } = response;
@@ -789,18 +826,29 @@ class CopilotClient {
     }
   }
   /**
-   * Verify that the server's protocol version is within the supported range
-   * and store the negotiated version.
+   * Send the `connect` handshake (carrying the optional token) and verify the
+   * server's protocol version. Falls back to `ping` against legacy servers
+   * that don't implement `connect`.
    */
   async verifyProtocolVersion() {
+    if (!this.connection) {
+      throw new Error("Client not connected");
+    }
     const maxVersion = getSdkProtocolVersion();
-    let pingResult;
-    if (this.processExitPromise) {
-      pingResult = await Promise.race([this.ping(), this.processExitPromise]);
-    } else {
-      pingResult = await this.ping();
+    const raceAgainstExit = (p) => this.processExitPromise ? Promise.race([p, this.processExitPromise]) : p;
+    let serverVersion;
+    try {
+      const result = await raceAgainstExit(
+        this.internalRpc.connect({ token: this.effectiveConnectionToken })
+      );
+      serverVersion = result.protocolVersion;
+    } catch (err) {
+      if (err instanceof ResponseError && err.code === ErrorCodes.MethodNotFound) {
+        serverVersion = (await raceAgainstExit(this.ping())).protocolVersion;
+      } else {
+        throw err;
+      }
     }
-    const serverVersion = pingResult.protocolVersion;
     if (serverVersion === void 0) {
       throw new Error(
         `SDK protocol version mismatch: SDK supports versions ${MIN_PROTOCOL_VERSION}-${maxVersion}, but server does not report a protocol version. Please update your server to ensure compatibility.`
@@ -1035,6 +1083,12 @@ class CopilotClient {
       if (this.options.gitHubToken) {
         envWithoutNodeDebug.COPILOT_SDK_AUTH_TOKEN = this.options.gitHubToken;
       }
+      if (this.effectiveConnectionToken) {
+        envWithoutNodeDebug.COPILOT_CONNECTION_TOKEN = this.effectiveConnectionToken;
+      }
+      if (this.options.copilotHome) {
+        envWithoutNodeDebug.COPILOT_HOME = this.options.copilotHome;
+      }
       if (!this.options.cliPath) {
         throw new Error(
           "Path to Copilot CLI is required. Please provide it via the cliPath option, or use cliUrl to rely on a remote CLI."