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

package/README.md

@@ -79,18 +79,17 @@ new CopilotClient(options?: CopilotClientOptions)
 
 **Options:**
 
-- `cliPath?: string` - Path to CLI executable (default: uses COPILOT_CLI_PATH env var or bundled instance)
-- `cliArgs?: string[]` - Extra arguments prepended before SDK-managed flags (e.g. `["./dist-cli/index.js"]` when using `node`)
-- `cliUrl?: string` - URL of existing CLI server to connect to (e.g., `"localhost:8080"`, `"http://127.0.0.1:9000"`, or just `"8080"`). When provided, the client will not spawn a CLI process.
-- `port?: number` - Server port (default: 0 for random)
-- `useStdio?: boolean` - Use stdio transport instead of TCP (default: true)
-- `logLevel?: string` - Log level (default: "info")
-- `autoStart?: boolean` - Auto-start server (default: true)
+- `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).
+- `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"`).
 - `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 `cliUrl`.
-- `copilotHome?: string` - Base directory for Copilot data (session state, config, etc.). Sets `COPILOT_HOME` on the spawned CLI process. When not set, the CLI defaults to `~/.copilot`. Useful in restricted environments where only specific directories are writable. Ignored when using `cliUrl`.
-- `telemetry?: TelemetryConfig` - OpenTelemetry configuration for the CLI 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 CLI's spans. Not needed for normal telemetry collection. See [Telemetry](#telemetry) below.
+- `useLoggedInUser?: boolean` - Whether to use logged-in user for authentication (default: true, but false when `gitHubToken` is provided). Cannot be used with `RuntimeConnection.forUri`.
+- `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.
 
 #### Methods
 
@@ -132,10 +131,6 @@ Resume an existing session. Returns the session with `workspacePath` populated i
 
 Ping the server to check connectivity.
 
-##### `getState(): ConnectionState`
-
-Get current connection state.
-
 ##### `listSessions(filter?: SessionListFilter): Promise<SessionMetadata[]>`
 
 List all available sessions. Optionally filter by working directory context.
@@ -173,7 +168,7 @@ Request the TUI to switch to displaying the specified session. Only available in
 Subscribe to a specific session lifecycle event type. Returns an unsubscribe function.
 
 ```typescript
-const unsubscribe = client.on("session.foreground", (event) => {
+const unsubscribe = client.onLifecycle("session.foreground", (event) => {
     console.log(`Session ${event.sessionId} is now in foreground`);
 });
 ```
