@github/copilot-sdk 1.0.13-preview.3 → 1.0.13-preview.4

package/README.md

@@ -95,6 +95,7 @@ new CopilotClient(options?: CopilotClientOptions)
     - `RuntimeConnection.forUri(url, { connectionToken? })` — connect to an already-running runtime (mutually exclusive with `gitHubToken`/`useLoggedInUser`). There is no top-level `cliUrl` shortcut; use this factory for URL-based connections.
     - `RuntimeConnection.forInProcess()` — host the runtime in-process over its native C ABI (FFI). **Experimental.** Because the runtime shares this process, `env`, `telemetry`, and `workingDirectory` are rejected with this transport; set them on the host process instead.
     - The child-process transports (`forStdio`/`forTcp`) also accept a per-connection `env`. Set it there or via the top-level `env` option — not both (setting both throws).
+    - Managed child-process connections materialize the bundled `copilot-runtime` and adjacent `runtime.node`, then launch the wrapper by default. An explicit connection `path` or `COPILOT_CLI_PATH` overrides the bundled runtime.
 - `mode?: "empty" | "copilot-cli"` - Defaulting strategy. Use `"empty"` for multi-user server mode; defaults to `"copilot-cli"`.
 - `workingDirectory?: string` - Working directory for the runtime process (default: current process cwd).
 - `baseDirectory?: string` - Base directory for Copilot data (session state, config, etc.). Sets `COPILOT_HOME` on the spawned runtime. When not set, the runtime defaults to `~/.copilot`. Ignored when connecting via `RuntimeConnection.forUri`.

package/dist/cjs/client.js

@@ -42,6 +42,7 @@ var import_node = require("vscode-jsonrpc/node.js");
 var import_rpc = require("./generated/rpc.js");
 var import_sdkProtocolVersion = require("./sdkProtocolVersion.js");
 var import_session = require("./session.js");
+var import_runtimeArtifacts = require("./runtimeArtifacts.js");
 var import_sessionFsProvider = require("./sessionFsProvider.js");
 var import_copilotRequestHandler = require("./copilotRequestHandler.js");
 var import_telemetry = require("./telemetry.js");
