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

package/dist/session.js

@@ -1,7 +1,22 @@
-import { ConnectionError, ResponseError } from "vscode-jsonrpc/node.js";
+import { ConnectionError, ErrorCodes, ResponseError } from "vscode-jsonrpc/node.js";
 import { createSessionRpc } from "./generated/rpc.js";
+import { CanvasError } from "./canvas.js";
 import { getTraceContext } from "./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.
@@ -21,15 +36,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 = {};
   /**
@@ -76,59 +95,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 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;
@@ -269,6 +251,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);
     }
   }
   /**
@@ -371,8 +372,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.
@@ -383,7 +384,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);
+      }
     }
   }
   /**
@@ -396,6 +399,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 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.
    *
@@ -420,6 +478,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.
@@ -445,6 +521,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.
    *
@@ -454,6 +550,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(
@@ -593,33 +707,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.
    *
@@ -652,9 +739,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,
@@ -665,7 +755,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;
@@ -682,7 +772,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);
@@ -690,7 +780,7 @@ class CopilotSession {
    * }
    * ```
    */
-  async getMessages() {
+  async getEvents() {
     const response = await this.connection.sendRequest("session.getMessages", {
       sessionId: this.sessionId
     });
@@ -725,18 +815,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]() {
@@ -822,7 +904,12 @@ function isToolResultObject(value) {
   ];
   return allowedResultTypes.includes(value.resultType);
 }
+function toCanvasRpcError(error) {
+  if (error instanceof ResponseError) return error;
+  const code = error instanceof CanvasError ? error.code : "canvas_handler_error";
+  const message = error instanceof Error ? error.message : String(error);
+  return new ResponseError(ErrorCodes.InternalError, message, { code, message });
+}
 export {
-  CopilotSession,
-  NO_RESULT_PERMISSION_V2_ERROR
+  CopilotSession
 };

package/dist/sessionFsProvider.d.ts

@@ -1,4 +1,5 @@
-import type { SessionFsHandler, SessionFsStatResult, SessionFsReaddirWithTypesEntry } from "./generated/rpc.js";
+import type { SessionFsHandler, SessionFsStatResult, SessionFsReaddirWithTypesEntry, SessionFsSqliteQueryResult as GeneratedSqliteQueryResult, SessionFsSqliteQueryType } from "./generated/rpc.js";
+export type { SessionFsSqliteQueryType };
 /**
  * File metadata returned by {@link SessionFsProvider.stat}.
  * Same shape as the generated {@link SessionFsStatResult} but without the
@@ -6,7 +7,31 @@ import type { SessionFsHandler, SessionFsStatResult, SessionFsReaddirWithTypesEn
  */
 export type SessionFsFileInfo = Omit<SessionFsStatResult, "error">;
 /**
- * Interface for session filesystem providers. Implementors use idiomatic
+ * Result of a SQLite query execution via {@link SessionFsSqliteProvider.query}.
+ * Same shape as the generated {@link GeneratedSqliteQueryResult} but without the
+ * `error` field, since providers signal errors by throwing.
+ */
+export type SessionFsSqliteQueryResult = Omit<GeneratedSqliteQueryResult, "error">;
+/**
+ * SQLite operations for the per-session database.
+ * Implementers provide query execution and existence checking.
+ */
+export interface SessionFsSqliteProvider {
+    /**
+     * Execute a SQLite query against the per-session database.
+     *
+     * @param queryType - How to execute: `"exec"` for DDL/multi-statement, `"query"` for SELECT, `"run"` for INSERT/UPDATE/DELETE.
+     * @param query - SQL query to execute.
+     * @param params - Optional named bind parameters.
+     */
+    query(queryType: SessionFsSqliteQueryType, query: string, params?: Record<string, string | number | null>): Promise<SessionFsSqliteQueryResult | undefined>;
+    /**
+     * Check whether the per-session database already exists, without creating it.
+     */
+    exists(): Promise<boolean>;
+}
+/**
+ * Interface for session filesystem providers. Implementers use idiomatic
  * TypeScript patterns: throw on error, return values directly. Use
  * {@link createSessionFsAdapter} to convert a provider into the
  * {@link SessionFsHandler} expected by the SDK.
@@ -35,6 +60,8 @@ export interface SessionFsProvider {
     rm(path: string, recursive: boolean, force: boolean): Promise<void>;
     /** Renames/moves a file or directory. */
     rename(src: string, dest: string): Promise<void>;
+    /** Per-session SQLite database operations. Optional — omit if the provider does not support SQLite. */
+    sqlite?: SessionFsSqliteProvider;
 }
 /**
  * Wraps a {@link SessionFsProvider} into the {@link SessionFsHandler}

package/dist/sessionFsProvider.js

@@ -1,3 +1,15 @@
+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 }) => {
@@ -84,6 +96,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/toolSet.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Builder that produces a list of source-qualified tool filter strings for
+ * {@link SessionConfigBase.availableTools}.
+ *
+ * Tools are classified by the runtime at registration time (not from name
+ * parsing), so `addBuiltIn("foo")` matches only tools the runtime registered
+ * as built-in, even if an MCP server or custom-agent extension happens to
+ * register a tool with the same wire name.
+ *
+ * @example
+ * ```typescript
+ * const tools = new ToolSet()
+ *     .addBuiltIn(BuiltInTools.Isolated)
+ *     .addMcp("*")
+ *     .addCustom("*");
+ *
+ * const session = await client.createSession({
+ *     availableTools: tools,
+ *     // ...
+ * });
+ * ```
+ */
+export declare class ToolSet {
+    private readonly items;
+    /**
+     * Adds one or more built-in tool patterns.
+     *
+     * @param name A specific built-in tool name (e.g. `"bash"`) or `"*"` to match all
+     *   built-in tools.
+     */
+    addBuiltIn(name: string): ToolSet;
+    /**
+     * Adds a list of built-in tool patterns (e.g. {@link BuiltInTools.Isolated}).
+     */
+    addBuiltIn(names: readonly string[]): ToolSet;
+    /**
+     * 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: string): ToolSet;
+    /**
+     * 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: string): ToolSet;
+    /**
+     * Returns a defensive copy of the accumulated filter strings, suitable for
+     * passing as {@link SessionConfigBase.availableTools}.
+     */
+    toArray(): string[];
+}
+/**
+ * Curated sets of built-in tool names for common scenarios. Each constant is
+ * meant to be passed to {@link ToolSet.addBuiltIn}.
+ */
+export declare 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.
+     */
+    readonly Isolated: readonly string[];
+};

package/dist/toolSet.js

@@ -0,0 +1,82 @@
+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"
+  ]
+};
+export {
+  BuiltInTools,
+  ToolSet
+};