Improve extension API via joinSession

Author: SteveSandersonMS

nodejs/docs/agent-author.md

@@ -20,8 +20,7 @@ For user-scoped extensions (persist across all repos), add `location: "user"`.
 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 `extension.resumeSession(process.env.SESSION_ID, { ... })`
-- Set `disableResume: true`
+- Call `joinSession({ ... })`
 
 ### Step 3: Reload extensions
 
@@ -61,10 +60,9 @@ Discovery rules:
 
 ```js
 import { approveAll } from "@github/copilot-sdk";
-import { extension } from "@github/copilot-sdk/extension";
+import { joinSession } from "@github/copilot-sdk/extension";
 
-await extension.resumeSession(process.env.SESSION_ID, {
-    disableResume: true,           // Required — extensions attach to existing sessions
+await joinSession({
     onPermissionRequest: approveAll, // Required — handle permission requests
     tools: [],                     // Optional — custom tools
     hooks: {},                     // Optional — lifecycle hooks
@@ -194,7 +192,7 @@ All handlers may return `void`/`undefined` (no-op) or an output object.
 
 ## Session Object
 
-After `resumeSession()`, the returned `session` provides:
+After `joinSession()`, the returned `session` provides:
 
 ### session.send(options)
 
@@ -259,10 +257,9 @@ Low-level typed RPC access to all session APIs (model, mode, plan, workspace, et
 
 ## Gotchas
 
-1. **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.
-2. **Tool name collisions are fatal.** If two extensions register the same tool name, the second extension fails to initialize.
-3. **`disableResume: true` is required.** Extensions always attach to existing sessions.
-4. **Don't call `session.send()` synchronously from `onUserPromptSubmitted`.** Use `setTimeout(() => session.send(...), 0)` to avoid infinite loops.
-5. **Extensions are reloaded on `/clear`.** Any in-memory state is lost between sessions.
-6. **Only `.mjs` is supported.** TypeScript (`.ts`) is not yet supported.
-7. **The handler's return value is the tool result.** Returning `undefined` sends an empty success. Throwing sends a failure with the error message.
+- **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.

nodejs/docs/examples.md

@@ -8,17 +8,16 @@ Every extension starts with the same boilerplate:
 
 ```js
 import { approveAll } from "@github/copilot-sdk";
-import { extension } from "@github/copilot-sdk/extension";
+import { joinSession } from "@github/copilot-sdk/extension";
 
