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

package/README.md

@@ -2,8 +2,6 @@
 
 TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC.
 
-> **Note:** This SDK is in public preview and may change in breaking ways.
-
 ## Installation
 
 ```bash
@@ -57,7 +55,7 @@ await session.disconnect();
 await client.stop();
 ```
 
-Sessions also support `Symbol.asyncDispose` for use with [`await using`](https://github.com/tc39/proposal-explicit-resource-management) (TypeScript 5.2+/Node.js 18.0+):
+Sessions also support `Symbol.asyncDispose` for use with [`await using`](https://github.com/tc39/proposal-explicit-resource-management) (TypeScript 5.2+ / Node.js 20+):
 
 ```typescript
 await using session = await client.createSession({
@@ -82,14 +80,20 @@ new CopilotClient(options?: CopilotClientOptions)
 - `connection?: RuntimeConnection` - How to connect to the Copilot runtime. Construct via the factory functions on `RuntimeConnection`:
     - `RuntimeConnection.forStdio({ path?, args? })` (default) — spawn the runtime and communicate over its stdin/stdout.
     - `RuntimeConnection.forTcp({ port?, connectionToken?, path?, args? })` — spawn the runtime as a TCP server.
-    - `RuntimeConnection.forUri(url, { connectionToken? })` — connect to an already-running runtime (mutually exclusive with `gitHubToken`/`useLoggedInUser`).
-- `cwd?: string` - Working directory for the runtime process (default: current process cwd).
+    - `RuntimeConnection.forUri(url, { connectionToken? })` — connect to an already-running runtime (mutually exclusive with `gitHubToken`/`useLoggedInUser`). There is no top-level `cliUrl` shortcut; use this factory for URL-based connections.
+- `mode?: "empty" | "copilot-cli"` - Defaulting strategy. Use `"empty"` for multi-user server mode; defaults to `"copilot-cli"`.
+- `workingDirectory?: string` - Working directory for the runtime process (default: current process cwd).
 - `baseDirectory?: string` - Base directory for Copilot data (session state, config, etc.). Sets `COPILOT_HOME` on the spawned runtime. When not set, the runtime defaults to `~/.copilot`. Ignored when connecting via `RuntimeConnection.forUri`.
-- `logLevel?: string` - Log level. When omitted, the runtime uses its own default (currently `"info"`).
+- `logLevel?: "none" | "error" | "warning" | "info" | "debug" | "all"` - Log level. When omitted, the runtime uses its own default (currently `"info"`).
+- `env?: Record<string, string | undefined>` - Environment variables for the runtime process. When omitted, inherits `process.env`.
 - `gitHubToken?: string` - GitHub token for authentication. When provided, takes priority over other auth methods.
 - `useLoggedInUser?: boolean` - Whether to use logged-in user for authentication (default: true, but false when `gitHubToken` is provided). Cannot be used with `RuntimeConnection.forUri`.
+- `onListModels?: () => Promise<ModelInfo[]> | ModelInfo[]` - Optional model-list provider, useful when using a custom provider.
 - `telemetry?: TelemetryConfig` - OpenTelemetry configuration for the runtime process. Providing this object enables telemetry — no separate flag needed. See [Telemetry](#telemetry) below.
 - `onGetTraceContext?: TraceContextProvider` - Advanced: callback for linking your application's own OpenTelemetry spans into the same distributed trace as the runtime's spans. Not needed for normal telemetry collection. See [Telemetry](#telemetry) below.
+- `sessionFs?: SessionFsConfig` - Custom session filesystem provider.
+- `sessionIdleTimeoutSeconds?: number` - Server-wide idle timeout for sessions in seconds. Ignored when connecting via `RuntimeConnection.forUri`.
+- `enableRemoteSessions?: boolean` - Enable Mission Control remote session support. Ignored when connecting via `RuntimeConnection.forUri`.
 
 #### Methods
 
@@ -163,7 +167,7 @@ Get the ID of the session currently displayed in the TUI. Only available when co
 
 Request the TUI to switch to displaying the specified session. Only available in TUI+server mode.
 
-##### `on(eventType: SessionLifecycleEventType, handler): () => void`
+##### `onLifecycle(eventType: SessionLifecycleEventType, handler): () => void`
 
 Subscribe to a specific session lifecycle event type. Returns an unsubscribe function.
 
@@ -173,7 +177,7 @@ const unsubscribe = client.onLifecycle("session.foreground", (event) => {
 });
 ```
 
-##### `on(handler: SessionLifecycleHandler): () => void`
+##### `onLifecycle(handler: SessionLifecycleHandler): () => void`
 
 Subscribe to all session lifecycle events. Returns an unsubscribe function.
 

package/dist/canvas.d.ts

@@ -1,14 +1,17 @@
 import type { CanvasJsonSchema, CanvasProviderCloseRequest, CanvasProviderInvokeActionRequest, CanvasProviderOpenRequest, CanvasProviderOpenResult } from "./generated/rpc.js";
-export type { CanvasJsonSchema, CanvasHostContext } from "./generated/rpc.js";
+export type { CanvasJsonSchema, CanvasHostContext, CanvasHostContextCapabilities, } from "./generated/rpc.js";
 /**
  * Extension-owned canvases declared via
  * `joinSession({ canvases: [createCanvas({...})] })`.
  *
  * The runtime sends provider callbacks as `canvas.open`, `canvas.close`, and
- * `canvas.invokeAction` JSON-RPC requests via the codegen client session API
+ * `canvas.action.invoke` JSON-RPC requests via the codegen client session API
  * pipeline. The SDK routes those requests by `canvasId` to the in-process
  * handlers bound by `createCanvas`. Re-opening with an existing `instanceId`
  * is how the host focuses an existing panel; reload is a renderer-only concern.
+ *
+ * @experimental Canvas types are part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
  */
 /**
  * A single agent-callable action contributed by a canvas. The metadata
@@ -18,6 +21,9 @@ export type { CanvasJsonSchema, CanvasHostContext } from "./generated/rpc.js";
  *
  * Names MUST NOT start with `canvas.` — that prefix is reserved for
  * lifecycle verbs.
+ *
+ * @experimental This type is part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
  */
 export interface CanvasAction {
     /** Action identifier, unique within the canvas. */
@@ -32,6 +38,9 @@ export interface CanvasAction {
 /**
  * Declarative metadata for a single canvas, serialized over the wire on
  * `session.create` / `session.resume`.
+ *
+ * @experimental This type is part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
  */
 export interface CanvasDeclaration {
     /** Canvas id, unique within the declaring connection. */
@@ -45,7 +54,12 @@ export interface CanvasDeclaration {
     /** Agent-invocable actions exposed via `invoke_canvas_action`. */
     actions?: Omit<CanvasAction, "handler">[];
 }
-/** Structured error returned from canvas handlers. */
+/**
+ * Structured error returned from canvas handlers.
+ *
+ * @experimental This class is part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
+ */
 export declare class CanvasError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
@@ -55,6 +69,9 @@ export declare class CanvasError extends Error {
 /**
  * Options accepted by {@link createCanvas}. Combines the declarative
  * {@link CanvasDeclaration} fields with the in-process handler closures.
+ *
+ * @experimental This interface is part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
  */
 export interface CanvasOptions {
     /** @see CanvasDeclaration.id */
@@ -87,6 +104,9 @@ export interface CanvasOptions {
  * ergonomics) where other SDKs (Rust, Python, Go, .NET) expose a single
  * `CanvasHandler` per session that switches on `canvasId`. Both shapes target
  * the same JSON-RPC wire protocol; the divergence is API ergonomics only.
+ *
+ * @experimental This class is part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
  */
 export declare class Canvas {
     readonly declaration: CanvasDeclaration;
@@ -99,5 +119,8 @@ export declare class Canvas {
  * `DefineTool`'s co-location ergonomics) where other SDKs (Rust, Python, Go,
  * .NET) expose a single `CanvasHandler` per session that switches on
  * `canvasId`. Both shapes target the same JSON-RPC wire protocol.
+ *
+ * @experimental This function is part of an experimental wire-protocol surface
+ * and may change or be removed in future SDK or CLI releases.
  */
 export declare function createCanvas(options: CanvasOptions): Canvas;

package/dist/cjs/client.js

@@ -68,6 +68,15 @@ function toWireCustomAgents(agents) {
     return { ...rest, mcpServers: toWireMcpServers(mcpServers) };
   });
 }
+function toWireLargeOutput(config) {
+  if (!config) return void 0;
+  const { outputDirectory, ...rest } = config;
+  const wire = { ...rest };
+  if (outputDirectory !== void 0) {
+    wire.outputDir = outputDirectory;
+  }
+  return wire;
+}
 function toolFilterListToArray(value) {
   if (value === void 0) {
     return void 0;
@@ -620,7 +629,17 @@ class CopilotClient {
   /** Mode-specific defaults spread under the caller's config (app values win). */
   configDefaultsForMode() {
     if (this.options.mode === "empty") {
-      return { enableSessionTelemetry: false };
+      return {
+        enableSessionTelemetry: false,
+        mcpOAuthTokenStorage: "in-memory",
+        skipEmbeddingRetrieval: true,
+        embeddingCacheStorage: "in-memory",
+        enableOnDemandInstructionDiscovery: false,
+        enableFileHooks: false,
+        enableHostGitOperations: false,
+        enableSessionStore: false,
+        enableSkills: false
+      };
     }
     return {};
   }
@@ -706,51 +725,64 @@ class CopilotClient {
     }
     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,
-      this.connection,
-      void 0,
-      this.onGetTraceContext
-    );
-    session.registerTools(config.tools);
-    session.registerCanvases(config.canvases);
-    session.registerCommands(config.commands);
-    session.registerPermissionHandler(config.onPermissionRequest);
-    if (config.onUserInputRequest) {
-      session.registerUserInputHandler(config.onUserInputRequest);
-    }
-    if (config.onElicitationRequest) {
-      session.registerElicitationHandler(config.onElicitationRequest);
-    }
-    if (config.onExitPlanModeRequest) {
-      session.registerExitPlanModeHandler(config.onExitPlanModeRequest);
-    }
-    if (config.onAutoModeSwitchRequest) {
-      session.registerAutoModeSwitchHandler(config.onAutoModeSwitchRequest);
-    }
-    if (config.hooks) {
-      session.registerHooks(config.hooks);
-    }
+    const callerSessionId = config.sessionId;
+    const useServerGeneratedId = config.cloud != null && callerSessionId == null;
+    const localSessionId = useServerGeneratedId ? void 0 : callerSessionId ?? (0, import_node_crypto.randomUUID)();
     const { wirePayload: wireSystemMessage, transformCallbacks } = extractTransformCallbacks(
       config.systemMessage
     );
-    if (transformCallbacks) {
-      session.registerTransformCallbacks(transformCallbacks);
-    }
-    if (config.onEvent) {
-      session.on(config.onEvent);
+    const initializeSession = (sessionId) => {
+      const s = new import_session.CopilotSession(
+        sessionId,
+        this.connection,
+        void 0,
+        this.onGetTraceContext
+      );
+      s.registerTools(config.tools);
+      s.registerCanvases(config.canvases);
+      s.registerCommands(config.commands);
+      s.registerPermissionHandler(config.onPermissionRequest);
+      if (config.onUserInputRequest) {
+        s.registerUserInputHandler(config.onUserInputRequest);
+      }
+      if (config.onElicitationRequest) {
+        s.registerElicitationHandler(config.onElicitationRequest);
+      }
+      if (config.onExitPlanModeRequest) {
+        s.registerExitPlanModeHandler(config.onExitPlanModeRequest);
+      }
+      if (config.onAutoModeSwitchRequest) {
+        s.registerAutoModeSwitchHandler(config.onAutoModeSwitchRequest);
+      }
+      if (config.hooks) {
+        s.registerHooks(config.hooks);
+      }
+      if (transformCallbacks) {
+        s.registerTransformCallbacks(transformCallbacks);
+      }
+      if (config.onEvent) {
+        s.on(config.onEvent);
+      }
+      this.sessions.set(sessionId, s);
+      this.setupSessionFs(s, config);
+      return s;
+    };
+    let session;
+    let registeredId;
+    if (localSessionId !== void 0) {
+      session = initializeSession(localSessionId);
+      registeredId = localSessionId;
     }
-    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),
         model: config.model,
-        sessionId,
+        sessionId: localSessionId,
         clientName: config.clientName,
         reasoningEffort: config.reasoningEffort,
+        reasoningSummary: config.reasoningSummary,
+        contextTier: config.contextTier,
         tools: config.tools?.map((tool) => ({
           name: tool.name,
           description: tool.description,
@@ -761,6 +793,7 @@ class CopilotClient {
         canvases: config.canvases?.map((canvas) => canvas.declaration),
         requestCanvasRenderer: config.requestCanvasRenderer,
         requestExtensions: config.requestExtensions,
+        extensionSdkPath: config.extensionSdkPath,
         extensionInfo: config.extensionInfo,
         commands: config.commands?.map((cmd) => ({
           name: cmd.name,
@@ -773,9 +806,11 @@ class CopilotClient {
         provider: config.provider,
         enableSessionTelemetry: config.enableSessionTelemetry,
         modelCapabilities: config.modelCapabilities,
+        largeOutput: toWireLargeOutput(config.largeOutput),
         requestPermission: !!config.onPermissionRequest,
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
+        ...config.enableMcpApps ? { requestMcpApps: true } : {},
         requestExitPlanMode: !!config.onExitPlanModeRequest,
         requestAutoModeSwitch: !!config.onAutoModeSwitchRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
@@ -783,13 +818,23 @@ class CopilotClient {
         streaming: config.streaming,
         includeSubAgentStreamingEvents: config.includeSubAgentStreamingEvents ?? true,
         mcpServers: toWireMcpServers(config.mcpServers),
+        mcpOAuthTokenStorage: config.mcpOAuthTokenStorage,
         envValueMode: "direct",
         customAgents: toWireCustomAgents(config.customAgents),
         defaultAgent: config.defaultAgent,
         agent: config.agent,
-        configDir: config.configDir,
+        configDir: config.configDirectory,
         enableConfigDiscovery: config.enableConfigDiscovery,
+        skipEmbeddingRetrieval: config.skipEmbeddingRetrieval,
+        embeddingCacheStorage: config.embeddingCacheStorage,
+        organizationCustomInstructions: config.organizationCustomInstructions,
+        enableOnDemandInstructionDiscovery: config.enableOnDemandInstructionDiscovery,
+        enableFileHooks: config.enableFileHooks,
+        enableHostGitOperations: config.enableHostGitOperations,
+        enableSessionStore: config.enableSessionStore,
+        enableSkills: config.enableSkills,
         skillDirectories: config.skillDirectories,
+        pluginDirectories: config.pluginDirectories,
         instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         infiniteSessions: config.infiniteSessions,
@@ -797,12 +842,30 @@ class CopilotClient {
         remoteSession: config.remoteSession,
         cloud: config.cloud
       });
-      const { workspacePath, capabilities } = response;
+      const {
+        sessionId: returnedSessionId,
+        workspacePath,
+        capabilities
+      } = response;
+      if (!returnedSessionId) {
+        throw new Error("session.create response did not include a sessionId");
+      }
+      if (localSessionId !== void 0 && localSessionId !== returnedSessionId) {
+        throw new Error(
+          `session.create returned sessionId ${returnedSessionId} but the caller requested ${localSessionId}`
+        );
+      }
+      if (session === void 0) {
+        session = initializeSession(returnedSessionId);
+        registeredId = returnedSessionId;
+      }
       session["_workspacePath"] = workspacePath;
       session.setCapabilities(capabilities);
       await this.updateSessionOptionsForMode(session, config);
     } catch (e) {
-      this.sessions.delete(sessionId);
+      if (registeredId !== void 0) {
+        this.sessions.delete(registeredId);
+      }
       throw e;
     }
     return session;
@@ -881,6 +944,8 @@ class CopilotClient {
         clientName: config.clientName,
         model: config.model,
         reasoningEffort: config.reasoningEffort,
+        reasoningSummary: config.reasoningSummary,
+        contextTier: config.contextTier,
         systemMessage: wireSystemMessage,
         availableTools: toolFilterOptions.availableTools,
         excludedTools: toolFilterOptions.excludedTools,
@@ -896,6 +961,7 @@ class CopilotClient {
         canvases: config.canvases?.map((canvas) => canvas.declaration),
         requestCanvasRenderer: config.requestCanvasRenderer,
         requestExtensions: config.requestExtensions,
+        extensionSdkPath: config.extensionSdkPath,
         extensionInfo: config.extensionInfo,
         commands: config.commands?.map((cmd) => ({
           name: cmd.name,
@@ -903,27 +969,39 @@ class CopilotClient {
         })),
         provider: config.provider,
         modelCapabilities: config.modelCapabilities,
+        largeOutput: toWireLargeOutput(config.largeOutput),
         requestPermission: config.onPermissionRequest !== import_types.defaultJoinSessionPermissionHandler,
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
+        ...config.enableMcpApps ? { requestMcpApps: true } : {},
         requestExitPlanMode: !!config.onExitPlanModeRequest,
         requestAutoModeSwitch: !!config.onAutoModeSwitchRequest,
         hooks: !!(config.hooks && Object.values(config.hooks).some(Boolean)),
         workingDirectory: config.workingDirectory,
-        configDir: config.configDir,
+        configDir: config.configDirectory,
         enableConfigDiscovery: config.enableConfigDiscovery,
+        skipEmbeddingRetrieval: config.skipEmbeddingRetrieval,
+        embeddingCacheStorage: config.embeddingCacheStorage,
+        organizationCustomInstructions: config.organizationCustomInstructions,
+        enableOnDemandInstructionDiscovery: config.enableOnDemandInstructionDiscovery,
+        enableFileHooks: config.enableFileHooks,
+        enableHostGitOperations: config.enableHostGitOperations,
+        enableSessionStore: config.enableSessionStore,
+        enableSkills: config.enableSkills,
         streaming: config.streaming,
         includeSubAgentStreamingEvents: config.includeSubAgentStreamingEvents ?? true,
         mcpServers: toWireMcpServers(config.mcpServers),
+        mcpOAuthTokenStorage: config.mcpOAuthTokenStorage,
         envValueMode: "direct",
         customAgents: toWireCustomAgents(config.customAgents),
         defaultAgent: config.defaultAgent,
         agent: config.agent,
         skillDirectories: config.skillDirectories,
+        pluginDirectories: config.pluginDirectories,
         instructionDirectories: config.instructionDirectories,
         disabledSkills: config.disabledSkills,
         infiniteSessions: config.infiniteSessions,
-        suppressResumeEvent: config.suppressResumeEvent,
+        disableResume: config.suppressResumeEvent,
         continuePendingWork: config.continuePendingWork,
         gitHubToken: config.gitHubToken,
         remoteSession: config.remoteSession,

package/dist/cjs/extension.js

@@ -35,8 +35,10 @@ async function joinSession(config = {}) {
     );
   }
   const client = new import_client.CopilotClient({ _internalConnection: { kind: "parent-process" } });
+  const { extensionSdkPath: _stripped, ...rest } = config;
+  void _stripped;
   return client.resumeSession(sessionId, {
-    ...config,
+    ...rest,
     onPermissionRequest: config.onPermissionRequest ?? import_types.defaultJoinSessionPermissionHandler,
     suppressResumeEvent: config.suppressResumeEvent ?? true
   });

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.
@@ -409,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.
        */
@@ -441,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: {
@@ -895,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: {
@@ -912,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: {
@@ -1501,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/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,6 +124,7 @@ 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,
@@ -266,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);
     }
   }
   /**
@@ -432,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);
@@ -547,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];