@github/copilot-sdk 1.0.14-preview.0 → 1.0.14-unstable.35049111350.g7f86a90

package/dist/generated/rpc.js

@@ -732,15 +732,7 @@ function createInternalServerRpc(connection) {
        */
       getBoardEntryCount: async (params) => connection.sendRequest("sessions.getBoardEntryCount", params),
       /**
-       * Registers extension-provided tools on the given session, gated by an optional `enabled` callback. Returns an opaque unsubscribe function the caller must invoke to deregister the tools when the extension is torn down. Marked internal because `loader`, `enabled`, and the returned `unsubscribe` are in-process handles that cannot cross the JSON-RPC boundary. Disappears once extension discovery / launch / tool registration are owned by the runtime: SDK consumers will pass pure config (search paths, disabled ids) via `SessionOptions` and the runtime will resolve, launch, register, and tear down extensions itself.
-       *
-       * @param params Params to attach an extension loader's tools to a session.
-       *
-       * @returns Handle for releasing the extension tool registration.
-       */
-      registerExtensionToolsOnSession: async (params) => connection.sendRequest("sessions.registerExtensionToolsOnSession", params),
-      /**
-       * Attaches (or detaches) an in-process ExtensionController delegate for the given session, used by shared-API surfaces that need to query or modify the session's extension state. Pass `controller: undefined` to detach. Marked internal because the controller is an in-process object that cannot cross the JSON-RPC boundary. Disappears alongside `registerExtensionToolsOnSession`: once the runtime owns extension management, the public surface exposes list/enable/disable/reload as dedicated RPCs served by the runtime.
+       * Attaches (or detaches) an in-process ExtensionController delegate for the given session in a local host adapter. Pass `controller: undefined` to detach. Internal because the controller cannot cross the JSON-RPC boundary; the runtime manages its own session extension service.
        *
        * @param params Params to attach or detach an in-process ExtensionController delegate.
        */
@@ -849,11 +841,11 @@ function createSessionRpc(connection, sessionId) {
     /** @experimental */
     debug: {
       /**
-       * Collects a redacted session debug log bundle into a local archive or staging directory. The runtime includes session-owned logs by default and accepts caller-provided diagnostic entries so host applications can add their own files without changing this API shape.
+       * Collects a session debug log bundle into a local archive or staging directory. Logs are redacted by default; redaction can be configured per caller-provided diagnostic entry. The runtime includes session-owned logs by default and accepts caller-provided diagnostic entries so host applications can add their own files without changing this API shape.
        *
-       * @param params Options for collecting a redacted session debug bundle.
+       * @param params Options for collecting a session debug bundle with configurable redaction.
        *
-       * @returns Result of collecting a redacted debug bundle.
+       * @returns Result of collecting a session debug bundle.
        */
       collectLogs: async (params) => connection.sendRequest("session.debug.collectLogs", { sessionId, ...params })
     },
@@ -1163,6 +1155,32 @@ function createSessionRpc(connection, sessionId) {
        * @param params Relative path and UTF-8 content for the workspace file to create or overwrite.
        */
       createFile: async (params) => connection.sendRequest("session.workspaces.createFile", { sessionId, ...params }),
+      /**
+       * Returns metadata for a file or directory in the session workspace files directory.
+       *
+       * @param params Relative path of the workspace file or directory to inspect.
+       *
+       * @returns Filesystem metadata for a path in the session workspace files directory.
+       */
+      statFile: async (params) => connection.sendRequest("session.workspaces.statFile", { sessionId, ...params }),
+      /**
+       * Creates a directory in the session workspace files directory.
+       *
+       * @param params Directory to create within the session workspace files directory.
+       */
+      createDirectory: async (params) => connection.sendRequest("session.workspaces.createDirectory", { sessionId, ...params }),
+      /**
+       * Removes a file or directory from the session workspace files directory.
+       *
+       * @param params File or directory to remove from the session workspace files directory.
+       */
+      removePath: async (params) => connection.sendRequest("session.workspaces.removePath", { sessionId, ...params }),
+      /**
+       * Renames a file or directory within the session workspace files directory.
+       *
+       * @param params Source and destination paths for a rename within the session workspace files directory.
+       */
+      renamePath: async (params) => connection.sendRequest("session.workspaces.renamePath", { sessionId, ...params }),
       /**
        * Lists workspace checkpoints in chronological order.
        *

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

@@ -482,6 +482,20 @@ export type AbortReason =
  | "user_abort"
 /** Autopilot stopped the run because the active objective reached its user-set --max-ai-credits limit. */
  | "autopilot_credit_limit";
+/**
+ * Configuration source: user, workspace, plugin, builtin, or managed
+ */
+export type McpServerSource = 
+/** Server configured in the user's global MCP configuration. */
+"user"
+/** Server configured by the current workspace. */
+ | "workspace"
+/** Server contributed by an installed plugin. */
+ | "plugin"
+/** Server bundled with the runtime. */
+ | "builtin"
+/** Server supplied by a trusted host-managed catalog. */
+ | "managed";
 /**
  * Transport mechanism: stdio, http, sse (deprecated), or memory (in-process MCP server)
  */
@@ -565,18 +579,6 @@ export type SkillInvokedTrigger =
  | "agent-invoked"
 /** Skill content loaded as part of another context, such as a configured custom agent or subagent. */
  | "context-load";
-/**
- * Where the model input for a task-tool sub-agent came from.
- */
-export type SubagentTaskModelSource = 
-/** The spawning agent supplied the task tool's model argument. */
-"task_argument"
-/** The task omitted a model and the per-sub-agent settings entry supplied a concrete one. */
- | "subagent_configuration"
-/** The task omitted a model and the user-defined custom agent's definition supplied one. */
- | "custom_agent_definition"
-/** Neither the task call, the per-sub-agent settings entry, nor a custom agent definition supplied a model. */
- | "unset";
 /**
  * Authority or runtime mechanism responsible for sub-agent model selection.
  */
@@ -595,6 +597,18 @@ export type SubagentModelSelectionSource =
  | "agent_definition_default"
 /** Runtime policy, Auto mode, or an experiment selected the model. */
  | "runtime_policy";
+/**
+ * Where the model input for a task-tool sub-agent came from.
+ */
+export type SubagentTaskModelSource = 
+/** The spawning agent supplied the task tool's model argument. */
+"task_argument"
+/** The task omitted a model and the per-sub-agent settings entry supplied a concrete one. */
+ | "subagent_configuration"
+/** The task omitted a model and the user-defined custom agent's definition supplied one. */
+ | "custom_agent_definition"
+/** Neither the task call, the per-sub-agent settings entry, nor a custom agent definition supplied a model. */
+ | "unset";
 /**
  * Binary asset type discriminator. Use "image" for images and "resource" otherwise.
  */
@@ -831,6 +845,8 @@ export type McpHeadersRefreshCompletedOutcome =
 "headers"
 /** The host responded with no dynamic headers. */
  | "none"
+/** The host credential broker rejected or failed the refresh. */
+ | "error"
 /** No response arrived within the bounded window. */
  | "timeout";
 /**
@@ -976,18 +992,6 @@ export type AgentModelPolicy =
 "preferred"
 /** Require subagent execution to use one of the authored models. */
  | "required";
-/**
- * Configuration source: user, workspace, plugin, or builtin
- */
-export type McpServerSource = 
-/** Server configured in the user's global MCP configuration. */
-"user"
-/** Server configured by the current workspace. */
- | "workspace"
-/** Server contributed by an installed plugin. */
- | "plugin"
-/** Server bundled with the runtime. */
- | "builtin";
 /**
  * Connection status: connected, failed, needs-auth, pending, disabled, stopped, or not_configured
  */
@@ -4745,6 +4749,10 @@ export interface AssistantMessageData {
      * Model that produced this assistant message, if known
      */
     model?: string;
+    /**
+     * Logical ID of the primary user message that initiated this run, matching the messageId returned by session.send (or the last messageId of session.sendMessages). Stable across model/tool iterations, steering messages, and stop-hook corrections. Subagent runs use their own initiating message ID, not the parent's. Absent for runs without an associated initiating message, such as empty batches.
+     */
+    originatingMessageId?: string;
     /**
      * Actual output token count from the API response (completion_tokens), used for accurate token accounting
      */
@@ -5764,6 +5772,11 @@ export interface ToolExecutionStartData {
      * @experimental
      */
     fusion?: FusionAttribution;
+    /**
+     * Preferred lookup name for the MCP server hosting this tool: the configured (namespaced) config-map key when the tool carries one, otherwise the display name from `mcpServerName`. Present when the tool is an MCP tool; this is the name unrestricted provenance telemetry hashes so it joins with `mcp_server_setup`, which keys off the configured name too.
+     */
+    mcpConfigServerName?: string;
+    mcpConfigSource?: McpServerSource;
     /**
      * Name of the MCP server hosting this tool, when the tool is an MCP tool
      */
@@ -6012,6 +6025,12 @@ export interface ToolExecutionCompleteData {
      * Whether this tool execution ran inside a sandbox container
      */
     sandboxed?: boolean;
+    /**
+     * Experimental shell completion facts captured before the persisted result contents are stripped.
+     *
+     * @experimental
+     */
+    shellExecution?: ToolExecutionCompleteShellExecution;
     /**
      * Whether the tool execution completed successfully
      */
@@ -6071,7 +6090,7 @@ export interface ToolExecutionCompleteResult {
      */
     contents?: ToolExecutionCompleteContent[];
     /**
-     * Full detailed tool result for UI/timeline display, preserving complete content such as diffs. Falls back to content when absent.
+     * Detailed tool result for UI/timeline display, preserving complete content such as diffs for most tools. Successful skill invocations intentionally use the concise model-facing content here; the authoritative skill body is carried by the corresponding skill invocation event. Falls back to content when absent.
      */
     detailedContent?: string;
     /**
@@ -6485,6 +6504,16 @@ export interface ToolExecutionCompleteUIResourceMetaUIPermissionsGeolocation {
  */
 export interface ToolExecutionCompleteUIResourceMetaUIPermissionsMicrophone {
 }
+/**
+ * Experimental shell completion facts retained independently of the full tool result.
+ */
+/** @experimental */
+export interface ToolExecutionCompleteShellExecution {
+    /**
+     * Process exit code reported by the shell driver.
+     */
+    exitCode: number;
+}
 /**
  * Tool definition metadata, present for MCP tools with MCP Apps support
  */
@@ -6699,6 +6728,7 @@ export interface SubagentStartedData {
      * Model the sub-agent will run with, when known at start.
      */
     model?: string;
+    modelSelectionSource?: SubagentModelSelectionSource;
     /**
      * Task-registry ID of the spawning sub-agent. Absent when the root session spawned this child.
      */
@@ -7073,7 +7103,7 @@ export interface HookStartData {
      */
     hookType: string;
     /**
-     * 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 data passed to the hook. For postToolUse hooks the retained copy served by session.eventLog.read (and by a resumed session) drops the tool result's inline `contents`/`uiResource`/`skillInvocation` and replaces duplicated text result fields with a `[copilot:elided ...]` marker; the live subscription stream still delivers the full value. Canonical tool output remains in the adjacent tool.execution_complete event, while an invoked skill's authoritative body remains in its skill invocation event.
      */
     input?: JsonValue;
     /**
@@ -7125,7 +7155,7 @@ export interface HookEndData {
      */
     hookType: string;
     /**
-     * Output data produced by the hook
+     * Output data produced by the hook. Durable and resumed postToolUse receipts may omit messages owned by a successful skill invocation and replace an unchanged skill sessionLog copy with an elision marker; hook-modified or re-sourced values are preserved, and the authoritative body remains in the skill invocation event.
      */
     output?: JsonValue;
     /**
@@ -11198,6 +11228,10 @@ export interface McpServersLoadedData {
  * A single MCP server status summary in `session.mcp_servers_loaded`, including name, status, source, transport, and plugin metadata.
  */
 export interface McpServersLoadedServer {
+    /**
+     * Human-readable display name supplied by a managed server catalog.
+     */
+    displayName?: string;
     /**
      * Error message if the server failed to connect
      */

package/dist/index.d.ts

@@ -12,4 +12,4 @@ export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasDeclar
 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 { 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";
+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/session.d.ts

@@ -59,6 +59,7 @@ export declare class CopilotSession {
     private hooks?;
     private transformCallbacks?;
     private _rpc;
+    private _internalRpc;
     private traceContextProvider?;
     private readonly managedSettingsEnabled;
     private _capabilities;

package/dist/session.js

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { ConnectionError, ErrorCodes, ResponseError } from "vscode-jsonrpc/node.js";
-import { createSessionRpc } from "./generated/rpc.js";
+import { createInternalSessionRpc, createSessionRpc } from "./generated/rpc.js";
 import { CanvasError } from "./canvas.js";
 import { getTraceContext } from "./telemetry.js";
 import { isAttributedPermissionResult } from "./types.js";
@@ -23,10 +23,14 @@ const factoryExecutionStore = new AsyncLocalStorage();
 function throwIfFactoryExecutionIsActive() {
   if (factoryExecutionStore.getStore()?.active) {
     throw new Error(
-      "factory.run and factory.resume are not allowed while a factory body is running on this call path."
+      "factory.run, factory.resume, and factory.pause are not allowed while a factory body is running on this call path."
     );
   }
 }
+function runInFactoryHelperScope(helperScope, callback) {
+  const current = factoryExecutionStore.getStore();
+  return factoryExecutionStore.run({ active: current?.active ?? false, helperScope }, callback);
+}
 function deserializeHookInput(raw) {
   if (!raw || typeof raw !== "object" || typeof raw.timestamp !== "number") {
     return raw;
@@ -70,7 +74,7 @@ async function runFactoryParallel(thunks) {
   }
   return Promise.all(
     thunks.map(
-      (thunk) => Promise.resolve().then(() => thunk()).catch((error) => {
+      (thunk) => Promise.resolve().then(() => runInFactoryHelperScope("parallel", thunk)).catch((error) => {
         if (isFactoryFatalError(error)) {
           throw error;
         }
@@ -89,7 +93,10 @@ async function runFactoryPipeline(items, ...stages) {
       let previous = item;
       for (const stage of stages) {
         try {
-          previous = await stage(previous, item, index);
+          previous = await runInFactoryHelperScope(
+            "pipeline",
+            () => stage(previous, item, index)
+          );
         } catch (error) {
           if (isFactoryFatalError(error)) {
             throw error;
@@ -246,6 +253,7 @@ class CopilotSession {
   hooks;
   transformCallbacks;
   _rpc = null;
+  _internalRpc = null;
   traceContextProvider;
   managedSettingsEnabled;
   _capabilities = {};
@@ -312,6 +320,10 @@ class CopilotSession {
     }),
     getRunDetail: (runId) => this.rpc.factory.getRunDetail({ runId }),
     getRunProgress: (runId, options = {}) => this.rpc.factory.getRunProgress({ runId, ...options }),
+    pause: async (runId) => {
+      throwIfFactoryExecutionIsActive();
+      return this.rpc.factory.pause({ runId });
+    },
     cancel: async (runId) => this.rpc.factory.cancel({ runId })
   };
   /**
@@ -410,6 +422,13 @@ class CopilotSession {
     }
     return this._rpc;
   }
+  /** @internal */
+  get internalRpc() {
+    if (!this._internalRpc) {
+      this._internalRpc = createInternalSessionRpc(this.connection, this.sessionId);
+    }
+    return this._internalRpc;
+  }
   /**
    * Path to the session workspace directory when infinite sessions are enabled.
    * Contains checkpoints/, plan.md, and files/ subdirectories.
@@ -1092,6 +1111,36 @@ class CopilotSession {
               );
               return result2;
             },
+            pause: async (key) => {
+              if (typeof key !== "string" || key.length === 0) {
+                throw new Error("Factory pause checkpoint key must not be empty");
+              }
+              const helperScope = factoryExecutionStore.getStore()?.helperScope;
+              if (helperScope !== void 0) {
+                throw new Error(
+                  `Factory pause checkpoints are not allowed inside ${helperScope}() branches`
+                );
+              }
+              await progress.flush();
+              const response = await awaitFactoryOperation(
+                () => self.internalRpc.factory.pauseAtCheckpoint({
+                  runId: params.runId,
+                  executionToken: params.executionToken,
+                  key
+                }),
+                controller.signal
+              );
+              switch (response.action) {
+                case "continue":
+                  return;
+                case "pause":
+                  await awaitFactoryOperation(
+                    () => new Promise(() => {
+                    }),
+                    controller.signal
+                  );
+              }
+            },
             parallel: runFactoryParallel,
             pipeline: runFactoryPipeline,
             factory: async () => {
@@ -1127,11 +1176,9 @@ class CopilotSession {
       },
       async abort(params) {
         const controllersForRun = self.factoryAbortControllers.get(params.runId);
-        if (controllersForRun !== void 0) {
-          const reason = new DOMException("Factory run was aborted", "AbortError");
-          for (const controller of controllersForRun.values()) {
-            controller.abort(reason);
-          }
+        const controller = controllersForRun?.get(params.executionToken);
+        if (controller !== void 0) {
+          controller.abort(new DOMException("Factory run was aborted", "AbortError"));
         }
         return {};
       }

package/docs/factories.md

@@ -62,19 +62,20 @@ Validation covers the model's `run_factory` path only. An extension calling `ses
 
 The `run()` context provides:
 
-- `ctx.runId`: Stable ID reused across resumed attempts.
-- `ctx.args`: Invocation arguments, forwarded verbatim. When the caller omits `args`, this is `{}` rather than `undefined`.
-- `ctx.agent(prompt, options?)`: Runs one factory-owned subagent. Options are exactly `label`, `schema`, `model`, `agent`, `reasoningEffort`, and `contextTier`. See [Subagent calls](#subagent-calls).
-- `ctx.parallel(thunks)`: Runs thunks concurrently and awaits all of them (a barrier). A thunk that throws becomes `null` in the result array, so one failed item does not lose the rest. Cancellation and hard runtime failures (`ResponseError`, `ConnectionError`) are the exception — those propagate and reject the whole call, because they mean the run itself is in trouble rather than one item having failed. Handle them at run level; do not assume every failure arrives as a `null`. Rejects above 4096 items.
-- `ctx.pipeline(items, ...stages)`: Flows each item through every stage without a barrier between stages, so one item can be in a later stage while another is still in an earlier one. Each stage is called as `(previous, item, index)`, where `previous` is the prior stage's result and `item` is the original input. A stage that throws drops that item to `null` and skips its remaining stages, with the same exception for cancellation and hard runtime failures. Rejects above 4096 items.
-- `ctx.phase(title)`: Starts a named progress phase. This sets a single run-global value, so calling it from inside concurrent `parallel`/`pipeline` stages races. Call it at run-level transitions and distinguish concurrent work by `label` instead.
-- `ctx.log(message)`: Appends a progress line. When a factory bounds its own coverage (top-N, sampling), log what was dropped.
-- `ctx.step(key, producer, options?)`: Journals the producer's JSON result under a stable key so a resume replays it without re-running the producer. A journaled (default) producer must return a JSON-serializable value; `undefined` or a non-JSON value is rejected. Pass `{ volatile: true }` to bypass the journal and run the producer every time.
+* `ctx.runId`: Stable ID reused across resumed attempts.
+* `ctx.args`: Invocation arguments, forwarded verbatim. When the caller omits `args`, this is `{}` rather than `undefined`.
+* `ctx.agent(prompt, options?)`: Runs one factory-owned subagent. Options are exactly `label`, `schema`, `model`, `agent`, `reasoningEffort`, and `contextTier`. See [Subagent calls](#subagent-calls).
+* `ctx.parallel(thunks)`: Runs thunks concurrently and awaits all of them (a barrier). A thunk that throws becomes `null` in the result array, so one failed item does not lose the rest. Cancellation and hard runtime failures (`ResponseError`, `ConnectionError`) are the exception — those propagate and reject the whole call, because they mean the run itself is in trouble rather than one item having failed. Handle them at run level; do not assume every failure arrives as a `null`. Rejects above 4096 items.
+* `ctx.pipeline(items, ...stages)`: Flows each item through every stage without a barrier between stages, so one item can be in a later stage while another is still in an earlier one. Each stage is called as `(previous, item, index)`, where `previous` is the prior stage's result and `item` is the original input. A stage that throws drops that item to `null` and skips its remaining stages, with the same exception for cancellation and hard runtime failures. Rejects above 4096 items.
+* `ctx.phase(title)`: Starts a named progress phase. This sets a single run-global value, so calling it from inside concurrent `parallel`/`pipeline` stages races. Call it at run-level transitions and distinguish concurrent work by `label` instead.
+* `ctx.log(message)`: Appends a progress line. When a factory bounds its own coverage (top-N, sampling), log what was dropped.
+* `ctx.step(key, producer, options?)`: Journals the producer's JSON result under a stable key so a resume replays it without re-running the producer. A journaled (default) producer must return a JSON-serializable value; `undefined` or a non-JSON value is rejected. Pass `{ volatile: true }` to bypass the journal and run the producer every time.
 
   The key is the *sole* identity: neither the producer body nor its inputs contribute to it. A resume replays the cached value for a matching key even if the producer has since changed, so version the key (`"scan-v2"`) whenever its inputs or meaning change. Journaled producers are best-effort at-least-once and may run again across crashes or concurrent same-key callers, so keep side effects idempotent.
-- `ctx.session`: The session returned by `joinSession`. It refuses calls that start or resume a factory run. Call `extensions_manage` with `operation: "guide"` to read more about the session APIs.
-- `ctx.signal`: Cooperative cancellation signal for extension work and subprocesses.
-- `ctx.factory(...)`: Always rejects because nested factories are not supported.
+* `ctx.pause(key)`: Pauses at a durable, one-shot checkpoint. The first attempt records the checkpoint, pauses, and throws `AbortError` after cooperative cancellation. When the run resumes, the factory starts again and the same checkpoint returns so execution can continue. Call it only from the main factory flow, not inside `ctx.parallel()` or `ctx.pipeline()`.
+* `ctx.session`: The session returned by `joinSession`. It refuses calls that start, resume, or pause a factory run. Call `extensions_manage` with `operation: "guide"` to read more about the session APIs.
+* `ctx.signal`: Cooperative cancellation signal for extension work and subprocesses.
+* `ctx.factory(...)`: Always rejects because nested factories are not supported.
 
 Factory-owned subagents are intentionally hidden from `read_agent` and `write_agent`. Use the factory observability APIs instead.
 
@@ -157,7 +158,7 @@ session.factory.run(
     name: string,
     options?: {
         args?: JsonValue;
-        limits?: FactoryLimits;
+        limits?: FactoryLimitOverrides;
         notifyOnComplete?: boolean;
         logPhaseNames?: boolean;
     },
@@ -180,7 +181,7 @@ The signature is:
 session.factory.resume(
     runId: string,
     options?: {
-        limits?: FactoryLimits;
+        limits?: FactoryLimitOverrides;
         notifyOnComplete?: boolean;
         logPhaseNames?: boolean;
     },
@@ -189,15 +190,31 @@ session.factory.resume(
 
 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`.
+Both resolve with the run envelope (`FactoryRunResult`) for **every** outcome—`completed`, `error`, `halted`, `paused`, and `cancelled` alike. Inspect `status` and read `result` only when the run completed; a limit breach carries a typed `failure`. A `paused` envelope means that the current attempt settled, not that the durable run is permanently finished. Resume the same run ID to start another attempt with its journal and accounting intact. 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.
 
+Pause a running attempt from outside its factory body:
+
+```ts
+const paused = await session.factory.pause(runId);
+```
+
+Inside a factory body, use a durable checkpoint instead:
+
+```ts
+await ctx.step("prepare", prepareInput);
+await ctx.pause("review-ready");
+await ctx.agent("Review the prepared input");
+```
+
+The first attempt pauses at `"review-ready"` and ends through cooperative cancellation. On resume, the factory starts from the beginning, reuses the journaled step, returns from the checkpoint, and continues.
+
 The agent-facing `run_factory` tool has exactly two input branches:
 
 ```ts
-{ name: string; args?: JsonValue; limits?: FactoryLimits }
-{ resumeFromRunId: string; limits?: FactoryLimits }
+{ name: string; args?: JsonValue; limits?: FactoryLimitOverrides }
+{ resumeFromRunId: string; limits?: FactoryLimitOverrides }
 ```
 
 ## Authoring a factory from inside a session
@@ -253,9 +270,9 @@ const progressPage = await session.factory.getRunProgress(runId, {
 - `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.
 
-`getRun(runId)` reads the latest run envelope, and `cancel(runId)` cancels a run and returns its terminal envelope.
+`getRun(runId)` reads the latest run envelope. `pause(runId)` pauses a running attempt and returns its `paused` envelope. `cancel(runId)` cancels a run and returns its terminal envelope.
 
-`waitForRun(runId, options?)` resolves with the terminal envelope once the run settles into `completed`, `error`, `halted`, or `cancelled`, and resolves immediately when it has already settled:
+`waitForRun(runId, options?)` resolves with the current attempt's envelope once it settles into `completed`, `error`, `halted`, `paused`, or `cancelled`. It resolves immediately when the current attempt has already settled:
 
 ```ts
 const settled = await session.factory.waitForRun(runId);
@@ -272,7 +289,7 @@ setTimeout(() => controller.abort(), 30_000);
 const settled = await session.factory.waitForRun(runId, { signal: controller.signal });
 ```
 
-Aborting rejects the wait and has no effect on the run, which keeps executing — use `cancel(runId)` to actually stop it. Because a terminal envelope is final, the resolved value never changes afterwards. `isFactoryRunTerminal(status)` exposes the same terminal-status test for callers driving their own loop.
+Aborting rejects the wait and has no effect on the run, which keeps executing—use `pause(runId)` or `cancel(runId)` to stop it. The resolved object is a snapshot of that settled attempt. If its status is `paused`, a later resume updates the durable envelope under the same run ID. Call `getRun(runId)` to read the latest envelope. `isFactoryRunTerminal(status)` exposes the same current-attempt settlement test for callers driving their own loop.
 
 Listen for the ephemeral `factory.run_updated` event. Its `{ runId, revision }` payload is an invalidation signal. Re-read the desired API when a newer monotonic revision arrives.
 

package/package.json

@@ -4,8 +4,8 @@
         "type": "git",
         "url": "https://github.com/github/copilot-sdk.git"
     },
-    "version": "1.0.14-preview.0",
-    "copilotCliVersion": "1.0.84-5",
+    "version": "1.0.14-unstable.35049111350.g7f86a90",
+    "copilotCliVersion": "1.0.84-9.unstable.r35045926061.g4848e94",
     "description": "TypeScript SDK for programmatic control of GitHub Copilot CLI via JSON-RPC",
     "main": "./dist/cjs/index.js",
     "types": "./dist/index.d.ts",
@@ -36,8 +36,10 @@
         "auth:refresh": "node ../scripts/npm-auth-refresh.mjs --run",
         "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",
         "verify:release-packages": "tsx scripts/verify-release-packages.ts",
+        "release:manifest": "tsx scripts/release-manifest.ts",
         "prepare:runtime": "tsx scripts/prepare-runtime.ts",
         "test": "vitest run",
         "test:watch": "vitest",
@@ -96,13 +98,13 @@
         "README.md"
     ],
     "optionalDependencies": {
-        "@github/copilot-sdk-darwin-arm64": "1.0.14-preview.0",
-        "@github/copilot-sdk-darwin-x64": "1.0.14-preview.0",
-        "@github/copilot-sdk-linux-arm64": "1.0.14-preview.0",
-        "@github/copilot-sdk-linux-x64": "1.0.14-preview.0",
-        "@github/copilot-sdk-linuxmusl-arm64": "1.0.14-preview.0",
-        "@github/copilot-sdk-linuxmusl-x64": "1.0.14-preview.0",
-        "@github/copilot-sdk-win32-arm64": "1.0.14-preview.0",
-        "@github/copilot-sdk-win32-x64": "1.0.14-preview.0"
+        "@github/copilot-sdk-darwin-arm64": "1.0.14-unstable.35049111350.g7f86a90",
+        "@github/copilot-sdk-darwin-x64": "1.0.14-unstable.35049111350.g7f86a90",
+        "@github/copilot-sdk-linux-arm64": "1.0.14-unstable.35049111350.g7f86a90",
+        "@github/copilot-sdk-linux-x64": "1.0.14-unstable.35049111350.g7f86a90",
+        "@github/copilot-sdk-linuxmusl-arm64": "1.0.14-unstable.35049111350.g7f86a90",
+        "@github/copilot-sdk-linuxmusl-x64": "1.0.14-unstable.35049111350.g7f86a90",
+        "@github/copilot-sdk-win32-arm64": "1.0.14-unstable.35049111350.g7f86a90",
+        "@github/copilot-sdk-win32-x64": "1.0.14-unstable.35049111350.g7f86a90"
     }
 }