@github/copilot-sdk-darwin-arm64 0.0.1 → 1.0.13-preview.6

package/copilot-sdk/docs/extensions.md

@@ -0,0 +1,81 @@
+# Copilot CLI Extensions
+
+Extensions add custom tools, hooks, and behaviors to the Copilot CLI. They run as separate Node.js processes that communicate with the CLI over JSON-RPC via stdio.
+
+## How Extensions Work
+
+```
+┌─────────────────────┐          JSON-RPC / stdio           ┌──────────────────────┐
+│   Copilot CLI        │ ◄──────────────────────────────────► │  Extension Process   │
+│   (parent process)   │    tool calls, events, hooks        │  (forked child)      │
+│                      │                                      │                      │
+│  • Discovers exts    │                                      │  • Registers tools   │
+│  • Forks processes   │                                      │  • Registers hooks   │
+│  • Routes tool calls │                                      │  • Listens to events │
+│  • Manages lifecycle │                                      │  • Uses SDK APIs     │
+└─────────────────────┘                                      └──────────────────────┘
+```
+
+1. **Discovery**: The CLI scans `.github/extensions/` (project) and the user's copilot config extensions directory for subdirectories containing `extension.mjs`.
+2. **Launch**: Each extension is forked as a child process with `@github/copilot-sdk` available via an automatic module resolver.
+3. **Connection**: The extension calls `joinSession()` which establishes a JSON-RPC connection over stdio to the CLI and attaches to the user's current foreground session.
+4. **Registration**: Tools and hooks declared in the session options are registered with the CLI and become available to the agent.
+5. **Lifecycle**: Extensions are reloaded on `/clear` (or if the foreground session is replaced) and stopped on CLI exit (SIGTERM, then SIGKILL after 5s).
+
+## File Structure
+
+```
+.github/extensions/
+  my-extension/
+    extension.mjs      ← Entry point (required, must be .mjs)
+```
+
+- Only `.mjs` files are supported (ES modules). The file must be named `extension.mjs`.
+- Each extension lives in its own subdirectory.
+- The `@github/copilot-sdk` import is resolved automatically — you don't install it.
+
+## The SDK
+
+Extensions use `@github/copilot-sdk` for all interactions with the CLI:
+
+```js
+import { joinSession } from "@github/copilot-sdk/extension";
+
+const session = await joinSession({
+    tools: [
+        /* ... */
+    ],
+    hooks: {
+        /* ... */
+    },
+});
+```
+
+The `session` object provides methods for sending messages, logging to the timeline, listening to events, and accessing the RPC API. See the `.d.ts` files in the SDK package for full type information.
+
+## Requesting Sensitive Environment Variables
+
+The CLI strips sensitive environment variables (for example `GITHUB_TOKEN`) from every extension process before it starts. An extension that needs one asks for it by name:
+
+```js
+import { joinSession } from "@github/copilot-sdk/extension";
+
+const session = await joinSession({
+    requestedEnvironmentVariables: ["GITHUB_TOKEN"],
+});
+
+// Granted values are in process.env once joinSession resolves.
+const token = process.env.GITHUB_TOKEN;
+```
+
+The CLI prompts the user with the extension's name and the exact list of variables requested. If the user approves, only those variables reach this extension and their values are written into `process.env` before `joinSession()` resolves. If the user denies, `joinSession()` rejects, the extension does not load, and its tools never reach the model.
+
+An approval is remembered against the exact set of names the user saw, so an extension that later asks for an additional variable prompts again. Names that are unset, or that the CLI does not filter from extensions, are not prompted for.
+
+An approved extension can pass a granted value to anything it starts, so ask only for what the extension genuinely needs.
+
+## 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/copilot-sdk/docs/factories.md

