@github/copilot-sdk 1.0.0-beta.1 → 1.0.0-beta.10

package/dist/cjs/index.js

@@ -18,25 +18,40 @@ 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,
-  SYSTEM_PROMPT_SECTIONS: () => import_types.SYSTEM_PROMPT_SECTIONS,
-  approveAll: () => import_types.approveAll,
-  convertMcpCallToolResult: () => import_types.convertMcpCallToolResult,
-  createSessionFsAdapter: () => import_types.createSessionFsAdapter,
-  defineTool: () => import_types.defineTool
+  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,
+  createSessionFsAdapter: () => import_types2.createSessionFsAdapter,
+  defineTool: () => import_types2.defineTool
 });
 module.exports = __toCommonJS(index_exports);
 var import_client = require("./client.js");
-var import_session = require("./session.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,
-  SYSTEM_PROMPT_SECTIONS,
+  RuntimeConnection,
+  SYSTEM_MESSAGE_SECTIONS,
+  ToolSet,
   approveAll,
   convertMcpCallToolResult,
+  createCanvas,
   createSessionFsAdapter,
   defineTool
 });

package/dist/cjs/session.js

@@ -18,14 +18,28 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var session_exports = {};
 __export(session_exports, {
-  CopilotSession: () => CopilotSession,
-  NO_RESULT_PERMISSION_V2_ERROR: () => NO_RESULT_PERMISSION_V2_ERROR
+  CopilotSession: () => CopilotSession
 });
 module.exports = __toCommonJS(session_exports);
 var import_node = require("vscode-jsonrpc/node.js");
 var import_rpc = require("./generated/rpc.js");
+var import_canvas = require("./canvas.js");
 var import_telemetry = require("./telemetry.js");
