@github/copilot-sdk 1.0.10-preview.0 → 1.0.11-preview.1

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

@@ -2,6 +2,10 @@
  * AUTO-GENERATED FILE - DO NOT EDIT
  * Generated from: session-events.schema.json
  */
+/** A value that can be represented losslessly on the SDK JSON wire. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
 /**
  * Union of all session event variants emitted by the Copilot CLI runtime.
  */
@@ -484,6 +488,10 @@ export type ElicitationCompletedAction =
  | "decline"
 /** The user dismissed the request. */
  | "cancel";
+/**
+ * Opaque JSON value submitted for one field in accepted `elicitation.completed` form content.
+ */
+export type ElicitationCompletedContent = JsonValue | undefined;
 /**
  * Reason the runtime is requesting host-provided MCP OAuth credentials
  */
@@ -524,6 +532,10 @@ export type McpHeadersRefreshCompletedOutcome =
  | "none"
 /** No response arrived within the bounded window. */
  | "timeout";
+/**
+ * Source-defined JSON payload for the custom notification
+ */
+export type CustomNotificationPayload = JsonValue;
 /**
  * The user's auto-mode-switch choice
  */
@@ -3024,9 +3036,7 @@ export interface AttachmentExtensionContext {
     /**
      * Caller-supplied JSON payload
      */
-    payload?: {
-        [k: string]: unknown | undefined;
-    };
+    payload?: JsonValue;
     /**
      * Human-readable composer pill label
      */
@@ -3566,9 +3576,7 @@ export interface CitationReference {
     /**
      * Provider-native citation correlation data (e.g. Anthropic search_result_index / document_index), passed through opaquely for debugging and forward compatibility.
      */
-    providerMetadata?: {
-        [k: string]: unknown | undefined;
-    };
+    providerMetadata?: JsonValue;
     /**
      * Identifier of the CitationSource this reference points to (CitationSource.id).
      */
@@ -3637,9 +3645,9 @@ export interface AssistantMessageServerTools {
     functionCallNamespaces?: {
         [k: string]: string | undefined;
     };
-    items?: unknown[];
+    items?: JsonValue[];
     provider: string;
-    rawContentBlocks?: unknown[];
+    rawContentBlocks?: JsonValue[];
 }
 /**
  * A tool invocation request from the assistant
@@ -3648,9 +3656,7 @@ export interface AssistantMessageToolRequest {
     /**
      * Arguments to pass to the tool, format depends on the tool
      */
-    arguments?: {
-        [k: string]: unknown | undefined;
-    };
+    arguments?: JsonValue;
     /**
      * Resolved intention summary describing what this specific call does
      */
@@ -4209,9 +4215,7 @@ export interface ToolUserRequestedData {
     /**
      * Arguments for the tool invocation
      */
-    arguments?: {
-        [k: string]: unknown | undefined;
-    };
+    arguments?: JsonValue;
     /**
      * Unique identifier for this tool call
      */
@@ -4258,9 +4262,7 @@ export interface ToolExecutionStartData {
     /**
      * Arguments passed to the tool
      */
-    arguments?: {
-        [k: string]: unknown | undefined;
-    };
+    arguments?: JsonValue;
     /**
      * When true, the tool output should be displayed expanded (verbatim) in the CLI timeline
      */
@@ -4484,9 +4486,7 @@ export interface ToolExecutionCompleteData {
      *
      * @experimental
      */
-    mcpMeta?: {
-        [k: string]: unknown | undefined;
-    };
+    mcpMeta?: JsonValue;
     /**
      * Model identifier that generated this tool call
      */
@@ -4515,7 +4515,7 @@ export interface ToolExecutionCompleteData {
      * Tool-specific telemetry data (e.g., CodeQL check counts, grep match counts)
      */
     toolTelemetry?: {
-        [k: string]: unknown | undefined;
+        [k: string]: JsonValue | undefined;
     };
     /**
      * Identifier for the agent loop turn this tool was invoked in, matching the corresponding assistant.turn_start event
@@ -4568,15 +4568,11 @@ export interface ToolExecutionCompleteResult {
      *
      * @experimental
      */
-    mcpMeta?: {
-        [k: string]: unknown | undefined;
-    };
+    mcpMeta?: JsonValue;
     /**
      * Structured content (arbitrary JSON) returned verbatim by the MCP tool
      */
-    structuredContent?: {
-        [k: string]: unknown | undefined;
-    };
+    structuredContent?: JsonValue;
     uiResource?: ToolExecutionCompleteUIResource;
 }
 /**
@@ -4595,7 +4591,7 @@ export interface PersistedBinaryImage {
      * Optional metadata from the producing tool.
      */
     metadata?: {
-        [k: string]: unknown | undefined;
+        [k: string]: JsonValue | undefined;
     };
     /**
      * MIME type of the binary data
@@ -4620,7 +4616,7 @@ export interface OmittedBinaryResult {
      * Optional metadata from the producing tool.
      */
     metadata?: {
-        [k: string]: unknown | undefined;
+        [k: string]: JsonValue | undefined;
     };
     /**
      * MIME type of the omitted binary data
@@ -4650,7 +4646,7 @@ export interface BinaryAssetReference {
      * Optional metadata from the producing tool.
      */
     metadata?: {
-        [k: string]: unknown | undefined;
+        [k: string]: JsonValue | undefined;
     };
     /**
      * MIME type of the referenced binary data
@@ -5201,6 +5197,10 @@ export interface SubagentCompletedData {
      * Internal name of the sub-agent
      */
     agentName: string;
+    /**
+     * Whether the sub-agent was torn down by cancellation - its own abort, or an ancestor being killed - instead of finishing its work. Cancellation is not a failure, so the run still reports completion; this distinguishes a torn-down sub-agent from one that ran to the end.
+     */
+    cancelled?: boolean;
     /**
      * Wall-clock duration of the sub-agent execution in milliseconds
      */
@@ -5416,9 +5416,7 @@ export interface HookStartData {
     /**
      * Input data passed to the hook
      */
-    input?: {
-        [k: string]: unknown | undefined;
-    };
+    input?: JsonValue;
 }
 /**
  * Session event "hook.end". Hook invocation completion details including output, success status, and error information
@@ -5466,9 +5464,7 @@ export interface HookEndData {
     /**
      * Output data produced by the hook
      */
-    output?: {
-        [k: string]: unknown | undefined;
-    };
+    output?: JsonValue;
     /**
      * Whether the hook completed successfully
      */
@@ -5589,7 +5585,7 @@ export interface BinaryAssetData {
      * Optional metadata from the producing tool.
      */
     metadata?: {
-        [k: string]: unknown | undefined;
+        [k: string]: JsonValue | undefined;
     };
     /**
      * MIME type of the binary asset
@@ -5658,7 +5654,7 @@ export interface SystemMessageMetadata {
      * Template variables used when constructing the prompt
      */
     variables?: {
-        [k: string]: unknown | undefined;
+        [k: string]: JsonValue | undefined;
     };
 }
 /**
@@ -5863,9 +5859,7 @@ export interface SystemNotificationFactoryCompleted {
     /**
      * Machine-readable terminal failure details, when present.
      */
-    failure?: {
-        [k: string]: unknown | undefined;
-    };
+    failure?: JsonValue;
     /**
      * Bounded prompt-safe preview of the completed result.
      */
@@ -5891,9 +5885,7 @@ export interface SystemNotificationUnclassified {
     /**
      * Opaque metadata supplied by the external host, when present.
      */
-    metadata?: {
-        [k: string]: unknown | undefined;
-    };
+    metadata?: JsonValue;
     /**
      * Type discriminator. Always "unclassified".
      */
@@ -5946,9 +5938,7 @@ export interface PermissionRequestedData {
     /**
      * Neutral risk metadata supplied by the tool host. Consumers may display this value but must not use it to bypass the permission decision.
      */
-    riskAssessment?: {
-        [k: string]: unknown | undefined;
-    };
+    riskAssessment?: JsonValue;
 }
 /**
  * Shell command permission request
@@ -6131,9 +6121,7 @@ export interface PermissionRequestMcp {
     /**
      * Arguments to pass to the MCP tool
      */
-    args?: {
-        [k: string]: unknown | undefined;
-    };
+    args?: JsonValue;
     /**
      * Permission kind discriminator
      */
@@ -6234,9 +6222,7 @@ export interface PermissionRequestCustomTool {
     /**
      * Arguments to pass to the custom tool
      */
-    args?: {
-        [k: string]: unknown | undefined;
-    };
+    args?: JsonValue;
     /**
      * Permission kind discriminator
      */
@@ -6269,9 +6255,7 @@ export interface PermissionRequestHook {
     /**
      * Arguments of the tool call being gated
      */
-    toolArgs?: {
-        [k: string]: unknown | undefined;
-    };
+    toolArgs?: JsonValue;
     /**
      * Tool call ID that triggered this permission request
      */
@@ -6530,9 +6514,7 @@ export interface PermissionPromptRequestMcp {
     /**
      * Arguments to pass to the MCP tool
      */
-    args?: {
-        [k: string]: unknown | undefined;
-    };
+    args?: JsonValue;
     /**
      * Auto-approval judge information for this request; present only when auto mode is enabled.
      *
@@ -6647,9 +6629,7 @@ export interface PermissionPromptRequestCustomTool {
     /**
      * Arguments to pass to the custom tool
      */
-    args?: {
-        [k: string]: unknown | undefined;
-    };
+    args?: JsonValue;
     /**
      * Auto-approval judge information for this request; present only when auto mode is enabled.
      *
@@ -6718,9 +6698,7 @@ export interface PermissionPromptRequestHook {
     /**
      * Arguments of the tool call being gated
      */
-    toolArgs?: {
-        [k: string]: unknown | undefined;
-    };
+    toolArgs?: JsonValue;
     /**
      * Tool call ID that triggered this permission request
      */
@@ -7300,7 +7278,7 @@ export interface ElicitationRequestedSchema {
      * Form field definitions, keyed by field name
      */
     properties: {
-        [k: string]: unknown | undefined;
+        [k: string]: JsonValue | undefined;
     };
     /**
      * List of required field names
@@ -7357,12 +7335,6 @@ export interface ElicitationCompletedData {
      */
     requestId: string;
 }
-/**
- * Opaque JSON value submitted for one field in accepted `elicitation.completed` form content.
- */
-export interface ElicitationCompletedContent {
-    [k: string]: unknown | undefined;
-}
 /**
  * Session event "sampling.requested". Sampling request from an MCP server; contains the server name and a requestId for correlation
  */
@@ -7400,9 +7372,7 @@ export interface SamplingRequestedData {
     /**
      * The JSON-RPC request ID from the MCP protocol
      */
-    mcpRequestId: {
-        [k: string]: unknown | undefined;
-    };
+    mcpRequestId: JsonValue;
     /**
      * Unique identifier for this sampling request; used to respond via session.respondToSampling()
      */
@@ -7751,12 +7721,6 @@ export interface CustomNotificationData {
      */
     version?: number;
 }
-/**
- * Source-defined JSON payload for the custom notification
- */
-export interface CustomNotificationPayload {
-    [k: string]: unknown | undefined;
-}
 /**
  * Optional source-defined string identifiers describing the payload subject
  */
@@ -7800,9 +7764,7 @@ export interface ExternalToolRequestedData {
     /**
      * Arguments to pass to the external tool
      */
-    arguments?: {
-        [k: string]: unknown | undefined;
-    };
+    arguments?: JsonValue;
     /**
      * Unique identifier for this request; used to respond via session.respondToExternalTool()
      */
@@ -8355,9 +8317,7 @@ export interface ManagedSettingsResolvedData {
     /**
      * The effective (resolved) managed settings values, so clients can render exactly what is enforced. Absent when no managed policy is in force.
      */
-    settings?: {
-        [k: string]: unknown | undefined;
-    };
+    settings?: JsonValue;
     source: ManagedSettingsResolvedSource;
 }
 /**
@@ -9208,9 +9168,7 @@ export interface CanvasOpenedData {
     /**
      * Input supplied when the instance was opened
      */
-    input?: {
-        [k: string]: unknown | undefined;
-    };
+    input?: JsonValue;
     /**
      * Stable caller-supplied canvas instance identifier
      */
@@ -9305,9 +9263,7 @@ export interface CanvasRegistryChangedCanvas {
     /**
      * JSON Schema for canvas open input
      */
-    inputSchema?: {
-        [k: string]: unknown | undefined;
-    };
+    inputSchema?: JsonValue;
 }
 /**
  * A single action within a canvas declaration, with its name, optional description, and optional input schema.
@@ -9321,9 +9277,7 @@ export interface CanvasRegistryChangedCanvasAction {
     /**
      * JSON Schema for action input
      */
-    inputSchema?: {
-        [k: string]: unknown | undefined;
-    };
+    inputSchema?: JsonValue;
     /**
      * Action name
      */
@@ -9474,9 +9428,7 @@ export interface CanvasRecordedData {
     /**
      * Input supplied when the instance was opened
      */
-    input?: {
-        [k: string]: unknown | undefined;
-    };
+    input?: JsonValue;
     /**
      * Stable caller-supplied canvas instance identifier
      */
@@ -9612,7 +9564,7 @@ export interface McpAppToolCallCompleteData {
      * Arguments passed to the tool by the app view, if any
      */
     arguments?: {
-        [k: string]: unknown | undefined;
+        [k: string]: JsonValue | undefined;
     };
     /**
      * Wall-clock duration of the underlying tools/call in milliseconds
@@ -9623,7 +9575,7 @@ export interface McpAppToolCallCompleteData {
      * Standard MCP CallToolResult returned by the server. Present whether or not the call set isError.
      */
     result?: {
-        [k: string]: unknown | undefined;
+        [k: string]: JsonValue | undefined;
     };
     /**
      * Name of the MCP server hosting the tool

package/dist/session.js

@@ -1,14 +1,30 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { ConnectionError, ErrorCodes, ResponseError } from "vscode-jsonrpc/node.js";
 import { createSessionRpc } from "./generated/rpc.js";
 import { CanvasError } from "./canvas.js";
 import { getTraceContext } from "./telemetry.js";
 import {
+  FACTORY_AGENT_OPTION_KEYS,
   getFactoryDefinition,
   FactoryResumeError,
   isFactoryRunTerminal
 } from "./factory.js";
 function isFactoryResumeErrorCode(value) {
-  return value === "not_found" || value === "non_resumable" || value === "already_active" || value === "reapproval_declined" || value === "no_approval_provider";
+  return value === "not_found" || value === "non_resumable" || value === "already_active" || value === "factory_already_running" || value === "factory_limits_invalid" || value === "factory_session_disposed" || value === "factory_storage_unavailable" || value === "factory_storage_corrupt";
+}
+function copyDefinedFactoryAgentOption(source, target, key) {
+  const value = source[key];
+  if (value !== void 0) {
+    target[key] = value;
+  }
+}
+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."
+    );
+  }
 }
 function deserializeHookInput(raw) {
   if (!raw || typeof raw !== "object" || typeof raw.timestamp !== "number") {
@@ -129,7 +145,10 @@ class FactoryProgressBuffer {
     const lines = this.pending.splice(0);
     await this.flushTail;
     if (this.flushFailed) {
-      throw this.flushError;
+      console.warn(
+        "Ignoring a background factory progress flush failure after the factory body settled",
+        this.flushError
+      );
     }
     if (lines.length > 0) {
       try {
@@ -160,9 +179,6 @@ class FactoryProgressBuffer {
     }
   }
 }
-function toPublicFactoryRunResult(envelope) {
-  return envelope;
-}
 async function awaitFactoryOperation(operation, signal) {
   let rejectAbort;
   const abortPromise = new Promise((_resolve, reject) => {
@@ -242,6 +258,7 @@ class CopilotSession {
    */
   factory = {
     run: (async (nameOrHandle, options) => {
+      throwIfFactoryExecutionIsActive();
       const name = typeof nameOrHandle === "string" ? nameOrHandle : getFactoryDefinition(nameOrHandle).meta.name;
       if (options?.resumeFromRunId !== void 0) {
         return this.factory.resume(options.resumeFromRunId, {
@@ -258,6 +275,7 @@ class CopilotSession {
       return this.settleFactoryRun(envelope);
     }),
     resume: (async (runId, options) => {
+      throwIfFactoryExecutionIsActive();
       let response;
       try {
         response = await this.rpc.factory.resume({
@@ -275,12 +293,12 @@ class CopilotSession {
       }
       return this.settleFactoryRun(response.run);
     }),
-    getRun: async (runId) => toPublicFactoryRunResult(await this.rpc.factory.getRun({ runId })),
+    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 () => (await this.rpc.factory.listRuns({})).runs,
     getRunDetail: (runId) => this.rpc.factory.getRunDetail({ runId }),
     getRunProgress: (runId, options = {}) => this.rpc.factory.getRunProgress({ runId, ...options }),
-    cancel: async (runId) => toPublicFactoryRunResult(await this.rpc.factory.cancel({ runId }))
+    cancel: async (runId) => this.rpc.factory.cancel({ runId })
   };
   /**
    * Resolve a start/resume envelope into the terminal envelope callers expect.
@@ -291,7 +309,7 @@ class CopilotSession {
    */
   settleFactoryRun(envelope) {
     if (isFactoryRunTerminal(envelope.status)) {
-      return Promise.resolve(toPublicFactoryRunResult(envelope));
+      return Promise.resolve(envelope);
     }
     return this.waitForFactoryRun(envelope.runId);
   }
@@ -345,7 +363,7 @@ class CopilotSession {
             rereadRequested = false;
             const envelope = await this.rpc.factory.getRun({ runId });
             if (isFactoryRunTerminal(envelope.status)) {
-              finish(() => resolve(toPublicFactoryRunResult(envelope)));
+              finish(() => resolve(envelope));
               return;
             }
           } while (rereadRequested && !settled);
@@ -945,16 +963,16 @@ class CopilotSession {
             },
             agent: async (prompt, options = {}) => {
               await progress.flush();
+              const opts = {};
+              for (const key of FACTORY_AGENT_OPTION_KEYS) {
+                copyDefinedFactoryAgentOption(options, opts, key);
+              }
               const response = await awaitFactoryOperation(
                 () => self.rpc.factory.agent({
                   factoryRunId: params.runId,
                   executionToken: params.executionToken,
                   prompt,
-                  opts: {
-                    label: options.label,
-                    schema: options.schema,
-                    model: options.model
-                  }
+                  opts
                 }),
                 controller.signal
               );
@@ -1002,7 +1020,14 @@ class CopilotSession {
               throw new Error("nested factories are not supported");
             }
           };
-          const result = await definition.run(context);
+          const execution = { active: true };
+          const result = await factoryExecutionStore.run(execution, async () => {
+            try {
+              return await definition.run(context);
+            } finally {
+              execution.active = false;
+            }
+          });
           if (result === void 0) {
             return {};
           }

package/dist/types.d.ts

@@ -6,6 +6,7 @@ import type { SessionFsProvider } from "./sessionFsProvider.js";
 import type { CopilotRequestHandler } from "./copilotRequestHandler.js";
 import type { PermissionRequest as GeneratedPermissionRequest, PermissionRequestedData as GeneratedPermissionRequestedData, PermissionRequestedEvent as GeneratedPermissionRequestedEvent, ReasoningSummary, SessionLimitsConfig, SessionEvent as GeneratedSessionEvent } from "./generated/session-events.js";
 import type { CopilotSession } from "./session.js";
+import type { JsonValue } from "./factory.js";
 import type { GitHubTelemetryNotification, ModelBillingTokenPrices, OpenCanvasInstance, RemoteSessionMode, CurrentToolMetadata } from "./generated/rpc.js";
 import type { ToolSet } from "./toolSet.js";
 export type { RemoteSessionMode } from "./generated/rpc.js";
@@ -355,7 +356,7 @@ export type ToolBinaryResult = {
     type: "image" | "resource";
     description?: string;
 };
-export type ToolTelemetry = Record<string, Record<string, unknown> | undefined>;
+export type ToolTelemetry = Record<string, Record<string, JsonValue> | undefined>;
 export type ToolResultObject = {
     textResultForLlm: string;
     binaryResultsForLlm?: ToolBinaryResult[];
@@ -1937,6 +1938,13 @@ export interface SessionConfigBase {
      * @experimental
      */
     enableCitations?: boolean;
+    /**
+     * Opt in to capturing file changes for session rewind and cumulative session
+     * diff. On create, capture starts with the first turn. On resume, this can
+     * enable tracking only when the session still has a valid baseline; it cannot
+     * reconstruct changes from earlier untracked turns.
+     */
+    enableFileChangeTracking?: boolean;
     /**
      * Limits applied to this session's current accounting window.
      *

package/docs/factories.md

@@ -53,7 +53,7 @@ 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`, and `model`. See [Subagent calls](#subagent-calls).
+- `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.
@@ -61,7 +61,7 @@ The `run()` context provides:
 - `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 full session returned by `joinSession`.
+- `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.
 
@@ -156,7 +156,7 @@ session.factory.resume(
 ): Promise<FactoryRunResult>;
 ```
 
-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`. A declined fresh run is not a pre-execution failure: the run row already exists by the time the prompt is answered, so it resolves with a terminal `cancelled` envelope carrying the run ID. Only failures that occur *before* a run exists reject: an unknown factory name or an already-active session. Pre-execution resume failures, including a declined reapproval, throw `FactoryResumeError`, whose `code` is one of `not_found`, `non_resumable`, `already_active`, `reapproval_declined`, or `no_approval_provider`.
+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.
 
@@ -210,7 +210,7 @@ const page = await session.factory.getRunProgress(runId, {
 });
 ```
 
-- `listRuns()` returns summaries in durable creation order.
+- `listRuns()` returns the newest default page of this session's durable factory runs.
 - `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.10-preview.0",
+  "version": "1.0.11-preview.1",
   "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.79-6",
+    "@github/copilot": "^1.0.79",
     "koffi": "^3.1.0",
     "vscode-jsonrpc": "^8.2.1",
     "zod": "^4.3.6"