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

package/dist/index.d.ts

@@ -6,6 +6,7 @@
 export { CopilotClient } from "./client.js";
 export { RuntimeConnection } from "./types.js";
 export { CopilotSession, type AssistantMessageEvent } from "./session.js";
-export { defineTool, approveAll, convertMcpCallToolResult, createSessionFsAdapter, SYSTEM_PROMPT_SECTIONS, } from "./types.js";
+export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasDeclaration, type CanvasHostContext, type CanvasJsonSchema, type CanvasOptions, } from "./canvas.js";
+export { defineTool, approveAll, convertMcpCallToolResult, createSessionFsAdapter, SYSTEM_MESSAGE_SECTIONS, } from "./types.js";
 export type * from "./generated/session-events.js";
-export type { CommandContext, CommandDefinition, CommandHandler, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, ConnectionState, CopilotClientOptions, StdioRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, UiInputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ProviderConfig, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemPromptSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolTelemetry, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export type { CommandContext, CommandDefinition, CommandHandler, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, CopilotClientOptions, StdioRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, UiInputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ProviderConfig, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolTelemetry, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";

package/dist/index.js

@@ -1,20 +1,28 @@
 import { CopilotClient } from "./client.js";
 import { RuntimeConnection } from "./types.js";
 import { CopilotSession } from "./session.js";
+import {
+  Canvas,
+  CanvasError,
+  createCanvas
+} from "./canvas.js";
 import {
   defineTool,
   approveAll,
   convertMcpCallToolResult,
   createSessionFsAdapter,
-  SYSTEM_PROMPT_SECTIONS
+  SYSTEM_MESSAGE_SECTIONS
 } from "./types.js";
 export {
+  Canvas,
+  CanvasError,
   CopilotClient,
   CopilotSession,
   RuntimeConnection,
-  SYSTEM_PROMPT_SECTIONS,
+  SYSTEM_MESSAGE_SECTIONS,
   approveAll,
   convertMcpCallToolResult,
+  createCanvas,
   createSessionFsAdapter,
   defineTool
 };

package/dist/session.d.ts

@@ -1,4 +1,5 @@
 import { createSessionRpc } from "./generated/rpc.js";
+import type { OpenCanvasInstance } from "./generated/rpc.js";
 import type { MessageOptions, ReasoningEffort, ModelCapabilitiesOverride, SessionCapabilities, SessionEvent, SessionEventHandler, SessionEventType, SessionUiApi, TypedSessionEventHandler } from "./types.js";
 /** Assistant message event - the final response from the assistant. */
 export type AssistantMessageEvent = Extract<SessionEvent, {
@@ -36,6 +37,7 @@ export declare class CopilotSession {
     private eventHandlers;
     private typedEventHandlers;
     private toolHandlers;
+    private canvases;
     private commandHandlers;
     private permissionHandler?;
     private userInputHandler?;
@@ -47,6 +49,7 @@ export declare class CopilotSession {
     private _rpc;
     private traceContextProvider?;
     private _capabilities;
+    private openCanvasInstances;
     /**
      * Typed session-scoped RPC methods.
      */
@@ -166,6 +169,13 @@ export declare class CopilotSession {
      * ```
      */
     on(handler: SessionEventHandler): () => void;
+    /**
+     * 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(): OpenCanvasInstance[];
     private assertElicitation;
     private _elicitation;
     private _confirm;

package/dist/session.js

@@ -1,7 +1,7 @@
-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;
@@ -29,6 +29,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;
@@ -40,6 +41,7 @@ class CopilotSession {
   _rpc = null;
   traceContextProvider;
   _capabilities = {};
+  openCanvasInstances = [];
   /** @internal Client session API handlers, populated by CopilotClient during create/resume. */
   clientSessionApis = {};
   /**
@@ -369,6 +371,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 invokeAction(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.
    *
@@ -465,6 +522,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(
@@ -604,33 +679,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.
    *
@@ -827,7 +875,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/types.d.ts

@@ -1,10 +1,12 @@
 /**
  * Type definitions for the Copilot SDK
  */
+import type { Canvas } from "./canvas.js";
 import type { SessionFsProvider } from "./sessionFsProvider.js";
 import type { SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
 import type { CopilotSession } from "./session.js";
 import type { RemoteSessionMode } from "./generated/rpc.js";
+import type { OpenCanvasInstance } from "./generated/rpc.js";
 export type { RemoteSessionMode } from "./generated/rpc.js";
 export type SessionEvent = GeneratedSessionEvent;
 export type { SessionFsProvider } from "./sessionFsProvider.js";
@@ -389,6 +391,8 @@ export interface SessionCapabilities {
     ui?: {
         /** Whether the host supports interactive elicitation dialogs. */
         elicitation?: boolean;
+        /** Whether the host supports canvas rendering. */
+        canvases?: boolean;
     };
 }
 /**
@@ -566,12 +570,12 @@ export interface ToolCallResponsePayload {
     result: ToolResult;
 }
 /**
- * Known system prompt section identifiers for the "customize" mode.
+ * Known system message section identifiers for the "customize" mode.
  * Each section corresponds to a distinct part of the system prompt.
  */
-export type SystemPromptSection = "identity" | "tone" | "tool_efficiency" | "environment_context" | "code_change_rules" | "guidelines" | "safety" | "tool_instructions" | "custom_instructions" | "last_instructions";
+export type SystemMessageSection = "identity" | "tone" | "tool_efficiency" | "environment_context" | "code_change_rules" | "guidelines" | "safety" | "tool_instructions" | "custom_instructions" | "runtime_instructions" | "last_instructions";
 /** Section metadata for documentation and tooling. */
-export declare const SYSTEM_PROMPT_SECTIONS: Record<SystemPromptSection, {
+export declare const SYSTEM_MESSAGE_SECTIONS: Record<SystemMessageSection, {
     description: string;
 }>;
 /**
@@ -589,7 +593,7 @@ export type SectionTransformFn = (currentContent: string) => string | Promise<st
  */
 export type SectionOverrideAction = "replace" | "remove" | "append" | "prepend" | SectionTransformFn;
 /**
- * Override operation for a single system prompt section.
+ * Override operation for a single system message section.
  */
 export interface SectionOverride {
     /**
@@ -638,7 +642,7 @@ export interface SystemMessageCustomizeConfig {
      * Unknown section IDs gracefully fall back: content-bearing overrides are appended
      * to additional instructions, and "remove" on unknown sections is a silent no-op.
      */
-    sections?: Partial<Record<SystemPromptSection, SectionOverride>>;
+    sections?: Partial<Record<SystemMessageSection, SectionOverride>>;
     /**
      * Additional content appended after all sections.
      * Equivalent to append mode's content field — provided for convenience.
@@ -1108,6 +1112,15 @@ export interface InfiniteSessionConfig {
  * Valid reasoning effort levels for models that support it.
  */
 export type ReasoningEffort = "low" | "medium" | "high" | "xhigh";
+/**
+ * Stable extension identity for session participants that provide canvases.
+ */
+export interface ExtensionInfo {
+    /** Extension namespace/source, e.g. "github-app". */
+    source: string;
+    /** Stable provider name within the source namespace. */
+    name: string;
+}
 /**
  * Shared configuration fields used by both {@link SessionConfig} (for
  * creating a new session) and {@link ResumeSessionConfig} (for resuming
@@ -1153,6 +1166,34 @@ export interface SessionConfigBase {
      * and must be resolved by the consumer via pending external tool request RPCs.
      */
     tools?: Tool<any>[];
+    /**
+     * Canvases contributed by this session participant. The declaring
+     * connection becomes the live provider for `canvas.open|focus|close|reload`
+     * and `canvas.action.invoke` dispatches targeting each canvas's `id` for
+     * the lifetime of the connection. Re-declaring the same id on resume
+     * replaces the prior declaration.
+     */
+    canvases?: Canvas[];
+    /**
+     * Renderer-side opt-in: when true, the runtime surfaces canvas agent tools
+     * (`list_canvas_capabilities`, `open_canvas`, `invoke_canvas_action`) to
+     * the model for this connection. Default off so SDK callers that cannot
+     * display canvases stay clean.
+     */
+    requestCanvasRenderer?: boolean;
+    /**
+     * Extension surface opt-in: when true, the runtime wires extension
+     * management tools and per-extension tool dispatch onto the session for
+     * this connection. Default off so callers that do not expose extensions
+     * stay clean.
+     */
+    requestExtensions?: boolean;
+    /**
+     * Stable extension identity for canvas providers on this connection. When
+     * set, the runtime uses `${source}:${name}` as the agent-facing extension
+     * id instead of a reconnect-specific connection id.
+     */
+    extensionInfo?: ExtensionInfo;
     /**
      * Slash commands registered for this session.
      * When the CLI has a TUI, each command appears as `/name` for the user to invoke.
@@ -1354,6 +1395,12 @@ export interface ResumeSessionConfig extends SessionConfigBase {
      * @default false
      */
     continuePendingWork?: boolean;
+    /**
+     * Snapshot of canvases that were already open when the session was suspended.
+     * When provided on resume, the runtime can rehydrate canvas state so consumers
+     * do not need to re-open canvases that were active before the previous shutdown.
+     */
+    openCanvases?: OpenCanvasInstance[];
 }
 /**
  * Configuration for a custom API provider.
@@ -1490,10 +1537,6 @@ export type TypedSessionEventHandler<T extends SessionEventType> = (event: Sessi
  * Event handler callback type (for all events)
  */
 export type SessionEventHandler = (event: SessionEvent) => void;
-/**
- * Connection state
- */
-export type ConnectionState = "disconnected" | "connecting" | "connected" | "error";
 /**
  * Working directory context for a session
  */

package/dist/types.js

@@ -72,7 +72,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 +82,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 +95,7 @@ const defaultJoinSessionPermissionHandler = () => ({
 });
 export {
   RuntimeConnection,
-  SYSTEM_PROMPT_SECTIONS,
+  SYSTEM_MESSAGE_SECTIONS,
   approveAll,
   convertMcpCallToolResult,
   createSessionFsAdapter,

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "1.0.0-beta.6",
+  "version": "1.0.0-beta.8",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/cjs/index.js",
   "types": "./dist/index.d.ts",
@@ -56,7 +56,7 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^1.0.52-1",
+    "@github/copilot": "^1.0.55-1",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.6"
   },