@github/copilot-sdk 1.0.13-preview.2 → 1.0.13-preview.4

package/dist/generated/session-events.d.ts

@@ -10,6 +10,16 @@ export type JsonValue = null | boolean | number | string | JsonValue[] | {
  * Union of all session event variants emitted by the Copilot CLI runtime.
  */
 export type SessionEvent = StartEvent | ResumeEvent | RemoteSteerableChangedEvent | ErrorEvent | IdleEvent | TitleChangedEvent | ScheduleCreatedEvent | ScheduleCancelledEvent | ScheduleRearmedEvent | AutopilotObjectiveChangedEvent | InfoEvent | WarningEvent | ModelChangeEvent | ModeChangedEvent | SessionLimitsChangedEvent | PermissionsChangedEvent | PlanChangedEvent | TodosChangedEvent | WorkspaceFileChangedEvent | HandoffEvent | TruncationEvent | SnapshotRewindEvent | ShutdownEvent | UsageCheckpointEvent | ContextChangedEvent | UsageInfoEvent | ContextClearedEvent | CompactionStartEvent | CompactionCompleteEvent | TaskCompleteEvent | FusionRouteStartedEvent | FusionRouteFailedEvent | FusionResolvedEvent | FusionCompletedEvent | UserMessageEvent | PendingMessagesModifiedEvent | AssistantTurnStartEvent | AssistantIntentEvent | AssistantFusionPhaseStartedEvent | AssistantFusionPhaseCompletedEvent | AssistantFusionPhaseFailedEvent | AssistantServerToolProgressEvent | AssistantReasoningEvent | AssistantReasoningDeltaEvent | AssistantToolCallDeltaEvent | AssistantStreamingDeltaEvent | AssistantMessageEvent | AssistantMessageStartEvent | AssistantMessageDeltaEvent | AssistantTurnEndEvent | AssistantIdleEvent | AssistantUsageEvent | ModelCallFailureEvent | ModelCallFinishedEvent | AbortEvent | ToolUserRequestedEvent | ToolExecutionStartEvent | ToolExecutionPartialResultEvent | ToolExecutionProgressEvent | ToolExecutionCompleteEvent | ToolSearchActivatedEvent | SkillInvokedEvent | SubagentStartedEvent | SubagentConfiguredEvent | SubagentCompletedEvent | SubagentFailedEvent | SubagentSelectedEvent | SubagentDeselectedEvent | HookStartEvent | HookEndEvent | HookProgressEvent | BinaryAssetEvent | SystemMessageEvent | SystemNotificationEvent | PermissionRequestedEvent | PermissionCompletedEvent | UserInputRequestedEvent | UserInputCompletedEvent | ElicitationRequestedEvent | ElicitationCompletedEvent | SamplingRequestedEvent | SamplingCompletedEvent | McpOauthRequiredEvent | McpOauthCompletedEvent | McpHeadersRefreshRequiredEvent | McpHeadersRefreshCompletedEvent | CustomNotificationEvent | UIEphemeralQueryEvent | ExternalToolRequestedEvent | ExternalToolCompletedEvent | CommandQueuedEvent | CommandExecuteEvent | CommandCompletedEvent | AutoModeSwitchRequestedEvent | AutoModeSwitchCompletedEvent | SessionLimitsExhaustedRequestedEvent | SessionLimitsExhaustedCompletedEvent | AutoModeResolvedEvent | ManagedSettingsResolvedEvent | ManagedSettingsEnforcedEvent | CommandsChangedEvent | CapabilitiesChangedEvent | ExitPlanModeRequestedEvent | ExitPlanModeCompletedEvent | ToolsUpdatedEvent | BackgroundTasksChangedEvent | FactoryRunUpdatedEvent | FactoryRunStartedEvent | FactoryRunSettledEvent | SkillsLoadedEvent | CustomAgentsUpdatedEvent | McpServersLoadedEvent | McpServerStatusChangedEvent | McpToolsListChangedEvent | McpResourcesListChangedEvent | McpPromptsListChangedEvent | ExtensionsLoadedEvent | CanvasOpenedEvent | CanvasRegistryChangedEvent | CanvasClosedEvent | CanvasUnavailableEvent | CanvasRecordedEvent | CanvasRemovedEvent | ExtensionsAttachmentsPushedEvent | McpAppToolCallCompleteEvent;
+/**
+ * Routing preference used when the session model is `auto`.
+ */
+export type AutoTier = 
+/** Optimize for efficiency. */
+"efficiency"
+/** Balance efficiency and intelligence. */
+ | "balance"
+/** Optimize for intelligence. */
+ | "intelligence";
 /**
  * Hosting platform type of the repository (github or ado)
  */
@@ -317,6 +327,10 @@ export type CitationProvider =
  */
 /** @experimental */
 export type CitationLocation = CitationLocationChar | CitationLocationPage | CitationLocationBlock;
+/**
+ * Hosted program caller type
+ */
+export type AssistantMessageToolRequestCallerType = "program";
 /**
  * API endpoint used for this model call, matching CAPI supported_endpoints vocabulary
  */
@@ -894,6 +908,7 @@ export interface StartData {
      * Whether the session was already in use by another client at start time
      */
     alreadyInUse?: boolean;
+    autoTier?: AutoTier;
     context?: WorkingDirectoryContext;
     /**
      * Context tier selected at session creation time for models with tiered context pricing; null when no tier is selected (e.g., non-tiered model)
@@ -1046,6 +1061,7 @@ export interface ResumeData {
      * Whether the session was already in use by another client at resume time
      */
     alreadyInUse?: boolean;
+    autoTier?: AutoTier;
     context?: WorkingDirectoryContext;
     /**
      * Context tier currently selected at resume time; null when no tier is active
@@ -4537,6 +4553,7 @@ export interface AssistantMessageToolRequest {
      * Arguments to pass to the tool, format depends on the tool
      */
     arguments?: JsonValue;
+    caller?: AssistantMessageToolRequestCaller;
     /**
      * Resolved intention summary describing what this specific call does
      */
@@ -4563,6 +4580,16 @@ export interface AssistantMessageToolRequest {
     toolTitle?: string;
     type?: AssistantMessageToolRequestType;
 }
+/**
+ * Hosted program that requested this client tool call
+ */
+export interface AssistantMessageToolRequestCaller {
+    /**
+     * Provider-assigned identifier for the hosted caller.
+     */
+    callerId: string;
+    type: AssistantMessageToolRequestCallerType;
+}
 /**
  * Session event "assistant.message_start". Streaming assistant message start metadata
  */
@@ -6553,7 +6580,7 @@ export interface HookStartData {
      */
     hookType: string;
     /**
-     * Input data passed to the hook
+     * Input data passed to the hook. For postToolUse hooks the retained copy served by session.eventLog.read (and by a resumed session) elides the tool result's inline `contents`/`uiResource` and replaces an over-long `textResultForLlm` with a `[copilot:elided ...]` marker, to keep a multi-megabyte payload out of the durable event log; the live subscription stream still delivers the full value. Read the adjacent tool.execution_complete event for the tool result itself.
      */
     input?: JsonValue;
     /**

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 { CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, UserPromptTransformedHandler, UserPromptTransformedHookInput, UserPromptTransformedHookOutput, 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, ManagedSettings, ManagedSettingsPermissions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, CapiSessionOptions, 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, FactoryResumeErrorCode, SessionFactoryApi, FactoryAgentOptions, FactoryContext, FactoryDefinition, FactoryHandle, FactoryJsonSchema, JsonValue, FactoryPipelineStage, FactoryStepOptions, FactoryRunResult, FactoryRunStatus, FactoryRunSummary, FactoryRunDetail, FactoryProgressPage, FactoryProgressLine, FactoryPhaseObservation, FactoryPhaseStatus, FactoryAgentSummary, } from "./factory.js";
+export type { AskUserVariant, CommandContext, CommandDefinition, CommandHandler, CanvasProviderIdentity, CloudSessionOptions, CloudSessionRepository, AutoModeSwitchHandler, AutoModeSwitchRequest, AutoModeSwitchResponse, AgentStopHandler, AgentStopHookInput, AgentStopHookOutput, UserPromptTransformedHandler, UserPromptTransformedHookInput, UserPromptTransformedHookOutput, 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, ManagedSettings, ManagedSettingsPermissions, ModelBilling, ModelBillingTokenPrices, ModelBillingTokenPricesLongContext, CapiSessionOptions, 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, 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/runtimeArtifacts.d.ts

@@ -0,0 +1,6 @@
+export interface RuntimeArtifactSources {
+    packageRoot: string;
+    platform: string;
+}
+export declare function defaultRuntimeCacheRoot(platform?: NodeJS.Platform, home?: string, environment?: NodeJS.ProcessEnv): string;
+export declare function materializeRuntimeBundle(sources: RuntimeArtifactSources, cacheRoot?: string): string;

package/dist/runtimeArtifacts.js

@@ -0,0 +1,145 @@
+import { createHash } from "node:crypto";
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, relative, sep } from "node:path";
+const EXCLUDED_TOP_LEVEL = /* @__PURE__ */ new Set([
+  "app.js",
+  "assets",
+  "changelog.json",
+  "copilot",
+  "copilot.exe",
+  "copilot-sdk",
+  "foundry-local-sdk",
+  "index.js",
+  "LICENSE.md",
+  "napi-oop-runtime",
+  "npm-loader.js",
+  "package.json",
+  "preloads",
+  "pvrecorder",
+  "queries",
+  "README.md",
+  "sdk",
+  "sea-loader.js",
+  "webview"
+]);
+function validateFile(path, label) {
+  if (!existsSync(path)) {
+    throw new Error(`${label} not found at ${path}.`);
+  }
+  if (statSync(path).size === 0) {
+    throw new Error(`${label} at ${path} is empty.`);
+  }
+}
+function validateRuntimeBundle(wrapper, runtimeNode) {
+  validateFile(wrapper, "Copilot runtime wrapper");
+  validateFile(runtimeNode, "Copilot runtime.node");
+}
+function isExcluded(relativePath) {
+  const parts = relativePath.split(sep);
+  const topLevel = parts[0];
+  const fileName = parts.at(-1) ?? "";
+  return EXCLUDED_TOP_LEVEL.has(topLevel) || /^tree-sitter.*\.wasm$/.test(topLevel) || /^voice-.*\.js$/.test(topLevel) || fileName === "cli-native.node" || parts.includes("mediaremote-adapter") || fileName.startsWith("copilot-runtime-bin");
+}
+function collectRuntimeAssets(sources) {
+  const assets = [];
+  const visit = (directory) => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const source = join(directory, entry.name);
+      const sourceRelative = relative(sources.packageRoot, source);
+      if (isExcluded(sourceRelative)) {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        visit(source);
+        continue;
+      }
+      if (!entry.isFile() && !entry.isSymbolicLink()) {
+        continue;
+      }
+      const parts = sourceRelative.split(sep);
+      let relativePath = sourceRelative;
+      if (parts[0] === "prebuilds") {
+        if (parts[1] !== sources.platform || parts.length < 3) {
+          continue;
+        }
+        relativePath = parts.slice(2).join(sep);
+      }
+      assets.push({ source, relativePath });
+    }
+  };
+  visit(sources.packageRoot);
+  return assets.sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+}
+function sourceFingerprint(assets) {
+  const hash = createHash("sha256");
+  for (const asset of assets) {
+    const stat = lstatSync(asset.source);
+    hash.update(asset.relativePath).update("\0");
+    hash.update(`${stat.size}:${stat.mtimeMs}`).update("\0");
+  }
+  return hash.digest("hex").slice(0, 20);
+}
+function makeExecutable(path) {
+  if (process.platform === "win32") {
+    return;
+  }
+  const mode = statSync(path).mode;
+  if ((mode & 73) === 0) {
+    chmodSync(path, mode | 73);
+  }
+}
+function defaultRuntimeCacheRoot(platform = process.platform, home = homedir(), environment = process.env) {
+  const cacheDirectory = platform === "win32" ? environment.LOCALAPPDATA ?? join(home, "AppData", "Local") : platform === "darwin" ? join(home, "Library", "Caches") : environment.XDG_CACHE_HOME ?? join(home, ".cache");
+  return join(cacheDirectory, "github-copilot-sdk", "runtime");
+}
+function materializeRuntimeBundle(sources, cacheRoot = defaultRuntimeCacheRoot()) {
+  const assets = collectRuntimeAssets(sources);
+  const wrapperName = process.platform === "win32" ? "copilot-runtime.exe" : "copilot-runtime";
+  const sourceWrapper = assets.find((asset) => asset.relativePath === wrapperName)?.source;
+  const sourceRuntimeNode = assets.find((asset) => asset.relativePath === "runtime.node")?.source;
+  validateRuntimeBundle(sourceWrapper ?? "", sourceRuntimeNode ?? "");
+  const installDir = join(cacheRoot, `${sources.platform}-${sourceFingerprint(assets)}`);
+  const installedWrapper = join(installDir, wrapperName);
+  const installedRuntimeNode = join(installDir, "runtime.node");
+  if (existsSync(installDir)) {
+    validateRuntimeBundle(installedWrapper, installedRuntimeNode);
+    makeExecutable(installedWrapper);
+    return installedWrapper;
+  }
+  mkdirSync(cacheRoot, { recursive: true });
+  const stagingDir = mkdtempSync(join(cacheRoot, ".runtime-"));
+  try {
+    for (const asset of assets) {
+      const destination = join(stagingDir, asset.relativePath);
+      mkdirSync(dirname(destination), { recursive: true });
+      copyFileSync(asset.source, destination);
+    }
+    const stagedWrapper = join(stagingDir, wrapperName);
+    makeExecutable(stagedWrapper);
+    renameSync(stagingDir, installDir);
+  } catch (error) {
+    if (!existsSync(installDir)) {
+      throw error;
+    }
+    validateRuntimeBundle(installedWrapper, installedRuntimeNode);
+  } finally {
+    rmSync(stagingDir, { recursive: true, force: true });
+  }
+  return installedWrapper;
+}
+export {
+  defaultRuntimeCacheRoot,
+  materializeRuntimeBundle
+};

package/dist/session.js

@@ -265,14 +265,18 @@ class CopilotSession {
       const name = typeof nameOrHandle === "string" ? nameOrHandle : getFactoryDefinition(nameOrHandle).meta.name;
       if (options?.resumeFromRunId !== void 0) {
         return this.factory.resume(options.resumeFromRunId, {
-          limits: options.limits
+          limits: options.limits,
+          notifyOnComplete: options.notifyOnComplete,
+          logPhaseNames: options.logPhaseNames
         });
       }
       const envelope = await this.rpc.factory.run({
         name,
         args: options?.args === void 0 ? {} : options.args,
         options: {
-          limits: options?.limits
+          limits: options?.limits,
+          notifyOnComplete: options?.notifyOnComplete,
+          logPhaseNames: options?.logPhaseNames
         }
       });
       return this.settleFactoryRun(envelope);
@@ -283,7 +287,9 @@ class CopilotSession {
       try {
         response = await this.rpc.factory.resume({
           runId,
-          limits: options?.limits
+          limits: options?.limits,
+          notifyOnComplete: options?.notifyOnComplete,
+          logPhaseNames: options?.logPhaseNames
         });
       } catch (error) {
         if (error instanceof ResponseError && typeof error.data === "object" && error.data !== null) {
@@ -298,7 +304,10 @@ class CopilotSession {
     }),
     getRun: async (runId) => this.rpc.factory.getRun({ runId }),
     waitForRun: (runId, options) => this.waitForFactoryRun(runId, options?.signal),
-    listRuns: async () => (await this.rpc.factory.listRuns({})).runs,
+    listRuns: (async (options) => {
+      const page = await this.rpc.factory.listRuns(options ?? {});
+      return options === void 0 ? page.runs : page;
+    }),
     getRunDetail: (runId) => this.rpc.factory.getRunDetail({ runId }),
     getRunProgress: (runId, options = {}) => this.rpc.factory.getRunProgress({ runId, ...options }),
     cancel: async (runId) => this.rpc.factory.cancel({ runId })

package/dist/types.d.ts

@@ -943,7 +943,7 @@ export type PermissionHandler = (request: PermissionRequest, invocation: {
 export declare const approveAll: PermissionHandler;
 export declare const defaultJoinSessionPermissionHandler: PermissionHandler;
 /**
- * Request for user input from the agent (enables ask_user tool)
+ * Legacy question-and-answer request from the `ask_user` tool.
  */
 export interface UserInputRequest {
     /**
@@ -1813,6 +1813,8 @@ export interface ManagedSettings {
     /** Managed permission policy for the session. */
     permissions?: ManagedSettingsPermissions;
 }
+/** Selects the model-facing shape of the built-in `ask_user` tool. */
+export type AskUserVariant = "legacy" | "elicitation";
 /**
  * Shared configuration fields used by both {@link SessionConfig} (for
  * creating a new session) and {@link ResumeSessionConfig} (for resuming
@@ -2085,9 +2087,18 @@ export interface SessionConfigBase {
     onMcpAuthRequest?: McpAuthHandler;
     /**
      * Handler for user input requests from the agent.
-     * When provided, enables the ask_user tool allowing the agent to ask questions.
+     * When provided with the default `legacy` {@link AskUserVariant}, enables the
+     * question-and-answer form of the `ask_user` tool.
      */
     onUserInputRequest?: UserInputHandler;
+    /**
+     * Selects the model-facing shape of the built-in `ask_user` tool.
+     *
+     * The default is `"legacy"`. To use `"elicitation"`, also provide
+     * {@link onElicitationRequest} so the host can answer structured forms.
+     * The runtime resolves this option when it creates or cold-resumes the session.
+     */
+    askUserVariant?: AskUserVariant;
     /**
      * Handler for elicitation requests from the agent.
      * When provided, the server calls back to this client for form-based UI dialogs.

package/docs/factories.md

@@ -139,6 +139,8 @@ Run by registered name or handle:
 const run = await session.factory.run("review-changed", {
     args: { files: ["src/a.ts"] },
     limits: { maxAiCredits: 3 },
+    notifyOnComplete: true,
+    logPhaseNames: true,
 });
 
 if (run.status === "completed") {
@@ -153,7 +155,12 @@ The name overload is:
 ```ts
 session.factory.run(
     name: string,
-    options?: { args?: JsonValue; limits?: FactoryLimits },
+    options?: {
+        args?: JsonValue;
+        limits?: FactoryLimits;
+        notifyOnComplete?: boolean;
+        logPhaseNames?: boolean;
+    },
 ): Promise<FactoryRunResult>;
 ```
 
@@ -162,6 +169,8 @@ Resume by run ID without resending the name or arguments:
 ```ts
 const run = await session.factory.resume(runId, {
     limits: { maxAiCredits: 6 },
+    notifyOnComplete: true,
+    logPhaseNames: true,
 });
 ```
 
@@ -170,10 +179,16 @@ The signature is:
 ```ts
 session.factory.resume(
     runId: string,
-    options?: { limits?: FactoryLimits },
+    options?: {
+        limits?: FactoryLimits;
+        notifyOnComplete?: boolean;
+        logPhaseNames?: boolean;
+    },
 ): Promise<FactoryRunResult>;
 ```
 
+Set `notifyOnComplete` to `true` for factories that are likely to be invoked by an agent, so the originating session is notified when the factory completes. Set it to `false` for factories intended to be invoked programmatically, where the caller awaits the result directly. Set `logPhaseNames` to emit factory phase names to the session transcript. Both options apply to new and resumed runs.
+
 Both resolve with the run envelope (`FactoryRunResult`) for **every** outcome — `completed`, `error`, `halted`, and `cancelled` alike. Inspect `status` and read `result` only when the run completed; a limit breach carries a typed `failure`. SDK-initiated `run` and `resume` do not request permission, so they have no declined outcome. The model's `run_factory` tool requests permission before the durable row exists; declining it creates no run row. An SDK-initiated run is refused only when the session already has its maximum number of active top-level runs. Pre-execution resume failures throw `FactoryResumeError`, whose `code` is one of `not_found`, `non_resumable`, `already_active`, `factory_already_running`, `factory_limits_invalid`, `factory_session_disposed`, `factory_storage_unavailable`, or `factory_storage_corrupt`.
 
 An agent that no longer has a prior run's ID in context can recover it with `factories_manage` and `operation: "runs"`, which lists the session's factory runs with their IDs and statuses. This matters for resume: a run that reached a limit keeps its journal, so resuming it replays completed work for free, while restarting it from scratch pays for that work twice.
@@ -219,8 +234,13 @@ The calling session can inspect its own factory runs:
 
 ```ts
 const runs = await session.factory.listRuns();
+const runsPage = await session.factory.listRuns({
+    afterSeq,
+    beforeSeq,
+    limit,
+});
 const detail = await session.factory.getRunDetail(runId);
-const page = await session.factory.getRunProgress(runId, {
+const progressPage = await session.factory.getRunProgress(runId, {
     phaseId,
     afterSeq,
     beforeSeq,
@@ -228,7 +248,8 @@ const page = await session.factory.getRunProgress(runId, {
 });
 ```
 
-- `listRuns()` returns the newest default page of this session's durable factory runs.
+- `listRuns()` returns only the runs array from the newest default page of this session's durable factory runs. This overload preserves the original convenience API.
+- `listRuns({ afterSeq, beforeSeq, limit })` returns the full page. Its `oldestSeq`, `newestSeq`, `hasMoreNewer`, and `omittedOlder` fields let callers continue paging without raw RPC calls.
 - `getRunDetail(runId)` returns phases, prompt-safe agent summaries, and the latest progress page.
 - `getRunProgress(runId, options?)` pages progress forward, backward, by phase, or from the latest tail.
 

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/github/copilot-sdk.git"
   },
-  "version": "1.0.13-preview.2",
+  "version": "1.0.13-preview.4",
   "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
   "main": "./dist/cjs/index.js",
   "types": "./dist/index.d.ts",
@@ -56,7 +56,7 @@
   "author": "GitHub",
   "license": "MIT",
   "dependencies": {
-    "@github/copilot": "^1.0.82-0",
+    "@github/copilot": "^1.0.83-0",
     "koffi": "^3.1.0",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.6"