@github/copilot-sdk 1.0.14 → 1.0.15-unstable.35395657398.gad69ee1

package/README.md

@@ -305,6 +305,87 @@ Send a message and wait until the session becomes idle.
 
 Returns the final assistant message event, or undefined if none was received.
 
+##### Structured output (preview)
+
+Requires a runtime build with `responseFormat` and `originatingMessageId` support.
+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:
+
+```typescript
+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
+```
+
+For a typed result, pass the Zod schema as the **second argument** instead:
+
+```typescript
+const answer = await session.sendAndWait("What is 19 + 23?", answerSchema);
+console.log(answer.answer); // number; TResult is inferred from answerSchema
+```
+
+`sendAndWait<TResult>(options, schema, timeout?)` generates the JSON Schema from
+the schema value, parses the final JSON, and validates it with the schema's
+`parse` method. TypeScript cannot derive a runtime schema from an erased type
+parameter alone. Invalid JSON, a schema mismatch, or a completed run without a
+matching assistant message throws. Do not also set `options.responseSchema` when
+using the typed overload.
+
+The schema belongs to the submitted run, including its tool-call iterations.
+Internally generated stop-hook corrections retain the schema and originating
+message ID, so the wait returns the corrected answer. Independent subsequent
+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.
+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"`,
+`strict: true`).
+Each batch starts one run: the final returned message ID is its origin, preceding
+messages are context, and an empty batch has no origin. An immediate batch
+steers the active run instead and retains its origin.
+The schema is not a persisted session default: autonomous resume-pending work
+after a restart does not restore it. A terminal tool that clears context ends
+the old run; its fresh seed does not inherit the schema or origin. Such a run
+can finish without a structured result, in which case the typed wait throws.
+After a successful terminal tool, the runtime disables tools while the model
+produces the structured result. Stop-hook corrections remain supported.
+Remote sessions and known HydraFusion routes reject response formats before
+admission. Schemas larger than 32 MiB when JSON-encoded are also rejected before
+admission, using the runtime's existing request-size ceiling. This does not
+guarantee the schema plus conversation and tools fits the provider's budget.
+
+Structured waits select the last root-agent message whose `originatingMessageId`
+matches the ID returned by their send, then return at a non-autopilot
+`session.idle`. Other queued work can delay that idle, but cannot replace the
+selected result. The existing unformatted overload retains its session-wide
+behavior. `turnId` identifies an individual model/tool iteration, not the whole
+run; telemetry interaction IDs are not unique run identifiers.
+
+For event-driven consumption with `send`, subscribe before sending and collect
+root `assistant.message` events whose `data.originatingMessageId` matches the ID
+returned by `send`; events may arrive before that acknowledgement. Wait for
+`session.idle`, then parse the last matching message without tool requests.
+An earlier response may be superseded by a stop-hook correction. Handle
+`session.error` and aborted idle events rather than returning a partial result.
+
+Streaming still delivers ordinary text events, including intermediate messages
+and tool calls. Only the final selected message is parsed by the typed overload;
+not every event is necessarily a complete schema-conforming JSON document.
+Provider errors, refusals, cancellation, truncation, session errors, and timeouts
+can prevent a typed result. A timeout stops waiting, not the runtime's work.
+Use a model and endpoint that support native structured output. An API-compatible
+gateway may ignore format fields even when it accepts the request; for example,
+the Claude Chat-completions compatibility route is not equivalent to Anthropic's
+native `output_config.format` endpoint.
+
 ##### `on(eventType: string, handler: TypedSessionEventHandler): () => void`
 
 Subscribe to a specific event type. The handler receives properly typed events.

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.85";
+const COPILOT_CLI_VERSION = "1.0.86-unstable.r35389812552.g657d1e5";
 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

@@ -45,13 +45,11 @@ var import_cliVersion = require("./cliVersion.js");
 var import_sessionFsProvider = require("./sessionFsProvider.js");
 var import_copilotRequestHandler = require("./copilotRequestHandler.js");
 var import_telemetry = require("./telemetry.js");
+var import_schema = require("./schema.js");
 var import_toolSet = require("./toolSet.js");
 var import_types = require("./types.js");
 const MIN_PROTOCOL_VERSION = 3;
 const RUNTIME_SHUTDOWN_TIMEOUT_MS = 1e4;
