Add session.factory.waitForRun for run settlement

Adds an explicit settlement await to the factory API so a caller can block
on a run reaching a terminal status without hand-rolling a poll loop.

`waitForRun(runId, { signal? })` resolves with the terminal envelope once the
run settles into completed, error, halted, or cancelled, and resolves
immediately when it has already settled. It subscribes to the run's
`factory.run_updated` invalidation events and re-reads the durable envelope
rather than polling on a timer. The subscription is installed before the first
read so a transition landing between the two cannot be missed, and re-reads are
serialized so a burst of events collapses into one in-flight read — the run's
revision advances once per operation, so bursts are the normal case. The
subscription is released on settle, abort, and read failure. Aborting rejects
the wait and leaves the run executing; cancel() remains the way to stop it.

Also exports `isFactoryRunTerminal(status)` and the `FactoryRunStatus` type so
callers driving their own loop share one definition of terminal.

This is additive and carries no wire change: it is built entirely on the
existing `getRun` method and `factory.run_updated` session event, so it is
correct against the current foreground runtime, where it resolves on the first
read. It becomes load-bearing under background execution, where `run()` resolves
with a running envelope and `result` is only readable after settlement.

Verification: 94 factory unit tests pass (81 existing, 13 new). The runtime's
Agent Factories E2E suite passes 19/19 under STRICT_CAPTURES against a build of
this branch. The coalescing and unsubscribe tests were mutation-tested — each
goes red with its guard removed.

Author: MRayermannMSFT

nodejs/docs/factories.md

