@github/copilot-sdk 1.0.8 → 1.0.9-preview.1

package/dist/sessionFsProvider.d.ts

@@ -1,5 +1,5 @@
-import type { SessionFsHandler, SessionFsStatResult, SessionFsReaddirWithTypesEntry, SessionFsSqliteQueryResult as GeneratedSqliteQueryResult, SessionFsSqliteQueryType } from "./generated/rpc.js";
-export type { SessionFsSqliteQueryType };
+import type { SessionFsHandler, SessionFsStatResult, SessionFsReaddirWithTypesEntry, SessionFsSqliteQueryResult as GeneratedSqliteQueryResult, SessionFsSqliteTransactionErrorClass, SessionFsSqliteQueryType } from "./generated/rpc.js";
+export type { SessionFsSqliteQueryType, SessionFsSqliteTransactionErrorClass };
 /**
  * File metadata returned by {@link SessionFsProvider.stat}.
  * Same shape as the generated {@link SessionFsStatResult} but without the
@@ -12,6 +12,31 @@ export type SessionFsFileInfo = Omit<SessionFsStatResult, "error">;
  * `error` field, since providers signal errors by throwing.
  */
 export type SessionFsSqliteQueryResult = Omit<GeneratedSqliteQueryResult, "error">;
+/**
+ * One statement in an atomic SQLite transaction passed to
+ * {@link SessionFsSqliteProvider.transaction}.
+ */
+export interface SessionFsSqliteStatement {
+    /** How to execute: `"exec"` for DDL/multi-statement, `"query"` for SELECT, `"run"` for INSERT/UPDATE/DELETE. */
+    queryType: SessionFsSqliteQueryType;
+    /** SQL statement to execute. */
+    query: string;
+    /** Optional named bind parameters. */
+    params?: Record<string, string | number | null>;
+}
+/**
+ * Error thrown by {@link SessionFsSqliteProvider.transaction} to classify a
+ * transaction failure for the runtime.
+ *
+ * Any other thrown value is reported as `"fatal"`. Throw this with
+ * `"busyOrLocked"` when SQLite reported BUSY/LOCKED before commit and the
+ * transaction was rolled back, so the runtime knows the call is safe to retry.
+ */
+export declare class SessionFsSqliteTransactionFailure extends Error {
+    /** Failure classification reported to the runtime. */
+    readonly errorClass: SessionFsSqliteTransactionErrorClass;
+    constructor(message: string, errorClass?: SessionFsSqliteTransactionErrorClass);
+}
 /**
  * SQLite operations for the per-session database.
  * Implementers provide query execution and existence checking.
@@ -25,6 +50,17 @@ export interface SessionFsSqliteProvider {
      * @param params - Optional named bind parameters.
      */
     query(queryType: SessionFsSqliteQueryType, query: string, params?: Record<string, string | number | null>): Promise<SessionFsSqliteQueryResult | undefined>;
+    /**
+     * Execute `statements` atomically against the per-session database.
+     *
+     * Apply busy handling to every statement and roll back the whole batch if
+     * any statement fails. Throw {@link SessionFsSqliteTransactionFailure} to
+     * classify the failure; any other thrown value is reported as `"fatal"`.
+     *
+     * @param statements - Statements to execute in order inside a single transaction.
+     * @returns One result per statement, in the same order.
+     */
+    transaction?(statements: SessionFsSqliteStatement[]): Promise<SessionFsSqliteQueryResult[]>;
     /**
      * Check whether the per-session database already exists, without creating it.
      */

package/dist/sessionFsProvider.js

