@github/copilot-sdk 0.1.32 → 0.1.33-preview.1

package/dist/session.d.ts

@@ -2,9 +2,10 @@
  * Copilot Session - represents a single conversation session with the Copilot CLI.
  * @module session
  */
-import type { MessageConnection } from "vscode-jsonrpc/node";
+import type { MessageConnection } from "vscode-jsonrpc/node.js";
 import { createSessionRpc } from "./generated/rpc.js";
 import type { MessageOptions, PermissionHandler, PermissionRequestResult, SessionEvent, SessionEventHandler, SessionEventType, SessionHooks, Tool, ToolHandler, TypedSessionEventHandler, UserInputHandler, UserInputResponse } from "./types.js";
+export declare const NO_RESULT_PERMISSION_V2_ERROR = "Permission handlers cannot return 'no-result' when connected to a protocol v2 server.";
 /** Assistant message event - the final response from the assistant. */
 export type AssistantMessageEvent = Extract<SessionEvent, {
     type: "assistant.message";
@@ -37,7 +38,7 @@ export type AssistantMessageEvent = Extract<SessionEvent, {
 export declare class CopilotSession {
     readonly sessionId: string;
     private connection;
-    private readonly _workspacePath?;
+    private _workspacePath?;
     private eventHandlers;
     private typedEventHandlers;
     private toolHandlers;
@@ -339,4 +340,24 @@ export declare class CopilotSession {
      * ```
      */
     setModel(model: string): Promise<void>;
+    /**
+     * Log a message to the session timeline.
+     * The message appears in the session event stream and is visible to SDK consumers
+     * and (for non-ephemeral messages) persisted to the session event log on disk.
+     *
+     * @param message - Human-readable message text
+     * @param options - Optional log level and ephemeral flag
+     *
+     * @example
+     * ```typescript
+     * await session.log("Processing started");
+     * await session.log("Disk usage high", { level: "warning" });
+     * await session.log("Connection failed", { level: "error" });
+     * await session.log("Debug info", { ephemeral: true });
+     * ```
+     */
+    log(message: string, options?: {
+        level?: "info" | "warning" | "error";
+        ephemeral?: boolean;
+    }): Promise<void>;
 }

package/dist/session.js

@@ -1,5 +1,6 @@
-import { ConnectionError, ResponseError } from "vscode-jsonrpc/node";
+import { ConnectionError, ResponseError } from "vscode-jsonrpc/node.js";
 import { createSessionRpc } from "./generated/rpc.js";
+const NO_RESULT_PERMISSION_V2_ERROR = "Permission handlers cannot return 'no-result' when connected to a protocol v2 server.";
 class CopilotSession {
   /**
    * Creates a new CopilotSession instance.
@@ -239,6 +240,9 @@ class CopilotSession {
       const result = await this.permissionHandler(permissionRequest, {
         sessionId: this.sessionId
       });
+      if (result.kind === "no-result") {
+        return;
+      }
       await this.rpc.permissions.handlePendingPermissionRequest({ requestId, result });
     } catch (_error) {
       try {
@@ -335,8 +339,14 @@ class CopilotSession {
       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) {
+    } catch (error) {
+      if (error instanceof Error && error.message === NO_RESULT_PERMISSION_V2_ERROR) {
+        throw error;
+      }
       return { kind: "denied-no-approval-rule-and-could-not-request-from-user" };
     }
   }
@@ -501,7 +511,27 @@ class CopilotSession {
   async setModel(model) {
     await this.rpc.model.switchTo({ modelId: model });
   }
+  /**
+   * Log a message to the session timeline.
+   * The message appears in the session event stream and is visible to SDK consumers
+   * and (for non-ephemeral messages) persisted to the session event log on disk.
+   *
+   * @param message - Human-readable message text
+   * @param options - Optional log level and ephemeral flag
+   *
+   * @example
+   * ```typescript
+   * await session.log("Processing started");
+   * await session.log("Disk usage high", { level: "warning" });
+   * await session.log("Connection failed", { level: "error" });
+   * await session.log("Debug info", { ephemeral: true });
+   * ```
+   */
+  async log(message, options) {
+    await this.rpc.log({ message, ...options });
+  }
 }
 export {
-  CopilotSession
+  CopilotSession,
+  NO_RESULT_PERMISSION_V2_ERROR
 };

package/dist/types.d.ts

@@ -56,8 +56,7 @@ export interface CopilotClientOptions {
      */
     autoStart?: boolean;
     /**
-     * Auto-restart the CLI server if it crashes
-     * @default true
+     * @deprecated This option has no effect and will be removed in a future release.
      */
     autoRestart?: boolean;
     /**
@@ -77,6 +76,13 @@ export interface CopilotClientOptions {
      * @default true (but defaults to false when githubToken is provided)
      */
     useLoggedInUser?: boolean;
+    /**
+     * Custom handler for listing available models.
+     * When provided, client.listModels() calls this handler instead of
+     * querying the CLI server. Useful in BYOK mode to return models
+     * available from your custom provider.
+     */
+    onListModels?: () => Promise<ModelInfo[]> | ModelInfo[];
 }
 /**
  * Configuration for creating a session
@@ -129,6 +135,10 @@ export interface Tool<TArgs = unknown> {
      * will return an error.
      */
     overridesBuiltInTool?: boolean;
+    /**
+     * When true, the tool can execute without a permission prompt.
+     */
+    skipPermission?: boolean;
 }
 /**
  * Helper to define a tool with Zod schema and get type inference for the handler.
@@ -139,6 +149,7 @@ export declare function defineTool<T = unknown>(name: string, config: {
     parameters?: ZodSchema<T> | Record<string, unknown>;
     handler: ToolHandler<T>;
     overridesBuiltInTool?: boolean;
+    skipPermission?: boolean;
 }): Tool<T>;
 export interface ToolCallRequestPayload {
     sessionId: string;
@@ -186,7 +197,9 @@ export interface PermissionRequest {
     [key: string]: unknown;
 }
 import type { SessionPermissionsHandlePendingPermissionRequestParams } from "./generated/rpc.js";
-export type PermissionRequestResult = SessionPermissionsHandlePendingPermissionRequestParams["result"];
+export type PermissionRequestResult = SessionPermissionsHandlePendingPermissionRequestParams["result"] | {
+    kind: "no-result";
+};
 export type PermissionHandler = (request: PermissionRequest, invocation: {
     sessionId: string;
 }) => Promise<PermissionRequestResult> | PermissionRequestResult;
@@ -586,6 +599,12 @@ export interface SessionConfig {
      * Custom agent configurations for the session.
      */
     customAgents?: CustomAgentConfig[];
+    /**
+     * Name of the custom agent to activate when the session starts.
+     * Must match the `name` of one of the agents in `customAgents`.
+     * Equivalent to calling `session.rpc.agent.select({ name })` after creation.
+     */
+    agent?: string;
     /**
      * Directories to load skills from.
      */
@@ -600,11 +619,21 @@ export interface SessionConfig {
      * Set to `{ enabled: false }` to disable.
      */
     infiniteSessions?: InfiniteSessionConfig;
+    /**
+     * Optional event handler that is registered on the session before the
+     * session.create RPC is issued. This guarantees that early events emitted
+     * by the CLI during session creation (e.g. session.start) are delivered to
+     * the handler.
+     *
+     * Equivalent to calling `session.on(handler)` immediately after creation,
+     * but executes earlier in the lifecycle so no events are missed.
+     */
+    onEvent?: SessionEventHandler;
 }
 /**
  * Configuration for resuming a session
  */
-export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "tools" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "streaming" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "hooks" | "workingDirectory" | "configDir" | "mcpServers" | "customAgents" | "skillDirectories" | "disabledSkills" | "infiniteSessions"> & {
+export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "tools" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "streaming" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "hooks" | "workingDirectory" | "configDir" | "mcpServers" | "customAgents" | "agent" | "skillDirectories" | "disabledSkills" | "infiniteSessions" | "onEvent"> & {
     /**
      * When true, skips emitting the session.resume event.
      * Useful for reconnecting to a session without triggering resume-related side effects.

package/docs/agent-author.md

@@ -0,0 +1,263 @@
+# Agent Extension Authoring Guide
+
+A precise, step-by-step reference for agents writing Copilot CLI extensions programmatically.
+
+## Workflow
+
+### Step 1: Scaffold the extension
+
+Use the `extensions_manage` tool with `operation: "scaffold"`:
+
+```
+extensions_manage({ operation: "scaffold", name: "my-extension" })
+```
+
+This creates `.github/extensions/my-extension/extension.mjs` with a working skeleton.
+For user-scoped extensions (persist across all repos), add `location: "user"`.
+
+### Step 2: Edit the extension file
+
+Modify the generated `extension.mjs` using `edit` or `create` tools. The file must:
+- Be named `extension.mjs` (only `.mjs` is supported)
+- Use ES module syntax (`import`/`export`)
+- Call `joinSession({ ... })`
+
+### Step 3: Reload extensions
+
+```
+extensions_reload({})
+```
+
+This stops all running extensions and re-discovers/re-launches them. New tools are available immediately in the same turn (mid-turn refresh).
+
+### Step 4: Verify
+
+```
+extensions_manage({ operation: "list" })
+extensions_manage({ operation: "inspect", name: "my-extension" })
+```
+
+Check that the extension loaded successfully and isn't marked as "failed".
+
+---
+
+## File Structure
+
+```
+.github/extensions/<name>/extension.mjs
+```
+
+Discovery rules:
+- The CLI scans `.github/extensions/` relative to the git root
+- It also scans the user's copilot config extensions directory
+- Only immediate subdirectories are checked (not recursive)
+- Each subdirectory must contain a file named `extension.mjs`
+- Project extensions shadow user extensions on name collision
+
+---
+
+## Minimal Skeleton
+
+```js
+import { joinSession } from "@github/copilot-sdk/extension";
+
+await joinSession({
+    tools: [],                     // Optional — custom tools
+    hooks: {},                     // Optional — lifecycle hooks
+});
+```
+
+---
+
+## Registering Tools
+
+```js
+tools: [
+    {
+        name: "tool_name",           // Required. Must be globally unique across all extensions.
+        description: "What it does", // Required. Shown to the agent in tool descriptions.
+        parameters: {                // Optional. JSON Schema for the arguments.
+            type: "object",
+            properties: {
+                arg1: { type: "string", description: "..." },
+            },
+            required: ["arg1"],
+        },
+        handler: async (args, invocation) => {
+            // args: parsed arguments matching the schema
+            // invocation.sessionId: current session ID
+            // invocation.toolCallId: unique call ID
+            // invocation.toolName: this tool's name
+            //
+            // Return value: string or ToolResultObject
+            //   string → treated as success
+            //   { textResultForLlm, resultType } → structured result
+            //     resultType: "success" | "failure" | "rejected" | "denied"
+            return `Result: ${args.arg1}`;
+        },
+    },
+]
+```
+
+**Constraints:**
+- Tool names must be unique across ALL loaded extensions. Collisions cause the second extension to fail to load.
+- Handler must return a string or `{ textResultForLlm: string, resultType?: string }`.
+- Handler receives `(args, invocation)` — the second argument has `sessionId`, `toolCallId`, `toolName`.
+- Use `session.log()` to surface messages to the user. Don't use `console.log()` (stdout is reserved for JSON-RPC).
+
+---
+
+## Registering Hooks
+
+```js
+hooks: {
+    onUserPromptSubmitted: async (input, invocation) => { ... },
+    onPreToolUse: async (input, invocation) => { ... },
+    onPostToolUse: async (input, invocation) => { ... },
+    onSessionStart: async (input, invocation) => { ... },
+    onSessionEnd: async (input, invocation) => { ... },
+    onErrorOccurred: async (input, invocation) => { ... },
+}
+```
+
+All hook inputs include `timestamp` (unix ms) and `cwd` (working directory).
+All handlers receive `invocation: { sessionId: string }` as the second argument.
+All handlers may return `void`/`undefined` (no-op) or an output object.
+
+### onUserPromptSubmitted
+
+**Input:** `{ prompt: string, timestamp, cwd }`
+
+**Output (all fields optional):**
+| Field | Type | Effect |
+|-------|------|--------|
+| `modifiedPrompt` | `string` | Replaces the user's prompt |
+| `additionalContext` | `string` | Appended as hidden context the agent sees |
+
+### onPreToolUse
+
+**Input:** `{ toolName: string, toolArgs: unknown, timestamp, cwd }`
+
+**Output (all fields optional):**
+| Field | Type | Effect |
+|-------|------|--------|
+| `permissionDecision` | `"allow" \| "deny" \| "ask"` | Override the permission check |
+| `permissionDecisionReason` | `string` | Shown to user if denied |
+| `modifiedArgs` | `unknown` | Replaces the tool arguments |
+| `additionalContext` | `string` | Injected into the conversation |
+
+### onPostToolUse
+
+**Input:** `{ toolName: string, toolArgs: unknown, toolResult: ToolResultObject, timestamp, cwd }`
+
+**Output (all fields optional):**
+| Field | Type | Effect |
+|-------|------|--------|
+| `modifiedResult` | `ToolResultObject` | Replaces the tool result |
+| `additionalContext` | `string` | Injected into the conversation |
+
+### onSessionStart
+
+**Input:** `{ source: "startup" \| "resume" \| "new", initialPrompt?: string, timestamp, cwd }`
+
+**Output (all fields optional):**
+| Field | Type | Effect |
+|-------|------|--------|
+| `additionalContext` | `string` | Injected as initial context |
+
+### onSessionEnd
+
+**Input:** `{ reason: "complete" \| "error" \| "abort" \| "timeout" \| "user_exit", finalMessage?: string, error?: string, timestamp, cwd }`
+
+**Output (all fields optional):**
+| Field | Type | Effect |
+|-------|------|--------|
+| `sessionSummary` | `string` | Summary for session persistence |
+| `cleanupActions` | `string[]` | Cleanup descriptions |
+
+### onErrorOccurred
+
+**Input:** `{ error: string, errorContext: "model_call" \| "tool_execution" \| "system" \| "user_input", recoverable: boolean, timestamp, cwd }`
+
+**Output (all fields optional):**
+| Field | Type | Effect |
+|-------|------|--------|
+| `errorHandling` | `"retry" \| "skip" \| "abort"` | How to handle the error |
+| `retryCount` | `number` | Max retries (when errorHandling is "retry") |
+| `userNotification` | `string` | Message shown to the user |
+
+---
+
+## Session Object
+
+After `joinSession()`, the returned `session` provides:
+
+### session.send(options)
+
+Send a message programmatically:
+```js
+await session.send({ prompt: "Analyze the test results." });
+await session.send({
+    prompt: "Review this file",
+    attachments: [{ type: "file", path: "./src/index.ts" }],
+});
+```
+
+### session.sendAndWait(options, timeout?)
+
+Send and block until the agent finishes (resolves on `session.idle`):
+```js
+const response = await session.sendAndWait({ prompt: "What is 2+2?" });
+// response?.data.content contains the agent's reply
+```
+
+### session.log(message, options?)
+
+Log to the CLI timeline:
+```js
+await session.log("Extension ready");
+await session.log("Rate limit approaching", { level: "warning" });
+await session.log("Connection failed", { level: "error" });
+await session.log("Processing...", { ephemeral: true }); // transient, not persisted
+```
+
+### session.on(eventType, handler)
+
+Subscribe to session events. Returns an unsubscribe function.
+```js
+const unsub = session.on("tool.execution_complete", (event) => {
+    // event.data.toolName, event.data.success, event.data.result
+});
+```
+
+### Key Event Types
+
+| Event | Key Data Fields |
+|-------|----------------|
+| `assistant.message` | `content`, `messageId` |
+| `tool.execution_start` | `toolCallId`, `toolName`, `arguments` |
+| `tool.execution_complete` | `toolCallId`, `toolName`, `success`, `result`, `error` |
+| `user.message` | `content`, `attachments`, `source` |
+| `session.idle` | `backgroundTasks` |
+| `session.error` | `errorType`, `message`, `stack` |
+| `permission.requested` | `requestId`, `permissionRequest.kind` |
+| `session.shutdown` | `shutdownType`, `totalPremiumRequests` |
+
+### session.workspacePath
+
+Path to the session workspace directory (checkpoints, plan.md, files/). `undefined` if infinite sessions disabled.
+
+### session.rpc
+
+Low-level typed RPC access to all session APIs (model, mode, plan, workspace, etc.).
+
+---
+
+## Gotchas
+
+- **stdout is reserved for JSON-RPC.** Don't use `console.log()` — it will corrupt the protocol. Use `session.log()` to surface messages to the user.
+- **Tool name collisions are fatal.** If two extensions register the same tool name, the second extension fails to initialize.
+- **Don't call `session.send()` synchronously from `onUserPromptSubmitted`.** Use `setTimeout(() => session.send(...), 0)` to avoid infinite loops.
+- **Extensions are reloaded on `/clear`.** Any in-memory state is lost between sessions.
+- **Only `.mjs` is supported.** TypeScript (`.ts`) is not yet supported.
+- **The handler's return value is the tool result.** Returning `undefined` sends an empty success. Throwing sends a failure with the error message.