@github/copilot-sdk 0.2.2 → 0.3.0-preview.1

package/dist/index.d.ts

@@ -5,5 +5,5 @@
  */
 export { CopilotClient } from "./client.js";
 export { CopilotSession, type AssistantMessageEvent } from "./session.js";
-export { defineTool, approveAll, SYSTEM_PROMPT_SECTIONS } from "./types.js";
-export type { CommandContext, CommandDefinition, CommandHandler, ConnectionState, CopilotClientOptions, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, InputOptions, MCPLocalServerConfig, MCPRemoteServerConfig, MCPServerConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventType, SessionLifecycleHandler, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsHandler, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemPromptSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export { defineTool, approveAll, convertMcpCallToolResult, createSessionFsAdapter, SYSTEM_PROMPT_SECTIONS, } from "./types.js";
+export type { CommandContext, CommandDefinition, CommandHandler, ConnectionState, CopilotClientOptions, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, InfiniteSessionConfig, InputOptions, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, MessageOptions, ModelBilling, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, PermissionHandler, PermissionRequest, PermissionRequestResult, ProviderConfig, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventType, SessionLifecycleHandler, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemPromptSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, ToolResultObject, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";

package/dist/index.js

@@ -1,10 +1,18 @@
 import { CopilotClient } from "./client.js";
 import { CopilotSession } from "./session.js";
-import { defineTool, approveAll, SYSTEM_PROMPT_SECTIONS } from "./types.js";
+import {
+  defineTool,
+  approveAll,
+  convertMcpCallToolResult,
+  createSessionFsAdapter,
+  SYSTEM_PROMPT_SECTIONS
+} from "./types.js";
 export {
   CopilotClient,
   CopilotSession,
   SYSTEM_PROMPT_SECTIONS,
   approveAll,
+  convertMcpCallToolResult,
+  createSessionFsAdapter,
   defineTool
 };

package/dist/session.js

@@ -100,7 +100,8 @@ class CopilotSession {
       sessionId: this.sessionId,
       prompt: options.prompt,
       attachments: options.attachments,
-      mode: options.mode
+      mode: options.mode,
+      requestHeaders: options.requestHeaders
     });
     return response.messageId;
   }
