Simplify factory docs so they do not encode transient facts

- Describe ctx.session by what it omits, and point at the extensions_manage guide
- Drop the hardcoded active-run limit, which will become a setting
- Drop the listRuns paging parenthetical

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 5ece6b29-8b10-47aa-ab17-b64c47f5fdcd

Author: MRayermannMSFT

nodejs/docs/factories.md

@@ -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`. It remains the full session, but `factory.run` and `factory.resume` are refused while the factory body runs on the same call path.
+- `ctx.session`: The session returned by `joinSession`, without the APIs that start and resume factory runs. 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`. 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 four top-level runs are already active. 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`, 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 the newest default page (the SDK sends `{}`, so the runtime defaults to 200 runs and caps the page at 500).
+- `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.
 

nodejs/src/factory.ts

@@ -175,10 +175,8 @@ export interface FactoryContext<TArgs extends JsonValue = JsonValue> {
     /** Caller-supplied input, forwarded verbatim. */
     args: TArgs;
     /**
-     * The same full session instance returned by `joinSession`.
-     *
-     * While the factory body runs, `factory.run` and `factory.resume` are
-     * refused on the same call path.
+     * The session instance returned by `joinSession`, without the APIs that
+     * start and resume factory runs.
      */
     session: CopilotSession;
     /** Cooperative cancellation signal for the current factory run. */
@@ -291,7 +289,8 @@ export interface SessionFactoryApi {
      * declined outcome. The model's `run_factory` tool requests permission
      * before a durable row exists; declining it creates no run row. Failures
      * that occur before a run exists (such as an unknown factory or attempting
-     * to start a fifth top-level run while four are active) still reject.
+     * to start a run while the session is at its active top-level run limit)
+     * still reject.
      */
     run(name: string, options?: RunOptions): Promise<FactoryRunResult>;
     run<TArgs extends JsonValue>(
@@ -324,8 +323,7 @@ export interface SessionFactoryApi {
      */
     waitForRun(runId: string, options?: { signal?: AbortSignal }): Promise<FactoryRunResult>;
     /**
-     * List the newest default page (the SDK sends `{}`, so the runtime defaults
-     * to 200 runs and caps the page at 500).
+     * List the newest default page of this session's durable factory runs.
      */
     listRuns(): Promise<FactoryRunSummary[]>;
     /** Read durable phases, direct agents, and the latest progress tail for a run. */

nodejs/test/factory.test.ts

@@ -405,8 +405,7 @@ describe("factories", () => {
     it("documents factory invocation and list paging behavior accurately", () => {
         const guide = readFileSync(new URL("../docs/factories.md", import.meta.url), "utf8");
         const publicApi = readFileSync(new URL("../src/factory.ts", import.meta.url), "utf8");
-        const listRunsPagingWording =
-            "newest default page (the SDK sends `{}`, so the runtime defaults to 200 runs and caps the page at 500)";
+        const listRunsPagingWording = "newest default page of this session's durable factory runs";
         const resumeCodes = [
             "not_found",
             "non_resumable",
@@ -439,26 +438,26 @@ describe("factories", () => {
             "`run_factory` tool requests permission before the durable row exists"
         );
         expect(normalizedGuide).toContain("declining it creates no run row");
-        expect(normalizedGuide).toContain("only when four top-level runs are already active");
+        expect(normalizedGuide).toContain("its maximum number of active top-level runs");
         for (const code of resumeCodes) {
             expect(guide).toContain(`\`${code}\``);
         }
         expect(guide).toContain(
             "Options are exactly `label`, `schema`, `model`, `agent`, `reasoningEffort`, and `contextTier`"
         );
-        expect(normalizedGuide).toContain("full session returned by `joinSession`");
-        expect(normalizedGuide).toContain("factory body runs on the same call path");
+        expect(normalizedGuide).toContain(
+            "session returned by `joinSession`, without the APIs that start and resume factory runs"
+        );
 
         expect(normalizedPublicApi).toContain("SDK-initiated runs do not request permission");
         expect(normalizedPublicApi).toContain("declining it creates no run row");
-        expect(normalizedPublicApi).toContain("fifth top-level run while four are active");
-        expect(normalizedPublicApi).toContain("SDK-initiated resumes do not request permission");
-        expect(normalizedPublicApi).toContain("with a documented resume code rejects with");
         expect(normalizedPublicApi).toContain(
-            "same full session instance returned by `joinSession`"
+            "while the session is at its active top-level run limit"
         );
+        expect(normalizedPublicApi).toContain("SDK-initiated resumes do not request permission");
+        expect(normalizedPublicApi).toContain("with a documented resume code rejects with");
         expect(normalizedPublicApi).toContain(
-            "factory.run` and `factory.resume` are refused on the same call path"
+            "session instance returned by `joinSession`, without the APIs that start and resume factory runs"
         );
     });