@github/copilot-sdk 1.0.14 → 1.0.15-preview.0

package/dist/session.d.ts

@@ -1,7 +1,7 @@
 import { createSessionRpc } from "./generated/rpc.js";
 import type { ModelSwitchAutoTierResult } from "./generated/rpc.js";
 import type { OpenCanvasInstance } from "./generated/rpc.js";
-import type { MessageOptions, ContextTier, ReasoningEffort, ReasoningSummary, AutoTier, ModelCapabilitiesOverride, SessionCapabilities, SessionEvent, SessionEventHandler, SessionEventType, SessionUiApi, TypedSessionEventHandler } from "./types.js";
+import type { MessageOptions, ResponseSchema, ContextTier, ReasoningEffort, ReasoningSummary, AutoTier, ModelCapabilitiesOverride, SessionCapabilities, SessionEvent, SessionEventHandler, SessionEventType, SessionUiApi, TypedSessionEventHandler } from "./types.js";
 import { type SessionFactoryApi } from "./factory.js";
 /** Assistant message event - the final response from the assistant. */
 export type AssistantMessageEvent = Extract<SessionEvent, {
@@ -65,6 +65,7 @@ export declare class CopilotSession {
     private _capabilities;
     private openCanvasInstances;
     private disconnected;
+    private readonly pendingStructuredWaits;
     private disconnecting;
     private onDisconnected?;
     /**
@@ -122,13 +123,14 @@ export declare class CopilotSession {
      */
     get ui(): SessionUiApi;
     /**
-     * Sends a message to this session and waits for the response.
+     * Sends a message to this session and returns once it is admitted.
      *
      * The message is processed asynchronously. Subscribe to events via {@link on}
      * to receive streaming responses and other session events.
      *
      * @param options - The message options including the prompt and optional attachments
-     * @returns A promise that resolves with the message ID of the response
+     * @returns The submitted user message's ID, not an assistant response ID.
+     *          When this send starts a run, root assistant messages carry it as originatingMessageId.
      * @throws Error if the session has been disconnected or the connection fails
      *
      * @example
@@ -149,6 +151,9 @@ export declare class CopilotSession {
      * assistant has finished processing the message.
      *
      * Events are still delivered to handlers registered via {@link on} while waiting.
+     * With a schema as the second argument, returns its parsed, validated result.
+     * Structured waits select only root-agent output originating from this send;
+     * other queued work may delay session.idle but cannot replace the result.
      *
      * @param options - The message options including the prompt and optional attachments
      * @param timeout - Timeout in milliseconds (default: 60000). Controls how long to wait; does not abort in-flight agent work.
@@ -165,7 +170,9 @@ export declare class CopilotSession {
      * ```
      */
     sendAndWait(prompt: string, timeout?: number): Promise<AssistantMessageEvent | undefined>;
+    sendAndWait<TResult>(options: MessageOptions | string, responseSchema: ResponseSchema<TResult>, timeout?: number): Promise<TResult>;
     sendAndWait(options: MessageOptions, timeout?: number): Promise<AssistantMessageEvent | undefined>;
+    private sendAndWaitForStructuredMessage;
     /**
      * Subscribes to events from this session.
      *

package/dist/session.js

@@ -3,6 +3,7 @@ import { ConnectionError, ErrorCodes, ResponseError } from "vscode-jsonrpc/node.
 import { createInternalSessionRpc, createSessionRpc } from "./generated/rpc.js";
 import { CanvasError } from "./canvas.js";
 import { getTraceContext } from "./telemetry.js";
+import { isResponseSchema, toJsonSchema } from "./schema.js";
 import { isAttributedPermissionResult } from "./types.js";
 import {
   FACTORY_AGENT_OPTION_KEYS,
@@ -259,6 +260,7 @@ class CopilotSession {
   _capabilities = {};
   openCanvasInstances = [];
   disconnected = false;
+  pendingStructuredWaits = /* @__PURE__ */ new Set();
   disconnecting = false;
   onDisconnected;
   /** @internal Client session API handlers, populated by CopilotClient during create/resume. */
@@ -475,13 +477,54 @@ class CopilotSession {
       attachments: options.attachments,
       mode: options.mode,
       agentMode: options.agentMode,
-      requestHeaders: options.requestHeaders
+      requestHeaders: options.requestHeaders,
+      ...options.responseSchema ? {
+        responseFormat: {
+          type: "json_schema",
+          jsonSchema: {
+            name: "response",
+            strict: true,
+            schema: toJsonSchema(options.responseSchema)
+          }
+        }
+      } : {}
     });
     return response.messageId;
   }