@@ -72,7 +73,7 @@ async function waitForChildExit(child, timeoutMs) {
   if (child.exitCode != null || child.signalCode != null) {
     return true;
   }
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     let timeout;
     let settled = false;
     const onExit = () => {
@@ -81,7 +82,7 @@ async function waitForChildExit(child, timeoutMs) {
       }
       settled = true;
       clearTimeout(timeout);
-      resolve(true);
+      resolve2(true);
     };
     timeout = setTimeout(() => {
       if (settled) {
@@ -89,7 +90,7 @@ async function waitForChildExit(child, timeoutMs) {
       }
       settled = true;
       child.off("exit", onExit);
-      resolve(false);
+      resolve2(false);
     }, timeoutMs);
     child.once("exit", onExit);
     if (child.exitCode != null || child.signalCode != null) {
@@ -212,14 +213,17 @@ function getCliPlatformPackageNames() {
   const variants = process.platform === "linux" ? ["linux", "linuxmusl"] : [process.platform];
   return variants.map((variant) => `@github/copilot-${variant}-${arch}`);
 }
-function getBundledCliPath() {
+function getBundledCliPackage() {
   const packageNames = getCliPlatformPackageNames();
   if (typeof import_meta.resolve === "function") {
     for (const packageName of packageNames) {
       try {
         const packageEntryUrl = import_meta.resolve(packageName);
         const packageEntryPath = (0, import_node_url.fileURLToPath)(packageEntryUrl);
-        return (0, import_node_path.join)((0, import_node_path.dirname)(packageEntryPath), "index.js");
+        return {
+          root: (0, import_node_path.dirname)(packageEntryPath),
+          platform: packageName.slice("@github/copilot-".length)
+        };
       } catch {
       }
     }
@@ -231,9 +235,13 @@ function getBundledCliPath() {
   const searchPaths = req.resolve.paths("@github/copilot") ?? [];
   for (const base of searchPaths) {
     for (const packageName of packageNames) {
-      const candidate = (0, import_node_path.join)(base, ...packageName.split("/"), "index.js");
+      const root = (0, import_node_path.join)(base, ...packageName.split("/"));
+      const candidate = (0, import_node_path.join)(root, "index.js");
       if ((0, import_node_fs.existsSync)(candidate)) {
-        return candidate;
+        return {
+          root,
+          platform: packageName.slice("@github/copilot-".length)
+        };
       }
     }
   }
@@ -241,6 +249,13 @@ function getBundledCliPath() {
     `Could not find a @github/copilot platform package (tried ${packageNames.join(", ")}). Searched ${searchPaths.length} paths. Ensure @github/copilot is installed, or pass cliPath/cliUrl to CopilotClient.`
   );
 }
+function getBundledRuntimePath() {
+  const bundled = getBundledCliPackage();
+  return (0, import_runtimeArtifacts.materializeRuntimeBundle)({
+    packageRoot: bundled.root,
+    platform: bundled.platform
+  });
+}
 class TeardownResilientStreamMessageWriter extends import_node.StreamMessageWriter {
   suppressWriteErrors = false;
   async write(msg) {
@@ -287,6 +302,7 @@ class CopilotClient {
   _internalRpc = null;
   processExitPromise = null;
   // Rejects when CLI process exits
+  processTransportError = null;
   negotiatedProtocolVersion = null;
   /** Connection-level session filesystem config, set via constructor option. */
   sessionFsConfig = null;
@@ -453,7 +469,14 @@ class CopilotClient {
     const connEnv = conn.kind === "stdio" || conn.kind === "tcp" ? conn.env : void 0;
     const effectiveEnv = connEnv ?? options.env ?? process.env;
     this.resolvedEnv = effectiveEnv;
-    this.resolvedCliPath = conn.kind === "stdio" || conn.kind === "tcp" ? conn.path ?? effectiveEnv.COPILOT_CLI_PATH ?? getBundledCliPath() : void 0;
+    if (conn.kind === "stdio" || conn.kind === "tcp") {
+      const explicitCliPath = conn.path ?? effectiveEnv.COPILOT_CLI_PATH;
+      if (explicitCliPath) {
+        this.resolvedCliPath = explicitCliPath;
+      } else {
+        this.resolvedCliPath = getBundledRuntimePath();
+      }
+    }
     const connArgs = conn.kind === "stdio" || conn.kind === "tcp" ? conn.args ?? [] : [];
     this.connectionExtraArgs = [...connArgs];
     this.options = {
@@ -621,6 +644,8 @@ class CopilotClient {
     if (this.state === "connected") {
       return;
     }
+    this.forceStopping = false;
+    this.processTransportError = null;
     this.state = "connecting";
     try {
       if (this.connectionConfig.kind === "inprocess") {
@@ -653,8 +678,10 @@ class CopilotClient {
       }
       this.state = "connected";
     } catch (error) {
+      const startupError = this.processTransportError ?? error;
+      await this.forceStop();
       this.state = "error";
-      throw error;
+      throw startupError;
     }
   }
   /**
@@ -699,7 +726,7 @@ class CopilotClient {
           lastError = error instanceof Error ? error : new Error(String(error));
           if (attempt < 3) {
             const delay = 100 * Math.pow(2, attempt - 1);
-            await new Promise((resolve) => setTimeout(resolve, delay));
+            await new Promise((resolve2) => setTimeout(resolve2, delay));
           }
         }
       }
@@ -766,8 +793,8 @@ class CopilotClient {
       this.socket = null;
       try {
         if (!socket.destroyed) {
-          await new Promise((resolve) => {
-            socket.once("close", () => resolve());
+          await new Promise((resolve2) => {
+            socket.once("close", () => resolve2());
             socket.end();
           });
         }
@@ -1573,8 +1600,8 @@ class CopilotClient {
   async listModels() {
     await this.modelsCacheLock;
     let resolveLock;
-    this.modelsCacheLock = new Promise((resolve) => {
-      resolveLock = resolve;
+    this.modelsCacheLock = new Promise((resolve2) => {
+      resolveLock = resolve2;
     });
     try {
       if (this.modelsCache !== null) {
@@ -1890,7 +1917,7 @@ class CopilotClient {
    * Start the CLI server process
    */
   async startCLIServer() {
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       this.stderrBuffer = "";
       const args = [...this.connectionExtraArgs, "--headless", "--no-auto-update"];
       if (this.options.logLevel) {
@@ -1951,7 +1978,7 @@ class CopilotClient {
       let resolved = false;
       if (this.connectionConfig.kind === "stdio") {
         resolved = true;
-        resolve();
+        resolve2();
       } else {
         this.cliProcess.stdout?.on("data", (data) => {
           stdout += data.toString();
@@ -1959,7 +1986,7 @@ class CopilotClient {
           if (match && !resolved) {
             this.runtimePort = parseInt(match[1], 10);
             resolved = true;
-            resolve();
+            resolve2();
           }
         });
       }
@@ -1991,26 +2018,27 @@ stderr: ${stderrOutput}`
       });
       this.processExitPromise = new Promise((_, rejectProcessExit) => {
         this.cliProcess.on("exit", (code) => {
-          setTimeout(() => {
-            const stderrOutput = this.stderrBuffer.trim();
-            if (stderrOutput) {
-              rejectProcessExit(
-                new Error(
-                  `CLI server exited with code ${code}
+          if (this.messageWriter) {
+            this.messageWriter.suppressWriteErrors = true;
+          }
+          const stderrOutput = this.stderrBuffer.trim();
+          if (stderrOutput) {
+            rejectProcessExit(
+              new Error(
+                `CLI server exited with code ${code}
 stderr: ${stderrOutput}`
-                )
-              );
-            } else {
-              rejectProcessExit(
-                new Error(`CLI server exited unexpectedly with code ${code}`)
-              );
-            }
-          }, 50);
+              )
+            );
+          } else {
+            rejectProcessExit(
+              new Error(`CLI server exited unexpectedly with code ${code}`)
+            );
+          }
         });
       });
       this.processExitPromise.catch(() => {
       });
-      this.cliProcess.on("exit", (code) => {
+      this.cliProcess.on("close", (code) => {
         if (!resolved) {
           resolved = true;
           const stderrOutput = this.stderrBuffer.trim();
@@ -2052,7 +2080,13 @@ stderr: ${stderrOutput}`
   }
   /** Starts the in-process FFI runtime with SDK-managed typed options. */
   async startInProcessFfi() {
-    const entrypoint = this.resolveCliPathForFfi();
+    const explicitEntrypoint = this.resolvedEnv.COPILOT_CLI_PATH;
+    const runtimeLibrary = explicitEntrypoint ? (0, import_node_path.join)(
+      (0, import_node_path.dirname)((0, import_node_path.resolve)(explicitEntrypoint)),
+      "prebuilds",
+      CopilotClient.getNapiPrebuildsFolder(explicitEntrypoint),
+      "runtime.node"
+    ) : (0, import_node_path.join)((0, import_node_path.dirname)(getBundledRuntimePath()), "runtime.node");
     const { FfiRuntimeHost } = await import("./ffiRuntimeHost.js");
     const environment = {};
     if (this.options.gitHubToken) {
@@ -2080,12 +2114,7 @@ stderr: ${stderrOutput}`
     if (this.options.enableRemoteSessions) {
       args.push("--remote");
     }
-    const host = FfiRuntimeHost.create(
-      entrypoint,
-      CopilotClient.getNapiPrebuildsFolder(entrypoint),
-      environment,
-      args
-    );
+    const host = FfiRuntimeHost.create(runtimeLibrary, explicitEntrypoint, environment, args);
     this.ffiHost = host;
     await host.start();
   }
@@ -2105,19 +2134,6 @@ stderr: ${stderrOutput}`
     this.attachConnectionHandlers();
     this.connection.listen();
   }
-  /**
-   * Resolves the CLI entrypoint used for in-process FFI hosting: `COPILOT_CLI_PATH`
-   * when set, otherwise the bundled platform-package entrypoint.
-   */
-  resolveCliPathForFfi() {
-    return this.resolvedEnv.COPILOT_CLI_PATH ?? getBundledCliPath();
-  }
-  /**
-   * Returns the napi prebuilds folder name for the current host — the
-   * `<node-platform>-<arch>` convention (e.g. `win32-x64`, `darwin-arm64`,
-   * `linux-x64`, `linuxmusl-x64`) under which the runtime ships
-   * `prebuilds/<folder>/runtime.node`.
-   */
   static getNapiPrebuildsFolder(entrypoint) {
     const arch = process.arch;
     if (arch !== "x64" && arch !== "arm64") {
@@ -2153,6 +2169,11 @@ stderr: ${stderrOutput}`
       }
       this.state = "error";
       const reason = err instanceof Error ? err.stack ?? err.message : String(err);
+      const stderrOutput = this.stderrBuffer.trim();
+      this.processTransportError = new Error(
+        `CLI server connection failed: ${reason}${stderrOutput ? `
+stderr: ${stderrOutput}` : ""}`
+      );
       this.logDebug(`stdin pipe error: ${reason}`);
       try {
         this.connection?.dispose();
@@ -2189,7 +2210,7 @@ stderr: ${stderrOutput}`
     if (!this.runtimePort) {
       throw new Error("Server port not available");
     }
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       this.socket = new import_node_net.Socket();
       const connectionTimeout = setTimeout(() => {
         this.socket?.destroy();
@@ -2204,7 +2225,7 @@ stderr: ${stderrOutput}`
         );
         this.attachConnectionHandlers();
         this.connection.listen();
-        resolve();
+        resolve2();
       });
       this.socket.on("error", (error) => {
         clearTimeout(connectionTimeout);

package/dist/cjs/ffiRuntimeHost.js

@@ -85,7 +85,7 @@ function loadLibrary(libraryPath) {
   return loadedLibrary;
 }
 function buildArgvJson(cliEntrypoint, args) {
-  const argv = cliEntrypoint.toLowerCase().endsWith(".js") ? ["node", cliEntrypoint, "--embedded-host", "--no-auto-update"] : [cliEntrypoint, "--embedded-host", "--no-auto-update"];
+  const argv = cliEntrypoint ? cliEntrypoint.toLowerCase().endsWith(".js") ? ["node", cliEntrypoint, "--embedded-host", "--no-auto-update"] : [cliEntrypoint, "--embedded-host", "--no-auto-update"] : [];
   argv.push(...args);
   return Buffer.from(JSON.stringify(argv), "utf8");
 }
@@ -140,24 +140,21 @@ class FfiRuntimeHost {
   /** The stream JSON-RPC writes client→server frames to. */
   sendStream;
   /**
-   * Resolves the cdylib next to the given CLI entrypoint and prepares the FFI host.
-   * The cdylib is resolved as `prebuilds/<prebuildsFolder>/runtime.node` relative to
-   * the entrypoint directory (the napi-rs `<node-platform>-<arch>` layout, e.g.
-   * `linux-x64`). Throws if it cannot be found.
+   * Loads the runtime cdylib at the given path and prepares the FFI host.
    */
-  static create(cliEntrypoint, prebuildsFolder, environment, args) {
-    const fullEntrypoint = (0, import_node_path.resolve)(cliEntrypoint);
-    const distDir = (0, import_node_path.dirname)(fullEntrypoint);
-    const libraryPath = (0, import_node_path.join)(distDir, "prebuilds", prebuildsFolder, "runtime.node");
-    if (!(0, import_node_fs.existsSync)(libraryPath)) {
-      throw new Error(`FFI runtime library not found. Looked for '${libraryPath}'.`);
+  static create(libraryPath, cliEntrypoint, environment, args) {
+    const fullLibraryPath = (0, import_node_path.resolve)(libraryPath);
+    if (!(0, import_node_fs.existsSync)(fullLibraryPath)) {
+      throw new Error(`FFI runtime library not found at '${fullLibraryPath}'.`);
     }
-    return new FfiRuntimeHost(libraryPath, fullEntrypoint, environment, args);
+    return new FfiRuntimeHost(
+      fullLibraryPath,
+      cliEntrypoint ? (0, import_node_path.resolve)(cliEntrypoint) : void 0,
+      environment,
+      args
+    );
   }
-  /**
-   * Starts the in-process runtime: spawns the CLI worker via the native host,
-   * waits for readiness, and opens the FFI JSON-RPC connection.
-   */
+  /** Starts the in-process Rust runtime and opens the FFI JSON-RPC connection. */
   async start() {
     const argvJson = buildArgvJson(this.cliEntrypoint, this.args);
     const envJson = buildEnvJson(this.environment);
@@ -177,9 +174,7 @@ class FfiRuntimeHost {
       );
     });
     if (!this.serverId) {
-      throw new Error(
-        `copilot_runtime_host_start failed (library '${this.libraryPath}', entrypoint '${this.cliEntrypoint}').`
-      );
+      throw new Error(`copilot_runtime_host_start failed (library '${this.libraryPath}').`);
     }
     this.outboundCallback = import_koffi.default.register(
       (_userData, bytesPtr, bytesLen) => this.feedInbound(bytesPtr, bytesLen),

package/dist/cjs/runtimeArtifacts.js

@@ -0,0 +1,159 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var runtimeArtifacts_exports = {};
+__export(runtimeArtifacts_exports, {
+  defaultRuntimeCacheRoot: () => defaultRuntimeCacheRoot,
+  materializeRuntimeBundle: () => materializeRuntimeBundle
+});
+module.exports = __toCommonJS(runtimeArtifacts_exports);
+var import_node_crypto = require("node:crypto");
+var import_node_fs = require("node:fs");
+var import_node_os = require("node:os");
+var import_node_path = require("node:path");
+const EXCLUDED_TOP_LEVEL = /* @__PURE__ */ new Set([
+  "app.js",
+  "assets",
+  "changelog.json",
+  "copilot",
+  "copilot.exe",
+  "copilot-sdk",
+  "foundry-local-sdk",
+  "index.js",
+  "LICENSE.md",
+  "napi-oop-runtime",
+  "npm-loader.js",
+  "package.json",
+  "preloads",
+  "pvrecorder",
+  "queries",
+  "README.md",
+  "sdk",
+  "sea-loader.js",
+  "webview"
+]);
+function validateFile(path, label) {
+  if (!(0, import_node_fs.existsSync)(path)) {
+    throw new Error(`${label} not found at ${path}.`);
+  }
+  if ((0, import_node_fs.statSync)(path).size === 0) {
+    throw new Error(`${label} at ${path} is empty.`);
+  }
+}
+function validateRuntimeBundle(wrapper, runtimeNode) {
+  validateFile(wrapper, "Copilot runtime wrapper");
+  validateFile(runtimeNode, "Copilot runtime.node");
+}
+function isExcluded(relativePath) {
+  const parts = relativePath.split(import_node_path.sep);
+  const topLevel = parts[0];
+  const fileName = parts.at(-1) ?? "";
+  return EXCLUDED_TOP_LEVEL.has(topLevel) || /^tree-sitter.*\.wasm$/.test(topLevel) || /^voice-.*\.js$/.test(topLevel) || fileName === "cli-native.node" || parts.includes("mediaremote-adapter") || fileName.startsWith("copilot-runtime-bin");
+}
+function collectRuntimeAssets(sources) {
+  const assets = [];
+  const visit = (directory) => {
+    for (const entry of (0, import_node_fs.readdirSync)(directory, { withFileTypes: true })) {
+      const source = (0, import_node_path.join)(directory, entry.name);
+      const sourceRelative = (0, import_node_path.relative)(sources.packageRoot, source);
+      if (isExcluded(sourceRelative)) {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        visit(source);
+        continue;
+      }
+      if (!entry.isFile() && !entry.isSymbolicLink()) {
+        continue;
+      }
+      const parts = sourceRelative.split(import_node_path.sep);
+      let relativePath = sourceRelative;
+      if (parts[0] === "prebuilds") {
+        if (parts[1] !== sources.platform || parts.length < 3) {
+          continue;
+        }
+        relativePath = parts.slice(2).join(import_node_path.sep);
+      }
+      assets.push({ source, relativePath });
+    }
+  };
+  visit(sources.packageRoot);
+  return assets.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+function sourceFingerprint(assets) {
+  const hash = (0, import_node_crypto.createHash)("sha256");
+  for (const asset of assets) {
+    const stat = (0, import_node_fs.lstatSync)(asset.source);
+    hash.update(asset.relativePath).update("\0");
+    hash.update(`${stat.size}:${stat.mtimeMs}`).update("\0");
+  }
+  return hash.digest("hex").slice(0, 20);
+}
+function makeExecutable(path) {
+  if (process.platform === "win32") {
+    return;
+  }
+  const mode = (0, import_node_fs.statSync)(path).mode;
+  if ((mode & 73) === 0) {
+    (0, import_node_fs.chmodSync)(path, mode | 73);
+  }
+}
+function defaultRuntimeCacheRoot(platform = process.platform, home = (0, import_node_os.homedir)(), environment = process.env) {
+  const cacheDirectory = platform === "win32" ? environment.LOCALAPPDATA ?? (0, import_node_path.join)(home, "AppData", "Local") : platform === "darwin" ? (0, import_node_path.join)(home, "Library", "Caches") : environment.XDG_CACHE_HOME ?? (0, import_node_path.join)(home, ".cache");
+  return (0, import_node_path.join)(cacheDirectory, "github-copilot-sdk", "runtime");
+}
+function materializeRuntimeBundle(sources, cacheRoot = defaultRuntimeCacheRoot()) {
+  const assets = collectRuntimeAssets(sources);
+  const wrapperName = process.platform === "win32" ? "copilot-runtime.exe" : "copilot-runtime";
+  const sourceWrapper = assets.find((asset) => asset.relativePath === wrapperName)?.source;
+  const sourceRuntimeNode = assets.find((asset) => asset.relativePath === "runtime.node")?.source;
+  validateRuntimeBundle(sourceWrapper ?? "", sourceRuntimeNode ?? "");
+  const installDir = (0, import_node_path.join)(cacheRoot, `${sources.platform}-${sourceFingerprint(assets)}`);
+  const installedWrapper = (0, import_node_path.join)(installDir, wrapperName);
+  const installedRuntimeNode = (0, import_node_path.join)(installDir, "runtime.node");
+  if ((0, import_node_fs.existsSync)(installDir)) {
+    validateRuntimeBundle(installedWrapper, installedRuntimeNode);
+    makeExecutable(installedWrapper);
+    return installedWrapper;
+  }
+  (0, import_node_fs.mkdirSync)(cacheRoot, { recursive: true });
+  const stagingDir = (0, import_node_fs.mkdtempSync)((0, import_node_path.join)(cacheRoot, ".runtime-"));
+  try {
+    for (const asset of assets) {
+      const destination = (0, import_node_path.join)(stagingDir, asset.relativePath);
+      (0, import_node_fs.mkdirSync)((0, import_node_path.dirname)(destination), { recursive: true });
+      (0, import_node_fs.copyFileSync)(asset.source, destination);
+    }
+    const stagedWrapper = (0, import_node_path.join)(stagingDir, wrapperName);
+    makeExecutable(stagedWrapper);
+    (0, import_node_fs.renameSync)(stagingDir, installDir);
+  } catch (error) {
+    if (!(0, import_node_fs.existsSync)(installDir)) {
+      throw error;
+    }
+    validateRuntimeBundle(installedWrapper, installedRuntimeNode);
+  } finally {
+    (0, import_node_fs.rmSync)(stagingDir, { recursive: true, force: true });
+  }
+  return installedWrapper;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  defaultRuntimeCacheRoot,
+  materializeRuntimeBundle
+});

package/dist/client.d.ts

@@ -33,6 +33,7 @@ export declare class CopilotClient {
     private _rpc;
     private _internalRpc;
     private processExitPromise;
+    private processTransportError;
     private negotiatedProtocolVersion;
     /** Connection-level session filesystem config, set via constructor option. */
     private sessionFsConfig;
@@ -452,17 +453,6 @@ export declare class CopilotClient {
      * reusing the same `vscode-jsonrpc` framing as the stdio transport.
      */
     private connectViaFfi;
-    /**
-     * Resolves the CLI entrypoint used for in-process FFI hosting: `COPILOT_CLI_PATH`
-     * when set, otherwise the bundled platform-package entrypoint.
-     */
-    private resolveCliPathForFfi;
-    /**
-     * Returns the napi prebuilds folder name for the current host — the
-     * `<node-platform>-<arch>` convention (e.g. `win32-x64`, `darwin-arm64`,
-     * `linux-x64`, `linuxmusl-x64`) under which the runtime ships
-     * `prebuilds/<folder>/runtime.node`.
-     */
     private static getNapiPrebuildsFolder;
     private static isMusl;
     /**

package/dist/client.js

@@ -3,7 +3,7 @@ import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
 import { createRequire } from "node:module";
 import { Socket } from "node:net";
-import { dirname, isAbsolute, join } from "node:path";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
   createMessageConnection,
@@ -20,6 +20,7 @@ import {
 } from "./generated/rpc.js";
 import { getSdkProtocolVersion } from "./sdkProtocolVersion.js";
 import { CopilotSession } from "./session.js";
+import { materializeRuntimeBundle } from "./runtimeArtifacts.js";
 import { createSessionFsAdapter } from "./sessionFsProvider.js";
 import { createCopilotRequestAdapter } from "./copilotRequestHandler.js";
 import { getTraceContext } from "./telemetry.js";
@@ -49,7 +50,7 @@ async function waitForChildExit(child, timeoutMs) {
   if (child.exitCode != null || child.signalCode != null) {
     return true;
   }
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     let timeout;
     let settled = false;
     const onExit = () => {
@@ -58,7 +59,7 @@ async function waitForChildExit(child, timeoutMs) {
       }
       settled = true;
       clearTimeout(timeout);
-      resolve(true);
+      resolve2(true);
     };
     timeout = setTimeout(() => {
       if (settled) {
@@ -66,7 +67,7 @@ async function waitForChildExit(child, timeoutMs) {
       }
       settled = true;
       child.off("exit", onExit);
-      resolve(false);
+      resolve2(false);
     }, timeoutMs);
     child.once("exit", onExit);
     if (child.exitCode != null || child.signalCode != null) {
@@ -189,14 +190,17 @@ function getCliPlatformPackageNames() {
   const variants = process.platform === "linux" ? ["linux", "linuxmusl"] : [process.platform];
   return variants.map((variant) => `@github/copilot-${variant}-${arch}`);
 }
-function getBundledCliPath() {
+function getBundledCliPackage() {
   const packageNames = getCliPlatformPackageNames();
   if (typeof import.meta.resolve === "function") {
     for (const packageName of packageNames) {
       try {
         const packageEntryUrl = import.meta.resolve(packageName);
         const packageEntryPath = fileURLToPath(packageEntryUrl);
-        return join(dirname(packageEntryPath), "index.js");
+        return {
+          root: dirname(packageEntryPath),
+          platform: packageName.slice("@github/copilot-".length)
+        };
       } catch {
       }
     }
@@ -208,9 +212,13 @@ function getBundledCliPath() {
   const searchPaths = req.resolve.paths("@github/copilot") ?? [];
   for (const base of searchPaths) {
     for (const packageName of packageNames) {
-      const candidate = join(base, ...packageName.split("/"), "index.js");
+      const root = join(base, ...packageName.split("/"));
+      const candidate = join(root, "index.js");
       if (existsSync(candidate)) {
-        return candidate;
+        return {
+          root,
+          platform: packageName.slice("@github/copilot-".length)
+        };
       }
     }
   }
@@ -218,6 +226,13 @@ function getBundledCliPath() {
     `Could not find a @github/copilot platform package (tried ${packageNames.join(", ")}). Searched ${searchPaths.length} paths. Ensure @github/copilot is installed, or pass cliPath/cliUrl to CopilotClient.`
   );
 }
+function getBundledRuntimePath() {
+  const bundled = getBundledCliPackage();
+  return materializeRuntimeBundle({
+    packageRoot: bundled.root,
+    platform: bundled.platform
+  });
+}
 class TeardownResilientStreamMessageWriter extends StreamMessageWriter {
   suppressWriteErrors = false;
   async write(msg) {
@@ -264,6 +279,7 @@ class CopilotClient {
   _internalRpc = null;
   processExitPromise = null;
   // Rejects when CLI process exits
+  processTransportError = null;
   negotiatedProtocolVersion = null;
   /** Connection-level session filesystem config, set via constructor option. */
   sessionFsConfig = null;
@@ -430,7 +446,14 @@ class CopilotClient {
     const connEnv = conn.kind === "stdio" || conn.kind === "tcp" ? conn.env : void 0;
     const effectiveEnv = connEnv ?? options.env ?? process.env;
     this.resolvedEnv = effectiveEnv;
-    this.resolvedCliPath = conn.kind === "stdio" || conn.kind === "tcp" ? conn.path ?? effectiveEnv.COPILOT_CLI_PATH ?? getBundledCliPath() : void 0;
+    if (conn.kind === "stdio" || conn.kind === "tcp") {
+      const explicitCliPath = conn.path ?? effectiveEnv.COPILOT_CLI_PATH;
+      if (explicitCliPath) {
+        this.resolvedCliPath = explicitCliPath;
+      } else {
+        this.resolvedCliPath = getBundledRuntimePath();
+      }
+    }
     const connArgs = conn.kind === "stdio" || conn.kind === "tcp" ? conn.args ?? [] : [];
     this.connectionExtraArgs = [...connArgs];
     this.options = {
@@ -598,6 +621,8 @@ class CopilotClient {
     if (this.state === "connected") {
       return;
     }
+    this.forceStopping = false;
+    this.processTransportError = null;
     this.state = "connecting";
     try {
       if (this.connectionConfig.kind === "inprocess") {
@@ -630,8 +655,10 @@ class CopilotClient {
       }
       this.state = "connected";
     } catch (error) {
+      const startupError = this.processTransportError ?? error;
+      await this.forceStop();
       this.state = "error";
-      throw error;
+      throw startupError;
     }
   }
   /**
@@ -676,7 +703,7 @@ class CopilotClient {
           lastError = error instanceof Error ? error : new Error(String(error));
           if (attempt < 3) {
             const delay = 100 * Math.pow(2, attempt - 1);
-            await new Promise((resolve) => setTimeout(resolve, delay));
+            await new Promise((resolve2) => setTimeout(resolve2, delay));
           }
         }
       }
@@ -743,8 +770,8 @@ class CopilotClient {
       this.socket = null;
       try {
         if (!socket.destroyed) {
-          await new Promise((resolve) => {
-            socket.once("close", () => resolve());
+          await new Promise((resolve2) => {
+            socket.once("close", () => resolve2());
             socket.end();
           });
         }
@@ -1550,8 +1577,8 @@ class CopilotClient {
   async listModels() {
     await this.modelsCacheLock;
     let resolveLock;
-    this.modelsCacheLock = new Promise((resolve) => {
-      resolveLock = resolve;
+    this.modelsCacheLock = new Promise((resolve2) => {
+      resolveLock = resolve2;
     });
     try {
       if (this.modelsCache !== null) {
@@ -1867,7 +1894,7 @@ class CopilotClient {
    * Start the CLI server process
    */
   async startCLIServer() {
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       this.stderrBuffer = "";
       const args = [...this.connectionExtraArgs, "--headless", "--no-auto-update"];
       if (this.options.logLevel) {
@@ -1928,7 +1955,7 @@ class CopilotClient {
       let resolved = false;
       if (this.connectionConfig.kind === "stdio") {
         resolved = true;
-        resolve();
+        resolve2();
       } else {
         this.cliProcess.stdout?.on("data", (data) => {
           stdout += data.toString();
@@ -1936,7 +1963,7 @@ class CopilotClient {
           if (match && !resolved) {
             this.runtimePort = parseInt(match[1], 10);
             resolved = true;
-            resolve();
+            resolve2();
           }
         });
       }
@@ -1968,26 +1995,27 @@ stderr: ${stderrOutput}`
       });
       this.processExitPromise = new Promise((_, rejectProcessExit) => {
         this.cliProcess.on("exit", (code) => {
-          setTimeout(() => {
-            const stderrOutput = this.stderrBuffer.trim();
-            if (stderrOutput) {
-              rejectProcessExit(
-                new Error(
-                  `CLI server exited with code ${code}
+          if (this.messageWriter) {
+            this.messageWriter.suppressWriteErrors = true;
+          }
+          const stderrOutput = this.stderrBuffer.trim();
+          if (stderrOutput) {
+            rejectProcessExit(
+              new Error(
+                `CLI server exited with code ${code}
 stderr: ${stderrOutput}`
-                )
-              );
-            } else {
-              rejectProcessExit(
-                new Error(`CLI server exited unexpectedly with code ${code}`)
-              );
-            }
-          }, 50);
+              )
+            );
+          } else {
+            rejectProcessExit(
+              new Error(`CLI server exited unexpectedly with code ${code}`)
+            );
+          }
         });
       });
       this.processExitPromise.catch(() => {
       });
-      this.cliProcess.on("exit", (code) => {
+      this.cliProcess.on("close", (code) => {
         if (!resolved) {
           resolved = true;
           const stderrOutput = this.stderrBuffer.trim();
@@ -2029,7 +2057,13 @@ stderr: ${stderrOutput}`
   }
   /** Starts the in-process FFI runtime with SDK-managed typed options. */
   async startInProcessFfi() {
-    const entrypoint = this.resolveCliPathForFfi();
+    const explicitEntrypoint = this.resolvedEnv.COPILOT_CLI_PATH;
+    const runtimeLibrary = explicitEntrypoint ? join(
+      dirname(resolve(explicitEntrypoint)),
+      "prebuilds",
+      CopilotClient.getNapiPrebuildsFolder(explicitEntrypoint),
+      "runtime.node"
+    ) : join(dirname(getBundledRuntimePath()), "runtime.node");
     const { FfiRuntimeHost } = await import("./ffiRuntimeHost.js");
     const environment = {};
     if (this.options.gitHubToken) {
@@ -2057,12 +2091,7 @@ stderr: ${stderrOutput}`
     if (this.options.enableRemoteSessions) {
       args.push("--remote");
     }
-    const host = FfiRuntimeHost.create(
-      entrypoint,
-      CopilotClient.getNapiPrebuildsFolder(entrypoint),
-      environment,
-      args
-    );
+    const host = FfiRuntimeHost.create(runtimeLibrary, explicitEntrypoint, environment, args);
     this.ffiHost = host;
     await host.start();
   }
@@ -2082,19 +2111,6 @@ stderr: ${stderrOutput}`
     this.attachConnectionHandlers();
     this.connection.listen();
   }
-  /**
-   * Resolves the CLI entrypoint used for in-process FFI hosting: `COPILOT_CLI_PATH`
-   * when set, otherwise the bundled platform-package entrypoint.
-   */
-  resolveCliPathForFfi() {
-    return this.resolvedEnv.COPILOT_CLI_PATH ?? getBundledCliPath();
-  }
-  /**
-   * Returns the napi prebuilds folder name for the current host — the
-   * `<node-platform>-<arch>` convention (e.g. `win32-x64`, `darwin-arm64`,
-   * `linux-x64`, `linuxmusl-x64`) under which the runtime ships
-   * `prebuilds/<folder>/runtime.node`.
-   */
   static getNapiPrebuildsFolder(entrypoint) {
     const arch = process.arch;
     if (arch !== "x64" && arch !== "arm64") {
@@ -2130,6 +2146,11 @@ stderr: ${stderrOutput}`
       }
       this.state = "error";
       const reason = err instanceof Error ? err.stack ?? err.message : String(err);
+      const stderrOutput = this.stderrBuffer.trim();
+      this.processTransportError = new Error(
+        `CLI server connection failed: ${reason}${stderrOutput ? `
+stderr: ${stderrOutput}` : ""}`
+      );
       this.logDebug(`stdin pipe error: ${reason}`);
       try {
         this.connection?.dispose();
@@ -2166,7 +2187,7 @@ stderr: ${stderrOutput}`
     if (!this.runtimePort) {
       throw new Error("Server port not available");
     }
-    return new Promise((resolve, reject) => {
+    return new Promise((resolve2, reject) => {
       this.socket = new Socket();
       const connectionTimeout = setTimeout(() => {
         this.socket?.destroy();
@@ -2181,7 +2202,7 @@ stderr: ${stderrOutput}`
         );
         this.attachConnectionHandlers();
         this.connection.listen();
-        resolve();
+        resolve2();
       });
       this.socket.on("error", (error) => {
         clearTimeout(connectionTimeout);

package/dist/ffiRuntimeHost.d.ts

@@ -16,16 +16,10 @@ export declare class FfiRuntimeHost {
     readonly sendStream: Writable;
     private constructor();
     /**
-     * Resolves the cdylib next to the given CLI entrypoint and prepares the FFI host.
-     * The cdylib is resolved as `prebuilds/<prebuildsFolder>/runtime.node` relative to
-     * the entrypoint directory (the napi-rs `<node-platform>-<arch>` layout, e.g.
-     * `linux-x64`). Throws if it cannot be found.
-     */
-    static create(cliEntrypoint: string, prebuildsFolder: string, environment: Record<string, string | undefined> | undefined, args: readonly string[]): FfiRuntimeHost;
-    /**
-     * Starts the in-process runtime: spawns the CLI worker via the native host,
-     * waits for readiness, and opens the FFI JSON-RPC connection.
+     * Loads the runtime cdylib at the given path and prepares the FFI host.
      */
+    static create(libraryPath: string, cliEntrypoint: string | undefined, environment: Record<string, string | undefined> | undefined, args: readonly string[]): FfiRuntimeHost;
+    /** Starts the in-process Rust runtime and opens the FFI JSON-RPC connection. */
     start(): Promise<void>;
     private writeFrame;
     /**

package/dist/ffiRuntimeHost.js

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import koffi from "koffi";
-import { dirname, join, resolve } from "node:path";
+import { resolve } from "node:path";
 import { PassThrough, Writable } from "node:stream";
 const SYMBOL_PREFIX = "copilot_runtime_";
 const KEEP_ALIVE_INTERVAL_MS = 1 << 30;
@@ -52,7 +52,7 @@ function loadLibrary(libraryPath) {
   return loadedLibrary;
 }
 function buildArgvJson(cliEntrypoint, args) {
-  const argv = cliEntrypoint.toLowerCase().endsWith(".js") ? ["node", cliEntrypoint, "--embedded-host", "--no-auto-update"] : [cliEntrypoint, "--embedded-host", "--no-auto-update"];
+  const argv = cliEntrypoint ? cliEntrypoint.toLowerCase().endsWith(".js") ? ["node", cliEntrypoint, "--embedded-host", "--no-auto-update"] : [cliEntrypoint, "--embedded-host", "--no-auto-update"] : [];
   argv.push(...args);
   return Buffer.from(JSON.stringify(argv), "utf8");
 }
@@ -107,24 +107,21 @@ class FfiRuntimeHost {
   /** The stream JSON-RPC writes client→server frames to. */
   sendStream;
   /**
-   * Resolves the cdylib next to the given CLI entrypoint and prepares the FFI host.
-   * The cdylib is resolved as `prebuilds/<prebuildsFolder>/runtime.node` relative to
-   * the entrypoint directory (the napi-rs `<node-platform>-<arch>` layout, e.g.
-   * `linux-x64`). Throws if it cannot be found.
+   * Loads the runtime cdylib at the given path and prepares the FFI host.
    */
-  static create(cliEntrypoint, prebuildsFolder, environment, args) {
-    const fullEntrypoint = resolve(cliEntrypoint);
-    const distDir = dirname(fullEntrypoint);
-    const libraryPath = join(distDir, "prebuilds", prebuildsFolder, "runtime.node");
-    if (!existsSync(libraryPath)) {
-      throw new Error(`FFI runtime library not found. Looked for '${libraryPath}'.`);
+  static create(libraryPath, cliEntrypoint, environment, args) {
+    const fullLibraryPath = resolve(libraryPath);
+    if (!existsSync(fullLibraryPath)) {
+      throw new Error(`FFI runtime library not found at '${fullLibraryPath}'.`);
     }
-    return new FfiRuntimeHost(libraryPath, fullEntrypoint, environment, args);
+    return new FfiRuntimeHost(
+      fullLibraryPath,
+      cliEntrypoint ? resolve(cliEntrypoint) : void 0,
+      environment,
+      args
+    );
   }
-  /**
-   * Starts the in-process runtime: spawns the CLI worker via the native host,
-   * waits for readiness, and opens the FFI JSON-RPC connection.
-   */
+  /** Starts the in-process Rust runtime and opens the FFI JSON-RPC connection. */
   async start() {
     const argvJson = buildArgvJson(this.cliEntrypoint, this.args);
     const envJson = buildEnvJson(this.environment);
@@ -144,9 +141,7 @@ class FfiRuntimeHost {
       );
     });
     if (!this.serverId) {
-      throw new Error(
-        `copilot_runtime_host_start failed (library '${this.libraryPath}', entrypoint '${this.cliEntrypoint}').`
-      );
+      throw new Error(`copilot_runtime_host_start failed (library '${this.libraryPath}').`);
     }
     this.outboundCallback = koffi.register(
       (_userData, bytesPtr, bytesLen) => this.feedInbound(bytesPtr, bytesLen),

package/dist/runtimeArtifacts.d.ts

@@ -0,0 +1,6 @@
+export interface RuntimeArtifactSources {
+    packageRoot: string;
+    platform: string;
+}
+export declare function defaultRuntimeCacheRoot(platform?: NodeJS.Platform, home?: string, environment?: NodeJS.ProcessEnv): string;
+export declare function materializeRuntimeBundle(sources: RuntimeArtifactSources, cacheRoot?: string): string;

package/dist/runtimeArtifacts.js

@@ -0,0 +1,145 @@
+import { createHash } from "node:crypto";
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, relative, sep } from "node:path";
+const EXCLUDED_TOP_LEVEL = /* @__PURE__ */ new Set([
+  "app.js",
+  "assets",
+  "changelog.json",
+  "copilot",
+  "copilot.exe",
+  "copilot-sdk",
+  "foundry-local-sdk",
+  "index.js",
+  "LICENSE.md",
+  "napi-oop-runtime",
+  "npm-loader.js",
+  "package.json",
+  "preloads",
+  "pvrecorder",
+  "queries",
+  "README.md",
+  "sdk",
+  "sea-loader.js",
+  "webview"
+]);
+function validateFile(path, label) {
+  if (!existsSync(path)) {
+    throw new Error(`${label} not found at ${path}.`);
+  }
+  if (statSync(path).size === 0) {
+    throw new Error(`${label} at ${path} is empty.`);
+  }
+}
+function validateRuntimeBundle(wrapper, runtimeNode) {
+  validateFile(wrapper, "Copilot runtime wrapper");
+  validateFile(runtimeNode, "Copilot runtime.node");
+}
+function isExcluded(relativePath) {
+  const parts = relativePath.split(sep);
+  const topLevel = parts[0];
+  const fileName = parts.at(-1) ?? "";
+  return EXCLUDED_TOP_LEVEL.has(topLevel) || /^tree-sitter.*\.wasm$/.test(topLevel) || /^voice-.*\.js$/.test(topLevel) || fileName === "cli-native.node" || parts.includes("mediaremote-adapter") || fileName.startsWith("copilot-runtime-bin");
+}
+function collectRuntimeAssets(sources) {
+  const assets = [];
+  const visit = (directory) => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const source = join(directory, entry.name);
+      const sourceRelative = relative(sources.packageRoot, source);
+      if (isExcluded(sourceRelative)) {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        visit(source);
+        continue;
+      }
+      if (!entry.isFile() && !entry.isSymbolicLink()) {
+        continue;
+      }
+      const parts = sourceRelative.split(sep);
+      let relativePath = sourceRelative;
+      if (parts[0] === "prebuilds") {
+        if (parts[1] !== sources.platform || parts.length < 3) {
+          continue;
+        }
+        relativePath = parts.slice(2).join(sep);
+      }
+      assets.push({ source, relativePath });
+    }
+  };
+  visit(sources.packageRoot);
+  return assets.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+function sourceFingerprint(assets) {
+  const hash = createHash("sha256");
+  for (const asset of assets) {
+    const stat = lstatSync(asset.source);
+    hash.update(asset.relativePath).update("\0");
+    hash.update(`${stat.size}:${stat.mtimeMs}`).update("\0");
+  }
+  return hash.digest("hex").slice(0, 20);
+}
+function makeExecutable(path) {
+  if (process.platform === "win32") {
+    return;
+  }
+  const mode = statSync(path).mode;
+  if ((mode & 73) === 0) {
+    chmodSync(path, mode | 73);
+  }
+}
+function defaultRuntimeCacheRoot(platform = process.platform, home = homedir(), environment = process.env) {
+  const cacheDirectory = platform === "win32" ? environment.LOCALAPPDATA ?? join(home, "AppData", "Local") : platform === "darwin" ? join(home, "Library", "Caches") : environment.XDG_CACHE_HOME ?? join(home, ".cache");
+  return join(cacheDirectory, "github-copilot-sdk", "runtime");
+}
+function materializeRuntimeBundle(sources, cacheRoot = defaultRuntimeCacheRoot()) {
+  const assets = collectRuntimeAssets(sources);
+  const wrapperName = process.platform === "win32" ? "copilot-runtime.exe" : "copilot-runtime";
+  const sourceWrapper = assets.find((asset) => asset.relativePath === wrapperName)?.source;
+  const sourceRuntimeNode = assets.find((asset) => asset.relativePath === "runtime.node")?.source;
+  validateRuntimeBundle(sourceWrapper ?? "", sourceRuntimeNode ?? "");
+  const installDir = join(cacheRoot, `${sources.platform}-${sourceFingerprint(assets)}`);
+  const installedWrapper = join(installDir, wrapperName);
+  const installedRuntimeNode = join(installDir, "runtime.node");
+  if (existsSync(installDir)) {
+    validateRuntimeBundle(installedWrapper, installedRuntimeNode);
+    makeExecutable(installedWrapper);
+    return installedWrapper;
+  }
+  mkdirSync(cacheRoot, { recursive: true });
+  const stagingDir = mkdtempSync(join(cacheRoot, ".runtime-"));
+  try {
+    for (const asset of assets) {
+      const destination = join(stagingDir, asset.relativePath);
+      mkdirSync(dirname(destination), { recursive: true });
+      copyFileSync(asset.source, destination);
+    }
+    const stagedWrapper = join(stagingDir, wrapperName);
+    makeExecutable(stagedWrapper);
+    renameSync(stagingDir, installDir);
+  } catch (error) {
+    if (!existsSync(installDir)) {
+      throw error;
+    }
+    validateRuntimeBundle(installedWrapper, installedRuntimeNode);
+  } finally {
+    rmSync(stagingDir, { recursive: true, force: true });
+  }
+  return installedWrapper;
+}
+export {
+  defaultRuntimeCacheRoot,
+  materializeRuntimeBundle
+};

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "1.0.13-preview.3",
+  "version": "1.0.13-preview.4",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/cjs/index.js",
   "types": "./dist/index.d.ts",