Add the Agent Factories authoring surface

Agent Factories let a trusted extension declare a JavaScript closure that
orchestrates a fleet of subagents, and invoke it by name. The runtime half
shipped in copilot-agent-runtime#12953 and #13077; this is the SDK half.
The feature is dark behind the runtime's `agent_factories` flag plus its
billing gate, and every public type is marked `@experimental`.

RPC surface
- Generated wire types for the factory session methods (`run`, `resume`,
  `getRun`, `listRuns`, `getRunDetail`, `getRunProgress`, `cancel`), the
  reverse `factory.execute` / `factory.abort` calls, run envelopes,
  registration metadata, and the observability DTOs.
- Fixes opaque-JSON codegen so a factory's args and result can be any JSON
  value rather than an object alone, which also lets a void factory
  complete without a result.

Authoring harness
- `defineFactory({ meta, run })` returns an opaque handle; an extension
  registers it through `joinSession({ factories: [...] })`. Only metadata
  crosses to the runtime — the closure stays in the extension process and
  is invoked over the reverse `factory.execute` RPC.
- The `run()` context: `args`, the extension's full `session`, a per-run
  `signal`, `runId`, plus `agent()` (one single-turn subagent, optionally
  schema-constrained), `step()` (journal-backed memoization), `parallel()`,
  `pipeline()`, and `phase()` / `log()` progress markers. `factory()`
  throws, because nesting is forbidden.
- `session.factory.*` friendly wrappers, including `resume(runId)`, which
  reuses the persisted name, arguments, journal, and accounting so a caller
  never re-sends them.
- Declared limits (`maxConcurrentSubagents`, `maxTotalSubagents`,
  `timeoutSeconds`, `maxAiCredits`) validated at the authoring boundary.
- Strict JSON validation shared by factory results and journaled `step()`
  producers, so a lossy value is rejected rather than silently mutating on
  a resumed replay.

`run()` and `resume()` resolve with the run envelope for every outcome —
completed, error, halted, or cancelled — and reject only when no run
exists (an unknown factory, a declined approval, an already-active
session). This keeps the signature stable for the planned background-only
execution mode, which changes a run's timing and status but not its shape.

Authoring documentation lives in `nodejs/docs/factories.md`.

Author: MRayermannMSFT

nodejs/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

nodejs/docs/factories.md

@@ -0,0 +1,150 @@
+# 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",
+        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`.
+
+`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.
+- `ctx.agent(prompt, options?)`: Runs one factory-owned subagent. Options include `label`, `schema`, and `model`.
+- `ctx.parallel(thunks)`: Runs thunks concurrently and returns `null` for a thunk that throws, except cooperative cancellation propagates.
+- `ctx.pipeline(items, ...stages)`: Flows each item through every stage without a barrier between stages.
+- `ctx.phase(title)`: Starts a named progress phase.
+- `ctx.log(message)`: Appends a progress line.
+- `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.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.
+
+## 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`. Only failures that occur *before* a run exists reject: an unknown factory name, a declined approval, or an already-active session. Pre-execution resume failures throw `FactoryResumeError`, whose `code` is one of `not_found`, `non_resumable`, `already_active`, `reapproval_declined`, or `no_approval_provider`.
+
+The agent-facing `run_factory` tool has exactly two input branches:
+
+```ts
+{ name: string; args?: JsonValue; limits?: FactoryLimits }
+{ resumeFromRunId: string; limits?: FactoryLimits }
+```
+
+## 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.
+
+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/client.ts

@@ -35,6 +35,7 @@ import {
 } from "./generated/rpc.js";
 import type {
     GitHubTelemetryNotification,
+    JsonValue,
     OpenCanvasInstance,
     SessionUpdateOptionsParams,
 } from "./generated/rpc.js";
@@ -85,6 +86,7 @@ import type {
     TypedSessionLifecycleHandler,
 } from "./types.js";
 import { defaultJoinSessionPermissionHandler } from "./types.js";
