@github/copilot-sdk 1.0.29-preview.1 → 1.0.29-preview.10

package/README.md

@@ -64,6 +64,7 @@ By default the callback authenticates only requests made for sessions this clien
 `startAhpHost()` requires `authentication`: `github`, or direct-only `none` / `custom`
 (`requireIdentity` and a validator returning `{identity,expiresAt}` or `null`):
 
+<!-- docs-validate: strict -->
 ```typescript
 import { CopilotClient } from "@github/copilot-sdk";
 
@@ -134,6 +135,7 @@ by the SDK. Published sessions remain discoverable after hosting stops.
 
 Supply `createSession` to materialize fresh AHP sessions in your application:
 
+<!-- docs-validate: strict -->
 ```typescript
 import { approveAll, CopilotClient, defineTool } from "@github/copilot-sdk";
 
@@ -218,6 +220,7 @@ npm start
 
 ## Quick Start
 
+<!-- docs-validate: strict -->
 ```typescript
 import { CopilotClient, approveAll } from "@github/copilot-sdk";
 
@@ -252,7 +255,10 @@ await client.stop();
 
 Sessions also support `Symbol.asyncDispose` for use with [`await using`](https://github.com/tc39/proposal-explicit-resource-management) (TypeScript 5.2+ / Node.js 20+):
 
+<!-- docs-validate: strict -->
 ```typescript