@@ -210,6 +210,25 @@ const page = await session.factory.getRunProgress(runId, {
 
 `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 rather than polling on a timer, and it collapses a burst of invalidation events into a single in-flight read. 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.

nodejs/src/extension.ts

@@ -40,6 +40,7 @@ export type { ExtensionInfo, FactoryLimits, FactoryMeta } from "./types.js";
 export {
     defineFactory,
     FactoryResumeError,
+    isFactoryRunTerminal,
     type RunOptions,
     type ResumeOptions,
     type FactoryResumeErrorCode,
@@ -53,6 +54,7 @@ export {
     type FactoryPipelineStage,
     type FactoryStepOptions,
     type FactoryRunResult,
+    type FactoryRunStatus,
     type FactoryRunSummary,
     type FactoryRunDetail,
     type FactoryProgressPage,

nodejs/src/factory.ts

@@ -7,6 +7,7 @@ import type {
     FactoryProgressPage,
     FactoryRunDetail,
     FactoryRunResult,
+    FactoryRunStatus,
     FactoryRunSummary,
 } from "./generated/rpc.js";
 import type { CopilotSession } from "./session.js";
@@ -25,9 +26,34 @@ export type {
     FactoryProgressPage,
     FactoryRunDetail,
     FactoryRunResult,
+    FactoryRunStatus,
     FactoryRunSummary,
 } from "./generated/rpc.js";
 
+/**
+ * Run statuses a factory run can no longer move away from.
+ *
+ * A run is either still in flight (`pending`, `running`) or settled into one of
+ * these four. Terminal state is final: once written it is never reopened, so a
+ * caller that observes one of these can stop watching the run.
+ */
+const FACTORY_TERMINAL_STATUSES: ReadonlySet<FactoryRunStatus> = new Set([
+    "completed",
+    "halted",
+    "cancelled",
+    "error",
+]);
+
+/**
+ * Whether a factory run status is terminal.
+ *
+ * @experimental Part of the experimental Agent Factories surface and may
+ * change or be removed in future SDK or CLI releases.
+ */
+export function isFactoryRunTerminal(status: FactoryRunStatus): boolean {
+    return FACTORY_TERMINAL_STATUSES.has(status);
+}
+
 declare const factoryHandleBrand: unique symbol;
 
 /** A value that can be represented losslessly on the SDK JSON wire. */
@@ -230,6 +256,24 @@ export interface SessionFactoryApi {
     resume(runId: string, options?: ResumeOptions): Promise<FactoryRunResult>;
     /** Read the latest durable envelope for a factory run. */
     getRun(runId: string): Promise<FactoryRunResult>;
+    /**
+     * Wait for a run to settle and resolve with its terminal envelope.
+     *
+     * Resolves as soon as the run reaches `completed`, `error`, `halted`, or
+     * `cancelled`, and resolves immediately when it has already settled. A
+     * terminal envelope is final, so the resolved value never changes
+     * afterwards.
+     *
+     * This watches the run's `factory.run_updated` invalidation events and
+     * re-reads the durable envelope rather than polling on a timer. Pass a
+     * `signal` to stop waiting; aborting rejects and has no effect on the run
+     * itself, which keeps executing. Use {@link SessionFactoryApi.cancel} to
+     * actually stop it.
+     */
+    waitForRun(
+        runId: string,
+        options?: { signal?: AbortSignal }
+    ): Promise<FactoryRunResult>;
     /** List this session's durable factory runs in creation order. */
     listRuns(): Promise<FactoryRunSummary[]>;
     /** Read durable phases, direct agents, and the latest progress tail for a run. */

nodejs/src/index.ts

@@ -12,7 +12,7 @@ export { CopilotClient } from "./client.js";
 export { RuntimeConnection } from "./types.js";
 export { BuiltInTools, ToolSet } from "./toolSet.js";
 export { CopilotSession, type AssistantMessageEvent } from "./session.js";
-export { defineFactory, FactoryResumeError } from "./factory.js";
+export { defineFactory, FactoryResumeError, isFactoryRunTerminal } from "./factory.js";
 export {
     Canvas,
     CanvasError,
@@ -178,6 +178,7 @@ export type {
     FactoryPipelineStage,
     FactoryStepOptions,
     FactoryRunResult,
+    FactoryRunStatus,
     FactoryRunSummary,
     FactoryRunDetail,
     FactoryProgressPage,

nodejs/src/session.ts

@@ -64,7 +64,9 @@ import type {
 import {
     getFactoryDefinition,
     FactoryResumeError,
+    isFactoryRunTerminal,
     type FactoryResumeErrorCode,
+    type FactoryRunResult,
     type RunOptions,
     type SessionFactoryApi,
     type FactoryContext,
@@ -447,13 +449,92 @@ export class CopilotSession {
             return response.run;
         }) as SessionFactoryApi["resume"],
         getRun: (runId) => this.rpc.factory.getRun({ runId }),
+        waitForRun: (runId, options) => this.waitForFactoryRun(runId, options?.signal),
         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: (runId) => this.rpc.factory.cancel({ runId }),
     };
 
+    /**
+     * Resolve when a factory run reaches a terminal status.
+     *
+     * The subscription is installed *before* the first read so a transition
+     * landing between the two cannot be missed, and re-reads are serialized so
+     * overlapping invalidation events cannot interleave — the run's revision
+     * advances once per operation, so a burst of events is common and must
+     * collapse into a single in-flight read.
+     */
+    private waitForFactoryRun(
+        runId: string,
+        signal?: AbortSignal
+    ): Promise<FactoryRunResult> {
+        const abortError = (): unknown =>
+            signal?.reason ?? new DOMException("Factory run wait was aborted", "AbortError");
+        if (signal?.aborted === true) {
+            return Promise.reject(abortError());
+        }
+
+        return new Promise<FactoryRunResult>((resolve, reject) => {
+            let settled = false;
+            let reading = false;
+            let rereadRequested = false;
+            let unsubscribe: (() => void) | undefined;
+            let onAbort: (() => void) | undefined;
+
+            const finish = (complete: () => void): void => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                unsubscribe?.();
+                if (onAbort !== undefined) {
+                    signal?.removeEventListener("abort", onAbort);
+                }
+                complete();
+            };
+
+            const read = async (): Promise<void> => {
+                if (settled) {
+                    return;
+                }
+                if (reading) {
+                    rereadRequested = true;
+                    return;
+                }
+                reading = true;
+                try {
+                    do {
+                        rereadRequested = false;
+                        const envelope = await this.rpc.factory.getRun({ runId });
+                        if (isFactoryRunTerminal(envelope.status)) {
+                            finish(() => resolve(envelope));
+                            return;
+                        }
+                    } while (rereadRequested && !settled);
+                } catch (error) {
+                    finish(() => reject(error));
+                } finally {
+                    reading = false;
+                }
+            };
+
+            if (signal !== undefined) {
+                onAbort = (): void => finish(() => reject(abortError()));
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+
+            unsubscribe = this.on("factory.run_updated", (event) => {
+                if (event.data.runId === runId) {
+                    void read();
+                }
+            });
+
+            void read();
+        });
+    }
+
     /**
      * Creates a new CopilotSession instance.
      *