+import type { FactoryHandle } from "./factory.js";
 
 /**
  * Minimum protocol version this SDK can communicate with.
@@ -1663,6 +1665,23 @@ export class CopilotClient {
      * ```
      */
     async resumeSession(sessionId: string, config: ResumeSessionConfig): Promise<CopilotSession> {
+        return this.resumeSessionInternal(sessionId, config);
+    }
+
+    /** @internal */
+    async resumeSessionForExtension(
+        sessionId: string,
+        config: ResumeSessionConfig,
+        factories?: FactoryHandle[]
+    ): Promise<CopilotSession> {
+        return this.resumeSessionInternal(sessionId, config, factories);
+    }
+
+    private async resumeSessionInternal(
+        sessionId: string,
+        config: ResumeSessionConfig,
+        factories?: FactoryHandle[]
+    ): Promise<CopilotSession> {
         if (!this.connection) {
             await this.start();
         }
@@ -1679,6 +1698,7 @@ export class CopilotClient {
         session.registerTools(config.tools);
         session.registerCanvases(config.canvases);
         session.registerCommands(config.commands);
+        session.registerFactories(factories);
         const {
             wireProvider: bearerWireProvider,
             wireProviders: bearerWireProviders,
@@ -1750,6 +1770,7 @@ export class CopilotClient {
                 })),
                 toolSearch: config.toolSearch,
                 canvases: config.canvases?.map((canvas) => canvas.declaration),
+                factories: factories?.map((factory) => factory.meta),
                 requestCanvasRenderer: config.requestCanvasRenderer,
                 requestExtensions: config.requestExtensions,
                 extensionSdkPath: config.extensionSdkPath,
@@ -2981,7 +3002,7 @@ export class CopilotClient {
         sessionId: string;
         hookType: string;
         input: unknown;
-    }): Promise<{ output?: unknown }> {
+    }): Promise<{ output?: JsonValue }> {
         if (
             !params ||
             typeof params.sessionId !== "string" ||
@@ -2996,7 +3017,7 @@ export class CopilotClient {
         }
 
         const output = await session._handleHooksInvoke(params.hookType, params.input);
-        return { output };
+        return output === undefined ? {} : { output: JSON.parse(JSON.stringify(output)) };
     }
 
     private async handleSystemMessageTransform(params: {

nodejs/src/extension.ts

@@ -6,10 +6,10 @@ import { CopilotClient } from "./client.js";
 import type { CopilotSession } from "./session.js";
 import {
     defaultJoinSessionPermissionHandler,
-    type ExtensionInfo,
     type PermissionHandler,
     type ResumeSessionConfig,
 } from "./types.js";
+import type { FactoryHandle } from "./factory.js";
 
 export {
     Canvas,
@@ -27,9 +27,33 @@ export type JoinSessionConfig = Omit<
     "onPermissionRequest" | "extensionSdkPath"
 > & {
     onPermissionRequest?: PermissionHandler;
+    /**
+     * Factory handles to register when the extension joins the session.
+     *
+     * @experimental Part of the experimental Agent Factories surface and may
+     * change or be removed in future SDK or CLI releases.
+     */
+    factories?: FactoryHandle[];
 };
 
-export type { ExtensionInfo };
+export type { ExtensionInfo, FactoryLimits, FactoryMeta } from "./types.js";
+export {
+    defineFactory,
+    FactoryResumeError,
+    type RunOptions,
+    type ResumeOptions,
+    type FactoryResumeErrorCode,
+    type SessionFactoryApi,
+    type FactoryAgentOptions,
+    type FactoryContext,
+    type FactoryDefinition,
+    type FactoryHandle,
+    type FactoryJsonSchema,
+    type JsonValue,
+    type FactoryPipelineStage,
+    type FactoryStepOptions,
+    type FactoryRunResult,
+} from "./factory.js";
 
 /**
  * Joins the current foreground session.
@@ -58,14 +82,22 @@ export async function joinSession(config: JoinSessionConfig = {}): Promise<Copil
     // at the type level — untyped (JS) callers can still slip it through, and
     // honoring it here would be misleading since the extension subprocess has
     // already been forked by the host with the SDK the host chose.
-    const { extensionSdkPath: _stripped, ...rest } = config as JoinSessionConfig & {
+    const {
+        extensionSdkPath: _stripped,
+        factories,
+        ...rest
+    } = config as JoinSessionConfig & {
         extensionSdkPath?: string;
     };
     void _stripped;
 
-    return client.resumeSession(sessionId, {
-        ...rest,
-        onPermissionRequest: config.onPermissionRequest ?? defaultJoinSessionPermissionHandler,
-        suppressResumeEvent: config.suppressResumeEvent ?? true,
-    });
+    return client.resumeSessionForExtension(
+        sessionId,
+        {
+            ...rest,
+            onPermissionRequest: config.onPermissionRequest ?? defaultJoinSessionPermissionHandler,
+            suppressResumeEvent: config.suppressResumeEvent ?? true,
+        },
+        factories
+    );
 }