@@ -324,7 +325,7 @@ class CopilotSession {
         await this.rpc.permissions.handlePendingPermissionRequest({
           requestId,
           result: {
-            kind: "denied-no-approval-rule-and-could-not-request-from-user"
+            kind: "user-not-available"
           }
         });
       } catch (rpcError) {
@@ -602,7 +603,7 @@ class CopilotSession {
    */
   async _handlePermissionRequestV2(request) {
     if (!this.permissionHandler) {
-      return { kind: "denied-no-approval-rule-and-could-not-request-from-user" };
+      return { kind: "user-not-available" };
     }
     try {
       const result = await this.permissionHandler(request, {
@@ -616,7 +617,7 @@ class CopilotSession {
       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" };
+      return { kind: "user-not-available" };
     }
   }
   /**

package/dist/sessionFsProvider.d.ts

@@ -0,0 +1,44 @@
+import type { SessionFsHandler, SessionFsStatResult, SessionFsReaddirWithTypesEntry } from "./generated/rpc.js";
+/**
+ * File metadata returned by {@link SessionFsProvider.stat}.
+ * Same shape as the generated {@link SessionFsStatResult} but without the
+ * `error` field, since providers signal errors by throwing.
+ */
+export type SessionFsFileInfo = Omit<SessionFsStatResult, "error">;
+/**
+ * Interface for session filesystem providers. Implementors use idiomatic
+ * TypeScript patterns: throw on error, return values directly. Use
+ * {@link createSessionFsAdapter} to convert a provider into the
+ * {@link SessionFsHandler} expected by the SDK.
+ *
+ * Errors with a `code` property of `"ENOENT"` are mapped to the ENOENT
+ * error code; all others map to UNKNOWN.
+ */
+export interface SessionFsProvider {
+    /** Reads the full content of a file. Throw if the file does not exist. */
+    readFile(path: string): Promise<string>;
+    /** Writes content to a file, creating parent directories if needed. */
+    writeFile(path: string, content: string, mode?: number): Promise<void>;
+    /** Appends content to a file, creating parent directories if needed. */
+    appendFile(path: string, content: string, mode?: number): Promise<void>;
+    /** Checks whether a path exists. */
+    exists(path: string): Promise<boolean>;
+    /** Gets metadata about a file or directory. Throw if it does not exist. */
+    stat(path: string): Promise<SessionFsFileInfo>;
+    /** Creates a directory. If recursive is true, creates parents as needed. */
+    mkdir(path: string, recursive: boolean, mode?: number): Promise<void>;
+    /** Lists entry names in a directory. Throw if it does not exist. */
+    readdir(path: string): Promise<string[]>;
+    /** Lists entries with type info. Throw if the directory does not exist. */
+    readdirWithTypes(path: string): Promise<SessionFsReaddirWithTypesEntry[]>;
+    /** Removes a file or directory. If force is true, do not throw on ENOENT. */
+    rm(path: string, recursive: boolean, force: boolean): Promise<void>;
+    /** Renames/moves a file or directory. */
+    rename(src: string, dest: string): Promise<void>;
+}
+/**
+ * Wraps a {@link SessionFsProvider} into the {@link SessionFsHandler}
+ * interface expected by the SDK, converting thrown errors into
+ * {@link SessionFsError} results.
+ */
+export declare function createSessionFsAdapter(provider: SessionFsProvider): SessionFsHandler;

package/dist/sessionFsProvider.js

@@ -0,0 +1,97 @@
+function createSessionFsAdapter(provider) {
+  return {
+    readFile: async ({ path }) => {
+      try {
+        const content = await provider.readFile(path);
+        return { content };
+      } catch (err) {
+        return { content: "", error: toSessionFsError(err) };
+      }
+    },
+    writeFile: async ({ path, content, mode }) => {
+      try {
+        await provider.writeFile(path, content, mode);
+        return void 0;
+      } catch (err) {
+        return toSessionFsError(err);
+      }
+    },
+    appendFile: async ({ path, content, mode }) => {
+      try {
+        await provider.appendFile(path, content, mode);
+        return void 0;
+      } catch (err) {
+        return toSessionFsError(err);
+      }
+    },
+    exists: async ({ path }) => {
+      try {
+        return { exists: await provider.exists(path) };
+      } catch {
+        return { exists: false };
+      }
+    },
+    stat: async ({ path }) => {
+      try {
+        return await provider.stat(path);
+      } catch (err) {
+        return {
+          isFile: false,
+          isDirectory: false,
+          size: 0,
+          mtime: (/* @__PURE__ */ new Date()).toISOString(),
+          birthtime: (/* @__PURE__ */ new Date()).toISOString(),
+          error: toSessionFsError(err)
+        };
+      }
+    },
+    mkdir: async ({ path, recursive, mode }) => {
+      try {
+        await provider.mkdir(path, recursive ?? false, mode);
+        return void 0;
+      } catch (err) {
+        return toSessionFsError(err);
+      }
+    },
+    readdir: async ({ path }) => {
+      try {
+        const entries = await provider.readdir(path);
+        return { entries };
+      } catch (err) {
+        return { entries: [], error: toSessionFsError(err) };
+      }
+    },
+    readdirWithTypes: async ({ path }) => {
+      try {
+        const entries = await provider.readdirWithTypes(path);
+        return { entries };
+      } catch (err) {
+        return { entries: [], error: toSessionFsError(err) };
+      }
+    },
+    rm: async ({ path, recursive, force }) => {
+      try {
+        await provider.rm(path, recursive ?? false, force ?? false);
+        return void 0;
+      } catch (err) {
+        return toSessionFsError(err);
+      }
+    },
+    rename: async ({ src, dest }) => {
+      try {
+        await provider.rename(src, dest);
+        return void 0;
+      } catch (err) {
+        return toSessionFsError(err);
+      }
+    }
+  };
+}
+function toSessionFsError(err) {
+  const e = err;
+  const code = e.code === "ENOENT" ? "ENOENT" : "UNKNOWN";
+  return { code, message: e.message ?? String(err) };
+}
+export {
+  createSessionFsAdapter
+};

package/dist/types.d.ts

@@ -1,11 +1,13 @@
 /**
  * Type definitions for the Copilot SDK
  */
-import type { SessionFsHandler } from "./generated/rpc.js";
+import type { SessionFsProvider } from "./sessionFsProvider.js";
 import type { SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
 import type { CopilotSession } from "./session.js";
 export type SessionEvent = GeneratedSessionEvent;
-export type { SessionFsHandler } from "./generated/rpc.js";
+export type { SessionFsProvider } from "./sessionFsProvider.js";
+export { createSessionFsAdapter } from "./sessionFsProvider.js";
+export type { SessionFsFileInfo } from "./sessionFsProvider.js";
 /**
  * Options for creating a CopilotClient
  */
@@ -103,12 +105,12 @@ export interface CopilotClientOptions {
      * When provided, the token is passed to the CLI server via environment variable.
      * This takes priority over other authentication methods.
      */
-    githubToken?: string;
+    gitHubToken?: string;
     /**
      * Whether to use the logged-in user for authentication.
      * When true, the CLI server will attempt to use stored OAuth tokens or gh CLI auth.
-     * When false, only explicit tokens (githubToken or environment variables) are used.
-     * @default true (but defaults to false when githubToken is provided)
+     * When false, only explicit tokens (gitHubToken or environment variables) are used.
+     * @default true (but defaults to false when gitHubToken is provided)
      */
     useLoggedInUser?: boolean;
     /**
@@ -156,6 +158,15 @@ export interface CopilotClientOptions {
      * instead of the server's default local filesystem storage.
      */
     sessionFs?: SessionFsConfig;
+    /**
+     * Server-wide idle timeout for sessions in seconds.
+     * Sessions without activity for this duration are automatically cleaned up.
+     * Set to 0 or omit to disable (sessions live indefinitely).
+     * This option is only used when the SDK spawns the CLI process; it is ignored
+     * when connecting to an external server via {@link cliUrl}.
+     * @default undefined (disabled)
+     */
+    sessionIdleTimeoutSeconds?: number;
 }
 /**
  * Configuration for creating a session
@@ -176,6 +187,40 @@ export type ToolResultObject = {
     toolTelemetry?: Record<string, unknown>;
 };
 export type ToolResult = string | ToolResultObject;
+/**
+ * Content block types within an MCP CallToolResult.
+ */
+type McpCallToolResultTextContent = {
+    type: "text";
+    text: string;
+};
+type McpCallToolResultImageContent = {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+type McpCallToolResultResourceContent = {
+    type: "resource";
+    resource: {
+        uri: string;
+        mimeType?: string;
+        text?: string;
+        blob?: string;
+    };
+};
+type McpCallToolResultContent = McpCallToolResultTextContent | McpCallToolResultImageContent | McpCallToolResultResourceContent;
+/**
+ * MCP-compatible CallToolResult type. Can be passed to
+ * {@link convertMcpCallToolResult} to produce a {@link ToolResultObject}.
+ */
+type McpCallToolResult = {
+    content: McpCallToolResultContent[];
+    isError?: boolean;
+};
+/**
+ * Converts an MCP CallToolResult into the SDK's ToolResultObject format.
+ */
+export declare function convertMcpCallToolResult(callResult: McpCallToolResult): ToolResultObject;
 export interface ToolInvocation {
     sessionId: string;
     toolCallId: string;
@@ -532,18 +577,18 @@ export type SystemMessageConfig = SystemMessageAppendConfig | SystemMessageRepla
  * Permission request types from the server
  */
 export interface PermissionRequest {
-    kind: "shell" | "write" | "mcp" | "read" | "url" | "custom-tool";
+    kind: "shell" | "write" | "mcp" | "read" | "url" | "custom-tool" | "memory" | "hook";
     toolCallId?: string;
-    [key: string]: unknown;
 }
-import type { SessionPermissionsHandlePendingPermissionRequestParams } from "./generated/rpc.js";
-export type PermissionRequestResult = SessionPermissionsHandlePendingPermissionRequestParams["result"] | {
+import type { PermissionDecisionRequest } from "./generated/rpc.js";
+export type PermissionRequestResult = PermissionDecisionRequest["result"] | {
     kind: "no-result";
 };
 export type PermissionHandler = (request: PermissionRequest, invocation: {
     sessionId: string;
 }) => Promise<PermissionRequestResult> | PermissionRequestResult;
 export declare const approveAll: PermissionHandler;
+export declare const defaultJoinSessionPermissionHandler: PermissionHandler;
 /**
  * Request for user input from the agent (enables ask_user tool)
  */
@@ -756,8 +801,8 @@ interface MCPServerConfigBase {
      */
     tools: string[];
     /**
-     * Indicates "remote" or "local" server type.
-     * If not specified, defaults to "local".
+     * Indicates the server type: "stdio" for local/subprocess servers, "http"/"sse" for remote servers.
+     * If not specified, defaults to "stdio".
      */
     type?: string;
     /**
@@ -768,7 +813,7 @@ interface MCPServerConfigBase {
 /**
  * Configuration for a local/stdio MCP server.
  */
-export interface MCPLocalServerConfig extends MCPServerConfigBase {
+export interface MCPStdioServerConfig extends MCPServerConfigBase {
     type?: "local" | "stdio";
     command: string;
     args: string[];
@@ -781,7 +826,7 @@ export interface MCPLocalServerConfig extends MCPServerConfigBase {
 /**
  * Configuration for a remote MCP server (HTTP or SSE).
  */
-export interface MCPRemoteServerConfig extends MCPServerConfigBase {
+export interface MCPHTTPServerConfig extends MCPServerConfigBase {
     type: "http" | "sse";
     /**
      * URL of the remote server.
@@ -795,7 +840,7 @@ export interface MCPRemoteServerConfig extends MCPServerConfigBase {
 /**
  * Union type for MCP server configurations.
  */
-export type MCPServerConfig = MCPLocalServerConfig | MCPRemoteServerConfig;
+export type MCPServerConfig = MCPStdioServerConfig | MCPHTTPServerConfig;
 /**
  * Configuration for a custom agent.
  */
@@ -830,6 +875,28 @@ export interface CustomAgentConfig {
      * @default true
      */
     infer?: boolean;
+    /**
+     * List of skill names to preload into this agent's context.
+     * When set, the full content of each listed skill is eagerly injected into
+     * the agent's context at startup. Skills are resolved by name from the
+     * session's configured skill directories (`skillDirectories`).
+     * When omitted, no skills are injected (opt-in model).
+     */
+    skills?: string[];
+}
+/**
+ * Configuration for the default agent (the built-in agent that handles
+ * turns when no custom agent is selected).
+ * Use this to control tool visibility for the default agent independently of custom sub-agents.
+ */
+export interface DefaultAgentConfig {
+    /**
+     * List of tool names to exclude from the default agent.
+     * These tools remain available to custom sub-agents that reference them in their `tools` array.
+     * Use this to register tools that should only be accessed via delegation to sub-agents,
+     * keeping the default agent's context clean.
+     */
+    excludedTools?: string[];
 }
 /**
  * Configuration for infinite sessions with automatic context compaction and workspace persistence.
@@ -956,6 +1023,16 @@ export interface SessionConfig {
      */
     workingDirectory?: string;
     streaming?: boolean;
+    /**
+     * Include sub-agent streaming events in the event stream. When true, streaming
+     * delta events from sub-agents (e.g., `assistant.message_delta`,
+     * `assistant.reasoning_delta`, `assistant.streaming_delta` with `agentId` set)
+     * are forwarded to this connection. When false, only non-streaming sub-agent
+     * events and `subagent.*` lifecycle events are forwarded; streaming deltas from
+     * sub-agents are suppressed.
+     * @default true
+     */
+    includeSubAgentStreamingEvents?: boolean;
     /**
      * MCP server configurations for the session.
      * Keys are server names, values are server configurations.
@@ -965,6 +1042,13 @@ export interface SessionConfig {
      * Custom agent configurations for the session.
      */
     customAgents?: CustomAgentConfig[];
+    /**
+     * Configuration for the default agent (the built-in agent that handles
+     * turns when no custom agent is selected).
+     * Use `excludedTools` to hide specific tools from the default agent while keeping
+     * them available to custom sub-agents.
+     */
+    defaultAgent?: DefaultAgentConfig;
     /**
      * Name of the custom agent to activate when the session starts.
      * Must match the `name` of one of the agents in `customAgents`.
@@ -985,6 +1069,17 @@ export interface SessionConfig {
      * Set to `{ enabled: false }` to disable.
      */
     infiniteSessions?: InfiniteSessionConfig;
+    /**
+     * GitHub token for per-session authentication.
+     * When provided, the runtime resolves this token into a full GitHub identity
+     * (login, Copilot plan, endpoints) and stores it on the session. This enables
+     * multitenancy — different sessions can have different GitHub identities.
+     *
+     * This is independent of the client-level `gitHubToken` in {@link CopilotClientOptions},
+     * which authenticates the CLI process itself. The session-level token determines
+     * the identity used for content exclusion, model routing, and quota checks.
+     */
+    gitHubToken?: string;
     /**
      * Optional event handler that is registered on the session before the
      * session.create RPC is issued. This guarantees that early events emitted
@@ -999,12 +1094,12 @@ export interface SessionConfig {
      * Supplies a handler for session filesystem operations. This takes effect
      * only if {@link CopilotClientOptions.sessionFs} is configured.
      */
-    createSessionFsHandler?: (session: CopilotSession) => SessionFsHandler;
+    createSessionFsHandler?: (session: CopilotSession) => SessionFsProvider;
 }
 /**
  * Configuration for resuming a session
  */
-export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "tools" | "commands" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "modelCapabilities" | "streaming" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "onElicitationRequest" | "hooks" | "workingDirectory" | "configDir" | "enableConfigDiscovery" | "mcpServers" | "customAgents" | "agent" | "skillDirectories" | "disabledSkills" | "infiniteSessions" | "onEvent" | "createSessionFsHandler"> & {
+export type ResumeSessionConfig = Pick<SessionConfig, "clientName" | "model" | "tools" | "commands" | "systemMessage" | "availableTools" | "excludedTools" | "provider" | "modelCapabilities" | "streaming" | "includeSubAgentStreamingEvents" | "reasoningEffort" | "onPermissionRequest" | "onUserInputRequest" | "onElicitationRequest" | "hooks" | "workingDirectory" | "configDir" | "enableConfigDiscovery" | "mcpServers" | "customAgents" | "defaultAgent" | "agent" | "skillDirectories" | "disabledSkills" | "infiniteSessions" | "gitHubToken" | "onEvent" | "createSessionFsHandler"> & {
     /**
      * When true, skips emitting the session.resume event.
      * Useful for reconnecting to a session without triggering resume-related side effects.
@@ -1047,6 +1142,10 @@ export interface ProviderConfig {
          */
         apiVersion?: string;
     };
+    /**
+     * Custom HTTP headers to include in outbound provider requests.
+     */
+    headers?: Record<string, string>;
 }
 /**
  * Options for sending a message to a session
@@ -1094,6 +1193,10 @@ export interface MessageOptions {
      * - "immediate": Send immediately
      */
     mode?: "enqueue" | "immediate";
+    /**
+     * Custom HTTP headers to include in outbound model requests for this turn.
+     */
+    requestHeaders?: Record<string, string>;
 }
 /**
  * All possible event type strings from SessionEvent

package/dist/types.js

@@ -1,3 +1,45 @@
+import { createSessionFsAdapter } from "./sessionFsProvider.js";
+function convertMcpCallToolResult(callResult) {
+  const textParts = [];
+  const binaryResults = [];
+  for (const block of callResult.content) {
+    switch (block.type) {
+      case "text":
+        if (typeof block.text === "string") {
+          textParts.push(block.text);
+        }
+        break;
+      case "image":
+        if (typeof block.data === "string" && block.data && typeof block.mimeType === "string") {
+          binaryResults.push({
+            data: block.data,
+            mimeType: block.mimeType,
+            type: "image"
+          });
+        }
+        break;
+      case "resource": {
+        if (block.resource?.text) {
+          textParts.push(block.resource.text);
+        }
+        if (block.resource?.blob) {
+          binaryResults.push({
+            data: block.resource.blob,
+            mimeType: block.resource.mimeType ?? "application/octet-stream",
+            type: "resource",
+            description: block.resource.uri
+          });
+        }
+        break;
+      }
+    }
+  }
+  return {
+    textResultForLlm: textParts.join("\n"),
+    resultType: callResult.isError ? "failure" : "success",
+    ...binaryResults.length > 0 ? { binaryResultsForLlm: binaryResults } : {}
+  };
+}
 function defineTool(name, config) {
   return { name, ...config };
 }
@@ -15,9 +57,15 @@ const SYSTEM_PROMPT_SECTIONS = {
     description: "End-of-prompt instructions: parallel tool calling, persistence, task completion"
   }
 };
-const approveAll = () => ({ kind: "approved" });
+const approveAll = () => ({ kind: "approve-once" });
+const defaultJoinSessionPermissionHandler = () => ({
+  kind: "no-result"
+});
 export {
   SYSTEM_PROMPT_SECTIONS,
   approveAll,
+  convertMcpCallToolResult,
+  createSessionFsAdapter,
+  defaultJoinSessionPermissionHandler,
   defineTool
 };

package/docs/agent-author.md

@@ -18,6 +18,7 @@ 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({ ... })`
@@ -48,6 +49,7 @@ Check that the extension loaded successfully and isn't marked as "failed".
 ```
 
 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)
@@ -62,8 +64,8 @@ Discovery rules:
 import { joinSession } from "@github/copilot-sdk/extension";
 
 await joinSession({
-    tools: [],                     // Optional — custom tools
-    hooks: {},                     // Optional — lifecycle hooks
+    tools: [], // Optional — custom tools
+    hooks: {}, // Optional — lifecycle hooks
 });
 ```
 
@@ -74,9 +76,10 @@ await joinSession({
 ```js
 tools: [
     {
-        name: "tool_name",           // Required. Must be globally unique across all extensions.
+        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.
+        parameters: {
+            // Optional. JSON Schema for the arguments.
             type: "object",
             properties: {
                 arg1: { type: "string", description: "..." },
@@ -96,10 +99,11 @@ tools: [
             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`.
@@ -195,6 +199,7 @@ 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({
@@ -206,6 +211,7 @@ await session.send({
 ### 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
@@ -214,6 +220,7 @@ const response = await session.sendAndWait({ prompt: "What is 2+2?" });
 ### session.log(message, options?)
 
 Log to the CLI timeline:
+
 ```js
 await session.log("Extension ready");
 await session.log("Rate limit approaching", { level: "warning" });
@@ -224,6 +231,7 @@ await session.log("Processing...", { ephemeral: true }); // transient, not persi
 ### 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
@@ -232,16 +240,16 @@ const unsub = session.on("tool.execution_complete", (event) => {
 
 ### Key Event Types
 
-| Event | Key Data Fields |
-|-------|----------------|
-| `assistant.message` | `content`, `messageId` |
-| `tool.execution_start` | `toolCallId`, `toolName`, `arguments` |
+| 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` |
+| `user.message`            | `content`, `attachments`, `source`                     |
+| `session.idle`            | `backgroundTasks`                                      |
+| `session.error`           | `errorType`, `message`, `stack`                        |
+| `permission.requested`    | `requestId`, `permissionRequest.kind`                  |
+| `session.shutdown`        | `shutdownType`, `totalPremiumRequests`                 |
 
 ### session.workspacePath