@github/copilot-sdk 1.0.0-beta.5 → 1.0.0-beta.7

package/dist/cjs/extension.js

@@ -18,11 +18,15 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var extension_exports = {};
 __export(extension_exports, {
+  Canvas: () => import_canvas.Canvas,
+  CanvasError: () => import_canvas.CanvasError,
+  createCanvas: () => import_canvas.createCanvas,
   joinSession: () => joinSession
 });
 module.exports = __toCommonJS(extension_exports);
 var import_client = require("./client.js");
 var import_types = require("./types.js");
+var import_canvas = require("./canvas.js");
 async function joinSession(config = {}) {
   const sessionId = process.env.SESSION_ID;
   if (!sessionId) {
@@ -30,14 +34,17 @@ async function joinSession(config = {}) {
       "joinSession() is intended for extensions running as child processes of the Copilot CLI."
     );
   }
-  const client = new import_client.CopilotClient({ isChildProcess: true });
+  const client = new import_client.CopilotClient({ _internalConnection: { kind: "parent-process" } });
   return client.resumeSession(sessionId, {
     ...config,
     onPermissionRequest: config.onPermissionRequest ?? import_types.defaultJoinSessionPermissionHandler,
-    disableResume: config.disableResume ?? true
+    suppressResumeEvent: config.suppressResumeEvent ?? true
   });
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  Canvas,
+  CanvasError,
+  createCanvas,
   joinSession
 });

package/dist/cjs/generated/rpc.js

@@ -64,6 +64,16 @@ function createServerRpc(connection) {
        */
       getQuota: async (params) => connection.sendRequest("account.getQuota", params)
     },