@@ -183,7 +178,7 @@ const unsubscribe = client.on("session.foreground", (event) => {
 Subscribe to all session lifecycle events. Returns an unsubscribe function.
 
 ```typescript
-const unsubscribe = client.on((event) => {
+const unsubscribe = client.onLifecycle((event) => {
     console.log(`${event.type}: ${event.sessionId}`);
 });
 ```
@@ -277,7 +272,7 @@ unsubscribe();
 
 Abort the currently processing message in this session.
 
-##### `getMessages(): Promise<SessionEvent[]>`
+##### `getEvents(): Promise<SessionEvent[]>`
 
 Get all events/messages from this session.
 
@@ -415,7 +410,7 @@ Note: `assistant.message` and `assistant.reasoning` (final events) are always se
 ### Manual Server Control
 
 ```typescript
-const client = new CopilotClient({ autoStart: false });
+const client = new CopilotClient({});
 
 // Start manually
 await client.start();
@@ -574,8 +569,8 @@ The SDK auto-injects environment context, tool instructions, and security guardr
 Use `mode: "customize"` to selectively override individual sections of the prompt while preserving the rest:
 
 ```typescript
-import { SYSTEM_PROMPT_SECTIONS } from "@github/copilot-sdk";
-import type { SectionOverride, SystemPromptSection } from "@github/copilot-sdk";
+import { SYSTEM_MESSAGE_SECTIONS } from "@github/copilot-sdk";
+import type { SectionOverride, SystemMessageSection } from "@github/copilot-sdk";
 
 const session = await client.createSession({
     model: "gpt-5",
@@ -598,7 +593,7 @@ const session = await client.createSession({
 });
 ```
 
-Available section IDs: `identity`, `tone`, `tool_efficiency`, `environment_context`, `code_change_rules`, `guidelines`, `safety`, `tool_instructions`, `custom_instructions`, `last_instructions`. Use the `SYSTEM_PROMPT_SECTIONS` constant for descriptions of each section.
+Available section IDs: `identity`, `tone`, `tool_efficiency`, `environment_context`, `code_change_rules`, `guidelines`, `safety`, `tool_instructions`, `custom_instructions`, `runtime_instructions`, `last_instructions`. Use the `SYSTEM_MESSAGE_SECTIONS` constant for descriptions of each section.
 
 Each section override supports four actions:
 
@@ -856,15 +851,15 @@ const session = await client.createSession({
 
 The handler must return one of the `PermissionDecision` shapes (or `{ kind: "no-result" }`). Approval scopes are present-tense — they describe the decision to apply, not the outcome reported back on session events:
 
-| Kind                     | Meaning                                                                                       | Extra fields                                                            |
-| ------------------------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
-| `"approve-once"`         | Allow this single request                                                                     | —                                                                       |
-| `"approve-for-session"`  | Allow this request and remember the approval for the rest of the session                      | `approval?` (rule to remember), `domain?` (for URL approvals)           |
+| Kind                     | Meaning                                                                                      | Extra fields                                                            |
+| ------------------------ | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `"approve-once"`         | Allow this single request                                                                    | —                                                                       |
+| `"approve-for-session"`  | Allow this request and remember the approval for the rest of the session                     | `approval?` (rule to remember), `domain?` (for URL approvals)           |
 | `"approve-for-location"` | Allow this request and persist the approval for this project location (git root or cwd)      | `approval` (rule to persist), `locationKey` (location to persist under) |
 | `"approve-permanently"`  | Allow this request and persist the approval across sessions (currently used for URL domains) | `domain` (URL domain to approve)                                        |
-| `"reject"`               | Deny the request                                                                              | `feedback?` (optional string surfaced to the agent)                     |
-| `"user-not-available"`   | Deny the request because no user is available to confirm it                                   | —                                                                       |
-| `"no-result"`            | Leave the request unanswered (only valid with protocol v1; rejected by protocol v2 servers)   | —                                                                       |
+| `"reject"`               | Deny the request                                                                             | `feedback?` (optional string surfaced to the agent)                     |
+| `"user-not-available"`   | Deny the request because no user is available to confirm it                                  | —                                                                       |
+| `"no-result"`            | Leave the request unanswered (only valid with protocol v1; rejected by protocol v2 servers)  | —                                                                       |
 
 ### Resuming Sessions
 
@@ -1026,7 +1021,7 @@ try {
 ## Requirements
 
 - Node.js >= 18.0.0
-- GitHub Copilot CLI installed and in PATH (or provide custom `cliPath`)
+- GitHub Copilot CLI installed and in PATH (or provide a custom `connection`)
 
 ## License
 

package/dist/canvas.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Extension-owned canvases declared via
+ * `joinSession({ canvases: [createCanvas({...})] })`.
+ *
+ * The runtime sends provider callbacks directly as `canvas.open`,
+ * `canvas.close`, and `canvas.action.invoke` JSON-RPC requests. 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.
+ */
+/** JSON Schema object used for canvas inputs. */
+export type CanvasJsonSchema = Record<string, unknown>;
+/**
+ * A single agent-callable action contributed by a canvas. The metadata
+ * (`name`, `description`, `inputSchema`) is serialized over the wire on
+ * `session.create` / `session.resume`; the `handler` closure is stripped
+ * before the declaration is sent and dispatched in-process by the SDK.
+ *
+ * Names MUST NOT start with `canvas.` — that prefix is reserved for
+ * lifecycle verbs.
+ */
+export interface CanvasAction {
+    /** Action identifier, unique within the canvas. */
+    name: string;
+    /** Description shown to the model when picking an action. */
+    description?: string;
+    /** Optional JSON Schema for the action's `input` payload. */
+    inputSchema?: CanvasJsonSchema;
+    /** Required per-action dispatch handler. */
+    handler: (ctx: CanvasActionContext) => Promise<unknown> | unknown;
+}
+/**
+ * Declarative metadata for a single canvas, serialized over the wire on
+ * `session.create` / `session.resume`.
+ */
+export interface CanvasDeclaration {
+    /** Canvas id, unique within the declaring connection. */
+    id: string;
+    /** Human-readable label shown in discovery and host UI chrome. */
+    displayName: string;
+    /** Short, single-sentence description shown to the agent in canvas catalogs. */
+    description: string;
+    /** Optional JSON Schema for the `input` payload accepted by `canvas.open`. */
+    inputSchema?: CanvasJsonSchema;
+    /** Agent-invocable actions exposed via `invoke_canvas_action`. */
+    actions?: Omit<CanvasAction, "handler">[];
+}
+/** Response returned from `open`. */
+export interface CanvasOpenResponse {
+    /** URL the host should render. Optional for native canvases. */
+    url?: string;
+    /** Provider-supplied title shown in host chrome. */
+    title?: string;
+    /** Provider-supplied status text shown in host chrome. */
+    status?: string;
+}
+/** Host capabilities passed to canvas callbacks. */
+export interface CanvasHostContext {
+    capabilities?: {
+        canvases?: boolean;
+    };
+}
+/** Context handed to a canvas's `open` handler. */
+export interface CanvasOpenContext {
+    /** Session that requested the canvas. */
+    sessionId: string;
+    /** Extension id that owns the canvas. */
+    extensionId: string;
+    /** Canvas id (matches the declaring `CanvasDeclaration.id`). */
+    canvasId: string;
+    /** Stable instance id supplied by the runtime. */
+    instanceId: string;
+    /** Validated `input` payload, shaped by `CanvasDeclaration.inputSchema`. */
+    input: unknown;
+    /** Host capabilities supplied by the runtime. */
+    host?: CanvasHostContext;
+}
+/** Context handed to a canvas action handler. */
+export interface CanvasActionContext {
+    /** Session that invoked the action. */
+    sessionId: string;
+    /** Extension id that owns the canvas. */
+    extensionId: string;
+    /** Canvas id targeted by the action. */
+    canvasId: string;
+    /** Instance id targeted by the action. */
+    instanceId: string;
+    /** Action name from `CanvasAction.name`. */
+    actionName: string;
+    /** Validated `input` payload, shaped by the action's `inputSchema`. */
+    input: unknown;
+    /** Host capabilities supplied by the runtime. */
+    host?: CanvasHostContext;
+}
+/** Context handed to a canvas's `onClose` handler. */
+export interface CanvasLifecycleContext {
+    /** Session owning the canvas instance. */
+    sessionId: string;
+    /** Extension id that owns the canvas. */
+    extensionId: string;
+    /** Canvas id (matches the declaring `CanvasDeclaration.id`). */
+    canvasId: string;
+    /** Instance id this lifecycle event applies to. */
+    instanceId: string;
+    /** Host capabilities supplied by the runtime. */
+    host?: CanvasHostContext;
+}
+/** Structured error returned from canvas handlers. */
+export declare class CanvasError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+    /** Default error when an action is declared but no `handler` is wired. */
+    static noHandler(): CanvasError;
+}
+/**
+ * Options accepted by {@link createCanvas}. Combines the declarative
+ * {@link CanvasDeclaration} fields with the in-process handler closures.
+ */
+export interface CanvasOptions {
+    /** @see CanvasDeclaration.id */
+    id: string;
+    /** @see CanvasDeclaration.displayName */
+    displayName: string;
+    /** @see CanvasDeclaration.description */
+    description: string;
+    /** @see CanvasDeclaration.inputSchema */
+    inputSchema?: CanvasJsonSchema;
+    /**
+     * Agent-invocable actions exposed via `invoke_canvas_action`. Each action
+     * carries its own required `handler`; the action's wire metadata
+     * (`name`, `description`, `inputSchema`) is what reaches the runtime.
+     */
+    actions?: CanvasAction[];
+    /** Required. Open a new canvas instance. */
+    open: (ctx: CanvasOpenContext) => Promise<CanvasOpenResponse> | CanvasOpenResponse;
+    /**
+     * Optional. Notified when a canvas instance is closed by the user, the
+     * agent, or the host. Fire-and-forget: the return value is ignored and
+     * errors are logged but not surfaced to the runtime.
+     */
+    onClose?: (ctx: CanvasLifecycleContext) => Promise<void> | void;
+}
+/** A registered canvas: declarative metadata + in-process handler closures.
+ *
+ * Node intentionally uses a per-canvas factory pattern (mirroring
+ * {@link https://github.com/github/copilot-sdk | `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; the divergence is API ergonomics only.
+ */
+export declare class Canvas {
+    readonly declaration: CanvasDeclaration;
+    readonly open: NonNullable<CanvasOptions["open"]>;
+    readonly onClose?: CanvasOptions["onClose"];
+}
+/** Create a canvas declaration with bound in-process handlers.
+ *
+ * Node intentionally uses this per-canvas factory pattern (mirroring
+ * `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.
+ */
+export declare function createCanvas(options: CanvasOptions): Canvas;

package/dist/canvas.js

@@ -0,0 +1,92 @@
+class CanvasError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "CanvasError";
+  }
+  /** Default error when an action is declared but no `handler` is wired. */
+  static noHandler() {
+    return new CanvasError(
+      "canvas_action_no_handler",
+      "No handler implemented for this canvas action"
+    );
+  }
+}
+class Canvas {
+  declaration;
+  open;
+  onClose;
+  /** @internal */
+  actionHandlers;
+  /** @internal */
+  constructor(options) {
+    const actionHandlers = /* @__PURE__ */ new Map();
+    const wireActions = options.actions?.map(
+      ({ handler, ...wire }) => {
+        actionHandlers.set(wire.name, handler);
+        return wire;
+      }
+    );
+    this.declaration = {
+      id: options.id,
+      displayName: options.displayName,
+      description: options.description,
+      inputSchema: options.inputSchema,
+      actions: wireActions
+    };
+    this.open = options.open;
+    this.onClose = options.onClose;
+    this.actionHandlers = actionHandlers;
+  }
+}
+function createCanvas(options) {
+  return new Canvas(options);
+}
+async function dispatchCanvasProviderRequest(canvas, actionName, params) {
+  switch (actionName) {
+    case "canvas.open": {
+      const result = await canvas.open({
+        sessionId: params.sessionId,
+        extensionId: params.extensionId,
+        canvasId: params.canvasId,
+        instanceId: params.instanceId,
+        input: params.input,
+        host: params.host
+      });
+      return result ?? {};
+    }
+    case "canvas.close": {
+      if (canvas.onClose) {
+        await canvas.onClose({
+          sessionId: params.sessionId,
+          extensionId: params.extensionId,
+          canvasId: params.canvasId,
+          instanceId: params.instanceId,
+          host: params.host
+        });
+      }
+      return void 0;
+    }
+    default: {
+      const perAction = canvas.actionHandlers.get(actionName);
+      if (!perAction) {
+        throw CanvasError.noHandler();
+      }
+      return perAction({
+        sessionId: params.sessionId,
+        extensionId: params.extensionId,
+        canvasId: params.canvasId,
+        instanceId: params.instanceId,
+        actionName,
+        input: params.input,
+        host: params.host
+      });
+    }
+  }
+}
+export {
+  Canvas,
+  CanvasError,
+  createCanvas,
+  dispatchCanvasProviderRequest
+};

package/dist/cjs/canvas.js

@@ -0,0 +1,119 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var canvas_exports = {};
+__export(canvas_exports, {
+  Canvas: () => Canvas,
+  CanvasError: () => CanvasError,
+  createCanvas: () => createCanvas,
+  dispatchCanvasProviderRequest: () => dispatchCanvasProviderRequest
+});
+module.exports = __toCommonJS(canvas_exports);
+class CanvasError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "CanvasError";
+  }
+  /** Default error when an action is declared but no `handler` is wired. */
+  static noHandler() {
+    return new CanvasError(
+      "canvas_action_no_handler",
+      "No handler implemented for this canvas action"
+    );
+  }
+}
+class Canvas {
+  declaration;
+  open;
+  onClose;
+  /** @internal */
+  actionHandlers;
+  /** @internal */
+  constructor(options) {
+    const actionHandlers = /* @__PURE__ */ new Map();
+    const wireActions = options.actions?.map(
+      ({ handler, ...wire }) => {
+        actionHandlers.set(wire.name, handler);
+        return wire;
+      }
+    );
+    this.declaration = {
+      id: options.id,
+      displayName: options.displayName,
+      description: options.description,
+      inputSchema: options.inputSchema,
+      actions: wireActions
+    };
+    this.open = options.open;
+    this.onClose = options.onClose;
+    this.actionHandlers = actionHandlers;
+  }
+}
+function createCanvas(options) {
+  return new Canvas(options);
+}
+async function dispatchCanvasProviderRequest(canvas, actionName, params) {
+  switch (actionName) {
+    case "canvas.open": {
+      const result = await canvas.open({
+        sessionId: params.sessionId,
+        extensionId: params.extensionId,
+        canvasId: params.canvasId,
+        instanceId: params.instanceId,
+        input: params.input,
+        host: params.host
+      });
+      return result ?? {};
+    }
+    case "canvas.close": {
+      if (canvas.onClose) {
+        await canvas.onClose({
+          sessionId: params.sessionId,
+          extensionId: params.extensionId,
+          canvasId: params.canvasId,
+          instanceId: params.instanceId,
+          host: params.host
+        });
+      }
+      return void 0;
+    }
+    default: {
+      const perAction = canvas.actionHandlers.get(actionName);
+      if (!perAction) {
+        throw CanvasError.noHandler();
+      }
+      return perAction({
+        sessionId: params.sessionId,
+        extensionId: params.extensionId,
+        canvasId: params.canvasId,
+        instanceId: params.instanceId,
+        actionName,
+        input: params.input,
+        host: params.host
+      });
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Canvas,
+  CanvasError,
+  createCanvas,
+  dispatchCanvasProviderRequest
+});