@@ -1,3 +1,12 @@
+class SessionFsSqliteTransactionFailure extends Error {
+  /** Failure classification reported to the runtime. */
+  errorClass;
+  constructor(message, errorClass = "fatal") {
+    super(message);
+    this.name = "SessionFsSqliteTransactionFailure";
+    this.errorClass = errorClass;
+  }
+}
 function normalizeSqliteParams(params) {
   if (!params) {
     return void 0;
@@ -113,6 +122,29 @@ function createSessionFsAdapter(provider) {
       );
       return result ?? { rows: [], columns: [], rowsAffected: 0 };
     },
+    sqliteTransaction: async ({ statements }) => {
+      if (!provider.sqlite?.transaction) {
+        return {
+          results: [],
+          error: {
+            errorClass: "fatal",
+            message: "SQLite transactions are not supported by this provider"
+          }
+        };
+      }
+      try {
+        const results = await provider.sqlite.transaction(
+          statements.map((statement) => ({
+            queryType: statement.queryType,
+            query: statement.query,
+            params: normalizeSqliteParams(statement.params)
+          }))
+        );
+        return { results: results.map((result) => ({ ...result })) };
+      } catch (err) {
+        return { results: [], error: toSqliteTransactionError(err) };
+      }
+    },
     sqliteExists: async () => {
       if (!provider.sqlite) {
         throw new Error("SQLite is not supported by this provider");
@@ -126,6 +158,16 @@ function toSessionFsError(err) {
   const code = e.code === "ENOENT" ? "ENOENT" : "UNKNOWN";
   return { code, message: e.message ?? String(err) };
 }
+function toSqliteTransactionError(err) {
+  if (err instanceof SessionFsSqliteTransactionFailure) {
+    return { errorClass: err.errorClass, message: err.message };
+  }
+  return {
+    errorClass: "fatal",
+    message: err instanceof Error ? err.message : String(err)
+  };
+}
 export {
+  SessionFsSqliteTransactionFailure,
   createSessionFsAdapter
 };

package/dist/types.d.ts

@@ -20,6 +20,9 @@ export type { SessionFsFileInfo } from "./sessionFsProvider.js";
 export type { SessionFsSqliteQueryResult } from "./sessionFsProvider.js";
 export type { SessionFsSqliteQueryType } from "./sessionFsProvider.js";
 export type { SessionFsSqliteProvider } from "./sessionFsProvider.js";
+export type { SessionFsSqliteStatement } from "./sessionFsProvider.js";
+export type { SessionFsSqliteTransactionErrorClass } from "./sessionFsProvider.js";
+export { SessionFsSqliteTransactionFailure } from "./sessionFsProvider.js";
 export type { LlmInferenceHeaders } from "./generated/rpc.js";
 export type { CopilotRequestContext } from "./copilotRequestHandler.js";
 export { CopilotRequestHandler, CopilotWebSocketHandler, CopilotWebSocketCloseStatus, CopilotWebSocketForwarder, } from "./copilotRequestHandler.js";
@@ -1154,6 +1157,45 @@ export interface ErrorOccurredHookOutput {
 export type ErrorOccurredHandler = (input: ErrorOccurredHookInput, invocation: {
     sessionId: string;
 }) => Promise<ErrorOccurredHookOutput | void> | ErrorOccurredHookOutput | void;
+/**
+ * Input for the agent-stop hook.
+ *
+ * Fires for the top-level (main) agent when it reaches a natural terminal stop
+ * — i.e. the agent has gone idle without a pending non-terminal tool call and
+ * was not aborted or blocked by a rejected tool. (For sub-agents, the runtime
+ * fires a separate sub-agent stop lifecycle.)
+ */
+export interface AgentStopHookInput extends BaseHookInput {
+    /** Why the agent stopped (for example, `"end_turn"`). */
+    stopReason?: string;
+    /** Path to the on-disk session transcript, when available. */
+    transcriptPath?: string;
+    /**
+     * True when this stop is a re-entry triggered by a previous agent-stop
+     * `block` decision (Claude-compatible `stop_hook_active` semantics). Lets a
+     * handler avoid blocking indefinitely.
+     */
+    stopHookActive?: boolean;
+}
+/**
+ * Output for the agent-stop hook.
+ *
+ * Return `{ decision: "block", reason }` to keep the agent running: the
+ * `reason` is enqueued as a follow-up user message so the agent continues
+ * working (for example, to remediate findings surfaced by the hook). The
+ * runtime caps consecutive blocks to prevent runaway loops. Returning nothing
+ * (or omitting `decision`) lets the agent stop normally.
+ */
+export interface AgentStopHookOutput {
+    decision?: "block";
+    reason?: string;
+}
+/**
+ * Handler for the agent-stop hook.
+ */
+export type AgentStopHandler = (input: AgentStopHookInput, invocation: {
+    sessionId: string;
+}) => Promise<AgentStopHookOutput | void> | AgentStopHookOutput | void;
 /**
  * Configuration for session hooks
  */
@@ -1197,6 +1239,15 @@ export interface SessionHooks {
      * Called when an error occurs
      */
     onErrorOccurred?: ErrorOccurredHandler;
+    /**
+     * Called when the top-level agent reaches a natural terminal stop (it went
+     * idle without pending work and was not aborted). Return
+     * `{ decision: "block", reason }` to keep the agent running with `reason`
+     * enqueued as a follow-up message — for example, to have the agent
+     * remediate findings the handler surfaced. Returning nothing lets the
+     * agent stop.
+     */
+    onAgentStop?: AgentStopHandler;
 }
 /**
  * Base interface for MCP server configuration.
@@ -1302,8 +1353,8 @@ export interface CustomAgentConfig {
     model?: string;
     /**
      * Reasoning effort level for this agent's model.
-     * When omitted, no per-agent override is sent and the backend chooses its
-     * default. The parent session effort is not inherited.
+     * When omitted, the runtime resolves the effort from model configuration,
+     * then inherits the parent effort only if this agent uses the same model.
      */
     reasoningEffort?: ReasoningEffort;
 }
@@ -1474,6 +1525,45 @@ export interface CanvasProviderIdentity {
     /** Optional display name surfaced as the canvas extension name. */
     name?: string;
 }
+/**
+ * Static resource ceilings declared by a factory before it runs.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface FactoryLimits {
+    /** Maximum number of factory subagents that may run concurrently. Must be positive when present. */
+    maxConcurrentSubagents?: number;
+    /** Maximum total number of factory subagents that may be spawned. Must be positive when present. */
+    maxTotalSubagents?: number;
+    /** Maximum AI credits consumed by factory subagents and descendants. This post-paid ceiling is soft. */
+    maxAiCredits?: number;
+    /**
+     * Maximum accumulated active-execution time, in seconds. Active execution includes the entire extension body,
+     * subprocess waits, queued-agent waits, and sleeps. The limit is armed from the remaining headroom when a run
+     * resumes; time between attempts is not counted. Must be finite and positive when present.
+     */
+    timeoutSeconds?: number;
+}
+/**
+ * Registration metadata for an extension-authored factory.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export interface FactoryMeta {
+    /** Stable factory name used for invocation. */
+    name: string;
+    /** Human-readable factory description. */
+    description: string;
+    /** Display metadata for the progress phases the factory may report. */
+    phases: Array<{
+        title: string;
+        detail?: string;
+    }>;
+    /** Optional resource ceilings presented to the user before execution. */
+    limits?: FactoryLimits;
+}
 /**
  * Provider-scoped options for the Copilot API (CAPI).
  *
@@ -1580,13 +1670,8 @@ export interface SessionConfigBase {
      */
     configDirectory?: string;
     /**
-     * When true, automatically discovers MCP server configurations (e.g. `.mcp.json`,
-     * `.vscode/mcp.json`) and skill directories from the working directory and merges
-     * them with any explicitly provided `mcpServers` and `skillDirectories`, with
-     * explicit values taking precedence on name collision.
-     *
-     * Note: custom instruction files (`.github/copilot-instructions.md`, `AGENTS.md`, etc.)
-     * are always loaded from the working directory regardless of this setting.
+     * Enables runtime discovery of supported configuration. Explicitly supplied
+     * configuration takes precedence over discovered values.
      *
      * @default false
      */
@@ -2157,7 +2242,7 @@ export interface ProviderConfig {
      */
     azure?: {
         /**
-         * API version. Defaults to "2024-10-21".
+         * API version. When omitted, the runtime uses the GA versionless v1 route.
          */
         apiVersion?: string;
     };

package/dist/types.js

@@ -1,4 +1,5 @@
 import { createSessionFsAdapter } from "./sessionFsProvider.js";
+import { SessionFsSqliteTransactionFailure } from "./sessionFsProvider.js";
 import {
   CopilotRequestHandler,
   CopilotWebSocketHandler,
@@ -122,6 +123,7 @@ export {
   CopilotWebSocketHandler,
   RuntimeConnection,
   SYSTEM_MESSAGE_SECTIONS,
+  SessionFsSqliteTransactionFailure,
   approveAll,
   convertMcpCallToolResult,
   createSessionFsAdapter,

package/docs/extensions.md

@@ -56,4 +56,5 @@ The `session` object provides methods for sending messages, logging to the timel
 ## Further Reading
 
 - `examples.md` — Practical code examples for tools, hooks, events, and complete extensions
+- `factories.md`: Authoring, running, resuming, and observing Agent Factories
 - `agent-author.md` — Step-by-step workflow for agents authoring extensions programmatically

package/docs/factories.md

@@ -0,0 +1,240 @@
+# Agent Factories
+
+Agent Factories are extension-authored, session-scoped workflows that coordinate subagents and durable steps. The API is experimental.
+
+## Define and register a factory
+
+Use `defineFactory` and pass the returned handle to `joinSession`:
+
+```js
+import { defineFactory, joinSession } from "@github/copilot-sdk/extension";
+
+const reviewChanged = defineFactory({
+    meta: {
+        name: "review-changed",
+        description:
+            "Review changed files and verify the findings. " +
+            "args: { files: string[] } — the paths to review.",
+        phases: [{ title: "Review" }, { title: "Verify" }],
+        limits: {
+            maxConcurrentSubagents: 3,
+            maxTotalSubagents: 10,
+            timeoutSeconds: 90.5,
+            maxAiCredits: 5,
+        },
+    },
+    run: async (ctx) => {
+        ctx.phase("Review");
+        const reviews = await ctx.parallel(
+            ctx.args.files.map(
+                (file) => () => ctx.agent(`Review ${file}`, { label: `Review ${file}` })
+            )
+        );
+
+        ctx.phase("Verify");
+        const report = await ctx.step("report", () => ({ reviews }));
+        ctx.log(`Completed factory run ${ctx.runId}`);
+        return report;
+    },
+});
+
+const session = await joinSession({ factories: [reviewChanged] });
+```
+
+Factory metadata contains a stable `name`, a human-readable `description`, declared `phases`, and optional `limits`. Phase entries contain a `title` and optional `detail`.
+
+There is no declared schema for `ctx.args`. The `run_factory` tool forwards `args` verbatim and its parameter is untyped, so **the `description` is the only thing telling an agent what arguments to supply** — state the expected shape there whenever a factory reads `ctx.args`, as the example above does. Arguments supplied by an extension calling `session.factory.run(...)` directly are typed through `defineFactory<TArgs>`, but that typing does not reach the model. A factory that reads `ctx.args` should validate it rather than assume a shape.
+
+`defineFactory<TArgs, TResult>` accepts a `run(context)` function returning `Promise<TResult>`, where `TResult` is `JsonValue | void`. Objects, arrays, strings, numbers, booleans, and `null` are valid results. Returning `undefined` completes the factory with no result. Other non-JSON values are rejected.
+
+## Factory context
+
+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.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 full session returned by `joinSession`.
+- `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.
+
+### Subagent calls
+
+`ctx.agent(prompt, options?)` spawns one factory-scoped subagent and awaits it. Without a schema it resolves to the subagent's final text. With `options.schema` it resolves to the parsed JSON value.
+
+**Identical calls are memoized into one subagent.** Each call is journaled by its canonical prompt and options, including `label`. Two calls with the same prompt and the same options return one shared result — even when issued concurrently. To spawn N *independent* subagents, give each a unique `label` or vary the prompt:
+
+```js
+// One subagent, awaited five times — almost certainly not what you want.
+await ctx.parallel([1, 2, 3, 4, 5].map(() => () => ctx.agent("Find a bug")));
+
+// Five independent subagents.
+await ctx.parallel(
+    [1, 2, 3, 4, 5].map((i) => () => ctx.agent("Find a bug", { label: `finder:${i}` }))
+);
+```
+
+**An ordinary failure resolves to `null` — it does not throw.** A subagent that errors, returns nothing, or (with a schema) produces output that still fails to parse or match after its one retry resolves `null`. Always guard the result before using it, including a bare `await ctx.agent(...)`:
+
+```js
+const finding = await ctx.agent(prompt, { label: "inspector" });
+if (!finding) return { finding: null };
+```
+
+Cancellation and hard runtime failures — a reached limit, a durable-state failure — reject instead, aborting the run. When filtering results, prefer `v => v !== null` over `Boolean`, which also discards a valid `false`, `0`, or `""`.
+
+**`schema` is a structural subset of JSON Schema, not a validator.** Honored: `type`, `required`, `enum`, `const`, recursive `properties`/`items`, and `anyOf`/`oneOf`/`allOf` — where `oneOf` is treated as `anyOf`, meaning at least one branch matches rather than exactly one. Ignored and *not* enforced: `additionalProperties`, `pattern`, `minLength`/`maxLength`, `format`, numeric ranges, and boolean schemas. Do not rely on an ignored keyword to constrain a result. A schema call retries once on a parse or match failure, so it may spawn twice, and both spawns count toward `maxTotalSubagents`.
+
+### Choosing between pipeline and parallel
+
+Prefer `pipeline` for multi-stage work. It has no barrier between stages, so each item advances as soon as its own prior stage finishes.
+
+Reach for a barrier — `parallel` between stages — only when a stage genuinely needs every prior result at once: deduplicating or merging across the full set, an early exit based on the total, or a prompt that compares one result against the others. Needing to map, filter, or flatten is not a reason to use a barrier; do that inside a pipeline stage. Barrier latency is real: if the slowest of N subagents takes three times the fastest, a barrier wastes the rest of the pool's time.
+
+See [factory-patterns.md](./factory-patterns.md) for composable orchestration patterns built on these primitives.
+
+## Resource limits
+
+Limits may be declared in `meta.limits` and overridden per invocation. All limits must be positive when present.
+
+- `maxConcurrentSubagents`: Positive integer concurrent-subagent cap. Additional subagents wait in a queue. Queueing applies backpressure and does not fail the run.
+- `maxTotalSubagents`: Positive integer cumulative admission cap. An attempted subagent beyond the cap ends the attempt with failure kind `maxTotalSubagents`.
+- `timeoutSeconds`: Positive finite number of seconds, including positive fractions, capped at `2_147_483.647`. It measures accumulated active-execution time across attempts, including the extension body, subprocess waits, queued-agent waits, and sleeps. Time between attempts is excluded. The timeout is soft because already-running work may take time to stop. Its failure kind is `timeoutSeconds`.
+- `maxAiCredits`: Positive finite AI-credit budget for the whole run's factory subagent subtree, including descendants. AI credits are GitHub Copilot's universal usage metric. This is a soft, post-paid ceiling, so completed or parallel turns can settle above it before the run stops. Accounting is fail-closed: an accounting failure stops a budgeted run rather than allowing untracked use. Its failure kind is `maxAiCredits`.
+
+`maxTotalSubagents`, `timeoutSeconds`, and `maxAiCredits` use reject-and-retry semantics. A rejected attempt ends with run status `error` and `failure.type` set to `factory_limit_reached`. The failed run keeps its ID, arguments, journal, and accounting. Resume the run with a raised limit when additional work is approved. Previously consumed resources still count.
+
+## Run and resume
+
+Run by registered name or handle:
+
+```ts
+const run = await session.factory.run("review-changed", {
+    args: { files: ["src/a.ts"] },
+    limits: { maxAiCredits: 3 },
+});
+
+if (run.status === "completed") {
+    console.log(run.result);
+} else {
+    console.error(`run ${run.runId} ended as ${run.status}`, run.failure ?? run.error);
+}
+```
+
+The name overload is:
+
+```ts
+session.factory.run(
+    name: string,
+    options?: { args?: JsonValue; limits?: FactoryLimits },
+): Promise<FactoryRunResult>;
+```
+
+Resume by run ID without resending the name or arguments:
+
+```ts
+const run = await session.factory.resume(runId, {
+    limits: { maxAiCredits: 6 },
+});
+```
+
+The signature is:
+
+```ts
+session.factory.resume(
+    runId: string,
+    options?: { limits?: FactoryLimits },
+): 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`.
+
+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.
+
+The agent-facing `run_factory` tool has exactly two input branches:
+
+```ts
+{ name: string; args?: JsonValue; limits?: FactoryLimits }
+{ resumeFromRunId: string; limits?: FactoryLimits }
+```
+
+## Authoring a factory from inside a session
+
+The agent-facing `factories_manage` tool writes a factory into a session-scoped extension at runtime with `operation: "author"`. The rules above all apply, plus one constraint that does not affect an extension author.
+
+**The `run` body is self-contained.** It is emitted verbatim into a generated module as a single async function expression. It closes over nothing: not the conversation that authored it, and not any authoring-time binding. Only its own locals, its `ctx` parameter, and standard Node and JavaScript globals are in scope, so every schema, constant, and helper must be defined *inside* the function. The generated module imports the SDK itself; the expression cannot add static `import` statements or use `require`. Load anything else with a dynamic `await import("...")` in the body.
+
+```js
+async ({ args, agent, phase }) => {
+    // Defined inside — there is no outer scope to close over.
+    const VERDICT = { type: "object", properties: { real: { type: "boolean" } }, required: ["real"] };
+
+    phase("Inspect");
+    const finding = await agent(`Name one likely bug in ${args.file ?? "the code"}.`, {
+        label: "inspector",
+    });
+    if (!finding) return { finding: null, real: false };
+
+    phase("Verify");
+    const verdict = await agent(`Is this a real bug? Claim: ${finding}`, {
+        label: "verifier",
+        schema: VERDICT,
+    });
+    return { finding, real: verdict?.real === true };
+};
+```
+
+Authoring registers the factory but does not run it. Invoke it afterwards with `run_factory`. Use `factories_manage` with `operation: "list"` to see the factories already registered in the session and `operation: "inspect"` to read one factory's description, phases, and limits before running it.
+
+## Observe a run
+
+The calling session can inspect its own factory runs:
+
+```ts
+const runs = await session.factory.listRuns();
+const detail = await session.factory.getRunDetail(runId);
+const page = await session.factory.getRunProgress(runId, {
+    phaseId,
+    afterSeq,
+    beforeSeq,
+    limit,
+});
+```
+
+- `listRuns()` returns summaries in durable creation order.
+- `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.
+
+`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:
+
+```ts
+const settled = await session.factory.waitForRun(runId);
+if (settled.status === "completed") {
+    console.log(settled.result);
+}
+```
+
+It watches `factory.run_updated` and re-reads the durable envelope on each invalidation, collapsing a burst of events into a single in-flight read. A low-frequency periodic re-read runs alongside the subscription, so a dropped or missing invalidation degrades into a slightly late resolution rather than an unbounded wait. Pass a `signal` to stop waiting:
+
+```ts
+const controller = new AbortController();
+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.
+
+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.
+
+Revisions cover durable lifecycle, accounting, phase, agent, and progress changes. Continuous read-time fields can change without a new revision. These include `observedAt`, active-time calculations, live counts, and a live agent's status or prompt-safe activity text. Factory prompts are never exposed by these APIs. A run is visible only through the session that owns it.