@github/copilot-sdk 1.0.7-preview.2 → 1.0.7-preview.3

package/README.md

@@ -84,9 +84,11 @@ new CopilotClient(options?: CopilotClientOptions)
 **Options:**
 
 - `connection?: RuntimeConnection` - How to connect to the Copilot runtime. Construct via the factory functions on `RuntimeConnection`:
-    - `RuntimeConnection.forStdio({ path?, args? })` (default) — spawn the runtime and communicate over its stdin/stdout.
-    - `RuntimeConnection.forTcp({ port?, connectionToken?, path?, args? })` — spawn the runtime as a TCP server.
+    - `RuntimeConnection.forStdio({ path?, args?, env? })` (default) — spawn the runtime and communicate over its stdin/stdout.
+    - `RuntimeConnection.forTcp({ port?, connectionToken?, path?, args?, env? })` — spawn the runtime as a TCP server.
     - `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).
 - `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

@@ -395,6 +395,21 @@ class CopilotClient {
         "workingDirectory is not supported with RuntimeConnection.forInProcess(): the in-process transport hosts the runtime in this process, so honoring it would require mutating the shared process-global cwd. Change the host process's working directory before constructing the client instead."
       );
     }
+    if (conn.kind === "inprocess" && options.env !== void 0) {
+      throw new Error(
+        "env is not supported with RuntimeConnection.forInProcess(): the in-process transport loads the native runtime into the shared host process, whose single environment block cannot carry per-client values. Set the variables on the host process environment instead."
+      );
+    }
+    if (conn.kind === "inprocess" && options.telemetry !== void 0) {
+      throw new Error(
+        "telemetry is not supported with RuntimeConnection.forInProcess(): telemetry configuration is lowered to environment variables read by native runtime code running in the shared host process, so per-client telemetry cannot be honored in-process. Configure telemetry via the host process environment, or use a child-process transport."
+      );
+    }
+    if ((conn.kind === "stdio" || conn.kind === "tcp") && conn.env !== void 0 && options.env !== void 0) {
+      throw new Error(
+        "Set environment variables via either the client-level env option or the connection's env (RuntimeConnection.forStdio/forTcp), not both. Prefer the connection-level env for child-process transports."
+      );
+    }
     if (conn.kind === "tcp" && conn.connectionToken !== void 0) {
       if (typeof conn.connectionToken !== "string" || conn.connectionToken.length === 0) {
         throw new Error("connectionToken must be a non-empty string");
@@ -423,7 +438,8 @@ class CopilotClient {
     this.requestHandler = options.requestHandler ?? null;
     this.onGitHubTelemetry = options.onGitHubTelemetry;
     this.setupClientGlobalHandlers();
-    const effectiveEnv = options.env ?? process.env;
+    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;
     const connArgs = conn.kind === "stdio" || conn.kind === "tcp" ? conn.args ?? [] : [];
@@ -1060,6 +1076,7 @@ class CopilotClient {
           skipPermission: tool.skipPermission,
           defer: tool.defer
         })),
+        toolSearch: config.toolSearch,
         canvases: config.canvases?.map((canvas) => canvas.declaration),
         requestCanvasRenderer: config.requestCanvasRenderer,
         requestExtensions: config.requestExtensions,
@@ -1258,6 +1275,7 @@ class CopilotClient {
           skipPermission: tool.skipPermission,
           defer: tool.defer
         })),
+        toolSearch: config.toolSearch,
         canvases: config.canvases?.map((canvas) => canvas.declaration),
         requestCanvasRenderer: config.requestCanvasRenderer,
         requestExtensions: config.requestExtensions,
@@ -1861,21 +1879,42 @@ stderr: ${stderrOutput}`
         return this.connectViaTcp();
     }
   }
-  /**
-   * Start the in-process FFI runtime host: resolve the CLI entrypoint and native
-   * runtime library, then let the native host spawn the CLI worker.
-   *
-   * The worker inherits this host process's ambient environment; per-client options
-   * that lower to environment variables (`env`, `telemetry`, `gitHubToken`,
-   * `baseDirectory`) are intentionally not applied here, because the native runtime
-   * loads into the shared host process and a single env block cannot carry per-client
-   * values. Configure the in-process runtime via the host process environment instead.
-   * See https://github.com/github/copilot-sdk/issues/1934.
-   */
+  /** Starts the in-process FFI runtime with SDK-managed typed options. */
   async startInProcessFfi() {
     const entrypoint = this.resolveCliPathForFfi();
     const { FfiRuntimeHost } = await import("./ffiRuntimeHost.js");
-    const host = FfiRuntimeHost.create(entrypoint, CopilotClient.getNapiPrebuildsFolder());
+    const environment = {};
+    if (this.options.gitHubToken) {
+      environment.COPILOT_SDK_AUTH_TOKEN = this.options.gitHubToken;
+    }
+    if (this.options.baseDirectory) {
+      environment.COPILOT_HOME = this.options.baseDirectory;
+    }
+    if (this.options.mode === "empty") {
+      environment.COPILOT_DISABLE_KEYTAR = "1";
+    }
+    const args = [];
+    if (this.options.logLevel) {
+      args.push("--log-level", this.options.logLevel);
+    }
+    if (this.options.gitHubToken) {
+      args.push("--auth-token-env", "COPILOT_SDK_AUTH_TOKEN");
+    }
+    if (!this.options.useLoggedInUser) {
+      args.push("--no-auto-login");
+    }
+    if (this.options.sessionIdleTimeoutSeconds > 0) {
+      args.push("--session-idle-timeout", this.options.sessionIdleTimeoutSeconds.toString());
+    }
+    if (this.options.enableRemoteSessions) {
+      args.push("--remote");
+    }
+    const host = FfiRuntimeHost.create(
+      entrypoint,
+      CopilotClient.getNapiPrebuildsFolder(entrypoint),
+      environment,
+      args
+    );
     this.ffiHost = host;
     await host.start();
   }
@@ -1905,14 +1944,30 @@ stderr: ${stderrOutput}`
   /**
    * Returns the napi prebuilds folder name for the current host — the
    * `<node-platform>-<arch>` convention (e.g. `win32-x64`, `darwin-arm64`,
-   * `linux-x64`) under which the runtime ships `prebuilds/<folder>/runtime.node`.
+   * `linux-x64`, `linuxmusl-x64`) under which the runtime ships
+   * `prebuilds/<folder>/runtime.node`.
    */