-const session = await extension.resumeSession(process.env.SESSION_ID, {
-    disableResume: true,
+const session = await joinSession({
     onPermissionRequest: approveAll,
     hooks: { /* ... */ },
     tools: [ /* ... */ ],
 });
 ```
 
-`resumeSession` returns a `CopilotSession` object you can use to send messages and subscribe to events.
+`joinSession` returns a `CopilotSession` object you can use to send messages and subscribe to events.
 
 > **Platform notes (Windows vs macOS/Linux):**
 > - Use `process.platform === "win32"` to detect Windows at runtime.
@@ -33,8 +32,7 @@ const session = await extension.resumeSession(process.env.SESSION_ID, {
 Use `session.log()` to surface messages to the user in the CLI timeline:
 
 ```js
-const session = await extension.resumeSession(process.env.SESSION_ID, {
-    disableResume: true,
+const session = await joinSession({
     onPermissionRequest: approveAll,
     hooks: {
         onSessionStart: async () => {
@@ -337,7 +335,7 @@ hooks: {
 
 ## Session Events
 
-After calling `resumeSession`, use `session.on()` to react to events in real time.
+After calling `joinSession`, use `session.on()` to react to events in real time.
 
 ### Listening to a specific event type
 
@@ -384,8 +382,7 @@ function copyToClipboard(text) {
     proc.stdin.end();
 }
 
-const session = await extension.resumeSession(process.env.SESSION_ID, {
-    disableResume: true,
+const session = await joinSession({
     onPermissionRequest: approveAll,
     hooks: {
         onUserPromptSubmitted: async (input) => {
@@ -429,13 +426,12 @@ Correlate `tool.execution_start` / `tool.execution_complete` events by `toolCall
 import { existsSync, watchFile, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { approveAll } from "@github/copilot-sdk";
-import { extension } from "@github/copilot-sdk/extension";
+import { joinSession } from "@github/copilot-sdk/extension";
 
 const agentEdits = new Set(); // toolCallIds for in-flight agent edits
 const recentAgentPaths = new Set(); // paths recently written by the agent
 
-const session = await extension.resumeSession(process.env.SESSION_ID, {
-    disableResume: true,
+const session = await joinSession({
     onPermissionRequest: approveAll,
 });
 
@@ -485,12 +481,11 @@ Filter out agent edits by tracking `tool.execution_start` / `tool.execution_comp
 import { watch, readFileSync, statSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import { approveAll } from "@github/copilot-sdk";
-import { extension } from "@github/copilot-sdk/extension";
+import { joinSession } from "@github/copilot-sdk/extension";
 
 const agentEditPaths = new Set();
 
-const session = await extension.resumeSession(process.env.SESSION_ID, {
-    disableResume: true,
+const session = await joinSession({
     onPermissionRequest: approveAll,
 });
 
@@ -567,7 +562,7 @@ await session.send({
 ### Custom permission logic
 
 ```js
-const session = await extension.resumeSession(process.env.SESSION_ID, {
+const session = await joinSession({
     onPermissionRequest: async (request) => {
         if (request.kind === "shell") {
             // request.fullCommandText has the shell command
@@ -586,7 +581,7 @@ const session = await extension.resumeSession(process.env.SESSION_ID, {
 Register `onUserInputRequest` to enable the agent's `ask_user` tool:
 
 ```js
-const session = await extension.resumeSession(process.env.SESSION_ID, {
+const session = await joinSession({
     onPermissionRequest: approveAll,
     onUserInputRequest: async (request) => {
         // request.question has the agent's question
@@ -605,7 +600,7 @@ An extension that combines tools, hooks, and events.
 ```js
 import { execFile, exec } from "node:child_process";
 import { approveAll } from "@github/copilot-sdk";
-import { extension } from "@github/copilot-sdk/extension";
+import { joinSession } from "@github/copilot-sdk/extension";
 
 const isWindows = process.platform === "win32";
 let copyNextResponse = false;
@@ -621,8 +616,7 @@ function openInEditor(filePath) {
     else execFile("code", [filePath], () => {});
 }
 
-const session = await extension.resumeSession(process.env.SESSION_ID, {
-    disableResume: true,
+const session = await joinSession({
     onPermissionRequest: approveAll,
     hooks: {
         onUserPromptSubmitted: async (input) => {

nodejs/docs/extensions.md

@@ -18,9 +18,9 @@ Extensions add custom tools, hooks, and behaviors to the Copilot CLI. They run a
 
 1. **Discovery**: The CLI scans `.github/extensions/` (project) and the user's copilot config extensions directory for subdirectories containing `extension.mjs`.
 2. **Launch**: Each extension is forked as a child process with `@github/copilot-sdk` available via an automatic module resolver.
-3. **Connection**: The extension calls `extension.resumeSession()` which establishes a JSON-RPC connection over stdio to the CLI.
+3. **Connection**: The extension calls `joinSession()` which establishes a JSON-RPC connection over stdio to the CLI and attaches to the user's current foreground session.
 4. **Registration**: Tools and hooks declared in the session options are registered with the CLI and become available to the agent.
-5. **Lifecycle**: Extensions are reloaded on `/clear` (new session) and stopped on CLI exit (SIGTERM, then SIGKILL after 5s).
+5. **Lifecycle**: Extensions are reloaded on `/clear` (or if the foreground session is replaced) and stopped on CLI exit (SIGTERM, then SIGKILL after 5s).
 
 ## File Structure
 
@@ -33,21 +33,23 @@ Extensions add custom tools, hooks, and behaviors to the Copilot CLI. They run a
 - Only `.mjs` files are supported (ES modules). The file must be named `extension.mjs`.
 - Each extension lives in its own subdirectory.
 - The `@github/copilot-sdk` import is resolved automatically — you don't install it.
-- `process.env.SESSION_ID` provides the session ID to connect to.
 
 ## The SDK
 
 Extensions use `@github/copilot-sdk` for all interactions with the CLI:
 
 ```js
 import { approveAll } from "@github/copilot-sdk";
-import { extension } from "@github/copilot-sdk/extension";
+import { joinSession } from "@github/copilot-sdk/extension";
 
-const session = await extension.resumeSession(process.env.SESSION_ID, {
-    disableResume: true,
+const session = await joinSession({
     onPermissionRequest: approveAll,
-    tools: [ /* ... */ ],
-    hooks: { /* ... */ },
+    tools: [
+        /* ... */
+    ],
+    hooks: {
+        /* ... */
+    },
 });
 ```
 

nodejs/src/client.ts

@@ -77,6 +77,26 @@ function toJsonSchema(parameters: Tool["parameters"]): Record<string, unknown> |
     return parameters;
 }
 
+function getNodeExecPath(): string {
+    if (process.versions.bun) {
+        return "node";
+    }
+    return process.execPath;
+}
+
+/**
+ * Gets the path to the bundled CLI from the @github/copilot package.
+ * Uses index.js directly rather than npm-loader.js (which spawns the native binary).
+ */
+function getBundledCliPath(): string {
+    // Find the actual location of the @github/copilot package by resolving its sdk export
+    const sdkUrl = import.meta.resolve("@github/copilot/sdk");
+    const sdkPath = fileURLToPath(sdkUrl);
+    // sdkPath is like .../node_modules/@github/copilot/sdk/index.js
+    // Go up two levels to get the package root, then append index.js
+    return join(dirname(dirname(sdkPath)), "index.js");
+}
+
 /**
  * Main client for interacting with the Copilot CLI.
  *
@@ -110,27 +130,6 @@ function toJsonSchema(parameters: Tool["parameters"]): Record<string, unknown> |
  * await client.stop();
  * ```
  */
-
-function getNodeExecPath(): string {
-    if (process.versions.bun) {
-        return "node";
-    }
-    return process.execPath;
-}
-
-/**
- * Gets the path to the bundled CLI from the @github/copilot package.
- * Uses index.js directly rather than npm-loader.js (which spawns the native binary).
- */
-function getBundledCliPath(): string {
-    // Find the actual location of the @github/copilot package by resolving its sdk export
-    const sdkUrl = import.meta.resolve("@github/copilot/sdk");
-    const sdkPath = fileURLToPath(sdkUrl);
-    // sdkPath is like .../node_modules/@github/copilot/sdk/index.js
-    // Go up two levels to get the package root, then append index.js
-    return join(dirname(dirname(sdkPath)), "index.js");
-}
-
 export class CopilotClient {
     private cliProcess: ChildProcess | null = null;
     private connection: MessageConnection | null = null;

nodejs/src/extension.ts

@@ -3,5 +3,37 @@
  *--------------------------------------------------------------------------------------------*/
 
 import { CopilotClient } from "./client.js";
+import type { CopilotSession } from "./session.js";
+import type { ResumeSessionConfig } from "./types.js";
 
-export const extension = new CopilotClient({ isChildProcess: true });
+/**
+ * Joins the current foreground session.
+ *
+ * @param config - Configuration to add to the session
+ * @returns A promise that resolves with the joined session
+ *
+ * @example
+ * ```typescript
+ * import { approveAll } from "@github/copilot-sdk";
+ * import { joinSession } from "@github/copilot-sdk/extension";
+ *
+ * const session = await joinSession({
+ *   onPermissionRequest: approveAll,
+ *   tools: [myTool],
+ * });
+ * ```
+ */
+export async function joinSession(config: ResumeSessionConfig): Promise<CopilotSession> {
+    const sessionId = process.env.SESSION_ID;
+    if (!sessionId) {
+        throw new Error(
+            "joinSession() is intended for extensions running as child processes of the Copilot CLI."
+        );
+    }
+
+    const client = new CopilotClient({ isChildProcess: true });
+    return client.resumeSession(sessionId, {
+        ...config,
+        disableResume: config.disableResume ?? true,
+    });
+}