-const NO_RESULT_PERMISSION_V2_ERROR = "Permission handlers cannot return 'no-result' when connected to a protocol v2 server.";
+function deserializeHookInput(raw) {
+  if (!raw || typeof raw !== "object" || typeof raw.timestamp !== "number") {
+    return raw;
+  }
+  const obj = 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.
@@ -45,15 +59,19 @@ class CopilotSession {
   eventHandlers = /* @__PURE__ */ new Set();
   typedEventHandlers = /* @__PURE__ */ new Map();
   toolHandlers = /* @__PURE__ */ new Map();
+  canvases = /* @__PURE__ */ new Map();
   commandHandlers = /* @__PURE__ */ new Map();
   permissionHandler;
   userInputHandler;
   elicitationHandler;
+  exitPlanModeHandler;
+  autoModeSwitchHandler;
   hooks;
   transformCallbacks;
   _rpc = null;
   traceContextProvider;
   _capabilities = {};
+  openCanvasInstances = [];
   /** @internal Client session API handlers, populated by CopilotClient during create/resume. */
   clientSessionApis = {};
   /**
@@ -100,59 +118,22 @@ class CopilotSession {
       input: (message, options) => this._input(message, options)
     };
   }
-  /**
-   * Sends a message to this session and waits for the response.
-   *
-   * The message is processed asynchronously. Subscribe to events via {@link on}
-   * to receive streaming responses and other session events.
-   *
-   * @param options - The message options including the prompt and optional attachments
-   * @returns A promise that resolves with the message ID of the response
-   * @throws Error if the session has been disconnected or the connection fails
-   *
-   * @example
-   * ```typescript
-   * const messageId = await session.send({
-   *   prompt: "Explain this code",
-   *   attachments: [{ type: "file", path: "./src/index.ts" }]
-   * });
-   * ```
-   */
-  async send(options) {
+  async send(optionsOrPrompt) {
+    const options = typeof optionsOrPrompt === "string" ? { prompt: optionsOrPrompt } : optionsOrPrompt;
     const response = await this.connection.sendRequest("session.send", {
       ...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;
   }
-  /**
-   * Sends a message to this session and waits until the session becomes idle.
-   *
-   * This is a convenience method that combines {@link send} with waiting for
-   * the `session.idle` event. Use this when you want to block until the
-   * assistant has finished processing the message.
-   *
-   * Events are still delivered to handlers registered via {@link on} while waiting.
-   *
-   * @param options - The message options including the prompt and optional attachments
-   * @param timeout - Timeout in milliseconds (default: 60000). Controls how long to wait; does not abort in-flight agent work.
-   * @returns A promise that resolves with the final assistant message when the session becomes idle,
-   *          or undefined if no assistant message was received
-   * @throws Error if the timeout is reached before the session becomes idle
-   * @throws Error if the session has been disconnected or the connection fails
-   *
-   * @example
-   * ```typescript
-   * // Send and wait for completion with default 60s timeout
-   * const response = await session.sendAndWait({ prompt: "What is 2+2?" });
-   * console.log(response?.data.content); // "4"
-   * ```
-   */
-  async sendAndWait(options, timeout) {
+  async sendAndWait(optionsOrPrompt, timeout) {
+    const options = typeof optionsOrPrompt === "string" ? { prompt: optionsOrPrompt } : optionsOrPrompt;
     const effectiveTimeout = timeout ?? 6e4;
     let resolveIdle;
     let rejectWithError;
@@ -293,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);
     }
   }
   /**
@@ -395,8 +395,8 @@ class CopilotSession {
   /**
    * Registers custom tool handlers for this session.
    *
-   * Tools allow the assistant to execute custom functions. When the assistant
-   * invokes a tool, the corresponding handler is called with the tool arguments.
+   * Tools with handlers allow the assistant to execute custom functions automatically.
+   * Declaration-only tools are surfaced as events and left pending for the consumer.
    *
    * @param tools - An array of tool definitions with their handlers, or undefined to clear all tools
    * @internal This method is typically called internally when creating a session with tools.
@@ -407,7 +407,9 @@ class CopilotSession {
       return;
     }
     for (const tool of tools) {
-      this.toolHandlers.set(tool.name, tool.handler);
+      if (tool.handler) {
+        this.toolHandlers.set(tool.name, tool.handler);
+      }
     }
   }
   /**
@@ -420,6 +422,61 @@ class CopilotSession {
   getToolHandler(name) {
     return this.toolHandlers.get(name);
   }
+  /**
+   * Registers canvas declarations and handlers for this session.
+   *
+   * @param canvases - Canvases created via `createCanvas`, or undefined to clear all canvases
+   * @internal Called by the SDK when creating/resuming a session with `canvases`.
+   */
+  registerCanvases(canvases) {
+    this.canvases.clear();
+    if (!canvases || canvases.length === 0) {
+      delete this.clientSessionApis.canvas;
+      return;
+    }
+    for (const canvas of canvases) {
+      this.canvases.set(canvas.declaration.id, canvas);
+    }
+    const self = this;
+    this.clientSessionApis.canvas = {
+      async open(params) {
+        const canvas = self.canvases.get(params.canvasId);
+        if (!canvas) throw new Error(`No canvas registered with id "${params.canvasId}"`);
+        try {
+          return await canvas.open(params) ?? {};
+        } catch (error) {
+          throw toCanvasRpcError(error);
+        }
+      },
+      async close(params) {
+        const canvas = self.canvases.get(params.canvasId);
+        if (!canvas) throw new Error(`No canvas registered with id "${params.canvasId}"`);
+        try {
+          if (canvas.onClose) {
+            await canvas.onClose(params);
+          }
+        } catch (error) {
+          throw toCanvasRpcError(error);
+        }
+      },
+      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);
+        if (!handler) {
+          throw new import_canvas.CanvasError(
+            "canvas_action_no_handler",
+            "No handler implemented for this canvas action"
+          );
+        }
+        try {
+          return await handler(params);
+        } catch (error) {
+          throw toCanvasRpcError(error);
+        }
+      }
+    };
+  }
   /**
    * Registers command handlers for this session.
    *
@@ -444,6 +501,24 @@ class CopilotSession {
   registerElicitationHandler(handler) {
     this.elicitationHandler = handler;
   }
+  /**
+   * Registers the exit-plan-mode handler for this session.
+   *
+   * @param handler - The handler to invoke when the server dispatches an exit-plan-mode request
+   * @internal This method is typically called internally when creating/resuming a session.
+   */
+  registerExitPlanModeHandler(handler) {
+    this.exitPlanModeHandler = handler;
+  }
+  /**
+   * Registers the auto-mode-switch handler for this session.
+   *
+   * @param handler - The handler to invoke when the server dispatches an auto-mode-switch request
+   * @internal This method is typically called internally when creating/resuming a session.
+   */
+  registerAutoModeSwitchHandler(handler) {
+    this.autoModeSwitchHandler = handler;
+  }
   /**
    * Handles an elicitation.requested broadcast event.
    * Invokes the registered handler and responds via handlePendingElicitation RPC.
@@ -469,6 +544,26 @@ class CopilotSession {
       }
     }
   }
+  /**
+   * Handles an exitPlanMode.request callback from the runtime.
+   * @internal
+   */
+  async _handleExitPlanModeRequest(request) {
+    if (!this.exitPlanModeHandler) {
+      return { approved: true };
+    }
+    return await this.exitPlanModeHandler(request, { sessionId: this.sessionId });
+  }
+  /**
+   * Handles an autoModeSwitch.request callback from the runtime.
+   * @internal
+   */
+  async _handleAutoModeSwitchRequest(request) {
+    if (!this.autoModeSwitchHandler) {
+      return "no";
+    }
+    return await this.autoModeSwitchHandler(request, { sessionId: this.sessionId });
+  }
   /**
    * Sets the host capabilities for this session.
    *
@@ -478,6 +573,24 @@ class CopilotSession {
   setCapabilities(capabilities) {
     this._capabilities = capabilities ?? {};
   }
+  /**
+   * 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];
+  }
+  /**
+   * Sets the open-canvas snapshot for this session.
+   *
+   * @param instances - The `openCanvases` array from the `session.resume` response.
+   * @internal This method is typically called internally when resuming a session.
+   */
+  setOpenCanvases(instances) {
+    this.openCanvasInstances = [...instances];
+  }
   assertElicitation() {
     if (!this._capabilities.ui?.elicitation) {
       throw new Error(
@@ -617,33 +730,6 @@ class CopilotSession {
     }
     return { sections: result };
   }
-  /**
-   * Handles a permission request in the v2 protocol format (synchronous RPC).
-   * Used as a back-compat adapter when connected to a v2 server.
-   *
-   * @param request - The permission request data from the CLI
-   * @returns A promise that resolves with the permission decision
-   * @internal This method is for internal use by the SDK.
-   */
-  async _handlePermissionRequestV2(request) {
-    if (!this.permissionHandler) {
-      return { kind: "user-not-available" };
-    }
-    try {
-      const result = await this.permissionHandler(request, {
-        sessionId: this.sessionId
-      });
-      if (result.kind === "no-result") {
-        throw new Error(NO_RESULT_PERMISSION_V2_ERROR);
-      }
-      return result;
-    } catch (error) {
-      if (error instanceof Error && error.message === NO_RESULT_PERMISSION_V2_ERROR) {
-        throw error;
-      }
-      return { kind: "user-not-available" };
-    }
-  }
   /**
    * Handles a user input request from the Copilot CLI.
    *
@@ -676,9 +762,12 @@ class CopilotSession {
     if (!this.hooks) {
       return void 0;
     }
+    const normalized = deserializeHookInput(input);
     const handlerMap = {
       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,
@@ -689,7 +778,7 @@ class CopilotSession {
       return void 0;
     }
     try {
-      const result = await handler(input, { sessionId: this.sessionId });
+      const result = await handler(normalized, { sessionId: this.sessionId });
       return result;
     } catch (_error) {
       return void 0;
@@ -706,7 +795,7 @@ class CopilotSession {
    *
    * @example
    * ```typescript
-   * const events = await session.getMessages();
+   * const events = await session.getEvents();
    * for (const event of events) {
    *   if (event.type === "assistant.message") {
    *     console.log("Assistant:", event.data.content);
@@ -714,7 +803,7 @@ class CopilotSession {
    * }
    * ```
    */
-  async getMessages() {
+  async getEvents() {
     const response = await this.connection.sendRequest("session.getMessages", {
       sessionId: this.sessionId
     });
@@ -749,18 +838,10 @@ class CopilotSession {
     this.typedEventHandlers.clear();
     this.toolHandlers.clear();
     this.permissionHandler = void 0;
-  }
-  /**
-   * @deprecated Use {@link disconnect} instead. This method will be removed in a future release.
-   *
-   * Disconnects this session and releases all in-memory resources.
-   * Session data on disk is preserved for later resumption.
-   *
-   * @returns A promise that resolves when the session is disconnected
-   * @throws Error if the connection fails
-   */
-  async destroy() {
-    return this.disconnect();
+    this.userInputHandler = void 0;
+    this.elicitationHandler = void 0;
+    this.exitPlanModeHandler = void 0;
+    this.autoModeSwitchHandler = void 0;
   }
   /** Enables `await using session = ...` syntax for automatic cleanup. */
   async [Symbol.asyncDispose]() {
@@ -846,8 +927,13 @@ function isToolResultObject(value) {
   ];
   return allowedResultTypes.includes(value.resultType);
 }
+function toCanvasRpcError(error) {
+  if (error instanceof import_node.ResponseError) return error;
+  const code = error instanceof import_canvas.CanvasError ? error.code : "canvas_handler_error";
+  const message = error instanceof Error ? error.message : String(error);
+  return new import_node.ResponseError(import_node.ErrorCodes.InternalError, message, { code, message });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  CopilotSession,
-  NO_RESULT_PERMISSION_V2_ERROR
+  CopilotSession
 });

package/dist/cjs/sessionFsProvider.js

@@ -21,6 +21,18 @@ __export(sessionFsProvider_exports, {
   createSessionFsAdapter: () => createSessionFsAdapter
 });
 module.exports = __toCommonJS(sessionFsProvider_exports);
+function normalizeSqliteParams(params) {
+  if (!params) {
+    return void 0;
+  }
+  const normalized = {};
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== void 0) {
+      normalized[key] = value;
+    }
+  }
+  return normalized;
+}
 function createSessionFsAdapter(provider) {
   return {
     readFile: async ({ path }) => {
@@ -107,6 +119,28 @@ function createSessionFsAdapter(provider) {
       } catch (err) {
         return toSessionFsError(err);
       }
+    },
+    // Unlike the FS methods above, SQLite methods let errors propagate to the JSON-RPC layer
+    // rather than catching and mapping via toSessionFsError. The FS error mapping is specifically
+    // for translating Node.js errno codes (e.g., ENOENT) into SessionFsError, which isn't
+    // meaningful for SQL errors. Letting exceptions propagate preserves the original error
+    // message in the JSON-RPC error response.
+    sqliteQuery: async ({ queryType, query, params: bindParams }) => {
+      if (!provider.sqlite) {
+        throw new Error("SQLite is not supported by this provider");
+      }
+      const result = await provider.sqlite.query(
+        queryType,
+        query,
+        normalizeSqliteParams(bindParams)
+      );
+      return result ?? { rows: [], columns: [], rowsAffected: 0 };
+    },
+    sqliteExists: async () => {
+      if (!provider.sqlite) {
+        throw new Error("SQLite is not supported by this provider");
+      }
+      return { exists: await provider.sqlite.exists() };
     }
   };
 }

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
+});