@@ -0,0 +1,279 @@
+# 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" }],
+        argsSchema: {
+            type: "object",
+            required: ["files"],
+            properties: {
+                files: { type: "array", items: { type: "string" } },
+            },
+        },
+    },
+    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`, an optional `argsSchema`, and optional `limits`. Phase entries contain a `title` and optional `detail`.
+
+## Declaring an argument shape
+
+A factory that reads `ctx.args` should declare `meta.argsSchema`, as the example above does. When the model invokes the factory through the `run_factory` tool, the CLI validates `args` against the declaration **before** the run starts.
+
+Declaring one turns an expensive failure into a cheap one. With a schema, a malformed call is rejected up front — the model gets a correction hint and retries, and no run row, permission prompt, or credit spend happens. Without one, nothing validates: the run starts, takes a user approval, spends credits, and then dies inside the factory body with a confusing error. Agents can read the declared shape with `factories_manage` using `operation: "inspect"`.
+
+Enforcement covers structure — types, required properties, and enum or const values. Finer constraints such as `minLength`, `pattern`, or `additionalProperties` are recorded in the declaration but not enforced. The accepted vocabulary is the `FactoryJsonSchema` subset also used for subagent structured output: `type`, `required`, `enum`, `const`, recursive `properties`/`items`, and `anyOf`/`oneOf`/`allOf`. A `type` is one of `null`, `boolean`, `integer`, `number`, `string`, `array`, or `object`, or a non-empty array of those such as `["object", "null"]`. A declaration outside that subset is rejected at registration.
+
+`argsSchema` is optional and backward compatible. A factory that omits it behaves exactly as before, so **the `description` is then the only thing telling an agent what arguments to supply** — state the expected shape there.
+
+Validation covers the model's `run_factory` path only. An extension calling `session.factory.run(...)` directly is not validated against `argsSchema`; those arguments are typed through `defineFactory<TArgs>` instead, and that typing does not reach the model. So a factory that reads `ctx.args` should still validate it rather than assume a shape — the declared subset does not enforce every constraint, and it does not run at all on the SDK path.
+
+`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`, `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.
+- `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 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.
+
+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. Every limit is optional and must be positive when present; an omitted limit leaves that dimension unbounded, except that an omitted `maxConcurrentSubagents` falls back to `maxTotalSubagents`, so a declared total cap also bounds concurrency.
+
+Set a ceiling only from real knowledge of what the factory costs, or because the user named one. A guessed ceiling does not make a run safer: it stops a healthy run partway with `factory_limit_reached`, after that run has already spent credits. An agent authoring or invoking a factory on the user's behalf has no basis for estimating a number, so it should leave `limits` unset and bound the work with the factory's own counters instead. Omitting limits does not remove oversight of a model-initiated run: `run_factory` requests permission first, and that prompt shows the effective limits. SDK-initiated `run` and `resume` do not request permission, so an SDK caller that wants a ceiling sets it deliberately, from the cost it already knows.
+
+```js
+// Only when the cost profile is known, or the user asked for this ceiling.
+limits: { maxTotalSubagents: 10 },
+```
+
+- `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 },
+    notifyOnComplete: true,
+    logPhaseNames: true,
+});
+
+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;
+        notifyOnComplete?: boolean;
+        logPhaseNames?: boolean;
+    },
+): Promise<FactoryRunResult>;
+```
+
+Resume by run ID without resending the name or arguments:
+
+```ts
+const run = await session.factory.resume(runId, {
+    limits: { maxAiCredits: 6 },
+    notifyOnComplete: true,
+    logPhaseNames: true,
+});
+```
+
+The signature is:
+
+```ts
+session.factory.resume(
+    runId: string,
+    options?: {
+        limits?: FactoryLimits;
+        notifyOnComplete?: boolean;
+        logPhaseNames?: boolean;
+    },
+): Promise<FactoryRunResult>;
+```
+
+Set `notifyOnComplete` to `true` for factories that are likely to be invoked by an agent, so the originating session is notified when the factory completes. Set it to `false` for factories intended to be invoked programmatically, where the caller awaits the result directly. Set `logPhaseNames` to emit factory phase names to the session transcript. Both options apply to new and resumed runs.
+
+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.
+
+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, declared argument shape, 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 runsPage = await session.factory.listRuns({
+    afterSeq,
+    beforeSeq,
+    limit,
+});
+const detail = await session.factory.getRunDetail(runId);
+const progressPage = await session.factory.getRunProgress(runId, {
+    phaseId,
+    afterSeq,
+    beforeSeq,
+    limit,
+});
+```
+
+- `listRuns()` returns only the runs array from the newest default page of this session's durable factory runs. This overload preserves the original convenience API.
+- `listRuns({ afterSeq, beforeSeq, limit })` returns the full page. Its `oldestSeq`, `newestSeq`, `hasMoreNewer`, and `omittedOlder` fields let callers continue paging without raw RPC calls.
+- `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.

package/copilot-sdk/docs/factory-patterns.md

@@ -0,0 +1,194 @@
+# Agent Factory patterns
+
+Composable orchestration patterns built on the factory context. Read [factories.md](./factories.md) first for the API and its semantics. The API is experimental.
+
+Every snippet below assumes the surrounding `async (ctx) => { ... }` run body and destructures the hooks it uses. Three rules apply throughout, because breaking them fails silently:
+
+- **Give every independent subagent a unique `label`.** Identical prompt-and-options pairs memoize into a single shared subagent.
+- **Guard every `agent()` result.** An ordinary failure resolves to `null` rather than throwing.
+- **Filter with `v => v !== null`,** not `Boolean`, which also discards a valid `false`, `0`, or `""`.
+
+## Multi-stage review
+
+The default shape: fan out across dimensions, and let each dimension verify as soon as its own review lands. No barrier, so a slow dimension never holds up a fast one.
+
+```js
+async ({ pipeline, parallel, agent, phase, log }) => {
+    const FINDINGS = {
+        type: "object",
+        properties: {
+            findings: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: { title: { type: "string" } },
+                    required: ["title"],
+                },
+            },
+        },
+        required: ["findings"],
+    };
+    const VERDICT = {
+        type: "object",
+        properties: { isReal: { type: "boolean" } },
+        required: ["isReal"],
+    };
+    const DIMENSIONS = [
+        { key: "bugs", prompt: "Review the diff for correctness bugs. Return JSON {findings:[{title}]}." },
+        { key: "perf", prompt: "Review the diff for performance issues. Return JSON {findings:[{title}]}." },
+    ];
+
+    phase("Review"); // Run-global: set it before the fan-out, never inside a stage.
+    const perDimension = await pipeline(
+        DIMENSIONS,
+        (d) => agent(d.prompt, { label: `review:${d.key}`, schema: FINDINGS }),
+        (review, d) => {
+            if (!review) {
+                log(`review:${d.key} produced nothing`);
+                return [];
+            }
+            return parallel(
+                (review.findings ?? []).map((f, i) => () =>
+                    agent(`Adversarially verify this finding is real: ${f.title}`, {
+                        label: `verify:${d.key}:${i}`,
+                        schema: VERDICT,
+                    }).then((v) => (v && v.isReal ? f : null))
+                )
+            );
+        }
+    );
+
+    return { confirmed: perDimension.flat().filter((v) => v !== null) };
+};
+```
+
+## When a barrier is correct
+
+Deduplicating across every finding needs the whole set in hand, so the barrier earns its cost here. Dedup itself is plain JavaScript, done in the body between the two fan-outs. This excerpt reuses `FINDINGS`, `VERDICT`, and `DIMENSIONS` from the previous example — define them inside your own function.
+
+```js
+const all = await parallel(
+    DIMENSIONS.map((d) => () => agent(d.prompt, { label: `find:${d.key}`, schema: FINDINGS }))
+);
+const findings = all.filter((v) => v !== null).flatMap((r) => r.findings ?? []);
+const deduped = [...new Map(findings.map((f) => [f.title, f])).values()]; // Needs all of them.
+const verified = await parallel(
+    deduped.map((f, i) => () => agent(`Verify: ${f.title}`, { label: `verify:${i}`, schema: VERDICT }))
+);
+```
+
+## Loop until count
+
+Accumulate toward a target. Each iteration needs a unique identity — a unique label plus a prompt that excludes what has already been found — a bounded attempt count, and a null guard.
+
+```js
+const BUG = {
+    type: "object",
+    properties: { title: { type: "string" } },
+    required: ["title"],
+};
+
+const bugs = [];
+let attempt = 0;
+while (bugs.length < 10 && attempt < 30) {
+    const r = await agent(
+        `Find ONE distinct bug NOT already listed: ${JSON.stringify(bugs.map((b) => b.title))}. Return JSON {title}.`,
+        { label: `finder:${attempt}`, schema: BUG }
+    );
+    attempt++;
+    if (r && r.title) bugs.push(r);
+    log(`${bugs.length}/10 found`);
+}
+```
+
+## Loop until dry
+
+Keep spawning finders until some number of consecutive rounds surface nothing new. Deduplicate against everything *seen*, not just what was kept, or discarded findings resurface every round.
+
+```js
+const BUGS = {
+    type: "object",
+    properties: {
+        bugs: {
+            type: "array",
+            items: { type: "object", properties: { title: { type: "string" } }, required: ["title"] },
+        },
+    },
+    required: ["bugs"],
+};
+const VERDICT = {
+    type: "object",
+    properties: { real: { type: "boolean" } },
+    required: ["real"],
+};
+
+const seen = new Set();
+const confirmed = [];
+const keyOf = (b) => b.title.toLowerCase();
+let dry = 0;
+let round = 0;
+
+while (dry < 2 && round < 20) {
+    const found = (
+        await parallel(
+            [0, 1, 2].map((i) => () =>
+                agent(`Find bugs (finder ${i}, round ${round}). Return JSON {bugs:[{title}]}.`, {
+                    label: `find:${round}:${i}`,
+                    schema: BUGS,
+                })
+            )
+        )
+    )
+        .filter((v) => v !== null)
+        .flatMap((r) => r.bugs ?? []);
+
+    const fresh = found.filter((b) => {
+        const k = keyOf(b);
+        if (seen.has(k)) return false;
+        seen.add(k);
+        return true;
+    });
+
+    if (!fresh.length) {
+        dry++;
+        round++;
+        continue;
+    }
+    dry = 0;
+
+    const judged = await parallel(
+        fresh.map((b, i) => () =>
+            parallel(
+                ["correctness", "security", "repro"].map((lens) => () =>
+                    agent(`Judge via ${lens}: is "${b.title}" real? Return JSON {real}.`, {
+                        label: `judge:${round}:${i}:${lens}`,
+                        schema: VERDICT,
+                    })
+                )
+            ).then((vs) => ({ b, real: vs.filter((v) => v !== null).filter((v) => v.real).length >= 2 }))
+        )
+    );
+
+    confirmed.push(...judged.filter((v) => v !== null && v.real).map((v) => v.b));
+    round++;
+}
+```
+
+## Quality patterns
+
+Compose these freely.
+
+- **Adversarial verify.** Spawn several independent skeptics per finding, each prompted to *refute* it and to default to refuted when uncertain. Keep only what a majority fails to refute.
+- **Perspective-diverse verify.** Give each verifier a distinct lens — correctness, security, performance, does-it-reproduce — instead of several identical skeptics. The distinct prompts also stop them memoizing into one subagent.
+- **Judge panel.** Generate several independent attempts from different angles, score them with parallel judges, then synthesize from the winner while grafting the best ideas from the runners-up.
+- **Multi-modal sweep.** Run parallel searchers that each look a different way: by container, by content, by entity, by time.
+- **Completeness critic.** End with an agent asking what is missing — an angle not run, a claim unverified, a source unread — and use its answer to seed the next round.
+- **No silent caps.** When the factory bounds its own coverage with a top-N, a sampling step, or a no-retry rule, `log()` what was dropped.
+
+## Scaling
+
+Match the orchestration to what was asked. A quick check wants a couple of subagents and single-vote verification; a request to be thorough or comprehensive wants a larger finder pool, a three-to-five vote adversarial pass, and a synthesis stage.
+
+There is no in-script budget object. Scale with your own counters, as in the loop patterns above, and treat any declared limits as the safety ceiling rather than the control mechanism. Only `agent()` spawns are throttled, by `maxConcurrentSubagents` falling back to `maxTotalSubagents`; with neither declared there is no built-in concurrency cap, so bound a wide fan-out with the factory's own counters. Do not invent a ceiling to compensate, and see [Resource limits](./factories.md#resource-limits) for when declaring one is appropriate. `parallel` itself is `Promise.all`, so non-agent work in a thunk runs fully concurrently regardless.
+
+These patterns are not exhaustive. Compose novel harnesses — tournament brackets, self-repair loops, staged escalation — when the task calls for it.

package/copilot-sdk/extension.d.ts

@@ -0,0 +1,59 @@
+import type { CopilotSession } from "./session.js";
+import { type PermissionHandler, type ResumeSessionConfig } from "./types.js";
+import type { FactoryHandle } from "./factory.js";
+export { Canvas, CanvasError, createCanvas, type CanvasAction, type CanvasDeclaration, type CanvasHostContext, type CanvasJsonSchema, type CanvasOptions, } from "./canvas.js";
+export type JoinSessionConfig = Omit<ResumeSessionConfig, "onPermissionRequest" | "extensionSdkPath"> & {
+    onPermissionRequest?: PermissionHandler;
+    /**
+     * Names of sensitive environment variables this extension needs, such as
+     * `"GITHUB_TOKEN"`.
+     *
+     * The Copilot CLI strips sensitive variables from every extension process
+     * before it starts, so an extension that needs one must ask for it by name.
+     * The CLI prompts the user with the extension's name and the exact list of
+     * variables requested. On approval the granted values are written into this
+     * process's `process.env` before {@link joinSession} resolves, so they are
+     * readable afterwards. On denial the join rejects and the extension does not
+     * load, so its tools never reach the model.
+     *
+     * An approval is remembered against the exact set of names the user saw, so
+     * asking for an additional variable later prompts again. Names that are unset
+     * or that the CLI does not filter from extensions are not prompted for. An
+     * empty list means the same as omitting the option: nothing is requested.
+     *
+     * Requires a Copilot CLI that supports extension environment access; older
+     * CLIs ignore the request and grant nothing.
+     *
+     * @example
+     * ```typescript
+     * const session = await joinSession({
+     *     requestedEnvironmentVariables: ["GITHUB_TOKEN"],
+     * });
+     * const token = process.env.GITHUB_TOKEN;
+     * ```
+     */
+    requestedEnvironmentVariables?: string[];
+    /**
+     * 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, FactoryLimits, FactoryMeta } from "./types.js";
+export { defineFactory, FactoryResumeError, isFactoryRunTerminal, 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, type FactoryRunStatus, type FactoryRunSummary, type FactoryListRunsOptions, type FactoryRunsPage, type FactoryRunDetail, type FactoryProgressPage, type FactoryProgressLine, type FactoryPhaseObservation, type FactoryPhaseStatus, type FactoryAgentSummary, } from "./factory.js";
+/**
+ * Joins the current foreground session.
+ *
+ * @param config - Configuration to add to the session
+ * @returns A promise that resolves with the joined session
+ *
+ * @example
+ * ```typescript
+ * import { joinSession } from "@github/copilot-sdk/extension";
+ *
+ * const session = await joinSession({ tools: [myTool] });
+ * ```
+ */
+export declare function joinSession(config?: JoinSessionConfig): Promise<CopilotSession>;