@github/copilot-sdk 1.0.29-preview.2 → 1.0.29-preview.3

package/README.md

@@ -813,6 +813,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({
@@ -840,6 +872,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?" });
 ```
@@ -848,6 +890,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",
@@ -1807,6 +1894,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) {

package/dist/cjs/cliVersion.js

@@ -22,7 +22,7 @@ __export(cliVersion_exports, {
   COPILOT_CLI_VERSION: () => COPILOT_CLI_VERSION
 });
 module.exports = __toCommonJS(cliVersion_exports);
-const COPILOT_CLI_VERSION = "1.0.106-3";
+const COPILOT_CLI_VERSION = "1.0.106-4";
 const COPILOT_CLI_USE_NPM_PACKAGE = false;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/cjs/client.js

@@ -3033,7 +3033,8 @@ stderr: ${stderrOutput}` : ""}`
     const result = await session._handleUserInputRequest({
       question: params.question,
       choices: params.choices,
-      allowFreeform: params.allowFreeform
+      allowFreeform: params.allowFreeform,
+      requestId: params.requestId
     });
     return result;
   }
@@ -3049,7 +3050,8 @@ stderr: ${stderrOutput}` : ""}`
       summary: params.summary,
       planContent: params.planContent,
       actions: params.actions,
-      recommendedAction: params.recommendedAction
+      recommendedAction: params.recommendedAction,
+      requestId: params.requestId
     });
   }
   async handleAutoModeSwitchRequest(params) {

package/dist/cjs/copilotRequestHandler.js

@@ -151,13 +151,16 @@ class CopilotWebSocketForwarder extends CopilotWebSocketHandler {
     });
   }
   async close(status = CopilotWebSocketCloseStatus.normalClosure) {
+    const upstream = this.#upstream;
+    this.#upstream = null;
+    const completion = super.close(status);
     try {
-      if (this.#upstream?.readyState === WebSocket.OPEN || this.#upstream?.readyState === WebSocket.CONNECTING) {
-        this.#upstream?.close();
+      if (upstream?.readyState === WebSocket.OPEN || upstream?.readyState === WebSocket.CONNECTING) {
+        upstream.close();
       }
     } catch {
     }
-    await super.close(status);
+    await completion;
   }
   async [Symbol.asyncDispose]() {
     try {

package/dist/cjs/generated/rpc.js

@@ -841,9 +841,17 @@ function createServerRpc(connection) {
        *
        * @param params A bounded catalog search. Both the query length and the result count are capped by the schema so a caller cannot request an unbounded scan.
        *
-       * @returns Outcome of a catalog.search call: either bounded inert candidates, or one typed refusal. Never a partial success.
+       * @returns Outcome of catalog.search or catalog.recommend: either bounded inert candidates, or one typed refusal. Never a partial success.
        */
       search: async (params) => connection.sendRequest("catalog.search", params),
+      /**
+       * Requests the initial page of at most ten official-product recommendations for a complete task and product, bound to an existing attached local session. Requires catalog-recommend, catalog-search-session-bound and catalog-search-credential-required. Uses the selected GitHub.com user credential on the fixed Agent Finder recommendations route; successful capability negotiation does not establish service acceptance. Returns the existing inert catalog candidates and retained install references with the typed catalog refusal union. No anonymous retry, unfiltered search fallback or continuation is performed. Server-owned product approvals establish provenance, not task suitability. Read-only: nothing is installed, configured or persisted.
+       *
+       * @param params Initial-page official-product recommendations for a complete task. The runtime fixes recommendationPolicy to official-product and pageSize to 10; callers cannot override the policy, request pagination or fall back to search.
+       *
+       * @returns Outcome of catalog.search or catalog.recommend: either bounded inert candidates, or one typed refusal. Never a partial success.
+       */
+      recommend: async (params) => connection.sendRequest("catalog.recommend", params),
       /**
        * Retrieves one saved feed by its opaque ID, optionally filtered by trust tier. Requires catalog-feeds and catalog-search-credential-required, and uses the same authority, credential policy, optional session binding and candidate projection as catalog.search, so available entries are the same inert candidates, with the same installability, handles and display metadata, and install through the same confirmed flows. Entries keep the feed's order; an entry the runtime cannot present is returned as unavailable with a reason rather than failing the feed. No anonymous retry. Read-only: nothing is installed, configured, or persisted.
        *

package/dist/cjs/session.js

@@ -1587,6 +1587,7 @@ class CopilotSession {
           assertWorkflowResult(result);
           return { result };
         } finally {
+          controller.abort(new DOMException("Workflow run has settled", "AbortError"));
           try {
             await progress.close();
           } finally {

package/dist/cliVersion.d.ts

@@ -1,2 +1,2 @@
-export declare const COPILOT_CLI_VERSION = "1.0.106-3";
+export declare const COPILOT_CLI_VERSION = "1.0.106-4";
 export declare const COPILOT_CLI_USE_NPM_PACKAGE = false;

package/dist/cliVersion.js

@@ -1,4 +1,4 @@
-const COPILOT_CLI_VERSION = "1.0.106-3";
+const COPILOT_CLI_VERSION = "1.0.106-4";
 const COPILOT_CLI_USE_NPM_PACKAGE = false;
 export {
   COPILOT_CLI_USE_NPM_PACKAGE,

package/dist/client.js

@@ -3015,7 +3015,8 @@ stderr: ${stderrOutput}` : ""}`
     const result = await session._handleUserInputRequest({
       question: params.question,
       choices: params.choices,
-      allowFreeform: params.allowFreeform
+      allowFreeform: params.allowFreeform,
+      requestId: params.requestId
     });
     return result;
   }
@@ -3031,7 +3032,8 @@ stderr: ${stderrOutput}` : ""}`
       summary: params.summary,
       planContent: params.planContent,
       actions: params.actions,
-      recommendedAction: params.recommendedAction
+      recommendedAction: params.recommendedAction,
+      requestId: params.requestId
     });
   }
   async handleAutoModeSwitchRequest(params) {

package/dist/copilotRequestHandler.js

@@ -124,13 +124,16 @@ class CopilotWebSocketForwarder extends CopilotWebSocketHandler {
     });
   }
   async close(status = CopilotWebSocketCloseStatus.normalClosure) {
+    const upstream = this.#upstream;
+    this.#upstream = null;
+    const completion = super.close(status);
     try {
-      if (this.#upstream?.readyState === WebSocket.OPEN || this.#upstream?.readyState === WebSocket.CONNECTING) {
-        this.#upstream?.close();
+      if (upstream?.readyState === WebSocket.OPEN || upstream?.readyState === WebSocket.CONNECTING) {
+        upstream.close();
       }
     } catch {
     }
-    await super.close(status);
+    await completion;
   }
   async [Symbol.asyncDispose]() {
     try {

package/dist/generated/rpc.d.ts

@@ -1081,6 +1081,8 @@ export type CatalogCapability =
  | "catalog-search-credential-required"
 /** Captures the exact existing native session, account, host and connection for authenticated catalogue search, selection and planning. Requires catalog-search-credential-required; does not grant installation or create a session. */
  | "catalog-search-session-bound"
+/** Understands initial-page official-product recommendations for a full task and product with fixed pageSize 10. Requires session-bound, credential-required catalogue support. No anonymous retry, broad-search fallback or continuation. Authentication uses the selected GitHub.com user credential; successful capability negotiation does not establish service acceptance. */
+ | "catalog-recommend"
 /** Understands effect-free preparation, exact human-confirmed apply and owned removal for fully resolved personal remote MCP choices without supplied inputs or configured secrets. Advertised only when the real producer and lower owned admission are linked; requires original connection and bound session authority for new work. */
  | "mcp-confirmed-remote-installation"
 /** Extends mcp-confirmed-remote-installation to declared non-secret header and URL values and receipt-owned header secrets for personal remote MCP choices. Requires mcp-confirmed-remote-installation and bound session authority. Secret values are written only to the reviewed backend after confirmation and are never returned; package and stdio choices remain unsupported. Advertised only when owned secret effects and owned secret activation are linked. */
@@ -1211,6 +1213,8 @@ export type CatalogInvalidRequestField =
 "policySessionId"
 /** The search query was empty or longer than permitted. */
  | "query"
+/** The requested recommendation product was missing, blank or longer than permitted. */
+ | "product"
 /** The requested result count fell outside its permitted range. */
  | "limit"
 /** The requested candidate kinds were empty or contained a duplicate. */
@@ -1714,7 +1718,7 @@ export type CatalogSearchTotalCountRelation =
 /** No exact/full-query or lower-bound guarantee is available. */
 "unknown";
 /**
- * Outcome of a catalog.search call: either bounded inert candidates, or one typed refusal. Never a partial success.
+ * Outcome of catalog.search or catalog.recommend: either bounded inert candidates, or one typed refusal. Never a partial success.
  *
  * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
  * via the `definition` "CatalogSearchResult".
@@ -11509,6 +11513,31 @@ export interface CatalogPolicyRejectedError {
      */
     message: string;
 }
+/**
+ * Initial-page official-product recommendations for a complete task. The runtime fixes recommendationPolicy to official-product and pageSize to 10; callers cannot override the policy, request pagination or fall back to search.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "CatalogRecommendRequest".
+ */
+/** @experimental */
+export interface CatalogRecommendRequest {
+    /**
+     * Required contract, including catalog-recommend, catalog-search-session-bound and catalog-search-credential-required.
+     */
+    contract: CatalogClientContract;
+    /**
+     * Existing attached local session whose account, host and connection own the candidate references. Never creates or resumes a session.
+     */
+    policySessionId: string;
+    /**
+     * Full original task, including action, account, output and host requirements. Forwarded without trimming or rewriting and excluded from telemetry.
+     */
+    query: string;
+    /**
+     * Requested product. Agent Finder resolves aliases and applies its versioned official-product approvals before limiting results.
+     */
+    product: string;
+}
 /**
  * A computed Skill install plan. Nothing has been applied.
  *
@@ -38814,9 +38843,17 @@ export declare function createServerRpc(connection: MessageConnection): {
          *
          * @param params A bounded catalog search. Both the query length and the result count are capped by the schema so a caller cannot request an unbounded scan.
          *
-         * @returns Outcome of a catalog.search call: either bounded inert candidates, or one typed refusal. Never a partial success.
+         * @returns Outcome of catalog.search or catalog.recommend: either bounded inert candidates, or one typed refusal. Never a partial success.
          */
         search: (params: CatalogSearchRequest) => Promise<CatalogSearchResult>;
+        /**
+         * Requests the initial page of at most ten official-product recommendations for a complete task and product, bound to an existing attached local session. Requires catalog-recommend, catalog-search-session-bound and catalog-search-credential-required. Uses the selected GitHub.com user credential on the fixed Agent Finder recommendations route; successful capability negotiation does not establish service acceptance. Returns the existing inert catalog candidates and retained install references with the typed catalog refusal union. No anonymous retry, unfiltered search fallback or continuation is performed. Server-owned product approvals establish provenance, not task suitability. Read-only: nothing is installed, configured or persisted.
+         *
+         * @param params Initial-page official-product recommendations for a complete task. The runtime fixes recommendationPolicy to official-product and pageSize to 10; callers cannot override the policy, request pagination or fall back to search.
+         *
+         * @returns Outcome of catalog.search or catalog.recommend: either bounded inert candidates, or one typed refusal. Never a partial success.
+         */
+        recommend: (params: CatalogRecommendRequest) => Promise<CatalogSearchResult>;
         /**
          * Retrieves one saved feed by its opaque ID, optionally filtered by trust tier. Requires catalog-feeds and catalog-search-credential-required, and uses the same authority, credential policy, optional session binding and candidate projection as catalog.search, so available entries are the same inert candidates, with the same installability, handles and display metadata, and install through the same confirmed flows. Entries keep the feed's order; an entry the runtime cannot present is returned as unavailable with a reason rather than failing the feed. No anonymous retry. Read-only: nothing is installed, configured, or persisted.
          *

package/dist/generated/rpc.js

@@ -813,9 +813,17 @@ function createServerRpc(connection) {
        *
        * @param params A bounded catalog search. Both the query length and the result count are capped by the schema so a caller cannot request an unbounded scan.
        *
-       * @returns Outcome of a catalog.search call: either bounded inert candidates, or one typed refusal. Never a partial success.
+       * @returns Outcome of catalog.search or catalog.recommend: either bounded inert candidates, or one typed refusal. Never a partial success.
        */
       search: async (params) => connection.sendRequest("catalog.search", params),
+      /**
+       * Requests the initial page of at most ten official-product recommendations for a complete task and product, bound to an existing attached local session. Requires catalog-recommend, catalog-search-session-bound and catalog-search-credential-required. Uses the selected GitHub.com user credential on the fixed Agent Finder recommendations route; successful capability negotiation does not establish service acceptance. Returns the existing inert catalog candidates and retained install references with the typed catalog refusal union. No anonymous retry, unfiltered search fallback or continuation is performed. Server-owned product approvals establish provenance, not task suitability. Read-only: nothing is installed, configured or persisted.
+       *
+       * @param params Initial-page official-product recommendations for a complete task. The runtime fixes recommendationPolicy to official-product and pageSize to 10; callers cannot override the policy, request pagination or fall back to search.
+       *
+       * @returns Outcome of catalog.search or catalog.recommend: either bounded inert candidates, or one typed refusal. Never a partial success.
+       */
+      recommend: async (params) => connection.sendRequest("catalog.recommend", params),
       /**
        * Retrieves one saved feed by its opaque ID, optionally filtered by trust tier. Requires catalog-feeds and catalog-search-credential-required, and uses the same authority, credential policy, optional session binding and candidate projection as catalog.search, so available entries are the same inert candidates, with the same installability, handles and display metadata, and install through the same confirmed flows. Entries keep the feed's order; an entry the runtime cannot present is returned as unavailable with a reason rather than failing the feed. No anonymous retry. Read-only: nothing is installed, configured, or persisted.
        *

package/dist/session.js

@@ -1574,6 +1574,7 @@ class CopilotSession {
           assertWorkflowResult(result);
           return { result };
         } finally {
+          controller.abort(new DOMException("Workflow run has settled", "AbortError"));
           try {
             await progress.close();
           } finally {

package/dist/types.d.ts

@@ -1192,6 +1192,12 @@ export interface UserInputRequest {
      * @default true
      */
     allowFreeform?: boolean;
+    /**
+     * Runtime ID of the pending `user_input.requested` request. Pass it as `requestId`
+     * to answer this exact request through the session's UI RPCs. Absent when the
+     * runtime predates this field.
+     */
+    requestId?: string;
 }
 /**
  * Response to a user input request
@@ -1224,6 +1230,12 @@ export interface ExitPlanModeRequest {
     actions: string[];
     /** The action recommended by the runtime. */
     recommendedAction: string;
+    /**
+     * Runtime ID of the pending `exit_plan_mode.requested` request. Pass it as
+     * `requestId` to answer this exact request through the session's UI RPCs. Absent
+     * when the runtime predates this field.
+     */
+    requestId?: string;
 }
 /**
  * Response to an exit-plan-mode request.

package/package.json

@@ -5,8 +5,8 @@
         "url": "https://github.com/github/copilot-agent-runtime.git",
         "directory": "src/sdk/nodejs"
     },
-    "version": "1.0.29-preview.2",
-    "copilotCliVersion": "1.0.106-3",
+    "version": "1.0.29-preview.3",
+    "copilotCliVersion": "1.0.106-4",
     "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
     "main": "./dist/cjs/index.js",
     "types": "./dist/index.d.ts",
@@ -115,18 +115,18 @@
         "README.md"
     ],
     "copilotRuntime": {
-        "sourceSha": "70ffdab66d4c7eb84302789a8536c02d955da3ed",
-        "version": "1.0.106-3",
+        "sourceSha": "54bae76dc3ced5344dc60a365e81a06c787fda53",
+        "version": "1.0.106-4",
         "visibility": "public"
     },
     "optionalDependencies": {
-        "@github/copilot-sdk-darwin-arm64": "1.0.29-preview.2",
-        "@github/copilot-sdk-darwin-x64": "1.0.29-preview.2",
-        "@github/copilot-sdk-linux-arm64": "1.0.29-preview.2",
-        "@github/copilot-sdk-linux-x64": "1.0.29-preview.2",
-        "@github/copilot-sdk-linuxmusl-arm64": "1.0.29-preview.2",
-        "@github/copilot-sdk-linuxmusl-x64": "1.0.29-preview.2",
-        "@github/copilot-sdk-win32-arm64": "1.0.29-preview.2",
-        "@github/copilot-sdk-win32-x64": "1.0.29-preview.2"
+        "@github/copilot-sdk-darwin-arm64": "1.0.29-preview.3",
+        "@github/copilot-sdk-darwin-x64": "1.0.29-preview.3",
+        "@github/copilot-sdk-linux-arm64": "1.0.29-preview.3",
+        "@github/copilot-sdk-linux-x64": "1.0.29-preview.3",
+        "@github/copilot-sdk-linuxmusl-arm64": "1.0.29-preview.3",
+        "@github/copilot-sdk-linuxmusl-x64": "1.0.29-preview.3",
+        "@github/copilot-sdk-win32-arm64": "1.0.29-preview.3",
+        "@github/copilot-sdk-win32-x64": "1.0.29-preview.3"
     }
 }