+    secrets: {
+      /**
+       * Registers secret values for redaction in session logs and exports. The SDK calls this to inject dynamically generated secret values (e.g., OIDC tokens).
+       *
+       * @param params Secret values to add to the redaction filter.
+       *
+       * @returns Confirmation that the secret values were registered.
+       */
+      addFilterValues: async (params) => connection.sendRequest("secrets.addFilterValues", params)
+    },
     mcp: {
       config: {
         /**
@@ -361,6 +371,43 @@ function createSessionRpc(connection, sessionId) {
       setCredentials: async (params) => connection.sendRequest("session.auth.setCredentials", { sessionId, ...params })
     },
     /** @experimental */
+    canvas: {
+      /**
+       * Lists canvases declared for the session.
+       *
+       * @returns Declared canvases available in this session.
+       */
+      list: async () => connection.sendRequest("session.canvas.list", { sessionId }),
+      /**
+       * Lists currently open canvas instances for the live session.
+       *
+       * @returns Live open-canvas snapshot.
+       */
+      listOpen: async () => connection.sendRequest("session.canvas.listOpen", { sessionId }),
+      /**
+       * Opens or focuses a canvas instance.
+       *
+       * @param params Canvas open parameters.
+       *
+       * @returns Open canvas instance snapshot.
+       */
+      open: async (params) => connection.sendRequest("session.canvas.open", { sessionId, ...params }),
+      /**
+       * Closes an open canvas instance.
+       *
+       * @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 */
     model: {
       /**
        * Gets the currently selected model for the session.
@@ -728,6 +775,53 @@ function createSessionRpc(connection, sessionId) {
          * @returns OAuth authorization URL the caller should open, or empty when cached tokens already authenticated the server.
          */
         login: async (params) => connection.sendRequest("session.mcp.oauth.login", { sessionId, ...params })
+      },
+      /** @experimental */
+      apps: {
+        /**
+         * Fetch an MCP resource (typically a `ui://` MCP App bundle, per SEP-1865) from a connected server. Requires the `mcp-apps` session capability.
+         *
+         * @param params MCP server and resource URI to fetch.
+         *
+         * @returns Resource contents returned by the MCP server.
+         */
+        readResource: async (params) => connection.sendRequest("session.mcp.apps.readResource", { sessionId, ...params }),
+        /**
+         * List tools that an MCP App view is allowed to call (SEP-1865 visibility filter). Returns tools whose `_meta.ui.visibility` is unset (default `["model","app"]`) or includes `"app"`.
+         *
+         * @param params MCP server to list app-callable tools for.
+         *
+         * @returns App-callable tools from the named MCP server.
+         */
+        listTools: async (params) => connection.sendRequest("session.mcp.apps.listTools", { sessionId, ...params }),
+        /**
+         * Call an MCP tool from an MCP App view (SEP-1865). Enforces the visibility check that prevents an app iframe from invoking model-only tools. Returns the standard MCP `CallToolResult`.
+         *
+         * @param params MCP server, tool name, and arguments to invoke from an MCP App view.
+         *
+         * @returns Standard MCP CallToolResult
+         */
+        callTool: async (params) => connection.sendRequest("session.mcp.apps.callTool", { sessionId, ...params }),
+        /**
+         * Replace the host context returned to MCP App guests on `ui/initialize`. Hosts use this to advertise theme, locale, or other metadata to the guest UI.
+         *
+         * @param params Host context to advertise to MCP App guests.
+         */
+        setHostContext: async (params) => connection.sendRequest("session.mcp.apps.setHostContext", { sessionId, ...params }),
+        /**
+         * Read the current host context advertised to MCP App guests.
+         *
+         * @returns Current host context advertised to MCP App guests.
+         */
+        getHostContext: async () => connection.sendRequest("session.mcp.apps.getHostContext", { sessionId }),
+        /**
+         * Diagnose MCP Apps wiring for a specific MCP server. Reports the session capability, feature-flag state, advertised extension, and how many tools have `_meta.ui` populated.
+         *
+         * @param params MCP server to diagnose MCP Apps wiring for.
+         *
+         * @returns Diagnostic snapshot of MCP Apps wiring for the named server.
+         */
+        diagnose: async (params) => connection.sendRequest("session.mcp.apps.diagnose", { sessionId, ...params })
       }
     },
     /** @experimental */
@@ -1168,9 +1262,11 @@ function createSessionRpc(connection, sessionId) {
       /**
        * Compacts the session history to reduce context usage.
        *
+       * @param params Optional compaction parameters.
+       *
        * @returns Compaction outcome with the number of tokens and messages removed, summary text, and the resulting context window breakdown.
        */
-      compact: async () => connection.sendRequest("session.history.compact", { sessionId }),
+      compact: async (params) => connection.sendRequest("session.history.compact", { sessionId, ...params }),
       /**
        * Truncates persisted session history to a specific event.
        *

package/dist/cjs/index.js

@@ -18,25 +18,35 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var index_exports = {};
 __export(index_exports, {
+  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,
+  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_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 = {
+  Canvas,
+  CanvasError,
   CopilotClient,
   CopilotSession,
-  SYSTEM_PROMPT_SECTIONS,
+  RuntimeConnection,
+  SYSTEM_MESSAGE_SECTIONS,
   approveAll,
   convertMcpCallToolResult,
+  createCanvas,
   createSessionFsAdapter,
   defineTool
 });

package/dist/cjs/session.js

@@ -18,14 +18,20 @@ 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_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 };
+}
 class CopilotSession {
   /**
    * Creates a new CopilotSession instance.
@@ -45,6 +51,7 @@ class CopilotSession {
   eventHandlers = /* @__PURE__ */ new Set();
   typedEventHandlers = /* @__PURE__ */ new Map();
   toolHandlers = /* @__PURE__ */ new Map();
+  canvases = /* @__PURE__ */ new Map();
   commandHandlers = /* @__PURE__ */ new Map();
   permissionHandler;
   userInputHandler;
@@ -56,6 +63,7 @@ class CopilotSession {
   _rpc = null;
   traceContextProvider;
   _capabilities = {};
+  openCanvasInstances = [];
   /** @internal Client session API handlers, populated by CopilotClient during create/resume. */
   clientSessionApis = {};
   /**
@@ -102,25 +110,8 @@ 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,
@@ -131,30 +122,8 @@ class CopilotSession {
     });
     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;
@@ -424,6 +393,31 @@ 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) {
+      return;
+    }
+    for (const canvas of canvases) {
+      this.canvases.set(canvas.declaration.id, canvas);
+    }
+  }
+  /**
+   * Retrieves a registered canvas by id.
+   *
+   * @param canvasId - The id of the canvas to retrieve
+   * @returns The registered Canvas if found, or undefined
+   * @internal Used by the SDK's direct `canvas.*` dispatcher.
+   */
+  getCanvas(canvasId) {
+    return this.canvases.get(canvasId);
+  }
   /**
    * Registers command handlers for this session.
    *
@@ -520,6 +514,24 @@ class CopilotSession {
   setCapabilities(capabilities) {
     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.
+   */
+  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(
@@ -659,33 +671,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.
    *
@@ -718,8 +703,10 @@ 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,
       userPromptSubmitted: this.hooks.onUserPromptSubmitted,
       sessionStart: this.hooks.onSessionStart,
@@ -731,7 +718,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;
@@ -748,7 +735,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);
@@ -756,7 +743,7 @@ class CopilotSession {
    * }
    * ```
    */
-  async getMessages() {
+  async getEvents() {
     const response = await this.connection.sendRequest("session.getMessages", {
       sessionId: this.sessionId
     });
@@ -796,18 +783,6 @@ class CopilotSession {
     this.exitPlanModeHandler = void 0;
     this.autoModeSwitchHandler = 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();
-  }
   /** Enables `await using session = ...` syntax for automatic cleanup. */
   async [Symbol.asyncDispose]() {
     return this.disconnect();
@@ -894,6 +869,5 @@ function isToolResultObject(value) {
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  CopilotSession,
-  NO_RESULT_PERMISSION_V2_ERROR
+  CopilotSession
 });

package/dist/cjs/types.js

@@ -18,7 +18,8 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var types_exports = {};
 __export(types_exports, {
-  SYSTEM_PROMPT_SECTIONS: () => SYSTEM_PROMPT_SECTIONS,
+  RuntimeConnection: () => RuntimeConnection,
+  SYSTEM_MESSAGE_SECTIONS: () => SYSTEM_MESSAGE_SECTIONS,
   approveAll: () => approveAll,
   convertMcpCallToolResult: () => convertMcpCallToolResult,
   createSessionFsAdapter: () => import_sessionFsProvider.createSessionFsAdapter,
@@ -27,6 +28,34 @@ __export(types_exports, {
 });
 module.exports = __toCommonJS(types_exports);
 var import_sessionFsProvider = require("./sessionFsProvider.js");
+const RuntimeConnection = {
+  /**
+   * Spawn a runtime child process and communicate over its stdin/stdout.
+   * This is the default if no {@link CopilotClientOptions.connection} is set.
+   */
+  forStdio(opts = {}) {
+    return { kind: "stdio", path: opts.path, args: opts.args };
+  },
+  /**
+   * Spawn a runtime child process that listens on a TCP socket and connect to it.
+   */
+  forTcp(opts = {}) {
+    return {
+      kind: "tcp",
+      port: opts.port,
+      connectionToken: opts.connectionToken,
+      path: opts.path,
+      args: opts.args
+    };
+  },
+  /**
+   * Connect to an already-running runtime at the given URL. The SDK does not
+   * spawn a process in this mode.
+   */
+  forUri(url, opts = {}) {
+    return { kind: "uri", url, connectionToken: opts.connectionToken };
+  }
+};
 function convertMcpCallToolResult(callResult) {
   const textParts = [];
   const binaryResults = [];
@@ -72,7 +101,7 @@ function convertMcpCallToolResult(callResult) {
 function defineTool(name, config) {
   return { name, ...config };
 }
-const SYSTEM_PROMPT_SECTIONS = {
+const SYSTEM_MESSAGE_SECTIONS = {
   identity: { description: "Agent identity preamble and mode statement" },
   tone: { description: "Response style, conciseness rules, output formatting preferences" },
   tool_efficiency: { description: "Tool usage patterns, parallel calling, batching guidelines" },
@@ -82,6 +111,9 @@ const SYSTEM_PROMPT_SECTIONS = {
   safety: { description: "Environment limitations, prohibited actions, security policies" },
   tool_instructions: { description: "Per-tool usage instructions" },
   custom_instructions: { description: "Repository and organization custom instructions" },
+  runtime_instructions: {
+    description: "Runtime-provided context and instructions (e.g. system notifications, memories, workspace context, mode-specific instructions, content-exclusion policy)"
+  },
   last_instructions: {
     description: "End-of-prompt instructions: parallel tool calling, persistence, task completion"
   }
@@ -92,7 +124,8 @@ const defaultJoinSessionPermissionHandler = () => ({
 });
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  SYSTEM_PROMPT_SECTIONS,
+  RuntimeConnection,
+  SYSTEM_MESSAGE_SECTIONS,
   approveAll,
   convertMcpCallToolResult,
   createSessionFsAdapter,