@github/copilot-sdk 0.3.0 → 1.0.0-beta.10

package/README.md

@@ -32,13 +32,13 @@ import { CopilotClient, approveAll } from "@github/copilot-sdk";
 const client = new CopilotClient();
 await client.start();
 
-// Create a session (onPermissionRequest is required)
+// Create a session (onPermissionRequest is optional; approveAll allows every tool)
 const session = await client.createSession({
     model: "gpt-5",
     onPermissionRequest: approveAll,
 });
 
-// Wait for response using typed event handlers
+// Wait for the response using typed event handlers
 const done = new Promise<void>((resolve) => {
     session.on("assistant.message", (event) => {
         console.log(event.data.content);
@@ -79,17 +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`.
-- `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
 
@@ -114,11 +114,11 @@ Create a new conversation session.
 - `sessionId?: string` - Custom session ID.
 - `model?: string` - Model to use ("gpt-5", "claude-sonnet-4.5", etc.). **Required when using custom provider.**
 - `reasoningEffort?: "low" | "medium" | "high" | "xhigh"` - Reasoning effort level for models that support it. Use `listModels()` to check which models support this option.
-- `tools?: Tool[]` - Custom tools exposed to the CLI
+- `tools?: Tool[]` - Custom tools exposed to the CLI. Tools without `handler` are declaration-only and must be resolved via pending tool-call RPCs.
 - `systemMessage?: SystemMessageConfig` - System message customization (see below)
 - `infiniteSessions?: InfiniteSessionConfig` - Configure automatic context compaction (see below)
 - `provider?: ProviderConfig` - Custom API provider configuration (BYOK - Bring Your Own Key). See [Custom Providers](#custom-providers) section.
-- `onPermissionRequest: PermissionHandler` - **Required.** Handler called before each tool execution to approve or deny it. Use `approveAll` to allow everything, or provide a custom function for fine-grained control. See [Permission Handling](#permission-handling) section.
+- `onPermissionRequest?: PermissionHandler` - Optional handler called before each tool execution to approve or deny it. When omitted, permission requests are emitted as events and left pending for manual resolution. Use `approveAll` to allow everything, or provide a custom function for fine-grained control. See [Permission Handling](#permission-handling) section.
 - `onUserInputRequest?: UserInputHandler` - Handler for user input requests from the agent. Enables the `ask_user` tool. See [User Input Requests](#user-input-requests) section.
 - `onElicitationRequest?: ElicitationHandler` - Handler for elicitation requests dispatched by the server. Enables this client to present form-based UI dialogs on behalf of the agent or other session participants. See [Elicitation Requests](#elicitation-requests) section.
 - `hooks?: SessionHooks` - Hook handlers for session lifecycle events. See [Session Hooks](#session-hooks) section.
@@ -127,14 +127,10 @@ Create a new conversation session.
 
 Resume an existing session. Returns the session with `workspacePath` populated if infinite sessions were enabled.
 
-##### `ping(message?: string): Promise<{ message: string; timestamp: number }>`
+##### `ping(message?: string): Promise<{ message: string; timestamp: string }>`
 
 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.
@@ -172,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`);
 });
 ```
@@ -182,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}`);
 });
 ```
@@ -276,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.
 
@@ -414,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();
@@ -573,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",
@@ -597,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:
 
@@ -801,7 +797,7 @@ Inbound trace context from the CLI is available on the `ToolInvocation` object p
 
 ## Permission Handling
 
-An `onPermissionRequest` handler is **required** whenever you create or resume a session. The handler is called before the agent executes each tool (file writes, shell commands, custom tools, etc.) and must return a decision.
+An `onPermissionRequest` handler is optional when you create or resume a session. When provided, it is called before the agent executes each tool (file writes, shell commands, custom tools, etc.) and returns a decision. When omitted, permission requests are emitted as events and left pending for the consumer to resolve with the pending permission RPC.
 
 ### Approve All (simplest)
 
@@ -842,29 +838,32 @@ const session = await client.createSession({
         // request.fullCommandText — full shell command (for shell)
 
         if (request.kind === "shell") {
-            // Deny shell commands
-            return { kind: "denied-interactively-by-user" };
+            // Deny shell commands, optionally telling the model why
+            return { kind: "reject", feedback: "Shell commands are not allowed." };
         }
 
-        return { kind: "approved" };
+        return { kind: "approve-once" };
     },
 });
 ```
 
 ### Permission Result Kinds
 
-| Kind                                                        | Meaning                                                                                     |
-| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `"approved"`                                                | Allow the tool to run                                                                       |
-| `"denied-interactively-by-user"`                            | User explicitly denied the request                                                          |
-| `"denied-no-approval-rule-and-could-not-request-from-user"` | No approval rule matched and user could not be asked                                        |
-| `"denied-by-rules"`                                         | Denied by a policy rule                                                                     |
-| `"denied-by-content-exclusion-policy"`                      | Denied due to a content exclusion policy                                                    |
-| `"no-result"`                                               | Leave the request unanswered (only valid with protocol v1; rejected by protocol v2 servers) |
+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)           |
+| `"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)  | —                                                                       |
 
 ### Resuming Sessions
 
-Pass `onPermissionRequest` when resuming a session too — it is required:
+You may pass `onPermissionRequest` when resuming a session too:
 
 ```typescript
 const session = await client.resumeSession("session-id", {
@@ -958,7 +957,7 @@ const session = await client.createSession({
             };
         },
 
-        // Called after each tool execution
+        // Called after each successful tool execution
         onPostToolUse: async (input, invocation) => {
             console.log(`Tool ${input.toolName} completed`);
             // Optionally modify the result or add context
@@ -967,6 +966,16 @@ const session = await client.createSession({
             };
         },
 
+        // Called after a tool execution whose result was "failure".
+        // onPostToolUse does NOT fire for failed tool calls — register this
+        // hook to observe them. Input includes `error` (the failure message
+        // extracted from the tool's result), not the full result object.
+        onPostToolUseFailure: async (input, invocation) => {
+            console.log(`Tool ${input.toolName} failed: ${input.error}`);
+            // Optionally append hidden guidance to the model.
+            return { additionalContext: "Suggest checking inputs and retrying." };
+        },
+
         // Called when user submits a prompt
         onUserPromptSubmitted: async (input, invocation) => {
             console.log(`User prompt: ${input.prompt}`);
@@ -1002,7 +1011,8 @@ const session = await client.createSession({
 **Available hooks:**
 
 - `onPreToolUse` - Intercept tool calls before execution. Can allow/deny or modify arguments.
-- `onPostToolUse` - Process tool results after execution. Can modify results or add context.
+- `onPostToolUse` - Process tool results after **successful** execution. Can modify results or add context.
+- `onPostToolUseFailure` - Observe and append hidden guidance to the model after tool executions whose result was `"failure"`. Register this in addition to `onPostToolUse` to see failed tool calls.
 - `onUserPromptSubmitted` - Intercept user prompts. Can modify the prompt before processing.
 - `onSessionStart` - Run logic when a session starts or resumes.
 - `onSessionEnd` - Cleanup or logging when session ends.
@@ -1022,7 +1032,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,126 @@
+import type { CanvasJsonSchema, CanvasProviderCloseRequest, CanvasProviderInvokeActionRequest, CanvasProviderOpenRequest, CanvasProviderOpenResult } 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.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
+ * (`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.
+ *
+ * @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. */
+    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: CanvasProviderInvokeActionRequest) => Promise<unknown> | unknown;
+}
+/**
+ * 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. */
+    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">[];
+}
+/**
+ * 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);
+    /** 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.
+ *
+ * @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 */
+    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: CanvasProviderOpenRequest) => Promise<CanvasProviderOpenResult> | CanvasProviderOpenResult;
+    /**
+     * 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: CanvasProviderCloseRequest) => 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.
+ *
+ * @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;
+    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.
+ *
+ * @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/canvas.js

@@ -0,0 +1,49 @@
+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);
+}
+export {
+  Canvas,
+  CanvasError,
+  createCanvas
+};

package/dist/cjs/canvas.js

@@ -0,0 +1,75 @@
+"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
+});
+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);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Canvas,
+  CanvasError,
+  createCanvas
+});