+import { approveAll } from "@github/copilot-sdk";
+
 await using session = await client.createSession({
     model: "gpt-5",
     onPermissionRequest: approveAll,
@@ -282,7 +288,7 @@ new CopilotClient(options?: CopilotClientOptions)
     - `RuntimeConnection.forStdio({ path?, args?, env? })` (default) — spawn the runtime and communicate over its stdin/stdout.
     - `RuntimeConnection.forTcp({ port?, connectionToken?, path?, args?, env? })` — spawn the runtime as a TCP server.
     - `RuntimeConnection.forUri(url, { connectionToken? })` — connect to an already-running runtime (mutually exclusive with `gitHubToken`/`useLoggedInUser`). There is no top-level `cliUrl` shortcut; use this factory for URL-based connections.
-    - `RuntimeConnection.forInProcess()` — host the runtime in-process over its native C ABI (FFI). **Experimental.** Because the runtime shares this process, `env`, `telemetry`, and `workingDirectory` are rejected with this transport; set them on the host process instead.
+    - `RuntimeConnection.forInProcess()` — host the runtime in-process over its native C ABI (FFI). **Experimental.** Client-level `env`, `telemetry`, and `workingDirectory` are rejected; use supported typed options and configure working directories per session.
     - The child-process transports (`forStdio`/`forTcp`) also accept a per-connection `env`. Set it there or via the top-level `env` option — not both (setting both throws).
     - Managed child-process connections materialize the bundled `copilot-runtime` and adjacent `runtime.node`, then launch the wrapper by default. An explicit connection `path` or `COPILOT_CLI_PATH` overrides the bundled runtime.
 - `mode?: "empty" | "copilot-cli"` - Defaulting strategy. Use `"empty"` for multi-user server mode; defaults to `"copilot-cli"`.
@@ -417,6 +423,20 @@ Create a new conversation session.
 - `hooks?: SessionHooks` - Hook handlers for session lifecycle events. See [Session Hooks](#session-hooks) section.
 - `skillProvider?: SkillProvider` - **Experimental.** Serves skills from host storage instead of skill directories. Not persisted; pass it again on resume. See [Skill providers](#skill-providers-experimental).
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+declare function acquireTokenForHost(host: string): Promise<string>;
+
+const session = await client.createSession({
+    gitHubTokenProvider: async ({ host }) => ({
+        kind: "token",
+        accessToken: await acquireTokenForHost(host),
+        expiresIn: 8 * 60 * 60,
+    }),
+});
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 const session = await client.createSession({
     gitHubTokenProvider: async ({ host }) => ({
@@ -465,6 +485,8 @@ List all available sessions. Optionally filter by working directory context.
 - `summary?: string` - Optional session summary
 - `isRemote: boolean` - Whether the session is remote
 - `context?: SessionContext` - Working directory context from session creation
+- `clientName?: string` - Client that created the session (for example `github/cli`)
+- `lastClientName?: string` - Client that most recently ran the session: the client that created it, or a client that resumed it and then ran it. Resuming a session only to observe it does not change it. Omitted when unknown, such as for sessions persisted before this field existed.
 
 **SessionContext:**
 
@@ -489,6 +511,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.
 
+<!-- docs-validate: strict -->
 ```typescript
 const unsubscribe = client.onLifecycle("session.foreground", (event) => {
     console.log(`Session ${event.sessionId} is now in foreground`);
@@ -499,6 +522,7 @@ const unsubscribe = client.onLifecycle("session.foreground", (event) => {
 
 Subscribe to all session lifecycle events. Returns an unsubscribe function.
 
+<!-- docs-validate: strict -->
 ```typescript
 const unsubscribe = client.onLifecycle((event) => {
     console.log(`${event.type}: ${event.sessionId}`);
@@ -546,12 +570,32 @@ Returns the message ID.
 
 Use `source: "system"` for automated messages from your application:
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import type { CopilotSession } from "@github/copilot-sdk";
+
+declare const session: CopilotSession;
+
+await session.send({ prompt: "Context updated", source: "system" });
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 await session.send({ prompt: "Context updated", source: "system" });
 ```
 
 For a message from another agent, use its trusted sender ID:
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import type { CopilotSession } from "@github/copilot-sdk";
+
+declare const session: CopilotSession;
+
+await session.send({ prompt: "Review complete", source: "agent-reviewer-id" });
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 await session.send({ prompt: "Review complete", source: "agent-reviewer-id" });
 ```
@@ -584,6 +628,23 @@ Pass a raw JSON Schema or a Zod schema as `responseSchema` to `send` or
 `sendAndWait`. As with custom tool parameters, the SDK converts Zod schemas to
 JSON Schema before sending them:
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import type { CopilotSession } from "@github/copilot-sdk";
+
+declare const session: CopilotSession;
+
+import { z } from "zod";
+
+const answerSchema = z.object({ answer: z.number().int() });
+const message = await session.sendAndWait({
+    prompt: "What is 19 + 23?",
+    responseSchema: answerSchema,
+});
+console.log(message?.data.content); // JSON text
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 import { z } from "zod";
 
@@ -597,6 +658,20 @@ console.log(message?.data.content); // JSON text
 
 For a typed result, pass the Zod schema as the **second argument** instead:
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import type { CopilotSession } from "@github/copilot-sdk";
+
+declare const session: CopilotSession;
+import { z } from "zod";
+
+const answerSchema = z.object({ answer: z.number().int() });
+
+const answer = await session.sendAndWait("What is 19 + 23?", answerSchema);
+console.log(answer.answer); // number; TResult is inferred from answerSchema
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 const answer = await session.sendAndWait("What is 19 + 23?", answerSchema);
 console.log(answer.answer); // number; TResult is inferred from answerSchema
@@ -616,6 +691,10 @@ sends do not inherit it. Ordinary immediate steering inherits the active schema
 and originating message ID, even when it arrives too late for the current model
 request and is promoted into a follow-up run. Specifying a schema with
 `mode: "immediate"` is rejected, even while idle.
+Provider schema restrictions still apply, and schemas are not rewritten. Strict
+OpenAI output needs an object root with every property listed in `required`.
+Zod leaves `.optional()` properties out of `required`, so use `.nullable()` for a
+field the model may leave empty.
 The generated `session.rpc.send` and `session.rpc.sendMessages` wrappers expose
 the full `responseFormat` contract when you need to set its name, description,
 or strict option rather than using the convenience defaults (`name: "response"`,
@@ -665,6 +744,28 @@ native `output_config.format` endpoint.
 
 Subscribe to a specific event type. The handler receives properly typed events.
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import type { CopilotSession } from "@github/copilot-sdk";
+
+declare const session: CopilotSession;
+
+// Listen for specific event types with full type inference
+session.on("assistant.message", (event) => {
+    console.log(event.data.content); // TypeScript knows about event.data.content
+});
+
+session.on("session.idle", () => {
+    console.log("Session is idle");
+});
+
+// Listen to streaming events
+session.on("assistant.message_delta", (event) => {
+    process.stdout.write(event.data.deltaContent);
+});
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 // Listen for specific event types with full type inference
 session.on("assistant.message", (event) => {
@@ -685,6 +786,22 @@ session.on("assistant.message_delta", (event) => {
 
 Subscribe to all session events. Returns an unsubscribe function.
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import type { CopilotSession } from "@github/copilot-sdk";
+
+declare const session: CopilotSession;
+
+const unsubscribe = session.on((event) => {
+    // Handle any event type
+    console.log(event.type, event);
+});
+
+// Later...
+unsubscribe();
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 const unsubscribe = session.on((event) => {
     // Handle any event type
@@ -712,6 +829,19 @@ The runtime does not apply the preference immediately. It records the request an
 
 Watch for the outcome through the `session.model_change` event on success or the ephemeral `session.auto_tier_switch_failed` event on failure. A failed activation leaves the incumbent effective tier unchanged. Read the authoritative state at any time with `session.rpc.model.getCurrent()`.
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import type { CopilotSession } from "@github/copilot-sdk";
+
+declare const session: CopilotSession;
+
+const result = await session.setAutoTier("intelligence");
+if (result.status === "pending") {
+    // Accepted, but not yet in effect.
+}
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 const result = await session.setAutoTier("intelligence");
 if (result.status === "pending") {
@@ -725,6 +855,23 @@ See [Auto tier persistence](../docs/features/session-persistence.md#auto-tier-pe
 
 Read the current model's reasoning-summary presentation policy without changing session state. Call `session.rpc.model.list()` first to load the model catalog; otherwise the result may have `ready: false`. The request and result types are exported from `@github/copilot-sdk`.
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import type { CopilotSession } from "@github/copilot-sdk";
+
+declare const session: CopilotSession;
+
+import type {
+    ModelGetReasoningSummariesRequest,
+    ModelGetReasoningSummariesResult,
+} from "@github/copilot-sdk";
+
+const presentation: ModelGetReasoningSummariesRequest = { summariesVisible: false };
+const policy: ModelGetReasoningSummariesResult =
+    await session.rpc.model.getReasoningSummaries(presentation);
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 import type {
     ModelGetReasoningSummariesRequest,
@@ -744,6 +891,26 @@ Replace the tools this client supplies to the session, together with the handler
 
 Once the runtime accepts the replacement, every tool call this session dispatches uses the new handlers; calls already running finish on their original handlers. If the runtime rejects it, the promise rejects and the previous tools and handlers stay in place. Concurrent calls are applied one at a time, in call order.
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import type { CopilotSession } from "@github/copilot-sdk";
+
+declare const session: CopilotSession;
+import { defineTool } from "@github/copilot-sdk";
+import { z } from "zod";
+
+declare function searchIssues(query: string): Promise<string>;
+
+await session.setTools([
+    defineTool("search_issues", {
+        description: "Search the issues shown on the current page",
+        parameters: z.object({ query: z.string() }),
+        handler: async ({ query }) => searchIssues(query),
+    }),
+]);
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 await session.setTools([
     defineTool("search_issues", {
@@ -772,6 +939,18 @@ Disconnect the session and free resources. Session data on disk is preserved for
 
 Host capabilities reported when the session was created or resumed. Use this to check feature support before calling capability-gated APIs.
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import type { CopilotSession } from "@github/copilot-sdk";
+
+declare const session: CopilotSession;
+
+if (session.capabilities.ui?.elicitation) {
+    const ok = await session.ui.confirm("Deploy?");
+}
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 if (session.capabilities.ui?.elicitation) {
     const ok = await session.ui.confirm("Deploy?");
@@ -784,10 +963,6 @@ Capabilities may update during the session. For example, when another client joi
 
 Interactive UI methods for showing dialogs to the user. Only available when the CLI host supports elicitation (`session.capabilities.ui?.elicitation === true`). See [UI Elicitation](#ui-elicitation) for full details.
 
-##### `destroy(): Promise<void>` _(deprecated)_
-
-Deprecated — use `disconnect()` instead.
-
 ---
 
 ## Event Types
@@ -809,6 +984,38 @@ See `SessionEvent` type in the source for full details.
 
 The SDK supports image attachments via the `attachments` parameter. You can attach images by providing their file path, or by passing base64-encoded data directly using a blob attachment:
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import type { CopilotSession } from "@github/copilot-sdk";
+
+declare const session: CopilotSession;
+declare const base64ImageData: string;
+
+// File attachment — runtime reads from disk
+await session.send({
+    prompt: "What's in this image?",
+    attachments: [
+        {
+            type: "file",
+            path: "/path/to/image.jpg",
+        },
+    ],
+});
+
+// Blob attachment — provide base64 data directly
+await session.send({
+    prompt: "What's in this image?",
+    attachments: [
+        {
+            type: "blob",
+            data: base64ImageData,
+            mimeType: "image/png",
+        },
+    ],
+});
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 // File attachment — runtime reads from disk
 await session.send({
@@ -836,6 +1043,16 @@ await session.send({
 
 Supported image formats are PNG, JPEG, WebP, and GIF. Images in other formats, such as BMP or TIFF, are not sent to the model. The agent's `view` tool can also read images directly from the filesystem, so you can also ask questions like:
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import type { CopilotSession } from "@github/copilot-sdk";
+
+declare const session: CopilotSession;
+
+await session.send({ prompt: "What does the most recent jpg in this directory portray?" });
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 await session.send({ prompt: "What does the most recent jpg in this directory portray?" });
 ```
@@ -844,6 +1061,51 @@ await session.send({ prompt: "What does the most recent jpg in this directory po
 
 Enable streaming to receive assistant response chunks as they're generated:
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import { approveAll } from "@github/copilot-sdk";
+
+const session = await client.createSession({
+    model: "gpt-5",
+    streaming: true,
+    onPermissionRequest: approveAll,
+});
+
+// Wait for completion using typed event handlers
+const done = new Promise<void>((resolve) => {
+    session.on("assistant.message_delta", (event) => {
+        // Streaming message chunk - print incrementally
+        process.stdout.write(event.data.deltaContent);
+    });
+
+    session.on("assistant.reasoning_delta", (event) => {
+        // Streaming reasoning chunk (if model supports reasoning)
+        process.stdout.write(event.data.deltaContent);
+    });
+
+    session.on("assistant.message", (event) => {
+        // Final message - complete content
+        console.log("\n--- Final message ---");
+        console.log(event.data.content);
+    });
+
+    session.on("assistant.reasoning", (event) => {
+        // Final reasoning content (if model supports reasoning)
+        console.log("--- Reasoning ---");
+        console.log(event.data.content);
+    });
+
+    session.on("session.idle", () => {
+        // Session finished processing
+        resolve();
+    });
+});
+
+await session.send({ prompt: "Tell me a short story" });
+await done; // Wait for streaming to complete
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 const session = await client.createSession({
     model: "gpt-5",
@@ -897,7 +1159,10 @@ Note: `assistant.message` and `assistant.reasoning` (final events) are always se
 
 ### Manual Server Control
 
+<!-- docs-validate: strict -->
 ```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
 const client = new CopilotClient({});
 
 // Start manually
@@ -913,6 +1178,31 @@ await client.stop();
 
 You can let the CLI call back into your process when the model needs capabilities you own. Use `defineTool` with Zod schemas for type-safe tool definitions:
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```ts
+import { z } from "zod";
+import { defineTool } from "@github/copilot-sdk";
+
+declare function fetchIssue(id: string): Promise<string>;
+
+const session = await client.createSession({
+    model: "gpt-5",
+    tools: [
+        defineTool("lookup_issue", {
+            description: "Fetch issue details from our tracker",
+            parameters: z.object({
+                id: z.string().describe("Issue identifier"),
+            }),
+            handler: async ({ id }) => {
+                const issue = await fetchIssue(id);
+                return issue;
+            },
+        }),
+    ],
+});
+```
+<!-- /docs-validate: hidden -->
 ```ts
 import { z } from "zod";
 import { CopilotClient, defineTool } from "@github/copilot-sdk";
@@ -940,6 +1230,22 @@ When Copilot invokes `lookup_issue`, the client automatically runs your handler
 
 If you register a tool with the same name as a built-in CLI tool (e.g. `edit_file`, `read_file`), the SDK will throw an error unless you explicitly opt in by setting `overridesBuiltInTool: true`. This flag signals that you intend to replace the built-in tool with your custom implementation.
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```ts
+import { z } from "zod";
+import { defineTool } from "@github/copilot-sdk";
+
+defineTool("edit_file", {
+    description: "Custom file editor with project-specific validation",
+    parameters: z.object({ path: z.string(), content: z.string() }),
+    overridesBuiltInTool: true,
+    handler: async ({ path, content }) => {
+        /* your logic */
+    },
+});
+```
+<!-- /docs-validate: hidden -->
 ```ts
 defineTool("edit_file", {
     description: "Custom file editor with project-specific validation",
@@ -956,6 +1262,19 @@ An `apply_patch` override can declare a string schema. The model sees a required
 dispatching to any SDK. Both a Zod-inferred Node handler and
 `invocation.arguments` receive the patch text as a string:
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```ts
+import { z } from "zod";
+import { defineTool } from "@github/copilot-sdk";
+
+defineTool("apply_patch", {
+    parameters: z.string(),
+    overridesBuiltInTool: true,
+    handler: (patch) => patch.trim(),
+});
+```
+<!-- /docs-validate: hidden -->
 ```ts
 defineTool("apply_patch", {
     parameters: z.string(),
@@ -971,6 +1290,22 @@ use an object schema if references are needed.
 
 Set `skipPermission: true` on a tool definition to allow it to execute without triggering a permission prompt:
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```ts
+import { z } from "zod";
+import { defineTool } from "@github/copilot-sdk";
+
+defineTool("safe_lookup", {
+    description: "A read-only lookup that needs no confirmation",
+    parameters: z.object({ id: z.string() }),
+    skipPermission: true,
+    handler: async ({ id }) => {
+        /* your logic */
+    },
+});
+```
+<!-- /docs-validate: hidden -->
 ```ts
 defineTool("safe_lookup", {
     description: "A read-only lookup that needs no confirmation",
@@ -986,6 +1321,22 @@ defineTool("safe_lookup", {
 
 Set `defer` to control whether a tool may be loaded lazily via tool search rather than always pre-loaded. Use `"auto"` to allow the tool to be deferred and surfaced through tool search, or `"never"` to force it to always be pre-loaded. Defaults to `"auto"`.
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```ts
+import { z } from "zod";
+import { defineTool } from "@github/copilot-sdk";
+
+defineTool("lookup_issue", {
+    description: "Fetch issue details",
+    parameters: z.object({ id: z.string() }),
+    defer: "auto",
+    handler: async ({ id }) => {
+        /* your logic */
+    },
+});
+```
+<!-- /docs-validate: hidden -->
 ```ts
 defineTool("lookup_issue", {
     description: "Fetch issue details",
@@ -1001,6 +1352,26 @@ defineTool("lookup_issue", {
 
 Register slash commands so that users of the CLI's TUI can invoke custom actions via `/commandName`. Each command has a `name`, optional `description`, and a `handler` called when the user executes it.
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```ts
+import { approveAll } from "@github/copilot-sdk";
+
+const session = await client.createSession({
+    onPermissionRequest: approveAll,
+    commands: [
+        {
+            name: "deploy",
+            description: "Deploy the app to production",
+            handler: async ({ commandName, args }) => {
+                console.log(`Deploying with args: ${args}`);
+                // Do work here — any thrown error is reported back to the CLI
+            },
+        },
+    ],
+});
+```
+<!-- /docs-validate: hidden -->
 ```ts
 const session = await client.createSession({
     onPermissionRequest: approveAll,
@@ -1027,6 +1398,44 @@ When the session has elicitation support — either from the CLI's TUI or from a
 
 > **Capability check:** Elicitation is only available when at least one connected participant advertises support. Always check `session.capabilities.ui?.elicitation` before calling UI methods — this property updates automatically as participants join and leave.
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```ts
+import { approveAll } from "@github/copilot-sdk";
+
+const session = await client.createSession({ onPermissionRequest: approveAll });
+
+if (session.capabilities.ui?.elicitation) {
+    // Confirm dialog — returns boolean
+    const ok = await session.ui.confirm("Deploy to production?");
+
+    // Selection dialog — returns selected value or null
+    const env = await session.ui.select("Pick environment", ["production", "staging", "dev"]);
+
+    // Text input — returns string or null
+    const name = await session.ui.input("Project name:", {
+        title: "Name",
+        minLength: 1,
+        maxLength: 50,
+    });
+
+    // Generic elicitation with full schema control
+    const result = await session.ui.elicitation({
+        message: "Configure deployment",
+        requestedSchema: {
+            type: "object",
+            properties: {
+                region: { type: "string", enum: ["us-east", "eu-west"] },
+                dryRun: { type: "boolean", default: true },
+            },
+            required: ["region"],
+        },
+    });
+    // result.action: "accept" | "decline" | "cancel"
+    // result.content: { region: "us-east", dryRun: true } (when accepted)
+}
+```
+<!-- /docs-validate: hidden -->
 ```ts
 const session = await client.createSession({ onPermissionRequest: approveAll });
 
@@ -1067,6 +1476,7 @@ All UI methods throw if elicitation is not supported by the host.
 
 Control the system prompt using `systemMessage` in session config:
 
+<!-- docs-validate: strict -->
 ```typescript
 const session = await client.createSession({
     model: "gpt-5",
@@ -1087,6 +1497,7 @@ 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:
 
+<!-- docs-validate: strict -->
 ```typescript
 import { SYSTEM_MESSAGE_SECTIONS } from "@github/copilot-sdk";
 import type { SectionOverride, SystemMessageSection } from "@github/copilot-sdk";
@@ -1134,6 +1545,7 @@ Unknown section IDs are handled gracefully: content from `replace`/`append`/`pre
 
 For full control (removes all guardrails), use `mode: "replace"`:
 
+<!-- docs-validate: strict -->
 ```typescript
 const session = await client.createSession({
     model: "gpt-5",
@@ -1148,6 +1560,8 @@ const session = await client.createSession({
 
 By default, sessions use **infinite sessions** which automatically manage context window limits through background compaction and persist state to a workspace directory.
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
 ```typescript
 // Default: infinite sessions enabled with default thresholds
 const session = await client.createSession({ model: "gpt-5" });
@@ -1157,7 +1571,7 @@ console.log(session.workspacePath);
 // => ~/.copilot/session-state/{sessionId}/
 
 // Custom thresholds
-const session = await client.createSession({
+const tuned = await client.createSession({
     model: "gpt-5",
     infiniteSessions: {
         enabled: true,
@@ -1167,7 +1581,32 @@ const session = await client.createSession({
 });
 
 // Disable infinite sessions
-const session = await client.createSession({
+const disabled = await client.createSession({
+    model: "gpt-5",
+    infiniteSessions: { enabled: false },
+});
+```
+<!-- /docs-validate: hidden -->
+```typescript
+// Default: infinite sessions enabled with default thresholds
+const session = await client.createSession({ model: "gpt-5" });
+
+// Access the workspace path for checkpoints and files
+console.log(session.workspacePath);
+// => ~/.copilot/session-state/{sessionId}/
+
+// Custom thresholds
+const tuned = await client.createSession({
+    model: "gpt-5",
+    infiniteSessions: {
+        enabled: true,
+        backgroundCompactionThreshold: 0.8, // Start compacting at 80% context usage
+        bufferExhaustionThreshold: 0.95, // Block at 95% until compaction completes
+    },
+});
+
+// Disable infinite sessions
+const disabled = await client.createSession({
     model: "gpt-5",
     infiniteSessions: { enabled: false },
 });
@@ -1187,15 +1626,31 @@ SDK leaves `memory` unset so the runtime applies its own default, while `"empty"
 defaults `memory` to disabled unless you set it explicitly.
 For more background, see [About GitHub Copilot Memory](https://docs.github.com/en/copilot/concepts/agents/copilot-memory).
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
 ```typescript
 // Enable memory for a session
-const session = await client.createSession({
+const enabled = await client.createSession({
     model: "gpt-5",
     memory: { enabled: true },
 });
 
 // Disable memory for a session
-const session = await client.createSession({
+const disabled = await client.createSession({
+    model: "gpt-5",
+    memory: { enabled: false },
+});
+```
+<!-- /docs-validate: hidden -->
+```typescript
+// Enable memory for a session
+const enabled = await client.createSession({
+    model: "gpt-5",
+    memory: { enabled: true },
+});
+
+// Disable memory for a session
+const disabled = await client.createSession({
     model: "gpt-5",
     memory: { enabled: false },
 });
@@ -1207,6 +1662,29 @@ A skill provider serves skills from your own storage, such as a database, instea
 files on disk. Provider skills join the session's skill catalog and load on demand through the
 `skill` tool, just like file-based skills.
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import { approveAll } from "@github/copilot-sdk";
+import type { SkillProvider } from "@github/copilot-sdk";
+
+declare const db: {
+    findSkill(name: string, options: { signal: AbortSignal }): Promise<{ markdown: string } | undefined>;
+};
+
+const skillProvider: SkillProvider = {
+    listSkills: async () => [
+        { name: "release-notes", description: "Writes release notes in the team's format." },
+    ],
+    readSkill: async (name, { signal }) => (await db.findSkill(name, { signal }))?.markdown ?? null,
+};
+
+const session = await client.createSession({
+    onPermissionRequest: approveAll,
+    skillProvider,
+});
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 import type { SkillProvider } from "@github/copilot-sdk";
 
@@ -1260,6 +1738,7 @@ See [Supporting files](../docs/features/skills.md#supporting-files-experimental)
 
 ### Multiple Sessions
 
+<!-- docs-validate: strict -->
 ```typescript
 const session1 = await client.createSession({ model: "gpt-5" });
 const session2 = await client.createSession({ model: "claude-sonnet-4.5" });
@@ -1271,6 +1750,7 @@ await session2.sendAndWait({ prompt: "Hello from session 2" });
 
 ### Custom Session IDs
 
+<!-- docs-validate: strict -->
 ```typescript
 const session = await client.createSession({
     sessionId: "my-custom-session-id",
@@ -1280,6 +1760,25 @@ const session = await client.createSession({
 
 ### File Attachments
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import { approveAll } from "@github/copilot-sdk";
+
+const session = await client.createSession({ onPermissionRequest: approveAll });
+
+await session.send({
+    prompt: "Analyze this file",
+    attachments: [
+        {
+            type: "file",
+            path: "/path/to/file.js",
+            displayName: "My File",
+        },
+    ],
+});
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 await session.send({
     prompt: "Analyze this file",
@@ -1308,6 +1807,7 @@ The SDK supports custom OpenAI-compatible API providers (BYOK - Bring Your Own K
 
 **Example with Ollama:**
 
+<!-- docs-validate: strict -->
 ```typescript
 const session = await client.createSession({
     model: "deepseek-coder-v2:16b", // Required when using custom provider
@@ -1323,6 +1823,7 @@ await session.sendAndWait({ prompt: "Hello!" });
 
 **Example with custom OpenAI-compatible API:**
 
+<!-- docs-validate: strict -->
 ```typescript
 const session = await client.createSession({
     model: "gpt-4",
@@ -1336,6 +1837,7 @@ const session = await client.createSession({
 
 **Example with Azure OpenAI:**
 
+<!-- docs-validate: strict -->
 ```typescript
 const session = await client.createSession({
     model: "gpt-4",
@@ -1360,7 +1862,10 @@ const session = await client.createSession({
 
 The SDK supports OpenTelemetry for distributed tracing. Provide a `telemetry` config to enable trace export from the CLI process — this is all most users need:
 
+<!-- docs-validate: strict -->
 ```typescript
+import { CopilotClient } from "@github/copilot-sdk";
+
 const client = new CopilotClient({
     telemetry: {
         otlpEndpoint: "http://localhost:4318",
@@ -1412,6 +1917,17 @@ Callbacks receive optional derived prompt context as `invocation.promptRequest`.
 
 Use the built-in `approveAll` helper when managed settings are disabled:
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import { approveAll } from "@github/copilot-sdk";
+
+const session = await client.createSession({
+    model: "gpt-5",
+    onPermissionRequest: approveAll,
+});
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 import { CopilotClient, approveAll } from "@github/copilot-sdk";
 
@@ -1427,6 +1943,7 @@ When `enableManagedSettings` is true for the session, `approveAll` throws. Use a
 
 Provide your own function to inspect each request and apply custom logic. Check `managedApprovalRequired` before any automatic approval:
 
+<!-- docs-validate: strict -->
 ```typescript
 import type { PermissionRequest, PermissionRequestResult } from "@github/copilot-sdk";
 
@@ -1500,6 +2017,26 @@ Recheck requires session opt-in through `enableManagedSettings: true`.
 Treat helper text as untrusted plain text, keep `diagnostic` secondary,
 and sanitize `helpLink` before navigation.
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import type { CopilotSession } from "@github/copilot-sdk";
+
+declare const session: CopilotSession;
+
+const snapshot = await session.rpc.managedSettings.get();
+
+if (snapshot.policyHelperFailure) {
+    console.warn(snapshot.policyHelperFailure.message);
+}
+
+if (snapshot.policyHelperCapabilities?.recheck === true) {
+    const refreshed = await session.rpc.managedSettings.recheckPolicyHelper();
+    // Only a current capable snapshot without policyHelperFailure establishes recovery.
+    console.log(refreshed.policyHelperFailure ?? "Policy Helper recovered");
+}
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 const snapshot = await session.rpc.managedSettings.get();
 
@@ -1538,6 +2075,16 @@ The handler must return one of the `PermissionDecision` shapes (or `{ kind: "no-
 
 You may pass `onPermissionRequest` when resuming a session too:
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+import { approveAll } from "@github/copilot-sdk";
+
+const session = await client.resumeSession("session-id", {
+    onPermissionRequest: approveAll,
+});
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 const session = await client.resumeSession("session-id", {
     onPermissionRequest: approveAll,
@@ -1552,6 +2099,7 @@ To let a specific custom tool bypass the permission prompt entirely, set `skipPe
 
 Enable the legacy question-and-answer `ask_user` tool by providing an `onUserInputRequest` handler:
 
+<!-- docs-validate: strict -->
 ```typescript
 const session = await client.createSession({
     model: "gpt-5",
@@ -1559,6 +2107,7 @@ const session = await client.createSession({
         // request.question - The question to ask
         // request.choices - Optional array of choices for multiple choice
         // request.allowFreeform - Whether freeform input is allowed (default: true)
+        // request.requestId - Runtime ID of the pending request (absent on older runtimes)
 
         console.log(`Agent asks: ${request.question}`);
         if (request.choices) {
@@ -1578,7 +2127,10 @@ const session = await client.createSession({
 
 Register an `onElicitationRequest` handler to let your client act as an elicitation provider — presenting form-based UI dialogs on behalf of the agent. When provided, the server notifies your client whenever a tool or MCP server needs structured user input.
 
+<!-- docs-validate: strict -->
 ```typescript
+import { approveAll } from "@github/copilot-sdk";
+
 const session = await client.createSession({
     model: "gpt-5",
     onPermissionRequest: approveAll,
@@ -1619,6 +2171,100 @@ In multi-client scenarios:
 
 Hook into session lifecycle events by providing handlers in the `hooks` configuration:
 
+<!-- docs-validate: strict -->
+<!-- docs-validate: hidden -->
+```typescript
+declare function needsMoreWork(): boolean;
+
+const session = await client.createSession({
+    model: "gpt-5",
+    hooks: {
+        // Called before each tool execution
+        onPreToolUse: async (input, invocation) => {
+            console.log(`About to run tool: ${input.toolName}`);
+            // Return permission decision and optionally modify args
+            return {
+                permissionDecision: "allow", // "allow", "deny", or "ask"
+                modifiedArgs: input.toolArgs, // Optionally modify tool arguments
+                additionalContext: "Extra context for the model",
+            };
+        },
+
+        // Called after each successful tool execution
+        onPostToolUse: async (input, invocation) => {
+            console.log(`Tool ${input.toolName} completed`);
+            // Optionally modify the result or add context
+            return {
+                additionalContext: "Post-execution notes",
+            };
+        },
+
+        // 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}`);
+            return {
+                modifiedPrompt: input.prompt, // Optionally modify the prompt
+            };
+        },
+
+        // Called when session starts
+        onSessionStart: async (input, invocation) => {
+            console.log(`Session started from: ${input.source}`); // "startup", "resume", "new"
+            return {
+                additionalContext: "Session initialization context",
+            };
+        },
+
+        // Called when session ends
+        onSessionEnd: async (input, invocation) => {
+            console.log(`Session ended: ${input.reason}`);
+        },
+
+        // Called when an error occurs
+        onErrorOccurred: async (input, invocation) => {
+            console.error(`Error in ${input.errorContext}: ${input.error}`);
+            return {
+                errorHandling: "retry", // "retry", "skip", or "abort"
+            };
+        },
+
+        // Called when the top-level agent naturally stops
+        onAgentStop: async (input, invocation) => {
+            if (!input.stopHookActive && needsMoreWork()) {
+                return {
+                    decision: "block",
+                    reason: "Run the final validation and fix any failures.",
+                };
+            }
+        },
+
+        // Called before a sub-agent's first turn (the input identifies the parent session)
+        onSubagentStart: (input, invocation) => {
+            console.log(`Starting ${input.agentDisplayName ?? input.agentName}`);
+            return { additionalContext: "Check the requested file before reporting back." };
+        },
+
+        // Called when a sub-agent completes a turn
+        onSubagentStop: (input, invocation) => {
+            console.log(`${input.agentName} replied: ${input.response}`);
+            // Return { decision: "block", reason: "Continue checking the file." }
+            // to request another child turn instead.
+            return { modifiedResponse: `Reviewed: ${input.response}` };
+        },
+    },
+});
+```
+<!-- /docs-validate: hidden -->
 ```typescript
 const session = await client.createSession({
     model: "gpt-5",
@@ -1724,12 +2370,13 @@ const session = await client.createSession({
 
 ## Error Handling
 
+<!-- docs-validate: strict -->
 ```typescript
 try {
-    const session = await client.createSession();
+    const session = await client.createSession({});
     await session.send({ prompt: "Hello" });
 } catch (error) {
-    console.error("Error:", error.message);
+    console.error("Error:", error instanceof Error ? error.message : error);
 }
 ```