-  async sendAndWait(optionsOrPrompt, timeout) {
+  async sendAndWait(optionsOrPrompt, schemaOrTimeout, timeout) {
     const options = typeof optionsOrPrompt === "string" ? { prompt: optionsOrPrompt } : optionsOrPrompt;
-    const effectiveTimeout = timeout ?? 6e4;
+    const typedSchema = isResponseSchema(schemaOrTimeout) ? schemaOrTimeout : void 0;
+    if (schemaOrTimeout !== void 0 && typeof schemaOrTimeout !== "number" && !typedSchema) {
+      throw new TypeError(
+        "The second argument must be a timeout or a schema with toJSONSchema() and parse(). Pass raw JSON Schema in options.responseSchema instead."
+      );
+    }
+    const effectiveTimeout = (typeof schemaOrTimeout === "number" ? schemaOrTimeout : timeout) ?? 6e4;
+    if (typedSchema && options.responseSchema) {
+      throw new Error(
+        "Do not specify responseSchema in options when requesting a typed response."
+      );
+    }
+    if (typedSchema && options.mode === "immediate") {
+      throw new Error(
+        "Structured output cannot be requested on an immediate steering message."
+      );
+    }
+    if (typedSchema || options.responseSchema) {
+      const message = await this.sendAndWaitForStructuredMessage(
+        typedSchema ? { ...options, responseSchema: typedSchema } : options,
+        effectiveTimeout
+      );
+      if (typedSchema) {
+        if (!message) {
+          throw new Error(
+            "The requested run completed without a structured assistant response."
+          );
+        }
+        return typedSchema.parse(JSON.parse(message.data.content));
+      }
+      return message;
+    }
     let resolveOutcome;
     const outcomePromise = new Promise((resolve) => {
       resolveOutcome = resolve;
@@ -523,12 +566,95 @@ class CopilotSession {
       unsubscribe();
     }
   }
+  async sendAndWaitForStructuredMessage(options, timeout) {
+    if (this.disconnected) {
+      throw new Error("Session is disconnected");
+    }
+    let resolveOutcome;
+    const outcomePromise = new Promise((resolve) => {
+      resolveOutcome = resolve;
+    });
+    const fail = (error) => resolveOutcome({ kind: "error", error });
+    let messageId;
+    let consumed = false;
+    let lastMessage;
+    const buffered = [];
+    const observe = (event) => {
+      if (event.agentId) return;
+      if (event.type === "user.message" && event.data.messageId === messageId) {
+        consumed = true;
+      } else if (event.type === "assistant.message" && event.data.originatingMessageId === messageId) {
+        consumed = true;
+        lastMessage = event.data.toolRequests?.length ? void 0 : event;
+      } else if (consumed && event.type === "session.idle" && event.data.mode !== "autopilot") {
+        if (event.data.aborted) {
+          fail(
+            new Error(
+              "The requested run was aborted before a structured result was completed."
+            )
+          );
+        } else {
+          resolveOutcome({ kind: "idle", message: lastMessage });
+        }
+      } else if (consumed && event.type === "session.error") {
+        const error = new Error(event.data.message);
+        error.stack = event.data.stack;
+        fail(error);
+      }
+    };
+    const unsubscribe = this.on((event) => {
+      if (event.type !== "user.message" && event.type !== "assistant.message" && event.type !== "session.idle" && event.type !== "session.error") {
+        return;
+      }
+      if (messageId === void 0) {
+        buffered.push(event);
+      } else {
+        observe(event);
+      }
+    });
+    this.pendingStructuredWaits.add(fail);
+    const timer = setTimeout(
+      () => fail(new Error(`Timeout after ${timeout}ms waiting for the structured response`)),
+      timeout
+    );
+    try {
+      const sendOutcome = this.send(options).then(
+        (id) => {
+          if (!id) {
+            throw new Error(
+              "The runtime did not return a message ID for the structured send."
+            );
+          }
+          messageId = id;
+          for (const event of buffered) observe(event);
+          buffered.length = 0;
+          return outcomePromise;
+        },
+        (error) => ({
+          kind: "error",
+          error: error instanceof Error ? error : new Error(String(error))
+        })
+      );
+      const outcome = await Promise.race([sendOutcome, outcomePromise]);
+      if (outcome.kind === "error") throw outcome.error;
+      return outcome.message;
+    } finally {
+      clearTimeout(timer);
+      buffered.length = 0;
+      unsubscribe();
+      this.pendingStructuredWaits.delete(fail);
+    }
+  }
   /** @internal */
   _markDisconnected() {
     if (this.disconnected) {
       return;
     }
     this.disconnected = true;
+    for (const fail of this.pendingStructuredWaits) {
+      fail(new Error("Session disconnected while waiting for a structured response"));
+    }
+    this.pendingStructuredWaits.clear();
     for (const controller of this.pendingExternalTools.values()) {
       controller.abort();
     }

package/dist/types.d.ts

@@ -4,14 +4,14 @@
 import type { Canvas } from "./canvas.js";
 import type { SessionFsProvider } from "./sessionFsProvider.js";
 import type { CopilotRequestHandler } from "./copilotRequestHandler.js";
-import type { AutoTier, PermissionRequest as GeneratedPermissionRequest, PermissionRequestedData as GeneratedPermissionRequestedData, PermissionRequestedEvent as GeneratedPermissionRequestedEvent, ReasoningSummary, SessionLimitsConfig, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
+import type { AttachmentExtensionContext as GeneratedExtensionContextAttachment, AutoTier, PermissionRequest as GeneratedPermissionRequest, PermissionRequestedData as GeneratedPermissionRequestedData, PermissionRequestedEvent as GeneratedPermissionRequestedEvent, ReasoningSummary, SessionLimitsConfig, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
 import type { CopilotSession } from "./session.js";
 import type { FactoryJsonSchema, JsonValue } from "./factory.js";
-import type { GitHubTokenAcquireRequest, GitHubTokenAcquireResult, GitHubTelemetryNotification, ModelBillingTokenPrices, OpenCanvasInstance, RemoteSessionMode, CurrentToolMetadata } from "./generated/rpc.js";
+import type { ExtensionLaunchProviderHandler as GeneratedExtensionLaunchProvider, GitHubTokenAcquireRequest, GitHubTokenAcquireResult, GitHubTelemetryNotification, ModelBillingTokenPrices, OpenCanvasInstance, RemoteSessionMode, CurrentToolMetadata } from "./generated/rpc.js";
 import type { ToolSet } from "./toolSet.js";
 export type { RemoteSessionMode } from "./generated/rpc.js";
 export type { CurrentToolMetadata } from "./generated/rpc.js";
-export type { GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, } from "./generated/rpc.js";
+export type { ExtensionLaunchProfile, ExtensionLaunchProviderResolveRequest, ExtensionLaunchProviderResolveResult, GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, } from "./generated/rpc.js";
 /**
  * Arguments passed to a session's {@link GitHubTokenProvider}.
  *
@@ -282,6 +282,14 @@ export interface CopilotClientOptions {
      * startup before any sessions can be created.
      */
     builtinPluginDirectories?: readonly string[];
+    /**
+     * Connection-level extension launch profile provider.
+     * When set, the client registers the provider during startup before any
+     * session can be created.
+     *
+     * @experimental
+     */
+    extensionLaunchProvider?: ExtensionLaunchProvider;
     /**
      * Log level for the Copilot runtime. When omitted, the runtime uses its
      * own default (currently `"info"`).
@@ -409,6 +417,8 @@ export interface CopilotClientOptions {
      */
     clientInfo?: CopilotClientInfo;
 }
+/** Resolves launch profiles for extension entrypoints discovered by the runtime. */
+export type ExtensionLaunchProvider = GeneratedExtensionLaunchProvider;
 /**
  * Configuration for creating a session
  */
@@ -510,6 +520,13 @@ export interface ZodSchema<T = unknown> {
     _output: T;
     toJSONSchema(): Record<string, unknown>;
 }
+/**
+ * A Zod-compatible output schema that both describes and parses a typed result.
+ * TypeScript types are erased at runtime, so typed output requires a schema value.
+ */
+export interface ResponseSchema<T = unknown> extends ZodSchema<T> {
+    parse(value: unknown): T;
+}
 /**
  * Tool definition. Parameters can be either:
  * - A Zod schema (provides type inference for handler)
@@ -2740,6 +2757,8 @@ export interface ProviderModelConfig {
  * Message provenance, independent of delivery mode.
  */
 export type MessageSource = "user" | "system" | `agent-${string}`;
+/** Structured context contributed by an extension. */
+export type ExtensionContextAttachment = GeneratedExtensionContextAttachment;
 export interface MessageOptions {
     /**
      * The prompt/message to send
@@ -2752,7 +2771,7 @@ export interface MessageOptions {
      */
     source?: MessageSource;
     /**
-     * File, directory, selection, or blob attachments
+     * File, directory, selection, blob, or extension context attachments
      */
     attachments?: Array<{
         type: "file";
@@ -2782,7 +2801,7 @@ export interface MessageOptions {
         data: string;
         mimeType: string;
         displayName?: string;
-    }>;
+    } | ExtensionContextAttachment>;
     /**
      * Message delivery mode
      * - "enqueue": Add to queue (default)
@@ -2802,6 +2821,19 @@ export interface MessageOptions {
      * If provided, this is shown in the timeline instead of `prompt`.
      */
     displayPrompt?: string;
+    /**
+     * JSON Schema or a Zod schema for this run's output, including requests after tool calls.
+     * Independent sends do not inherit it. Ordinary immediate steering retains the active
+     * schema and origin, even when promoted to a follow-up after the model request finishes.
+     * Specifying a schema with mode "immediate" is rejected, even while idle.
+     * This is not a persisted session default and does not survive a context reset.
+     *
+     * sendAndWait still returns an assistant message event. For a typed result, pass a
+     * Zod-compatible schema as sendAndWait's second argument instead.
+     * Streaming events remain text and may include intermediate messages.
+     * Use rpc.send's responseFormat for provider-specific name, description and strict options.
+     */
+    responseSchema?: ZodSchema | Record<string, unknown>;
 }
 /**
  * All possible event type strings from SessionEvent

package/package.json

@@ -4,8 +4,8 @@
         "type": "git",
         "url": "https://github.com/github/copilot-sdk.git"
     },
-    "version": "1.0.14",
-    "copilotCliVersion": "1.0.85",
+    "version": "1.0.15-preview.0",
+    "copilotCliVersion": "1.0.87-0",
     "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
     "main": "./dist/cjs/index.js",
     "types": "./dist/index.d.ts",
@@ -37,7 +37,8 @@
         "clean": "rimraf --glob dist *.tgz",
         "build": "tsx esbuild-copilotsdk-nodejs.ts",
         "acquire:runtime-packages": "tsx scripts/runtime-package-acquisition.ts",
-        "pack:release": "tsx scripts/package-sdk.ts",
+        "pack:release": "npm run verify:dependency-policy && tsx scripts/package-sdk.ts",
+        "verify:dependency-policy": "tsx scripts/verify-dependency-policy.ts",
         "verify:release-packages": "tsx scripts/verify-release-packages.ts",
         "release:manifest": "tsx scripts/release-manifest.ts",
         "prepare:runtime": "tsx scripts/prepare-runtime.ts",
@@ -64,13 +65,14 @@
     "author": "GitHub",
     "license": "MIT",
     "dependencies": {
-        "koffi": "^3.2.1",
-        "vscode-jsonrpc": "^8.2.1",
-        "zod": "^4.3.6"
+        "koffi": "3.2.1",
+        "vscode-jsonrpc": "8.2.1",
+        "zod": "4.3.6"
     },
     "devDependencies": {
         "@platformatic/vfs": "^0.3.0",
         "@types/node": "^25.2.0",
+        "@types/semver": "7.8.0",
         "@types/ws": "^8.18.1",
         "@typescript-eslint/eslint-plugin": "^8.54.0",
         "@typescript-eslint/parser": "^8.54.0",
@@ -98,13 +100,13 @@
         "README.md"
     ],
     "optionalDependencies": {
-        "@github/copilot-sdk-darwin-arm64": "1.0.14",
-        "@github/copilot-sdk-darwin-x64": "1.0.14",
-        "@github/copilot-sdk-linux-arm64": "1.0.14",
-        "@github/copilot-sdk-linux-x64": "1.0.14",
-        "@github/copilot-sdk-linuxmusl-arm64": "1.0.14",
-        "@github/copilot-sdk-linuxmusl-x64": "1.0.14",
-        "@github/copilot-sdk-win32-arm64": "1.0.14",
-        "@github/copilot-sdk-win32-x64": "1.0.14"
+        "@github/copilot-sdk-darwin-arm64": "1.0.15-preview.0",
+        "@github/copilot-sdk-darwin-x64": "1.0.15-preview.0",
+        "@github/copilot-sdk-linux-arm64": "1.0.15-preview.0",
+        "@github/copilot-sdk-linux-x64": "1.0.15-preview.0",
+        "@github/copilot-sdk-linuxmusl-arm64": "1.0.15-preview.0",
+        "@github/copilot-sdk-linuxmusl-x64": "1.0.15-preview.0",
+        "@github/copilot-sdk-win32-arm64": "1.0.15-preview.0",
+        "@github/copilot-sdk-win32-x64": "1.0.15-preview.0"
     }
 }