@github/copilot-sdk 1.0.0-beta.8 → 1.0.0-beta.9

package/README.md

@@ -957,7 +957,7 @@ const session = await client.createSession({
             };
         },
 
-        // Called after each tool execution
+        // Called after each successful tool execution
         onPostToolUse: async (input, invocation) => {
             console.log(`Tool ${input.toolName} completed`);
             // Optionally modify the result or add context
@@ -966,6 +966,16 @@ const session = await client.createSession({
             };
         },
 
+        // Called after a tool execution whose result was "failure".
+        // onPostToolUse does NOT fire for failed tool calls — register this
+        // hook to observe them. Input includes `error` (the failure message
+        // extracted from the tool's result), not the full result object.
+        onPostToolUseFailure: async (input, invocation) => {
+            console.log(`Tool ${input.toolName} failed: ${input.error}`);
+            // Optionally append hidden guidance to the model.
+            return { additionalContext: "Suggest checking inputs and retrying." };
+        },
+
         // Called when user submits a prompt
         onUserPromptSubmitted: async (input, invocation) => {
             console.log(`User prompt: ${input.prompt}`);
@@ -1001,7 +1011,8 @@ const session = await client.createSession({
 **Available hooks:**
 
 - `onPreToolUse` - Intercept tool calls before execution. Can allow/deny or modify arguments.
-- `onPostToolUse` - Process tool results after execution. Can modify results or add context.
+- `onPostToolUse` - Process tool results after **successful** execution. Can modify results or add context.
+- `onPostToolUseFailure` - Observe and append hidden guidance to the model after tool executions whose result was `"failure"`. Register this in addition to `onPostToolUse` to see failed tool calls.
 - `onUserPromptSubmitted` - Intercept user prompts. Can modify the prompt before processing.
 - `onSessionStart` - Run logic when a session starts or resumes.
 - `onSessionEnd` - Cleanup or logging when session ends.

package/dist/cjs/client.js

@@ -34,6 +34,7 @@ var import_sdkProtocolVersion = require("./sdkProtocolVersion.js");
 var import_session = require("./session.js");
 var import_sessionFsProvider = require("./sessionFsProvider.js");
 var import_telemetry = require("./telemetry.js");
+var import_toolSet = require("./toolSet.js");
 var import_types = require("./types.js");
 const import_meta = {};
 const MIN_PROTOCOL_VERSION = 3;
@@ -67,6 +68,24 @@ function toWireCustomAgents(agents) {
     return { ...rest, mcpServers: toWireMcpServers(mcpServers) };
   });
 }
+function toolFilterListToArray(value) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return value instanceof import_toolSet.ToolSet ? value.toArray() : value;
+}
+function validateToolFilterList(field, list) {
+  if (!list) {
+    return;
+  }
+  for (const entry of list) {
+    if (entry === "*") {
+      throw new Error(
+        `Invalid ${field} entry '*': there is no bare wildcard. Use one or more of \`new ToolSet().addBuiltIn('*')\`, \`.addMcp('*')\`, or \`.addCustom('*')\` to target a specific source.`
+      );
+    }
+  }
+}
 function extractTransformCallbacks(systemMessage) {
   if (!systemMessage || systemMessage.mode !== "customize" || !systemMessage.sections) {
     return { wirePayload: systemMessage, transformCallbacks: void 0 };
@@ -249,8 +268,19 @@ class CopilotClient {
       telemetry: options.telemetry,
       baseDirectory: options.baseDirectory,
       sessionIdleTimeoutSeconds: options.sessionIdleTimeoutSeconds ?? 0,
-      enableRemoteSessions: options.enableRemoteSessions ?? false
+      enableRemoteSessions: options.enableRemoteSessions ?? false,
+      mode: options.mode ?? "copilot-cli"
     };
+    if (this.options.mode === "empty") {
+      const hasPersistence = this.options.baseDirectory !== void 0 || this.sessionFsConfig !== null || // External runtimes manage their own persistence layer; the SDK
+      // can't enforce it from here.
+      conn.kind === "uri" || conn.kind === "parent-process";
+      if (!hasPersistence) {
+        throw new Error(
+          "CopilotClient was created with mode: 'empty' but neither 'baseDirectory' nor 'sessionFs' was set. Empty mode requires an explicit per-session persistence location; pick one."
+        );
+      }
+    }
   }
   connectionExtraArgs = [];
   /**
@@ -560,10 +590,122 @@ class CopilotClient {
    * });
    * ```
    */
+  /**
+   * Normalizes session-level tool filter options. Converts {@link ToolSet}
+   * instances to plain string arrays, rejects misuse (bare `"*"`) and the
+   * missing-availableTools case in `mode = "empty"`.
+   *
+   * The SDK always sends `toolFilterPrecedence: "excluded"` so callers can
+   * compose include + exclude lists naturally (e.g. "everything matching X
+   * except Y") regardless of mode. Allowlist-precedence is intentionally not
+   * exposed — it's available on the runtime side as a CLI-only concession to
+   * legacy behavior, but SDK consumers always get the composable semantics.
+   *
+   * @internal
+   */
+  resolveToolFilterOptions(config) {
+    const availableTools = toolFilterListToArray(config.availableTools);
+    const excludedTools = toolFilterListToArray(config.excludedTools);
+    validateToolFilterList("availableTools", availableTools);
+    validateToolFilterList("excludedTools", excludedTools);
+    if (this.options.mode === "empty") {
+      if (availableTools === void 0) {
+        throw new Error(
+          "CopilotClient is in mode: 'empty' but the session config did not specify 'availableTools'. Empty mode requires every session to explicitly opt into the tools it wants \u2014 e.g. `new ToolSet().addBuiltIn(BuiltInTools.Isolated)`."
+        );
+      }
+    }
+    return { availableTools, excludedTools, toolFilterPrecedence: "excluded" };
+  }
+  /** Mode-specific defaults spread under the caller's config (app values win). */
+  configDefaultsForMode() {
+    if (this.options.mode === "empty") {
+      return { enableSessionTelemetry: false };
+    }
+    return {};
+  }
+  /**
+   * Returns the systemMessage config to use, adjusted for the current mode.
+   * In empty mode we ensure the environment_context section is removed
+   * unless the app has already taken control of it. `append` (and
+   * unspecified) mode is promoted to `customize` so we can also strip
+   * environment_context; the caller's `content` is preserved verbatim
+   * because the runtime appends it as additional instructions in both
+   * customize and append modes.
+   */
+  getSystemMessageConfigForMode(supplied) {
+    if (this.options.mode !== "empty") return supplied;
+    if (!supplied) {
+      return {
+        mode: "customize",
+        sections: { environment_context: { action: "remove" } }
+      };
+    }
+    switch (supplied.mode) {
+      case "replace":
+        return supplied;
+      case "customize":
+        if (supplied.sections?.environment_context) return supplied;
+        return {
+          ...supplied,
+          sections: {
+            ...supplied.sections,
+            environment_context: { action: "remove" }
+          }
+        };
+      case "append":
+      case void 0:
+        return {
+          mode: "customize",
+          content: supplied.content,
+          sections: { environment_context: { action: "remove" } }
+        };
+    }
+  }
+  /**
+   * Mode-specific options applied via session.options.update after create/resume.
+   *
+   * In empty mode, defaults the four overridable feature flags to safe values
+   * (caller values from `config` win). `installedPlugins=[]` is unconditional
+   * in empty mode — apps that need custom plugins should switch modes.
+   */
+  async updateSessionOptionsForMode(session, config) {
+    const patch = {};
+    if (this.options.mode === "empty") {
+      patch.skipCustomInstructions = config.skipCustomInstructions ?? true;
+      patch.customAgentsLocalOnly = config.customAgentsLocalOnly ?? true;
+      patch.coauthorEnabled = config.coauthorEnabled ?? false;
+      patch.manageScheduleEnabled = config.manageScheduleEnabled ?? false;
+      patch.installedPlugins = [];
+    } else {
+      if (config.skipCustomInstructions !== void 0)
+        patch.skipCustomInstructions = config.skipCustomInstructions;
+      if (config.customAgentsLocalOnly !== void 0)
+        patch.customAgentsLocalOnly = config.customAgentsLocalOnly;
+      if (config.coauthorEnabled !== void 0)
+        patch.coauthorEnabled = config.coauthorEnabled;
+      if (config.manageScheduleEnabled !== void 0)
+        patch.manageScheduleEnabled = config.manageScheduleEnabled;
+    }
+    if (Object.keys(patch).length === 0) {
+      return;
+    }
+    try {
+      await session.rpc.options.update(patch);
+    } catch (e) {
+      try {
+        await session.disconnect();
+      } catch {
+      }
+      throw e;
+    }
+  }
   async createSession(config) {
     if (!this.connection) {
       await this.start();
     }
+    config = { ...this.configDefaultsForMode(), ...config };
+    config.systemMessage = this.getSystemMessageConfigForMode(config.systemMessage);
     const sessionId = config.sessionId ?? (0, import_node_crypto.randomUUID)();
     const session = new import_session.CopilotSession(
       sessionId,
@@ -601,6 +743,7 @@ class CopilotClient {
     }
     this.sessions.set(sessionId, session);
     this.setupSessionFs(session, config);
+    const toolFilterOptions = this.resolveToolFilterOptions(config);
     try {
       const response = await this.connection.sendRequest("session.create", {
         ...await (0, import_telemetry.getTraceContext)(this.onGetTraceContext),
@@ -624,8 +767,9 @@ class CopilotClient {
           description: cmd.description
         })),
         systemMessage: wireSystemMessage,
-        availableTools: config.availableTools,
-        excludedTools: config.excludedTools,
+        availableTools: toolFilterOptions.availableTools,
+        excludedTools: toolFilterOptions.excludedTools,
+        toolFilterPrecedence: toolFilterOptions.toolFilterPrecedence,
         provider: config.provider,
         enableSessionTelemetry: config.enableSessionTelemetry,
         modelCapabilities: config.modelCapabilities,
@@ -656,6 +800,7 @@ class CopilotClient {
       const { workspacePath, capabilities } = response;
       session["_workspacePath"] = workspacePath;
       session.setCapabilities(capabilities);
+      await this.updateSessionOptionsForMode(session, config);
     } catch (e) {
       this.sessions.delete(sessionId);
       throw e;
@@ -715,6 +860,8 @@ class CopilotClient {
     if (config.hooks) {
       session.registerHooks(config.hooks);
     }
+    config = { ...this.configDefaultsForMode(), ...config };
+    config.systemMessage = this.getSystemMessageConfigForMode(config.systemMessage);
     const { wirePayload: wireSystemMessage, transformCallbacks } = extractTransformCallbacks(
       config.systemMessage
     );
@@ -726,6 +873,7 @@ class CopilotClient {
     }
     this.sessions.set(sessionId, session);
     this.setupSessionFs(session, config);
+    const toolFilterOptions = this.resolveToolFilterOptions(config);
     try {
       const response = await this.connection.sendRequest("session.resume", {
         ...await (0, import_telemetry.getTraceContext)(this.onGetTraceContext),
@@ -734,8 +882,9 @@ class CopilotClient {
         model: config.model,
         reasoningEffort: config.reasoningEffort,
         systemMessage: wireSystemMessage,
-        availableTools: config.availableTools,
-        excludedTools: config.excludedTools,
+        availableTools: toolFilterOptions.availableTools,
+        excludedTools: toolFilterOptions.excludedTools,
+        toolFilterPrecedence: toolFilterOptions.toolFilterPrecedence,
         enableSessionTelemetry: config.enableSessionTelemetry,
         tools: config.tools?.map((tool) => ({
           name: tool.name,
@@ -784,6 +933,7 @@ class CopilotClient {
       session["_workspacePath"] = workspacePath;
       session.setCapabilities(capabilities);
       session.setOpenCanvases(openCanvases ?? []);
+      await this.updateSessionOptionsForMode(session, config);
     } catch (e) {
       this.sessions.delete(sessionId);
       throw e;
@@ -1162,6 +1312,9 @@ class CopilotClient {
       if (this.options.baseDirectory) {
         envWithoutNodeDebug.COPILOT_HOME = this.options.baseDirectory;
       }
+      if (this.options.mode === "empty") {
+        envWithoutNodeDebug.COPILOT_DISABLE_KEYTAR = "1";
+      }
       if (!this.resolvedCliPath) {
         throw new Error(
           "Path to Copilot CLI is required. Please supply it via `RuntimeConnection.forStdio({ path })` or `RuntimeConnection.forTcp({ path })`, set the COPILOT_CLI_PATH environment variable, or use `RuntimeConnection.forUri(...)` to connect to an already-running runtime."

package/dist/cjs/generated/rpc.js

@@ -171,7 +171,7 @@ function createServerRpc(connection) {
       /**
        * Lists persisted sessions, optionally filtered by working-directory context.
        *
-       * @param params Optional metadata-load limit and context filter applied to the returned sessions.
+       * @param params Optional metadata-load limit and filters applied to the returned sessions.
        *
        * @returns Persisted sessions matching the filter, ordered most-recently-modified first.
        */
@@ -302,6 +302,17 @@ function createServerRpc(connection) {
        * @returns Replace the manager-wide additional plugins. New session creations and subsequent hook reloads see the new set; already-running sessions keep their existing hook installation until the next reload.
        */
       setAdditionalPlugins: async (params) => connection.sendRequest("sessions.setAdditionalPlugins", params)
+    },
+    /** @experimental */
+    agentRegistry: {
+      /**
+       * Spawns a managed-server child with the supplied configuration and returns a discriminated-union result. The caller (typically the CLI controller) is responsible for attaching to the spawned child and sending any follow-up prompt. When the controller-local spawn gate is closed the server returns JSON-RPC MethodNotFound.
+       *
+       * @param params Inputs to spawn a managed-server child via the controller's spawn delegate.
+       *
+       * @returns Outcome of an agentRegistry.spawn call.
+       */
+      spawn: async (params) => connection.sendRequest("agentRegistry.spawn", params)
     }
   };
 }
@@ -1060,6 +1071,20 @@ function createSessionRpc(connection, sessionId) {
        * @returns Indicates whether the operation succeeded.
        */
       setApproveAll: async (params) => connection.sendRequest("session.permissions.setApproveAll", { sessionId, ...params }),
+      /**
+       * Enables or disables full allow-all permissions (tools, paths, and URLs) for the session. Used by attach-mode clients (e.g. LocalRpcSession's `/allow-all` forwarder) to flip the target session's permission state. Unlike `setApproveAll`, this swaps in the unrestricted path and URL managers and emits `session.permissions_changed` on transition. The result returns the authoritative post-mutation state so callers can update their local mirrors without racing the `session.permissions_changed` notification on the same wire.
+       *
+       * @param params Whether to enable full allow-all permissions for the session.
+       *
+       * @returns Indicates whether the operation succeeded and reports the post-mutation state.
+       */
+      setAllowAll: async (params) => connection.sendRequest("session.permissions.setAllowAll", { sessionId, ...params }),
+      /**
+       * Returns whether full allow-all permissions are currently active for the session.
+       *
+       * @returns Current full allow-all permission state.
+       */
+      getAllowAll: async () => connection.sendRequest("session.permissions.getAllowAll", { sessionId }),
       /**
        * Adds or removes session-scoped or location-scoped permission rules.
        *

package/dist/cjs/index.js

@@ -18,12 +18,14 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var index_exports = {};
 __export(index_exports, {
+  BuiltInTools: () => import_toolSet.BuiltInTools,
   Canvas: () => import_canvas.Canvas,
   CanvasError: () => import_canvas.CanvasError,
   CopilotClient: () => import_client.CopilotClient,
   CopilotSession: () => import_session.CopilotSession,
   RuntimeConnection: () => import_types.RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS: () => import_types2.SYSTEM_MESSAGE_SECTIONS,
+  ToolSet: () => import_toolSet.ToolSet,
   approveAll: () => import_types2.approveAll,
   convertMcpCallToolResult: () => import_types2.convertMcpCallToolResult,
   createCanvas: () => import_canvas.createCanvas,
@@ -33,17 +35,20 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 var import_client = require("./client.js");
 var import_types = require("./types.js");
+var import_toolSet = require("./toolSet.js");
 var import_session = require("./session.js");
 var import_canvas = require("./canvas.js");
 var import_types2 = require("./types.js");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  BuiltInTools,
   Canvas,
   CanvasError,
   CopilotClient,
   CopilotSession,
   RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS,
+  ToolSet,
   approveAll,
   convertMcpCallToolResult,
   createCanvas,

package/dist/cjs/session.js

@@ -119,6 +119,7 @@ class CopilotSession {
       prompt: options.prompt,
       attachments: options.attachments,
       mode: options.mode,
+      agentMode: options.agentMode,
       requestHeaders: options.requestHeaders
     });
     return response.messageId;
@@ -739,6 +740,7 @@ class CopilotSession {
       preToolUse: this.hooks.onPreToolUse,
       preMcpToolCall: this.hooks.onPreMcpToolCall,
       postToolUse: this.hooks.onPostToolUse,
+      postToolUseFailure: this.hooks.onPostToolUseFailure,
       userPromptSubmitted: this.hooks.onUserPromptSubmitted,
       sessionStart: this.hooks.onSessionStart,
       sessionEnd: this.hooks.onSessionEnd,

package/dist/cjs/toolSet.js

@@ -0,0 +1,107 @@
+"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 toolSet_exports = {};
+__export(toolSet_exports, {
+  BuiltInTools: () => BuiltInTools,
+  ToolSet: () => ToolSet
+});
+module.exports = __toCommonJS(toolSet_exports);
+const VALID_TOOL_NAME = /^[a-zA-Z0-9_-]+$/;
+function validateName(kind, name) {
+  if (name === "*") {
+    return;
+  }
+  if (!VALID_TOOL_NAME.test(name)) {
+    throw new Error(
+      `Invalid ${kind} tool name '${name}': tool names must match /^[a-zA-Z0-9_-]+$/ or be the wildcard '*'.`
+    );
+  }
+}
+class ToolSet {
+  items = [];
+  addBuiltIn(nameOrNames) {
+    const names = typeof nameOrNames === "string" ? [nameOrNames] : nameOrNames;
+    for (const name of names) {
+      validateName("builtin", name);
+      this.items.push(`builtin:${name}`);
+    }
+    return this;
+  }
+  /**
+   * Adds a custom tool pattern. Matches tools registered via the SDK's
+   * `tools` option or via custom agents.
+   *
+   * @param name A specific custom tool name or `"*"` to match all custom tools.
+   */
+  addCustom(name) {
+    validateName("custom", name);
+    this.items.push(`custom:${name}`);
+    return this;
+  }
+  /**
+   * Adds an MCP tool pattern. Matches tools advertised by any configured
+   * MCP server.
+   *
+   * @param toolName The runtime's canonical wire name for the MCP tool
+   *   (e.g. `"github-list_issues"`), or `"*"` to match all MCP tools from
+   *   any server.
+   */
+  addMcp(toolName) {
+    validateName("mcp", toolName);
+    this.items.push(`mcp:${toolName}`);
+    return this;
+  }
+  /**
+   * Returns a defensive copy of the accumulated filter strings, suitable for
+   * passing as {@link SessionConfigBase.availableTools}.
+   */
+  toArray() {
+    return [...this.items];
+  }
+}
+const BuiltInTools = {
+  /**
+   * Built-in tools that operate only within the bounds of a single session —
+   * no host filesystem access outside the session, no cross-session state,
+   * no host environment access, no network. Safe to enable in `Mode = "empty"`
+   * scenarios (e.g. multi-tenant servers) without leaking host capabilities.
+   *
+   * **Contract:** tools in this set MUST NOT be extended (even behind options
+   * or args) to read or write state outside the session boundary. Adding
+   * cross-session or host-state behavior to one of these tools is a
+   * breaking change that requires removing it from this set.
+   */
+  Isolated: [
+    "ask_user",
+    "task_complete",
+    "exit_plan_mode",
+    "task",
+    "read_agent",
+    "write_agent",
+    "list_agents",
+    "send_inbox",
+    "context_board",
+    "skill"
+  ]
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BuiltInTools,
+  ToolSet
+});

package/dist/client.d.ts

@@ -190,34 +190,26 @@ export declare class CopilotClient {
      * ```
      */
     forceStop(): Promise<void>;
+    /** Mode-specific defaults spread under the caller's config (app values win). */
+    private configDefaultsForMode;
     /**
-     * Creates a new conversation session with the Copilot CLI.
-     *
-     * Sessions maintain conversation state, handle events, and manage tool execution.
-     * If the client is not connected, this method automatically starts the connection.
-     *
-     * @param config - Optional configuration for the session
-     * @returns A promise that resolves with the created session
-     * @throws Error if the client fails to start
-     *
-     * @example
-     * ```typescript
-     * // Basic session
-     * const session = await client.createSession({ onPermissionRequest: approveAll });
+     * Returns the systemMessage config to use, adjusted for the current mode.
+     * In empty mode we ensure the environment_context section is removed
+     * unless the app has already taken control of it. `append` (and
+     * unspecified) mode is promoted to `customize` so we can also strip
+     * environment_context; the caller's `content` is preserved verbatim
+     * because the runtime appends it as additional instructions in both
+     * customize and append modes.
+     */
+    private getSystemMessageConfigForMode;
+    /**
+     * Mode-specific options applied via session.options.update after create/resume.
      *
-     * // Session with model and tools
-     * const session = await client.createSession({
-     *   onPermissionRequest: approveAll,
-     *   model: "gpt-4",
-     *   tools: [{
-     *     name: "get_weather",
-     *     description: "Get weather for a location",
-     *     parameters: { type: "object", properties: { location: { type: "string" } } },
-     *     handler: async (args) => ({ temperature: 72 })
-     *   }]
-     * });
-     * ```
+     * In empty mode, defaults the four overridable feature flags to safe values
+     * (caller values from `config` win). `installedPlugins=[]` is unconditional
+     * in empty mode — apps that need custom plugins should switch modes.
      */
+    private updateSessionOptionsForMode;
     createSession(config: SessionConfig): Promise<CopilotSession>;
     /**
      * Resumes an existing conversation session by its ID.