-  static getNapiPrebuildsFolder() {
+  static getNapiPrebuildsFolder(entrypoint) {
     const arch = process.arch;
     if (arch !== "x64" && arch !== "arm64") {
       throw new Error(`Unsupported architecture '${arch}' for in-process FFI hosting.`);
     }
-    return `${process.platform}-${arch}`;
+    let platform = process.platform;
+    if (platform === "linux" && CopilotClient.isMusl(entrypoint)) {
+      platform = "linuxmusl";
+    }
+    return `${platform}-${arch}`;
+  }
+  static isMusl(entrypoint) {
+    if (entrypoint.includes(`copilot-linuxmusl-${process.arch}`)) {
+      return true;
+    }
+    if (entrypoint.includes(`copilot-linux-${process.arch}`)) {
+      return false;
+    }
+    const report = process.report?.getReport();
+    const header = report && "header" in report ? report.header : void 0;
+    return header !== void 0 && header.glibcVersionRuntime === void 0;
   }
   /**
    * Connect to child via stdio pipes

package/dist/cjs/ffiRuntimeHost.js

@@ -84,8 +84,9 @@ function loadLibrary(libraryPath) {
   loadedLibraryPath = libraryPath;
   return loadedLibrary;
 }
-function buildArgvJson(cliEntrypoint) {
+function buildArgvJson(cliEntrypoint, args) {
   const argv = 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");
 }
 function buildEnvJson(environment) {
@@ -104,10 +105,11 @@ function buildEnvJson(environment) {
   return Buffer.from(JSON.stringify(obj), "utf8");
 }
 class FfiRuntimeHost {
-  constructor(libraryPath, cliEntrypoint, environment) {
+  constructor(libraryPath, cliEntrypoint, environment, args) {
     this.libraryPath = libraryPath;
     this.cliEntrypoint = cliEntrypoint;
     this.environment = environment;
+    this.args = args;
     this.lib = loadLibrary(libraryPath);
     this.receiveStream = new import_node_stream.PassThrough();
     this.sendStream = new import_node_stream.Writable({
@@ -126,6 +128,7 @@ class FfiRuntimeHost {
   libraryPath;
   cliEntrypoint;
   environment;
+  args;
   lib;
   serverId = 0;
   connectionId = 0;
@@ -142,21 +145,21 @@ class FfiRuntimeHost {
    * the entrypoint directory (the napi-rs `<node-platform>-<arch>` layout, e.g.
    * `linux-x64`). Throws if it cannot be found.
    */
-  static create(cliEntrypoint, prebuildsFolder, environment) {
+  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}'.`);
     }
