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

package/dist/cjs/generated/rpc.js

@@ -111,7 +111,11 @@ function createServerRpc(connection) {
          *
          * @param params MCP server names to disable for new sessions.
          */
-        disable: async (params) => connection.sendRequest("mcp.config.disable", params)
+        disable: async (params) => connection.sendRequest("mcp.config.disable", params),
+        /**
+         * Drops this runtime process's in-memory MCP server-definition cache so the next MCP config read observes disk.
+         */
+        reload: async () => connection.sendRequest("mcp.config.reload", {})
       },
       /**
        * Discovers MCP servers from user, workspace, plugin, and builtin sources.
@@ -140,6 +144,20 @@ function createServerRpc(connection) {
        */
       discover: async (params) => connection.sendRequest("skills.discover", params)
     },
+    user: {
+      settings: {
+        /**
+         * Drops this runtime process's in-memory user settings cache so the next settings read observes disk.
+         */
+        reload: async () => connection.sendRequest("user.settings.reload", {})
+      }
+    },
+    runtime: {
+      /**
+       * Gracefully shuts down an SDK-owned runtime. The response is sent only after cleanup completes; callers may then terminate the owned runtime process.
+       */
+      shutdown: async () => connection.sendRequest("runtime.shutdown", {})
+    },
     sessionFs: {
       /**
        * Registers an SDK client as the session filesystem provider.
@@ -171,7 +189,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 +320,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)
     }
   };
 }
@@ -398,27 +427,30 @@ function createSessionRpc(connection, sessionId) {
        * @param params Canvas close parameters.
        */
       close: async (params) => connection.sendRequest("session.canvas.close", { sessionId, ...params }),
-      /**
-       * Invokes an action on an open canvas instance.
-       *
-       * @param params Canvas action invocation parameters.
-       *
-       * @returns Canvas action invocation result.
-       */
-      invokeAction: async (params) => connection.sendRequest("session.canvas.invokeAction", { sessionId, ...params })
+      /** @experimental */
+      action: {
+        /**
+         * Invokes an action on an open canvas instance.
+         *
+         * @param params Canvas action invocation parameters.
+         *
+         * @returns Canvas action invocation result.
+         */
+        invoke: async (params) => connection.sendRequest("session.canvas.action.invoke", { sessionId, ...params })
+      }
     },
     /** @experimental */
     model: {
       /**
        * Gets the currently selected model for the session.
        *
-       * @returns The currently selected model and reasoning effort for the session.
+       * @returns The currently selected model, reasoning effort, and context tier for the session. The context tier reflects `Session.getContextTier()`, restored from the session journal on resume.
        */
       getCurrent: async () => connection.sendRequest("session.model.getCurrent", { sessionId }),
       /**
        * Switches the session to a model and optional reasoning configuration.
        *
-       * @param params Target model identifier and optional reasoning effort, summary, and capability overrides.
+       * @param params Target model identifier and optional reasoning effort, summary, capability overrides, and context tier.
        *
        * @returns The model identifier active on the session after the switch.
        */
@@ -430,7 +462,15 @@ function createSessionRpc(connection, sessionId) {
        *
        * @returns Update the session's reasoning effort without changing the selected model. Use `switchTo` instead when you also need to change the model. The runtime stores the effort on the session and applies it to subsequent turns.
        */
-      setReasoningEffort: async (params) => connection.sendRequest("session.model.setReasoningEffort", { sessionId, ...params })
+      setReasoningEffort: async (params) => connection.sendRequest("session.model.setReasoningEffort", { sessionId, ...params }),
+      /**
+       * Lists models available to this session using its own auth and integration context. Connected hosts (CLI TUI, GitHub App) should call this through the session client so remote sessions return the remote CLI's available models rather than the caller's.
+       *
+       * @param params Optional listing options.
+       *
+       * @returns The list of models available to this session.
+       */
+      list: async (params) => connection.sendRequest("session.model.list", { sessionId, ...params })
     },
     /** @experimental */
     mode: {
@@ -884,7 +924,13 @@ function createSessionRpc(connection, sessionId) {
       /**
        * Reloads extension definitions and processes for the session.
        */
-      reload: async () => connection.sendRequest("session.extensions.reload", { sessionId })
+      reload: async () => connection.sendRequest("session.extensions.reload", { sessionId }),
+      /**
+       * Push attachments into the next user-message turn from an extension. The host should surface them as composer pills and forward them via the next session.send call. Callable only by extension-owned connections.
+       *
+       * @param params Parameters for session.extensions.sendAttachmentsToMessage.
+       */
+      sendAttachmentsToMessage: async (params) => connection.sendRequest("session.extensions.sendAttachmentsToMessage", { sessionId, ...params })
     },
     /** @experimental */
     tools: {
@@ -901,7 +947,13 @@ function createSessionRpc(connection, sessionId) {
        *
        * @returns Resolve, build, and validate the runtime tool list for this session. Subagent sessions and consumer flows that need an initialized tool set before `send` invoke this. Default base-class implementation is a no-op for sessions that don't support tool validation.
        */
-      initializeAndValidate: async () => connection.sendRequest("session.tools.initializeAndValidate", { sessionId })
+      initializeAndValidate: async () => connection.sendRequest("session.tools.initializeAndValidate", { sessionId }),
+      /**
+       * Returns lightweight metadata for the session's currently initialized tools.
+       *
+       * @returns Current lightweight tool metadata snapshot for the session.
+       */
+      getCurrentMetadata: async () => connection.sendRequest("session.tools.getCurrentMetadata", { sessionId })
     },
     /** @experimental */
     commands: {
@@ -1060,6 +1112,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.
        *
@@ -1476,10 +1542,10 @@ function registerClientSessionApiHandlers(connection, getHandlers) {
     if (!handler) throw new Error(`No canvas handler registered for session: ${params.sessionId}`);
     return handler.close(params);
   });
-  connection.onRequest("canvas.invokeAction", async (params) => {
+  connection.onRequest("canvas.action.invoke", async (params) => {
     const handler = getHandlers(params.sessionId).canvas;
     if (!handler) throw new Error(`No canvas handler registered for session: ${params.sessionId}`);
-    return handler.invokeAction(params);
+    return handler.invoke(params);
   });
 }
 // Annotate the CommonJS export names for ESM import in node:

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

@@ -33,6 +33,13 @@ function deserializeHookInput(raw) {
   const { cwd, ...rest } = obj;
   return { ...rest, timestamp: new Date(obj.timestamp), workingDirectory: cwd };
 }
+function isOpenCanvasInstance(value) {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  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 && typeof instance.reopen === "boolean" && (instance.availability === "ready" || instance.availability === "stale");
+}
 class CopilotSession {
   /**
    * Creates a new CopilotSession instance.
@@ -117,8 +124,10 @@ class CopilotSession {
       ...await (0, import_telemetry.getTraceContext)(this.traceContextProvider),
       sessionId: this.sessionId,
       prompt: options.prompt,
+      displayPrompt: options.displayPrompt,
       attachments: options.attachments,
       mode: options.mode,
+      agentMode: options.agentMode,
       requestHeaders: options.requestHeaders
     });
     return response.messageId;
@@ -265,6 +274,25 @@ class CopilotSession {
       }
     } else if (event.type === "capabilities.changed") {
       this._capabilities = { ...this._capabilities, ...event.data };
+    } else if (event.type === "session.canvas.opened") {
+      this.upsertOpenCanvasFromEvent(event.data);
+    }
+  }
+  upsertOpenCanvasFromEvent(data) {
+    if (!isOpenCanvasInstance(data)) {
+      console.warn("failed to deserialize session.canvas.opened payload");
+      return;
+    }
+    this.upsertOpenCanvas(data);
+  }
+  upsertOpenCanvas(instance) {
+    const index = this.openCanvasInstances.findIndex(
+      (open) => open.instanceId === instance.instanceId
+    );
+    if (index >= 0) {
+      this.openCanvasInstances[index] = instance;
+    } else {
+      this.openCanvasInstances.push(instance);
     }
   }
   /**
@@ -431,7 +459,7 @@ class CopilotSession {
           throw toCanvasRpcError(error);
         }
       },
-      async invokeAction(params) {
+      async invoke(params) {
         const canvas = self.canvases.get(params.canvasId);
         if (!canvas) throw new Error(`No canvas registered with id "${params.canvasId}"`);
         const handler = canvas.actionHandlers.get(params.actionName);
@@ -546,10 +574,10 @@ class CopilotSession {
     this._capabilities = capabilities ?? {};
   }
   /**
-   * Snapshot of canvas instances that were already open when the session was
-   * resumed. Populated from the `session.resume` response; empty for freshly
-   * created sessions. Returns a defensive copy — mutating the returned array
-   * has no effect on the session.
+   * Snapshot of canvas instances currently known to be open for this session.
+   * Populated from the `session.resume` response and live `session.canvas.opened`
+   * events. Returns a defensive copy — mutating the returned array has no effect
+   * on the session.
    */
   get openCanvases() {
     return [...this.openCanvasInstances];
@@ -739,6 +767,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.