-function isZodSchema(value) {
-  return value != null && typeof value === "object" && "toJSONSchema" in value && typeof value.toJSONSchema === "function";
-}
 async function withTimeout(promise, timeoutMs, message) {
   let timeout;
   try {
@@ -96,13 +94,6 @@ async function waitForChildExit(child, timeoutMs) {
     }
   });
 }
-function toJsonSchema(parameters) {
-  if (!parameters) return void 0;
-  if (isZodSchema(parameters)) {
-    return parameters.toJSONSchema();
-  }
-  return parameters;
-}
 const DEFAULT_PROVIDER_NAME = "default";
 function extractBearerTokenProviders(provider, providers) {
   const callbacks = /* @__PURE__ */ new Map();
@@ -1188,7 +1179,7 @@ class CopilotClient {
         tools: config.tools?.map((tool) => ({
           name: tool.name,
           description: tool.description,
-          parameters: toJsonSchema(tool.parameters),
+          parameters: (0, import_schema.toJsonSchema)(tool.parameters),
           overridesBuiltInTool: tool.overridesBuiltInTool,
           skipPermission: tool.skipPermission,
           defer: tool.defer,
@@ -1432,7 +1423,7 @@ class CopilotClient {
         tools: config.tools?.map((tool) => ({
           name: tool.name,
           description: tool.description,
-          parameters: toJsonSchema(tool.parameters),
+          parameters: (0, import_schema.toJsonSchema)(tool.parameters),
           overridesBuiltInTool: tool.overridesBuiltInTool,
           skipPermission: tool.skipPermission,
           defer: tool.defer,

package/dist/cjs/schema.js

@@ -0,0 +1,40 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var schema_exports = {};
+__export(schema_exports, {
+  isResponseSchema: () => isResponseSchema,
+  isZodSchema: () => isZodSchema,
+  toJsonSchema: () => toJsonSchema
+});
+module.exports = __toCommonJS(schema_exports);
+function isZodSchema(value) {
+  return typeof value === "object" && value !== null && "toJSONSchema" in value && typeof value.toJSONSchema === "function";
+}
+function toJsonSchema(schema) {
+  return isZodSchema(schema) ? schema.toJSONSchema() : schema;
+}
+function isResponseSchema(value) {
+  return isZodSchema(value) && "parse" in value && typeof value.parse === "function";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isResponseSchema,
+  isZodSchema,
+  toJsonSchema
+});

package/dist/cjs/session.js

@@ -26,6 +26,7 @@ var import_node = require("vscode-jsonrpc/node.js");
 var import_rpc = require("./generated/rpc.js");
 var import_canvas = require("./canvas.js");
 var import_telemetry = require("./telemetry.js");
+var import_schema = require("./schema.js");
 var import_types = require("./types.js");
 var import_factory = require("./factory.js");
 function isFactoryResumeErrorCode(value) {
@@ -277,6 +278,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. */
@@ -493,13 +495,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: (0, import_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 = (0, import_schema.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;
@@ -541,12 +584,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/cliVersion.d.ts

@@ -1,2 +1,2 @@
-export declare const COPILOT_CLI_VERSION = "1.0.85";
+export declare const COPILOT_CLI_VERSION = "1.0.86-unstable.r35389812552.g657d1e5";
 export declare const COPILOT_CLI_USE_NPM_PACKAGE = false;

package/dist/cliVersion.js

@@ -1,4 +1,4 @@
-const COPILOT_CLI_VERSION = "1.0.85";
+const COPILOT_CLI_VERSION = "1.0.86-unstable.r35389812552.g657d1e5";
 const COPILOT_CLI_USE_NPM_PACKAGE = false;
 export {
   COPILOT_CLI_USE_NPM_PACKAGE,

package/dist/client.js

@@ -23,13 +23,11 @@ import { COPILOT_CLI_VERSION } from "./cliVersion.js";
 import { createSessionFsAdapter } from "./sessionFsProvider.js";
 import { createCopilotRequestAdapter } from "./copilotRequestHandler.js";
 import { getTraceContext } from "./telemetry.js";
+import { toJsonSchema } from "./schema.js";
 import { ToolSet } from "./toolSet.js";
 import { defaultJoinSessionPermissionHandler } from "./types.js";
 const MIN_PROTOCOL_VERSION = 3;
 const RUNTIME_SHUTDOWN_TIMEOUT_MS = 1e4;
-function isZodSchema(value) {
-  return value != null && typeof value === "object" && "toJSONSchema" in value && typeof value.toJSONSchema === "function";
-}
 async function withTimeout(promise, timeoutMs, message) {
   let timeout;
   try {
@@ -74,13 +72,6 @@ async function waitForChildExit(child, timeoutMs) {
     }
   });
 }
-function toJsonSchema(parameters) {
-  if (!parameters) return void 0;
-  if (isZodSchema(parameters)) {
-    return parameters.toJSONSchema();
-  }
-  return parameters;
-}
 const DEFAULT_PROVIDER_NAME = "default";
 function extractBearerTokenProviders(provider, providers) {
   const callbacks = /* @__PURE__ */ new Map();

package/dist/index.d.ts

@@ -11,5 +11,5 @@ export { defineFactory, FactoryResumeError, isFactoryRunTerminal } from "./facto
 export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasDeclaration, type CanvasHostContext, type CanvasHostContextCapabilities, type CanvasJsonSchema, type CanvasOptions, } from "./canvas.js";
 export { defineTool, approveAll, createAttributedPermissionResult, convertMcpCallToolResult, createSessionFsAdapter, CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, SessionFsSqliteTransactionFailure, SYSTEM_MESSAGE_SECTIONS, } from "./types.js";
 export type * from "./generated/session-events.js";
-export type { AskUserVariant, CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, UserPromptTransformedHandler, UserPromptTransformedHookInput, UserPromptTransformedHookOutput, CopilotClientInfo, CopilotClientMode, CopilotClientOptions, CopilotExpAssignmentResponse, StdioRuntimeConnection, InProcessRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, ChildProcessRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExpConfigEntry, ExpFlagValue, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, GitHubMcpToolConfig, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTokenProvider, GitHubTokenProviderArgs, GitHubTokenProviderResult, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, FactoryLimits, FactoryMeta, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, MessageOptions, MessageSource, ManagedSettings, ManagedSettingsPermissions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, AutoTier, CapiSessionOptions, CurrentModel, ModelSwitchAutoTierResult, ModelSwitchAutoTierStatus, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestedData, PermissionRequestedEvent, PermissionRequestResult, AttributedPermissionResult, PermissionDecisionContext, PermissionDecisionOutcome, PermissionDecisionSource, PermissionDecisionSurface, PermissionResponseCapability, ProviderConfig, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionHooks, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SessionFsSqliteStatement, SessionFsSqliteTransactionErrorClass, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, CurrentToolMetadata, ToolTelemetry, ToolResultObject, ToolSearchConfig, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
+export type { AskUserVariant, CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, UserPromptTransformedHandler, UserPromptTransformedHookInput, UserPromptTransformedHookOutput, CopilotClientInfo, CopilotClientMode, CopilotClientOptions, CopilotExpAssignmentResponse, StdioRuntimeConnection, InProcessRuntimeConnection, TcpRuntimeConnection, UriRuntimeConnection, ChildProcessRuntimeConnection, CustomAgentConfig, ElicitationFieldValue, ElicitationHandler, ElicitationParams, ElicitationContext, ElicitationResult, ElicitationSchema, ElicitationSchemaField, ExpConfigEntry, ExpFlagValue, ExitPlanModeHandler, ExitPlanModeRequest, ExitPlanModeResult, ExtensionInfo, ForegroundSessionInfo, GetAuthStatusResponse, GetStatusResponse, GitHubMcpToolConfig, GitHubTelemetryNotification, GitHubTelemetryEvent, GitHubTelemetryClientInfo, GitHubTokenAcquireReason, GitHubTokenAcquireResult, GitHubTokenProvider, GitHubTokenProviderArgs, GitHubTokenProviderResult, InfiniteSessionConfig, LargeToolOutputConfig, MemoryConfiguration, UiInputOptions, FactoryLimits, FactoryMeta, MCPStdioServerConfig, MCPHTTPServerConfig, MCPServerConfig, DefaultAgentConfig, BearerTokenProvider, MessageOptions, ResponseSchema, MessageSource, ManagedSettings, ManagedSettingsPermissions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, AutoTier, CapiSessionOptions, CurrentModel, ModelSwitchAutoTierResult, ModelSwitchAutoTierStatus, ModelCapabilities, ModelCapabilitiesOverride, ModelInfo, ModelPolicy, NamedProviderConfig, PermissionHandler, PermissionRequest, PermissionRequestedData, PermissionRequestedEvent, PermissionRequestResult, AttributedPermissionResult, PermissionDecisionContext, PermissionDecisionOutcome, PermissionDecisionSource, PermissionDecisionSurface, PermissionResponseCapability, ProviderConfig, ProviderModelConfig, ProviderTokenArgs, RemoteSessionMode, ResumeSessionConfig, SectionOverride, SectionOverrideAction, SectionTransformFn, SessionCapabilities, SessionConfig, SessionConfigBase, SessionEvent, SessionEventHandler, SessionEventPayload, SessionEventType, SessionLifecycleEvent, SessionLifecycleEventMetadata, SessionLifecycleEventType, SessionLifecycleHandler, SessionHooks, SessionCreatedEvent, SessionDeletedEvent, SessionUpdatedEvent, SessionForegroundEvent, SessionBackgroundEvent, SessionContext, SessionListFilter, SessionMetadata, SessionUiApi, SessionFsConfig, SessionFsProvider, SessionFsFileInfo, SessionFsSqliteQueryResult, SessionFsSqliteQueryType, SessionFsSqliteProvider, SessionFsSqliteStatement, SessionFsSqliteTransactionErrorClass, CopilotRequestContext, SystemMessageAppendConfig, SystemMessageConfig, SystemMessageCustomizeConfig, SystemMessageReplaceConfig, SystemMessageSection, TelemetryConfig, TraceContext, TraceContextProvider, Tool, ToolHandler, ToolInvocation, CurrentToolMetadata, ToolTelemetry, ToolResultObject, ToolSearchConfig, TypedSessionEventHandler, TypedSessionLifecycleHandler, ZodSchema, } from "./types.js";
 export type { RunOptions, ResumeOptions, FactoryLimitOverrides, FactoryResumeErrorCode, SessionFactoryApi, FactoryAgentOptions, FactoryContext, FactoryDefinition, FactoryHandle, FactoryJsonSchema, JsonValue, FactoryPipelineStage, FactoryStepOptions, FactoryRunResult, FactoryRunStatus, FactoryRunSummary, FactoryListRunsOptions, FactoryRunsPage, FactoryRunDetail, FactoryProgressPage, FactoryProgressLine, FactoryPhaseObservation, FactoryPhaseStatus, FactoryAgentSummary, } from "./factory.js";

package/dist/schema.d.ts

@@ -0,0 +1,4 @@
+import type { ResponseSchema, ZodSchema } from "./types.js";
+export declare function isZodSchema(value: unknown): value is ZodSchema;
+export declare function toJsonSchema(schema: ZodSchema | Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+export declare function isResponseSchema(value: unknown): value is ResponseSchema;

package/dist/schema.js

@@ -0,0 +1,14 @@
+function isZodSchema(value) {
+  return typeof value === "object" && value !== null && "toJSONSchema" in value && typeof value.toJSONSchema === "function";
+}
+function toJsonSchema(schema) {
+  return isZodSchema(schema) ? schema.toJSONSchema() : schema;
+}
+function isResponseSchema(value) {
+  return isZodSchema(value) && "parse" in value && typeof value.parse === "function";
+}
+export {
+  isResponseSchema,
+  isZodSchema,
+  toJsonSchema
+};

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

@@ -510,6 +510,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)
@@ -2802,6 +2809,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-unstable.35395657398.gad69ee1",
+    "copilotCliVersion": "1.0.86-unstable.r35389812552.g657d1e5",
     "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-unstable.35395657398.gad69ee1",
+        "@github/copilot-sdk-darwin-x64": "1.0.15-unstable.35395657398.gad69ee1",
+        "@github/copilot-sdk-linux-arm64": "1.0.15-unstable.35395657398.gad69ee1",
+        "@github/copilot-sdk-linux-x64": "1.0.15-unstable.35395657398.gad69ee1",
+        "@github/copilot-sdk-linuxmusl-arm64": "1.0.15-unstable.35395657398.gad69ee1",
+        "@github/copilot-sdk-linuxmusl-x64": "1.0.15-unstable.35395657398.gad69ee1",
+        "@github/copilot-sdk-win32-arm64": "1.0.15-unstable.35395657398.gad69ee1",
+        "@github/copilot-sdk-win32-x64": "1.0.15-unstable.35395657398.gad69ee1"
     }
 }