-    return new FfiRuntimeHost(libraryPath, fullEntrypoint, environment);
+    return new FfiRuntimeHost(libraryPath, fullEntrypoint, 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.
    */
   async start() {
-    const argvJson = buildArgvJson(this.cliEntrypoint);
+    const argvJson = buildArgvJson(this.cliEntrypoint, this.args);
     const envJson = buildEnvJson(this.environment);
     this.serverId = await new Promise((resolvePromise, rejectPromise) => {
       this.lib.hostStart.async(

package/dist/cjs/generated/rpc.js

@@ -223,7 +223,7 @@ function createServerRpc(connection) {
         /**
          * Registers a new marketplace from a source (owner/repo, URL, or local path).
          *
-         * @param params Marketplace source to register.
+         * @param params Marketplace source and optional working directory for relative-path resolution.
          *
          * @returns Result of registering a new marketplace.
          */
@@ -1231,13 +1231,11 @@ function createSessionRpc(connection, sessionId) {
       /** @experimental */
       apps: {
         /**
-         * Deprecated/obsolete alias for `session.mcp.resources.read`; retained for backwards compatibility with earlier MCP Apps host integrations.
+         * Fetch an MCP resource (typically a `ui://` MCP App bundle, per SEP-1865) from a connected server. Requires the `mcp-apps` session capability.
          *
-         * @param params Deprecated/obsolete MCP Apps alias for `McpResourcesReadRequest`; use `session.mcp.resources.read` instead.
-         *
-         * @returns Deprecated/obsolete MCP Apps alias for `McpResourcesReadResult`; use `session.mcp.resources.read` instead.
+         * @param params MCP server and resource URI to fetch.
          *
-         * @deprecated
+         * @returns Resource contents returned by the MCP server.
          */
         readResource: async (params) => connection.sendRequest("session.mcp.apps.readResource", { sessionId, ...params }),
         /**
@@ -1804,11 +1802,11 @@ function createSessionRpc(connection, sessionId) {
        */
       recordContextChange: async (params) => connection.sendRequest("session.metadata.recordContextChange", { sessionId, ...params }),
       /**
-       * Updates the session's recorded working directory.
+       * Updates the session's working directory. For local sessions the target is validated first (an absolute path that exists on disk) and the permission primary directory is re-based; a rejected validation fails the call before any session state changes.
        *
-       * @param params Absolute path to set as the session's new working directory.
+       * @param params Absolute path to set as the session's new working directory. For local sessions the path must be absolute and exist on disk: it is validated before any session state changes, and a failing validation rejects the call with nothing mutated, persisted, or emitted. Remote sessions record the path as-is.
        *
-       * @returns Update the session's working directory. Used by the host when the user explicitly changes cwd (e.g., the `/cd` slash command). The host is responsible for `process.chdir` and any related side-effects (file index, etc.); this method only updates the session's own recorded path.
+       * @returns Update the session's working directory. Used by the host when the user explicitly changes cwd (e.g., the `/cd` slash command). The host is responsible for any related side-effects (file index, etc.); it does NOT change the process working directory (a session's cwd is per-session, not process-global). For local sessions the runtime validates the target first (an absolute path that exists on disk) and re-bases the permission primary directory; a rejected validation fails the call before anything is mutated, persisted, or emitted. Location-scoped permission rules are then re-keyed to the new directory (best-effort). Remote sessions only record the path.
        */
       setWorkingDirectory: async (params) => connection.sendRequest("session.metadata.setWorkingDirectory", { sessionId, ...params }),
       /**

package/dist/cjs/session.js

@@ -40,6 +40,7 @@ function isOpenCanvasInstance(value) {
   const instance = value;
   return typeof instance.instanceId === "string" && instance.instanceId.length > 0 && typeof instance.extensionId === "string" && instance.extensionId.length > 0 && typeof instance.canvasId === "string" && instance.canvasId.length > 0;
 }
+const TOOL_SEARCH_TOOL_NAME = "tool_search_tool";
 class CopilotSession {
   /**
    * Creates a new CopilotSession instance.
@@ -352,11 +353,21 @@ class CopilotSession {
    */
   async _executeToolAndRespond(requestId, toolName, toolCallId, args, handler, traceparent, tracestate) {
     try {
+      let availableTools;
+      if (toolName === TOOL_SEARCH_TOOL_NAME) {
+        try {
+          const metadata = await this.rpc.tools.getCurrentMetadata();
+          availableTools = metadata.tools ?? void 0;
+        } catch {
+          availableTools = void 0;
+        }
+      }
       const rawResult = await handler(args, {
         sessionId: this.sessionId,
         toolCallId,
         toolName,
         arguments: args,
+        availableTools,
         traceparent,
         tracestate
       });
@@ -1009,7 +1020,7 @@ class CopilotSession {
    *
    * @example
    * ```typescript
-   * await session.setModel("gpt-4.1");
+   * await session.setModel("gpt-5.4");
    * await session.setModel("claude-sonnet-4.6", { reasoningEffort: "high" });
    * ```
    */

package/dist/cjs/types.js

@@ -39,7 +39,7 @@ const RuntimeConnection = {
    * This is the default if no {@link CopilotClientOptions.connection} is set.
    */
   forStdio(opts = {}) {
-    return { kind: "stdio", path: opts.path, args: opts.args };
+    return { kind: "stdio", path: opts.path, args: opts.args, env: opts.env };
   },
   /**
    * Spawn a runtime child process that listens on a TCP socket and connect to it.
@@ -50,7 +50,8 @@ const RuntimeConnection = {
       port: opts.port,
       connectionToken: opts.connectionToken,
       path: opts.path,
-      args: opts.args
+      args: opts.args,
+      env: opts.env
     };
   },
   /**

package/dist/client.d.ts

@@ -435,17 +435,7 @@ export declare class CopilotClient {
      * Connect to the CLI server (via socket or stdio)
      */
     private connectToServer;
-    /**
-     * Start the in-process FFI runtime host: resolve the CLI entrypoint and native
-     * runtime library, then let the native host spawn the CLI worker.
-     *
-     * The worker inherits this host process's ambient environment; per-client options
-     * that lower to environment variables (`env`, `telemetry`, `gitHubToken`,
-     * `baseDirectory`) are intentionally not applied here, because the native runtime
-     * loads into the shared host process and a single env block cannot carry per-client
-     * values. Configure the in-process runtime via the host process environment instead.
-     * See https://github.com/github/copilot-sdk/issues/1934.
-     */
+    /** Starts the in-process FFI runtime with SDK-managed typed options. */
     private startInProcessFfi;
     /**
      * Connect to the in-process FFI runtime host over its receive/send streams,
@@ -460,9 +450,11 @@ export declare class CopilotClient {
     /**
      * Returns the napi prebuilds folder name for the current host — the
      * `<node-platform>-<arch>` convention (e.g. `win32-x64`, `darwin-arm64`,
-     * `linux-x64`) under which the runtime ships `prebuilds/<folder>/runtime.node`.
+     * `linux-x64`, `linuxmusl-x64`) under which the runtime ships
+     * `prebuilds/<folder>/runtime.node`.
      */
     private static getNapiPrebuildsFolder;
+    private static isMusl;
     /**
      * Connect to child via stdio pipes
      */

package/dist/client.js

@@ -372,6 +372,21 @@ class CopilotClient {
         "workingDirectory is not supported with RuntimeConnection.forInProcess(): the in-process transport hosts the runtime in this process, so honoring it would require mutating the shared process-global cwd. Change the host process's working directory before constructing the client instead."
       );
     }
+    if (conn.kind === "inprocess" && options.env !== void 0) {
+      throw new Error(
+        "env is not supported with RuntimeConnection.forInProcess(): the in-process transport loads the native runtime into the shared host process, whose single environment block cannot carry per-client values. Set the variables on the host process environment instead."
+      );
+    }
+    if (conn.kind === "inprocess" && options.telemetry !== void 0) {
+      throw new Error(
+        "telemetry is not supported with RuntimeConnection.forInProcess(): telemetry configuration is lowered to environment variables read by native runtime code running in the shared host process, so per-client telemetry cannot be honored in-process. Configure telemetry via the host process environment, or use a child-process transport."
+      );
+    }
+    if ((conn.kind === "stdio" || conn.kind === "tcp") && conn.env !== void 0 && options.env !== void 0) {
+      throw new Error(
+        "Set environment variables via either the client-level env option or the connection's env (RuntimeConnection.forStdio/forTcp), not both. Prefer the connection-level env for child-process transports."
+      );
+    }
     if (conn.kind === "tcp" && conn.connectionToken !== void 0) {
       if (typeof conn.connectionToken !== "string" || conn.connectionToken.length === 0) {
         throw new Error("connectionToken must be a non-empty string");
@@ -400,7 +415,8 @@ class CopilotClient {
     this.requestHandler = options.requestHandler ?? null;
     this.onGitHubTelemetry = options.onGitHubTelemetry;
     this.setupClientGlobalHandlers();
-    const effectiveEnv = options.env ?? process.env;
+    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;
     const connArgs = conn.kind === "stdio" || conn.kind === "tcp" ? conn.args ?? [] : [];
@@ -1037,6 +1053,7 @@ class CopilotClient {
           skipPermission: tool.skipPermission,
           defer: tool.defer
         })),
+        toolSearch: config.toolSearch,
         canvases: config.canvases?.map((canvas) => canvas.declaration),
         requestCanvasRenderer: config.requestCanvasRenderer,
         requestExtensions: config.requestExtensions,
@@ -1235,6 +1252,7 @@ class CopilotClient {
           skipPermission: tool.skipPermission,
           defer: tool.defer
         })),
+        toolSearch: config.toolSearch,
         canvases: config.canvases?.map((canvas) => canvas.declaration),
         requestCanvasRenderer: config.requestCanvasRenderer,
         requestExtensions: config.requestExtensions,
@@ -1838,21 +1856,42 @@ stderr: ${stderrOutput}`
         return this.connectViaTcp();
     }
   }
-  /**
-   * Start the in-process FFI runtime host: resolve the CLI entrypoint and native
-   * runtime library, then let the native host spawn the CLI worker.
-   *
-   * The worker inherits this host process's ambient environment; per-client options
-   * that lower to environment variables (`env`, `telemetry`, `gitHubToken`,
-   * `baseDirectory`) are intentionally not applied here, because the native runtime
-   * loads into the shared host process and a single env block cannot carry per-client
-   * values. Configure the in-process runtime via the host process environment instead.
-   * See https://github.com/github/copilot-sdk/issues/1934.
-   */
+  /** Starts the in-process FFI runtime with SDK-managed typed options. */
   async startInProcessFfi() {
     const entrypoint = this.resolveCliPathForFfi();
     const { FfiRuntimeHost } = await import("./ffiRuntimeHost.js");
-    const host = FfiRuntimeHost.create(entrypoint, CopilotClient.getNapiPrebuildsFolder());
+    const environment = {};
+    if (this.options.gitHubToken) {
+      environment.COPILOT_SDK_AUTH_TOKEN = this.options.gitHubToken;
+    }
+    if (this.options.baseDirectory) {
+      environment.COPILOT_HOME = this.options.baseDirectory;
+    }
+    if (this.options.mode === "empty") {
+      environment.COPILOT_DISABLE_KEYTAR = "1";
+    }
+    const args = [];
+    if (this.options.logLevel) {
+      args.push("--log-level", this.options.logLevel);
+    }
+    if (this.options.gitHubToken) {
+      args.push("--auth-token-env", "COPILOT_SDK_AUTH_TOKEN");
+    }
+    if (!this.options.useLoggedInUser) {
+      args.push("--no-auto-login");
+    }
+    if (this.options.sessionIdleTimeoutSeconds > 0) {
+      args.push("--session-idle-timeout", this.options.sessionIdleTimeoutSeconds.toString());
+    }
+    if (this.options.enableRemoteSessions) {
+      args.push("--remote");
+    }
+    const host = FfiRuntimeHost.create(
+      entrypoint,
+      CopilotClient.getNapiPrebuildsFolder(entrypoint),
+      environment,
+      args
+    );
     this.ffiHost = host;
     await host.start();
   }
@@ -1882,14 +1921,30 @@ stderr: ${stderrOutput}`
   /**
    * Returns the napi prebuilds folder name for the current host — the
    * `<node-platform>-<arch>` convention (e.g. `win32-x64`, `darwin-arm64`,
-   * `linux-x64`) under which the runtime ships `prebuilds/<folder>/runtime.node`.
+   * `linux-x64`, `linuxmusl-x64`) under which the runtime ships
+   * `prebuilds/<folder>/runtime.node`.
    */
-  static getNapiPrebuildsFolder() {
+  static getNapiPrebuildsFolder(entrypoint) {
     const arch = process.arch;
     if (arch !== "x64" && arch !== "arm64") {
       throw new Error(`Unsupported architecture '${arch}' for in-process FFI hosting.`);
     }
-    return `${process.platform}-${arch}`;
+    let platform = process.platform;
+    if (platform === "linux" && CopilotClient.isMusl(entrypoint)) {
+      platform = "linuxmusl";
+    }
+    return `${platform}-${arch}`;
+  }
+  static isMusl(entrypoint) {
+    if (entrypoint.includes(`copilot-linuxmusl-${process.arch}`)) {
+      return true;
+    }
+    if (entrypoint.includes(`copilot-linux-${process.arch}`)) {
+      return false;
+    }
+    const report = process.report?.getReport();
+    const header = report && "header" in report ? report.header : void 0;
+    return header !== void 0 && header.glibcVersionRuntime === void 0;
   }
   /**
    * Connect to child via stdio pipes

package/dist/ffiRuntimeHost.d.ts

@@ -2,7 +2,8 @@ import { PassThrough, Writable } from "node:stream";
 export declare class FfiRuntimeHost {
     private readonly libraryPath;
     private readonly cliEntrypoint;
-    private readonly environment?;
+    private readonly environment;
+    private readonly args;
     private readonly lib;
     private serverId;
     private connectionId;
@@ -20,7 +21,7 @@ export declare class FfiRuntimeHost {
      * 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>): FfiRuntimeHost;
+    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.

package/dist/ffiRuntimeHost.js

@@ -51,8 +51,9 @@ function loadLibrary(libraryPath) {
   loadedLibraryPath = libraryPath;
   return loadedLibrary;
 }
-function buildArgvJson(cliEntrypoint) {
+function buildArgvJson(cliEntrypoint, args) {
   const argv = 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");
 }
 function buildEnvJson(environment) {
@@ -71,10 +72,11 @@ function buildEnvJson(environment) {
   return Buffer.from(JSON.stringify(obj), "utf8");
 }
 class FfiRuntimeHost {
-  constructor(libraryPath, cliEntrypoint, environment) {
+  constructor(libraryPath, cliEntrypoint, environment, args) {
     this.libraryPath = libraryPath;
     this.cliEntrypoint = cliEntrypoint;
     this.environment = environment;
+    this.args = args;
     this.lib = loadLibrary(libraryPath);
     this.receiveStream = new PassThrough();
     this.sendStream = new Writable({
@@ -93,6 +95,7 @@ class FfiRuntimeHost {
   libraryPath;
   cliEntrypoint;
   environment;
+  args;
   lib;
   serverId = 0;
   connectionId = 0;
@@ -109,21 +112,21 @@ class FfiRuntimeHost {
    * the entrypoint directory (the napi-rs `<node-platform>-<arch>` layout, e.g.
    * `linux-x64`). Throws if it cannot be found.
    */
-  static create(cliEntrypoint, prebuildsFolder, environment) {
+  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}'.`);
     }
-    return new FfiRuntimeHost(libraryPath, fullEntrypoint, environment);
+    return new FfiRuntimeHost(libraryPath, fullEntrypoint, 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.
    */
   async start() {
-    const argvJson = buildArgvJson(this.cliEntrypoint);
+    const argvJson = buildArgvJson(this.cliEntrypoint, this.args);
     const envJson = buildEnvJson(this.environment);
     this.serverId = await new Promise((resolvePromise, rejectPromise) => {
       this.lib.hostStart.async(

package/dist/generated/rpc.d.ts

@@ -3214,6 +3214,10 @@ export interface DiscoveredCanvas {
      * Short, single-sentence description shown to the agent in canvas catalogs.
      */
     description: string;
+    /**
+     * Host-local PNG path for the canvas icon, when supplied
+     */
+    icon?: string;
     inputSchema?: CanvasJsonSchema;
     /**
      * Actions the agent or host may invoke on an open instance
@@ -3269,6 +3273,10 @@ export interface OpenCanvasInstance {
      * Provider-local canvas identifier
      */
     canvasId: string;
+    /**
+     * Host-local PNG path for the canvas icon, when supplied
+     */
+    icon?: string;
     /**
      * Rendered title
      */
@@ -5791,27 +5799,24 @@ export interface McpAppsListToolsResult {
     }[];
 }
 /**
- * @deprecated
- * Deprecated/obsolete MCP Apps alias for `McpResourcesReadRequest`; use `session.mcp.resources.read` instead.
+ * MCP server and resource URI to fetch.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
  * via the `definition` "McpAppsReadResourceRequest".
  */
 /** @experimental */
-/** @deprecated */
 export interface McpAppsReadResourceRequest {
     /**
      * Name of the MCP server hosting the resource
      */
     serverName: string;
     /**
-     * Resource URI
+     * Resource URI (typically ui://...)
      */
     uri: string;
 }
 /**
- * @deprecated
- * Deprecated/obsolete MCP Apps alias for `McpResourcesReadResult`; use `session.mcp.resources.read` instead.
+ * Resource contents returned by the MCP server.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
  * via the `definition` "McpAppsReadResourceResult".
@@ -5824,8 +5829,7 @@ export interface McpAppsReadResourceResult {
     contents: McpAppsResourceContent[];
 }
 /**
- * @deprecated
- * Deprecated/obsolete MCP Apps alias for `McpResourceContent`; use `session.mcp.resources.read` instead.
+ * MCP Apps resource content with URI, optional MIME type, text or base64 blob, and resource metadata.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
  * via the `definition` "McpAppsResourceContent".
@@ -5833,7 +5837,7 @@ export interface McpAppsReadResourceResult {
 /** @experimental */
 export interface McpAppsResourceContent {
     /**
-     * The resource URI
+     * The resource URI (typically ui://...)
      */
     uri: string;
     /**
@@ -5849,7 +5853,7 @@ export interface McpAppsResourceContent {
      */
     blob?: string;
     /**
-     * Resource-level metadata
+     * Resource-level metadata (CSP, permissions, etc.)
      */
     _meta?: {
         [k: string]: unknown | undefined;
@@ -7107,7 +7111,7 @@ export interface SessionWorkingDirectoryContext {
 export interface MetadataRecordContextChangeResult {
 }
 /**
- * Absolute path to set as the session's new working directory.
+ * Absolute path to set as the session's new working directory. For local sessions the path must be absolute and exist on disk: it is validated before any session state changes, and a failing validation rejects the call with nothing mutated, persisted, or emitted. Remote sessions record the path as-is.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
  * via the `definition` "MetadataSetWorkingDirectoryRequest".
@@ -7120,7 +7124,7 @@ export interface MetadataSetWorkingDirectoryRequest {
     workingDirectory: string;
 }
 /**
- * Update the session's working directory. Used by the host when the user explicitly changes cwd (e.g., the `/cd` slash command). The host is responsible for `process.chdir` and any related side-effects (file index, etc.); this method only updates the session's own recorded path.
+ * Update the session's working directory. Used by the host when the user explicitly changes cwd (e.g., the `/cd` slash command). The host is responsible for any related side-effects (file index, etc.); it does NOT change the process working directory (a session's cwd is per-session, not process-global). For local sessions the runtime validates the target first (an absolute path that exists on disk) and re-bases the permission primary directory; a rejected validation fails the call before anything is mutated, persisted, or emitted. Location-scoped permission rules are then re-keyed to the new directory (best-effort). Remote sessions only record the path.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
  * via the `definition` "MetadataSetWorkingDirectoryResult".
@@ -7305,6 +7309,7 @@ export interface ModelBilling {
      * Whole-number percentage discount (0-100) applied to usage billed through this model. Populated for the synthetic `auto` model, where requests routed by auto-mode are billed at a reduced rate; absent for concrete models.
      */
     discountPercent?: number;
+    promo?: ModelBillingPromo;
 }
 /**
  * Token-level pricing information for this model
@@ -7389,6 +7394,31 @@ export interface ModelBillingTokenPricesLongContext {
      */
     maxPromptTokens?: number;
 }
+/**
+ * Active server-driven promotion for a model, including its discount and expiry.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "ModelBillingPromo".
+ */
+/** @experimental */
+export interface ModelBillingPromo {
+    /**
+     * Stable identifier for the promotion campaign.
+     */
+    id?: string;
+    /**
+     * Percentage discount (0-100) applied while the promotion is active. May be fractional.
+     */
+    discountPercent?: number;
+    /**
+     * UTC ISO 8601 timestamp marking when the promotion ends. Always present: the API only surfaces a promo whose expiry parses and is in the future. Consumers should treat a past value as expired.
+     */
+    endsAt: string;
+    /**
+     * Human-readable promotion message. Does not include the expiry timestamp; consumers may format endsAt and append it.
+     */
+    message?: string;
+}
 /**
  * Optional capability overrides (vision, tool_calls, reasoning, etc.).
  *
@@ -9272,7 +9302,7 @@ export interface PluginsInstallRequest {
     workingDirectory?: string;
 }
 /**
- * Marketplace source to register.
+ * Marketplace source and optional working directory for relative-path resolution.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
  * via the `definition` "PluginsMarketplacesAddRequest".
@@ -9283,6 +9313,10 @@ export interface PluginsMarketplacesAddRequest {
      * Marketplace source. Accepts the same forms as the CLI: "owner/repo" or "owner/repo#ref" (GitHub), an http/https/ssh URL (optionally with #ref), a git scp-style URL (user@host:path), or a local path. The marketplace's own name (from its manifest) is used as the registration key.
      */
     source: string;
+    /**
+     * Working directory used to resolve relative local paths in `source`. Defaults to the server's current working directory.
+     */
+    workingDirectory?: string;
 }
 /**
  * Name of the marketplace whose plugin catalog to fetch.
@@ -10185,7 +10219,7 @@ export interface QueueRemoveMostRecentResult {
 /** @experimental */
 export interface RegisterEventInterestParams {
     /**
-     * The event type the consumer wants the runtime to treat as 'observed' for behavior-switching gating. Some runtime code paths inspect whether any consumer is interested in a specific event type and choose a different implementation accordingly (e.g. `mcp.oauth_required`: when interest is registered the runtime delegates OAuth token acquisition to the consumer; when no interest is registered OAuth-required servers become needs-auth). SDK clients that long-poll events do NOT automatically appear as listeners to these gating checks — they must explicitly call `registerInterest` for each event type they want the runtime to count as having a consumer. Multiple registrations for the same event type from the same or different consumers are tracked independently and must each be released. See: `mcp.oauth_required`, `sampling.requested`, `auto_mode_switch.requested`, `session_limits_exhausted.requested`, `user_input.requested`, `elicitation.requested`, `command.queued`, `exit_plan_mode.requested`.
+     * The event type the consumer wants the runtime to treat as 'observed' for behavior-switching gating. Some runtime code paths inspect whether any consumer is interested in a specific event type and choose a different implementation accordingly (e.g. `mcp.oauth_required`: when interest is registered the runtime delegates interactive OAuth token acquisition to the consumer via `mcp.oauth_required` events; when no interest is registered the runtime still attempts non-interactive reconnect from cached or refreshable tokens, and only marks the server `needs-auth` if usable credentials are unavailable — it does not open a browser or start interactive OAuth without a consumer). SDK clients that long-poll events do NOT automatically appear as listeners to these gating checks — they must explicitly call `registerInterest` for each event type they want the runtime to count as having a consumer. Multiple registrations for the same event type from the same or different consumers are tracked independently and must each be released. See: `mcp.oauth_required`, `sampling.requested`, `auto_mode_switch.requested`, `session_limits_exhausted.requested`, `user_input.requested`, `elicitation.requested`, `command.queued`, `exit_plan_mode.requested`.
      */
     eventType: string;
 }
@@ -11826,6 +11860,10 @@ export interface SessionOpenOptions {
      * Denylist of tool names.
      */
     excludedTools?: string[];
+    /**
+     * Built-in subagent names to include in this session. When specified, only these built-ins are available, subject to runtime availability and exclusions. Custom agents with the same name remain available.
+     */
+    includedBuiltinAgents?: string[];
     /**
      * Built-in subagent names to exclude from this session. Excluded built-ins are hidden from agent discovery and cannot be dispatched unless a custom agent with the same name is available.
      */
@@ -12896,6 +12934,10 @@ export interface SessionUpdateOptionsParams {
      * Denylist of tool names for this session.
      */
     excludedTools?: string[];
+    /**
+     * Built-in subagent names to include in this session. When specified, only these built-ins are available, subject to runtime availability and exclusions. Custom agents with the same name remain available. Set to null to remove the allowlist restriction.
+     */
+    includedBuiltinAgents?: string[] | null;
     /**
      * Built-in subagent names to exclude from this session. Excluded built-ins are hidden from agent discovery and cannot be dispatched unless a custom agent with the same name is available.
      */
@@ -13384,7 +13426,7 @@ export interface SkillsLoadDiagnostics {
     errors: string[];
 }
 /**
- * Slash-command invocation result that submits an agent prompt, with display prompt, optional mode, and settings-change flag.
+ * Slash-command invocation result that submits an agent prompt, with display prompt, optional mode, optional user-facing notice, and settings-change flag.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
  * via the `definition` "SlashCommandAgentPromptResult".
@@ -13404,6 +13446,10 @@ export interface SlashCommandAgentPromptResult {
      */
     displayPrompt: string;
     mode?: SessionMode;
+    /**
+     * Optional user-facing notice to show before the prompt is submitted
+     */
+    notice?: string;
     /**
      * True when the invocation mutated user runtime settings; consumers caching settings should refresh
      */
@@ -15435,7 +15481,7 @@ export declare function createServerRpc(connection: MessageConnection): {
             /**
              * Registers a new marketplace from a source (owner/repo, URL, or local path).
              *
-             * @param params Marketplace source to register.
+             * @param params Marketplace source and optional working directory for relative-path resolution.
              *
              * @returns Result of registering a new marketplace.
              */
@@ -16387,13 +16433,11 @@ export declare function createSessionRpc(connection: MessageConnection, sessionI
         /** @experimental */
         apps: {
             /**
-             * Deprecated/obsolete alias for `session.mcp.resources.read`; retained for backwards compatibility with earlier MCP Apps host integrations.
-             *
-             * @param params Deprecated/obsolete MCP Apps alias for `McpResourcesReadRequest`; use `session.mcp.resources.read` instead.
+             * Fetch an MCP resource (typically a `ui://` MCP App bundle, per SEP-1865) from a connected server. Requires the `mcp-apps` session capability.
              *
-             * @returns Deprecated/obsolete MCP Apps alias for `McpResourcesReadResult`; use `session.mcp.resources.read` instead.
+             * @param params MCP server and resource URI to fetch.
              *
-             * @deprecated
+             * @returns Resource contents returned by the MCP server.
              */
             readResource: (params: McpAppsReadResourceRequest) => Promise<McpAppsReadResourceResult>;
             /**
@@ -16960,11 +17004,11 @@ export declare function createSessionRpc(connection: MessageConnection, sessionI
          */
         recordContextChange: (params: MetadataRecordContextChangeRequest) => Promise<MetadataRecordContextChangeResult>;
         /**
-         * Updates the session's recorded working directory.
+         * Updates the session's working directory. For local sessions the target is validated first (an absolute path that exists on disk) and the permission primary directory is re-based; a rejected validation fails the call before any session state changes.
          *
-         * @param params Absolute path to set as the session's new working directory.
+         * @param params Absolute path to set as the session's new working directory. For local sessions the path must be absolute and exist on disk: it is validated before any session state changes, and a failing validation rejects the call with nothing mutated, persisted, or emitted. Remote sessions record the path as-is.
          *
-         * @returns Update the session's working directory. Used by the host when the user explicitly changes cwd (e.g., the `/cd` slash command). The host is responsible for `process.chdir` and any related side-effects (file index, etc.); this method only updates the session's own recorded path.
+         * @returns Update the session's working directory. Used by the host when the user explicitly changes cwd (e.g., the `/cd` slash command). The host is responsible for any related side-effects (file index, etc.); it does NOT change the process working directory (a session's cwd is per-session, not process-global). For local sessions the runtime validates the target first (an absolute path that exists on disk) and re-bases the permission primary directory; a rejected validation fails the call before anything is mutated, persisted, or emitted. Location-scoped permission rules are then re-keyed to the new directory (best-effort). Remote sessions only record the path.
          */
         setWorkingDirectory: (params: MetadataSetWorkingDirectoryRequest) => Promise<MetadataSetWorkingDirectoryResult>;
         /**

package/dist/generated/rpc.js

@@ -195,7 +195,7 @@ function createServerRpc(connection) {
         /**
          * Registers a new marketplace from a source (owner/repo, URL, or local path).
          *
-         * @param params Marketplace source to register.
+         * @param params Marketplace source and optional working directory for relative-path resolution.
          *
          * @returns Result of registering a new marketplace.
          */
@@ -1203,13 +1203,11 @@ function createSessionRpc(connection, sessionId) {
       /** @experimental */
       apps: {
         /**
-         * Deprecated/obsolete alias for `session.mcp.resources.read`; retained for backwards compatibility with earlier MCP Apps host integrations.
+         * Fetch an MCP resource (typically a `ui://` MCP App bundle, per SEP-1865) from a connected server. Requires the `mcp-apps` session capability.
          *
-         * @param params Deprecated/obsolete MCP Apps alias for `McpResourcesReadRequest`; use `session.mcp.resources.read` instead.
-         *
-         * @returns Deprecated/obsolete MCP Apps alias for `McpResourcesReadResult`; use `session.mcp.resources.read` instead.
+         * @param params MCP server and resource URI to fetch.
          *
-         * @deprecated
+         * @returns Resource contents returned by the MCP server.
          */
         readResource: async (params) => connection.sendRequest("session.mcp.apps.readResource", { sessionId, ...params }),
         /**
@@ -1776,11 +1774,11 @@ function createSessionRpc(connection, sessionId) {
        */
       recordContextChange: async (params) => connection.sendRequest("session.metadata.recordContextChange", { sessionId, ...params }),
       /**
-       * Updates the session's recorded working directory.
+       * Updates the session's working directory. For local sessions the target is validated first (an absolute path that exists on disk) and the permission primary directory is re-based; a rejected validation fails the call before any session state changes.
        *
-       * @param params Absolute path to set as the session's new working directory.
+       * @param params Absolute path to set as the session's new working directory. For local sessions the path must be absolute and exist on disk: it is validated before any session state changes, and a failing validation rejects the call with nothing mutated, persisted, or emitted. Remote sessions record the path as-is.
        *
-       * @returns Update the session's working directory. Used by the host when the user explicitly changes cwd (e.g., the `/cd` slash command). The host is responsible for `process.chdir` and any related side-effects (file index, etc.); this method only updates the session's own recorded path.
+       * @returns Update the session's working directory. Used by the host when the user explicitly changes cwd (e.g., the `/cd` slash command). The host is responsible for any related side-effects (file index, etc.); it does NOT change the process working directory (a session's cwd is per-session, not process-global). For local sessions the runtime validates the target first (an absolute path that exists on disk) and re-bases the permission primary directory; a rejected validation fails the call before anything is mutated, persisted, or emitted. Location-scoped permission rules are then re-keyed to the new directory (best-effort). Remote sessions only record the path.
        */
       setWorkingDirectory: async (params) => connection.sendRequest("session.metadata.setWorkingDirectory", { sessionId, ...params }),
       /**

package/dist/generated/session-events.d.ts

@@ -4168,6 +4168,14 @@ export interface ToolExecutionCompleteData {
      * Whether this tool call was explicitly requested by the user rather than the assistant
      */
     isUserRequested?: boolean;
+    /**
+     * FIDES IFC label projected from tool ingress metadata (MCP `CallToolResult._meta` or synthesized built-in ingress labels). Persisted as `{ ifc: ... }` so the label survives session resume, including model-visible failure results. Experimental.
+     *
+     * @experimental
+     */
+    mcpMeta?: {
+        [k: string]: unknown | undefined;
+    };
     /**
      * Model identifier that generated this tool call
      */
@@ -4243,6 +4251,14 @@ export interface ToolExecutionCompleteResult {
      * Full detailed tool result for UI/timeline display, preserving complete content such as diffs. Falls back to content when absent.
      */
     detailedContent?: string;
+    /**
+     * FIDES IFC label projected from tool ingress metadata (MCP `CallToolResult._meta` or synthesized built-in ingress labels) — persisted as `{ ifc: ... }` (only the `ifc` key, not the whole `_meta`). Persisted so the FIDES IFC label survives session resume: the engine rehydrates accumulated taint by replaying these on load. Populated for ingress sources when FIDES IFC is on. Experimental.
+     *
+     * @experimental
+     */
+    mcpMeta?: {
+        [k: string]: unknown | undefined;
+    };
     /**
      * Structured content (arbitrary JSON) returned verbatim by the MCP tool
      */
@@ -8268,7 +8284,7 @@ export interface ExtensionsLoadedExtension {
     status: ExtensionsLoadedExtensionStatus;
 }
 /**
- * Session event "session.canvas.opened". Payload of `session.canvas.opened` with canvas instance and provider IDs plus optional title, status, URL, and input.
+ * Session event "session.canvas.opened". Payload of `session.canvas.opened` with canvas instance and provider IDs plus optional icon, title, status, URL, and input.
  */
 /** @experimental */
 export interface CanvasOpenedEvent {
@@ -8299,7 +8315,7 @@ export interface CanvasOpenedEvent {
     type: "session.canvas.opened";
 }
 /**
- * Payload of `session.canvas.opened` with canvas instance and provider IDs plus optional title, status, URL, and input.
+ * Payload of `session.canvas.opened` with canvas instance and provider IDs plus optional icon, title, status, URL, and input.
  */
 /** @experimental */
 export interface CanvasOpenedData {
@@ -8315,6 +8331,10 @@ export interface CanvasOpenedData {
      * Owning extension display name, when available
      */
     extensionName?: string;
+    /**
+     * Host-local PNG path for the canvas icon, when supplied
+     */
+    icon?: string;
     /**
      * Input supplied when the instance was opened
      */
@@ -8408,6 +8428,10 @@ export interface CanvasRegistryChangedCanvas {
      * Owning extension display name, when available
      */
     extensionName?: string;
+    /**
+     * Host-local PNG path for the canvas icon, when supplied
+     */
+    icon?: string;
     /**
      * JSON Schema for canvas open input
      */

package/dist/index.d.ts

@@ -10,4 +10,4 @@ export { CopilotSession, type AssistantMessageEvent } from "./session.js";
 export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasDeclaration, type CanvasHostContext, type CanvasHostContextCapabilities, type CanvasJsonSchema, type CanvasOptions, } from "./canvas.js";
 export { defineTool, approveAll, convertMcpCallToolResult, createSessionFsAdapter, CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, SYSTEM_MESSAGE_SECTIONS, } from "./types.js";
 export type * from "./generated/session-events.js";
-export type { CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, CopilotClientMode, CopilotClientOptions, StdioRuntimeConnection, InProcessRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, MessageOptions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, CapiSessionOptions, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestResult, ProviderConfig, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolTelemetry, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export type { CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, CopilotClientMode, CopilotClientOptions, StdioRuntimeConnection, InProcessRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, ChildProcessRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, MessageOptions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, CapiSessionOptions, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestResult, ProviderConfig, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, CurrentToolMetadata, ToolTelemetry, ToolResultObject, ToolSearchConfig, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";

package/dist/session.d.ts

@@ -30,6 +30,11 @@ export type AssistantMessageEvent = Extract<SessionEvent, {
  * await session.disconnect();
  * ```
  */
+/**
+ * Fixed name of the runtime's built-in tool-search tool. A client can replace
+ * its behavior by registering a {@link Tool} with this exact name and
+ * `overridesBuiltInTool: true`.
+ */
 export declare class CopilotSession {
     readonly sessionId: string;
     private connection;
@@ -262,7 +267,7 @@ export declare class CopilotSession {
      *
      * @example
      * ```typescript
-     * await session.setModel("gpt-4.1");
+     * await session.setModel("gpt-5.4");
      * await session.setModel("claude-sonnet-4.6", { reasoningEffort: "high" });
      * ```
      */

package/dist/session.js

@@ -17,6 +17,7 @@ function isOpenCanvasInstance(value) {
   const instance = value;
   return typeof instance.instanceId === "string" && instance.instanceId.length > 0 && typeof instance.extensionId === "string" && instance.extensionId.length > 0 && typeof instance.canvasId === "string" && instance.canvasId.length > 0;
 }
+const TOOL_SEARCH_TOOL_NAME = "tool_search_tool";
 class CopilotSession {
   /**
    * Creates a new CopilotSession instance.
@@ -329,11 +330,21 @@ class CopilotSession {
    */
   async _executeToolAndRespond(requestId, toolName, toolCallId, args, handler, traceparent, tracestate) {
     try {
+      let availableTools;
+      if (toolName === TOOL_SEARCH_TOOL_NAME) {
+        try {
+          const metadata = await this.rpc.tools.getCurrentMetadata();
+          availableTools = metadata.tools ?? void 0;
+        } catch {
+          availableTools = void 0;
+        }
+      }
       const rawResult = await handler(args, {
         sessionId: this.sessionId,
         toolCallId,
         toolName,
         arguments: args,
+        availableTools,
         traceparent,
         tracestate
       });
@@ -986,7 +997,7 @@ class CopilotSession {
    *
    * @example
    * ```typescript
-   * await session.setModel("gpt-4.1");
+   * await session.setModel("gpt-5.4");
    * await session.setModel("claude-sonnet-4.6", { reasoningEffort: "high" });
    * ```
    */

package/dist/types.d.ts

@@ -6,9 +6,10 @@ import type { SessionFsProvider } from "./sessionFsProvider.js";
 import type { CopilotRequestHandler } from "./copilotRequestHandler.js";
 import type { ReasoningSummary, SessionLimitsConfig, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
 import type { CopilotSession } from "./session.js";
-import type { GitHubTelemetryNotification, ModelBillingTokenPrices, OpenCanvasInstance, RemoteSessionMode } from "./generated/rpc.js";
+import type { GitHubTelemetryNotification, ModelBillingTokenPrices, OpenCanvasInstance, RemoteSessionMode, CurrentToolMetadata } from "./generated/rpc.js";
 import type { ToolSet } from "./toolSet.js";
 export type { RemoteSessionMode } from "./generated/rpc.js";
+export type { CurrentToolMetadata } from "./generated/rpc.js";
 export type { GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, } from "./generated/rpc.js";
 export type { ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, } from "./generated/rpc.js";
 export type SessionEvent = GeneratedSessionEvent;
@@ -65,15 +66,28 @@ export interface TelemetryConfig {
  */
 export type RuntimeConnection = StdioRuntimeConnection | InProcessRuntimeConnection | TcpRuntimeConnection | UriRuntimeConnection;
 /**
- * Spawns a runtime child process and communicates over its stdin/stdout.
- * This is the default if no {@link CopilotClientOptions.connection} is set.
+ * Shared shape for the transports that spawn a runtime **child process**
+ * ({@link StdioRuntimeConnection} and {@link TcpRuntimeConnection}).
  */
-export interface StdioRuntimeConnection {
-    readonly kind: "stdio";
+export interface ChildProcessRuntimeConnection {
     /** Path to the runtime executable. When omitted, the bundled runtime is used. */
     readonly path?: string;
     /** Extra command-line arguments to pass to the runtime process. */
     readonly args?: readonly string[];
+    /**
+     * Environment variables for the spawned runtime child process, replacing the
+     * inherited environment. Cannot be combined with
+     * {@link CopilotClientOptions.env}; setting both throws when the client is
+     * constructed. When omitted, the client-level env (or `process.env`) is used.
+     */
+    readonly env?: Record<string, string>;
+}
+/**
+ * Spawns a runtime child process and communicates over its stdin/stdout.
+ * This is the default if no {@link CopilotClientOptions.connection} is set.
+ */
+export interface StdioRuntimeConnection extends ChildProcessRuntimeConnection {
+    readonly kind: "stdio";
 }
 /**
  * Hosts the runtime in-process by loading the native runtime library and speaking
@@ -97,7 +111,7 @@ export interface InProcessRuntimeConnection {
 /**
  * Spawns a runtime child process that listens on a TCP socket and connects to it.
  */
-export interface TcpRuntimeConnection {
+export interface TcpRuntimeConnection extends ChildProcessRuntimeConnection {
     readonly kind: "tcp";
     /**
      * TCP port to listen on. `0` (the default) auto-allocates a free port.
@@ -110,10 +124,6 @@ export interface TcpRuntimeConnection {
      * loopback listener is safe by default.
      */
     readonly connectionToken?: string;
-    /** Path to the runtime executable. When omitted, the bundled runtime is used. */
-    readonly path?: string;
-    /** Extra command-line arguments to pass to the runtime process. */
-    readonly args?: readonly string[];
 }
 /**
  * Connects to an already-running runtime at the specified URL. The SDK does not
@@ -138,6 +148,7 @@ export declare const RuntimeConnection: {
     readonly forStdio: (opts?: {
         path?: string;
         args?: readonly string[];
+        env?: Record<string, string>;
     }) => StdioRuntimeConnection;
     /**
      * Spawn a runtime child process that listens on a TCP socket and connect to it.
@@ -147,6 +158,7 @@ export declare const RuntimeConnection: {
         connectionToken?: string;
         path?: string;
         args?: readonly string[];
+        env?: Record<string, string>;
     }) => TcpRuntimeConnection;
     /**
      * Connect to an already-running runtime at the given URL. The SDK does not
@@ -346,6 +358,10 @@ export type ToolResultObject = {
     error?: string;
     sessionLog?: string;
     toolTelemetry?: ToolTelemetry;
+    /**
+     * Names of tools returned by a tool-search tool.
+     */
+    toolReferences?: string[];
 };
 export type ToolResult = string | ToolResultObject;
 /**
@@ -401,6 +417,14 @@ export interface ToolInvocation {
     toolCallId: string;
     toolName: string;
     arguments: unknown;
+    /**
+     * Snapshot of the session's currently initialized tools. Populated by the
+     * SDK only when this invocation targets the built-in tool-search tool
+     * (`tool_search_tool`), so a tool-search override can rank/filter the live
+     * catalog — including MCP tools configured in settings — without issuing its
+     * own RPC. `undefined` for every other tool invocation.
+     */
+    availableTools?: CurrentToolMetadata[];
     /** W3C Trace Context traceparent from the CLI's execute_tool span. */
     traceparent?: string;
     /** W3C Trace Context tracestate from the CLI's execute_tool span. */
@@ -460,6 +484,33 @@ export declare function defineTool<T = unknown>(name: string, config: {
     skipPermission?: boolean;
     defer?: "auto" | "never";
 }): Tool<T>;
+/**
+ * SDK-supplied override for the runtime's built-in tool-search behavior.
+ *
+ * Tool search lets the model discover tools on demand instead of loading every
+ * tool definition up front. When the total tool count exceeds the deferral
+ * threshold, MCP and external tools are marked as deferred and surfaced through
+ * the built-in `tool_search_tool`.
+ *
+ * To override the tool-search tool's model-facing definition and/or its
+ * execution, register a {@link Tool} named `tool_search_tool` with
+ * `overridesBuiltInTool: true`. To customize the in-prompt tool-search
+ * guidance, use the `tool_instructions` section of {@link SystemMessageConfig}
+ * in `"customize"` mode.
+ */
+export interface ToolSearchConfig {
+    /**
+     * Toggle to enable/disable tool search. When disabled, all tools are pre-loaded
+     * and the model's active tool set is not deferred.
+     */
+    enabled?: boolean;
+    /**
+     * Overrides the total tool count at which MCP and external tools are
+     * automatically deferred behind tool search. Defaults to the built-in
+     * threshold (30) when omitted.
+     */
+    deferThreshold?: number;
+}
 /**
  * Context passed to a command handler when a command is executed.
  */
@@ -1553,6 +1604,14 @@ export interface SessionConfigBase {
      * Controls how the system prompt is constructed
      */
     systemMessage?: SystemMessageConfig;
+    /**
+     * Override for the runtime's built-in tool-search behavior.
+     *
+     * To also override the tool-search tool's implementation, register a
+     * {@link Tool} named `tool_search_tool` with `overridesBuiltInTool: true` in
+     * {@link SessionConfigBase.tools}.
+     */
+    toolSearch?: ToolSearchConfig;
     /**
      * List of tool names to allow. When specified, only these tools will be available.
      *

package/dist/types.js

@@ -11,7 +11,7 @@ const RuntimeConnection = {
    * This is the default if no {@link CopilotClientOptions.connection} is set.
    */
   forStdio(opts = {}) {
-    return { kind: "stdio", path: opts.path, args: opts.args };
+    return { kind: "stdio", path: opts.path, args: opts.args, env: opts.env };
   },
   /**
    * Spawn a runtime child process that listens on a TCP socket and connect to it.
@@ -22,7 +22,8 @@ const RuntimeConnection = {
       port: opts.port,
       connectionToken: opts.connectionToken,
       path: opts.path,
-      args: opts.args
+      args: opts.args,
+      env: opts.env
     };
   },
   /**

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "1.0.7-preview.2",
+  "version": "1.0.7-preview.3",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/cjs/index.js",
   "types": "./dist/index.d.ts",
@@ -56,7 +56,7 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^1.0.70",
+    "@github/copilot": "^1.0.71-2",
     "koffi": "^3.1.0",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.6"