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

package/README.md

@@ -140,7 +140,8 @@ Create a new conversation session.
 - `gitHubTokenProvider?: GitHubTokenProvider` - Acquires rotating, session-scoped GitHub tokens. Token results require a positive `expiresIn` value in seconds remaining when the callback completes; production tokens typically last eight hours. Cannot be combined with `gitHubToken`.
 - `provider?: ProviderConfig` - Custom API provider configuration (BYOK - Bring Your Own Key). See [Custom Providers](#custom-providers) section.
 - `onPermissionRequest?: PermissionHandler` - Optional handler called before each tool execution to approve or deny it. When omitted, permission requests are emitted as events and left pending for manual resolution. `approveAll` approves requests when managed settings are disabled and throws when `enableManagedSettings` is true. Custom handlers can inspect `managedApprovalRequired` for human-facing confirmation logic. See [Permission Handling](#permission-handling) section.
-- `onUserInputRequest?: UserInputHandler` - Handler for user input requests from the agent. Enables the `ask_user` tool. See [User Input Requests](#user-input-requests) section.
+- `onUserInputRequest?: UserInputHandler` - Handler for legacy question-and-answer requests from the agent. Enables the legacy `ask_user` tool. See [User Input Requests](#user-input-requests) section.
+- `askUserVariant?: "legacy" | "elicitation"` - Selects the model-facing `ask_user` tool shape when creating or cold-resuming a session. Defaults to `"legacy"`; use `"elicitation"` with `onElicitationRequest`.
 - `onElicitationRequest?: ElicitationHandler` - Handler for elicitation requests dispatched by the server. Enables this client to present form-based UI dialogs on behalf of the agent or other session participants. See [Elicitation Requests](#elicitation-requests) section.
 - `hooks?: SessionHooks` - Hook handlers for session lifecycle events. See [Session Hooks](#session-hooks) section.
 
@@ -959,7 +960,7 @@ To let a specific custom tool bypass the permission prompt entirely, set `skipPe
 
 ## User Input Requests
 
-Enable the agent to ask questions to the user using the `ask_user` tool by providing an `onUserInputRequest` handler:
+Enable the legacy question-and-answer `ask_user` tool by providing an `onUserInputRequest` handler:
 
 ```typescript
 const session = await client.createSession({
@@ -991,6 +992,7 @@ Register an `onElicitationRequest` handler to let your client act as an elicitat
 const session = await client.createSession({
     model: "gpt-5",
     onPermissionRequest: approveAll,
+    askUserVariant: "elicitation",
     onElicitationRequest: async (context) => {
         // context.sessionId - Session that triggered the request
         // context.message - Description of what information is needed
@@ -1012,6 +1014,9 @@ const session = await client.createSession({
 console.log(session.capabilities.ui?.elicitation); // true
 ```
 
+Set `askUserVariant: "elicitation"` to expose the structured form as the model's
+`ask_user` tool. Omit it to retain the legacy SDK behavior.
+
 When `onElicitationRequest` is provided, the SDK sends `requestElicitation: true` during session create/resume, which enables `session.capabilities.ui.elicitation` on the session.
 
 In multi-client scenarios:

package/dist/cjs/client.js

@@ -1208,6 +1208,7 @@ class CopilotClient {
         requestPermission: !!config.onPermissionRequest,
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
+        askUserVariant: config.askUserVariant,
         ...config.enableMcpApps ? { requestMcpApps: true } : {},
         ...config.githubMcpToolConfig != null ? { githubMcpToolConfig: config.githubMcpToolConfig } : {},
         requestExitPlanMode: !!config.onExitPlanModeRequest,
@@ -1440,6 +1441,7 @@ class CopilotClient {
         requestPermission: config.onPermissionRequest !== import_types.defaultJoinSessionPermissionHandler,
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
+        askUserVariant: config.askUserVariant,
         ...config.enableMcpApps ? { requestMcpApps: true } : {},
         ...config.githubMcpToolConfig != null ? { githubMcpToolConfig: config.githubMcpToolConfig } : {},
         requestExitPlanMode: !!config.onExitPlanModeRequest,

package/dist/cjs/generated/rpc.js

@@ -200,7 +200,7 @@ function createServerRpc(connection) {
       disable: async (params) => connection.sendRequest("extensions.disable", params)
     },
     /**
-     * Registers the calling SDK client as the per-entrypoint extension launch provider. Call before creating any sessions. When omitted, the runtime temporarily falls back to its built-in Node launcher for backward compatibility.
+     * Registers the calling SDK client as the per-entrypoint extension launch provider. Call before creating any sessions. When omitted, the runtime uses its built-in extension launcher.
      *
      * @experimental
      */
@@ -773,6 +773,15 @@ function createSessionRpc(connection, sessionId) {
      * @experimental
      */
     sendMessages: async (params) => connection.sendRequest("session.sendMessages", { sessionId, ...params }),
+    /** @experimental */
+    sandbox: {
+      /**
+       * Returns whether managed policy requires sandbox enforcement and whether an enforcement failure has permanently blocked the session.
+       *
+       * @returns Managed sandbox enforcement state for a session.
+       */
+      getEnforcementStatus: async () => connection.sendRequest("session.sandbox.getEnforcementStatus", { sessionId })
+    },
     /**
      * Aborts the current agent turn.
      *

package/dist/cjs/session.js

@@ -283,14 +283,18 @@ class CopilotSession {
       const name = typeof nameOrHandle === "string" ? nameOrHandle : (0, import_factory.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);
@@ -301,7 +305,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 import_node.ResponseError && typeof error.data === "object" && error.data !== null) {
@@ -316,7 +322,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/client.js

@@ -1185,6 +1185,7 @@ class CopilotClient {
         requestPermission: !!config.onPermissionRequest,
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
+        askUserVariant: config.askUserVariant,
         ...config.enableMcpApps ? { requestMcpApps: true } : {},
         ...config.githubMcpToolConfig != null ? { githubMcpToolConfig: config.githubMcpToolConfig } : {},
         requestExitPlanMode: !!config.onExitPlanModeRequest,
@@ -1417,6 +1418,7 @@ class CopilotClient {
         requestPermission: config.onPermissionRequest !== defaultJoinSessionPermissionHandler,
         requestUserInput: !!config.onUserInputRequest,
         requestElicitation: !!config.onElicitationRequest,
+        askUserVariant: config.askUserVariant,
         ...config.enableMcpApps ? { requestMcpApps: true } : {},
         ...config.githubMcpToolConfig != null ? { githubMcpToolConfig: config.githubMcpToolConfig } : {},
         requestExitPlanMode: !!config.onExitPlanModeRequest,

package/dist/extension.d.ts

@@ -42,7 +42,7 @@ export type JoinSessionConfig = Omit<ResumeSessionConfig, "onPermissionRequest"
     factories?: FactoryHandle[];
 };
 export type { ExtensionInfo, FactoryLimits, FactoryMeta } from "./types.js";
-export { defineFactory, FactoryResumeError, isFactoryRunTerminal, type RunOptions, type ResumeOptions, type FactoryResumeErrorCode, type SessionFactoryApi, type FactoryAgentOptions, type FactoryContext, type FactoryDefinition, type FactoryHandle, type FactoryJsonSchema, type JsonValue, type FactoryPipelineStage, type FactoryStepOptions, type FactoryRunResult, type FactoryRunStatus, type FactoryRunSummary, type FactoryRunDetail, type FactoryProgressPage, type FactoryProgressLine, type FactoryPhaseObservation, type FactoryPhaseStatus, type FactoryAgentSummary, } from "./factory.js";
+export { defineFactory, FactoryResumeError, isFactoryRunTerminal, type RunOptions, type ResumeOptions, type FactoryResumeErrorCode, type SessionFactoryApi, type FactoryAgentOptions, type FactoryContext, type FactoryDefinition, type FactoryHandle, type FactoryJsonSchema, type JsonValue, type FactoryPipelineStage, type FactoryStepOptions, type FactoryRunResult, type FactoryRunStatus, type FactoryRunSummary, type FactoryListRunsOptions, type FactoryRunsPage, type FactoryRunDetail, type FactoryProgressPage, type FactoryProgressLine, type FactoryPhaseObservation, type FactoryPhaseStatus, type FactoryAgentSummary, } from "./factory.js";
 /**
  * Joins the current foreground session.
  *

package/dist/factory.d.ts

@@ -1,9 +1,23 @@
-import type { FactoryGetRunProgressRequest, FactoryProgressPage, FactoryRunDetail, FactoryRunResult, FactoryRunStatus, FactoryRunSummary } from "./generated/rpc.js";
+import type { FactoryGetRunProgressRequest, FactoryListRunsRequest, FactoryListRunsResult, FactoryProgressPage, FactoryRunDetail, FactoryRunResult, FactoryRunStatus, FactoryRunSummary } from "./generated/rpc.js";
 import type { ContextTier } from "./generated/session-events.js";
 import type { CopilotSession } from "./session.js";
 import type { FactoryLimits, FactoryMeta } from "./types.js";
 export type { FactoryRunResult };
 export type { FactoryAgentSummary, FactoryPhaseStatus, FactoryPhaseObservation, FactoryProgressLine, FactoryProgressPage, FactoryRunDetail, FactoryRunStatus, FactoryRunSummary, } from "./generated/rpc.js";
+/**
+ * Options for paging durable factory runs.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export type FactoryListRunsOptions = FactoryListRunsRequest;
+/**
+ * A page of durable factory runs and its paging metadata.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export type FactoryRunsPage = FactoryListRunsResult;
 /**
  * Whether a factory run status is terminal.
  *
@@ -165,6 +179,10 @@ export interface RunOptions<TArgs extends JsonValue = JsonValue> {
     args?: TArgs;
     /** Optional per-invocation resource ceiling overrides. */
     limits?: FactoryLimits;
+    /** Whether to notify the originating session when the factory completes. */
+    notifyOnComplete?: boolean;
+    /** Whether to emit factory phase names to the session transcript. */
+    logPhaseNames?: boolean;
     /**
      * Prior run whose persisted identity, arguments, journal, and accounting should be resumed.
      *
@@ -181,6 +199,10 @@ export interface RunOptions<TArgs extends JsonValue = JsonValue> {
 export interface ResumeOptions {
     /** Optional per-invocation resource ceiling overrides. */
     limits?: FactoryLimits;
+    /** Whether to notify the originating session when the factory completes. */
+    notifyOnComplete?: boolean;
+    /** Whether to emit factory phase names to the session transcript. */
+    logPhaseNames?: boolean;
 }
 /**
  * Machine-readable pre-execution factory resume failure.
@@ -239,8 +261,20 @@ export interface SessionFactoryApi {
     }): Promise<FactoryRunResult>;
     /**
      * List the newest default page of this session's durable factory runs.
+     *
+     * This backwards-compatible overload returns only the runs array. Pass
+     * paging options to receive the full page, including its cursors and
+     * truncation metadata.
      */
     listRuns(): Promise<FactoryRunSummary[]>;
+    /**
+     * Page this session's durable factory runs.
+     *
+     * `afterSeq` and `beforeSeq` are exclusive cursors. The result includes
+     * `oldestSeq`, `newestSeq`, `hasMoreNewer`, and `omittedOlder` so callers
+     * can continue paging without using the raw RPC client.
+     */
+    listRuns(options: FactoryListRunsOptions): Promise<FactoryRunsPage>;
     /** Read durable phases, direct agents, and the latest progress tail for a run. */
     getRunDetail(runId: string): Promise<FactoryRunDetail>;
     /** Page durable progress forward, backward, or from the latest tail. */

package/dist/generated/rpc.d.ts

@@ -3,7 +3,7 @@
  * Generated from: api.schema.json
  */
 import type { MessageConnection } from "vscode-jsonrpc/node.js";
-import type { AbortReason, Attachment, ContextTier, EmbeddedBlobResourceContents, EmbeddedTextResourceContents, McpOauthHttpResponse, McpOauthWWWAuthenticateParams, McpServerSource, McpServerStatus, ModelChangeSource, PermissionMode, PermissionPromptRequest, PermissionRule, ReasoningSummary, SessionEvent, SessionLimitsConfig, SessionMode, ShutdownType, SkillSource, TaskCompleteData, TaskCompletionOutcome, UserToolSessionApproval, Verbosity } from "./session-events.js";
+import type { AbortReason, Attachment, AutoTier, ContextTier, EmbeddedBlobResourceContents, EmbeddedTextResourceContents, McpOauthHttpResponse, McpOauthWWWAuthenticateParams, McpServerSource, McpServerStatus, ModelChangeSource, PermissionMode, PermissionPromptRequest, PermissionRule, ReasoningSummary, SessionEvent, SessionLimitsConfig, SessionMode, ShutdownType, SkillSource, TaskCompleteData, TaskCompletionOutcome, UserToolSessionApproval, Verbosity } from "./session-events.js";
 /** A value that can be represented losslessly on the SDK JSON wire. */
 export type JsonValue = null | boolean | number | string | JsonValue[] | {
     [key: string]: JsonValue;
@@ -5180,6 +5180,7 @@ export interface CanvasProviderUnregisterRequest {
  */
 /** @experimental */
 export interface CapiSessionOptions {
+    autoTier?: AutoTier;
     /**
      * Whether to use WebSocket transport for the CAPI Responses API. Enabled by default when the model advertises `ws:/responses` support; set to `false` to force the HTTP Responses transport in environments where WebSockets are blocked (e.g. behind a proxy). Setting this to `false` is equivalent to the `COPILOT_CLI_DISABLE_WEBSOCKET_RESPONSES` environment variable.
      */
@@ -6463,6 +6464,10 @@ export interface EnqueueCommandParams {
      * Slash-prefixed command string to enqueue, e.g. '/compact' or '/model gpt-4'. Queued FIFO with any in-flight items; if the session is idle, processing kicks off immediately.
      */
     command: string;
+    /**
+     * Optional user-facing text for the queue row. The command string is shown when omitted.
+     */
+    displayText?: string | null;
 }
 /**
  * Indicates whether the command was accepted into the local execution queue.
@@ -15877,6 +15882,27 @@ export interface SandboxConfigAuth {
      */
     gh?: boolean;
 }
+/**
+ * Managed sandbox enforcement state for a session.
+ *
+ * This interface was referenced by `_RpcSchemaRoot`'s JSON-Schema
+ * via the `definition` "SandboxEnforcementStatus".
+ */
+/** @experimental */
+export interface SandboxEnforcementStatus {
+    /**
+     * Whether the effective managed policy requires an available sandbox backend.
+     */
+    required: boolean;
+    /**
+     * Whether an enforcement failure has permanently blocked the session.
+     */
+    blocked: boolean;
+    /**
+     * The first sandbox enforcement failure that blocked the session.
+     */
+    reason?: string;
+}
 /**
  * Register an absolute-time scheduled prompt.
  *
@@ -22160,7 +22186,7 @@ export declare function createServerRpc(connection: MessageConnection): {
         disable: (params: DiscoveredExtensionsDisableRequest) => Promise<void>;
     };
     /**
-     * Registers the calling SDK client as the per-entrypoint extension launch provider. Call before creating any sessions. When omitted, the runtime temporarily falls back to its built-in Node launcher for backward compatibility.
+     * Registers the calling SDK client as the per-entrypoint extension launch provider. Call before creating any sessions. When omitted, the runtime uses its built-in extension launcher.
      *
      * @experimental
      */
@@ -22655,6 +22681,15 @@ export declare function createSessionRpc(connection: MessageConnection, sessionI
      * @experimental
      */
     sendMessages: (params: SendMessagesRequest) => Promise<SendMessagesResult>;
+    /** @experimental */
+    sandbox: {
+        /**
+         * Returns whether managed policy requires sandbox enforcement and whether an enforcement failure has permanently blocked the session.
+         *
+         * @returns Managed sandbox enforcement state for a session.
+         */
+        getEnforcementStatus: () => Promise<SandboxEnforcementStatus>;
+    };
     /**
      * Aborts the current agent turn.
      *

package/dist/generated/rpc.js

@@ -172,7 +172,7 @@ function createServerRpc(connection) {
       disable: async (params) => connection.sendRequest("extensions.disable", params)
     },
     /**
-     * Registers the calling SDK client as the per-entrypoint extension launch provider. Call before creating any sessions. When omitted, the runtime temporarily falls back to its built-in Node launcher for backward compatibility.
+     * Registers the calling SDK client as the per-entrypoint extension launch provider. Call before creating any sessions. When omitted, the runtime uses its built-in extension launcher.
      *
      * @experimental
      */
@@ -745,6 +745,15 @@ function createSessionRpc(connection, sessionId) {
      * @experimental
      */
     sendMessages: async (params) => connection.sendRequest("session.sendMessages", { sessionId, ...params }),
+    /** @experimental */
+    sandbox: {
+      /**
+       * Returns whether managed policy requires sandbox enforcement and whether an enforcement failure has permanently blocked the session.
+       *
+       * @returns Managed sandbox enforcement state for a session.
+       */
+      getEnforcementStatus: async () => connection.sendRequest("session.sandbox.getEnforcementStatus", { sessionId })
+    },
     /**
      * Aborts the current agent turn.
      *

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/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.3",
   "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"