@alexkroman1/aai-cli 7.0.0 → 8.0.0

package/dist/scaffold/package.json

@@ -10,12 +10,13 @@
     "start": "node server.mjs",
     "build": "aai build",
     "test": "aai test",
+    "eval": "aai eval",
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^7.0.0",
-    "@alexkroman1/aai-runtime": "^7.0.0",
-    "@alexkroman1/aai-ui": "^7.0.0",
+    "@alexkroman1/aai": "^8.0.0",
+    "@alexkroman1/aai-runtime": "^8.0.0",
+    "@alexkroman1/aai-ui": "^8.0.0",
     "@workflow/world-postgres": "4.3.3",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
@@ -25,7 +26,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^7.0.0",
+    "@alexkroman1/aai-cli": "^8.0.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",

package/dist/scaffold/server.mjs

@@ -56,7 +56,12 @@ if (!existsSync(workerPath)) {
 // Windows, where a bare POSIX-looking path is not a valid module specifier.
 const { default: agent } = await import(pathToFileURL(workerPath).href);
 
-/** Parse a dotenv-syntax file into a record; `{}` when it does not exist. */
+/**
+ * Parse a dotenv-syntax file into a record; `{}` when it does not exist.
+ *
+ * @param {string} file - Path relative to the project root.
+ * @returns {Promise<Record<string, string | undefined>>}
+ */
 async function readEnvFile(file) {
   try {
     return parseEnv(await readFile(path.join(root, file), "utf-8"));
@@ -84,13 +89,15 @@ async function readEnvFile(file) {
  */
 async function resolveAgentEnv() {
   const declared = { ...(await readEnvFile(".env.example")), ...(await readEnvFile(".env")) };
+  /** @type {Record<string, string>} */
   const env = {};
   for (const [key, fileValue] of Object.entries(declared)) {
     const value = process.env[key] ?? fileValue;
     // An empty value is worse than a missing one: a provider would try to
     // authenticate with "" rather than report the credential as absent. The
-    // example file is full of them by design (`BRAVE_API_KEY=`).
-    if (value !== "") env[key] = value;
+    // example file is full of them by design (`BRAVE_API_KEY=`). A key the
+    // parser saw with no value at all is the same case.
+    if (value !== undefined && value !== "") env[key] = value;
   }
   return env;
 }

package/dist/scaffold/tsconfig.json

@@ -4,7 +4,6 @@
     "module": "ESNext",
     "moduleResolution": "bundler",
     "strict": true,
-    "noImplicitAny": false,
     "useUnknownInCatchVariables": false,
     "verbatimModuleSyntax": true,
     "allowImportingTsExtensions": true,

package/dist/{secret-CVvSLIDV.mjs → secret-Ct34kdgU.mjs}

@@ -2,7 +2,7 @@
 import { a as ok, n as fail } from "./_output-CKkmWs7i.mjs";
 import { n as log, s as unwrapCancel } from "./_ui-u7T4YooX.mjs";
 import { f as checkedResponse, p as isStringArray } from "./_studio-DR5yzZ1T.mjs";
-import { t as secretRequest } from "./_slug-api-nRFaBEPJ.mjs";
+import { t as secretRequest } from "./_slug-api-z-USxPtL.mjs";
 import { isRecord } from "@alexkroman1/aai/utils";
 import * as p from "@clack/prompts";
 import { text } from "node:stream/consumers";

package/dist/{storage-BvUrnvM3.mjs → storage-i_79ZwAR.mjs}

@@ -2,7 +2,7 @@
 import { a as ok, n as fail } from "./_output-CKkmWs7i.mjs";
 import { n as log } from "./_ui-u7T4YooX.mjs";
 import { f as checkedResponse } from "./_studio-DR5yzZ1T.mjs";
-import { n as slugRequest } from "./_slug-api-nRFaBEPJ.mjs";
+import { n as slugRequest } from "./_slug-api-z-USxPtL.mjs";
 import { isRecord } from "@alexkroman1/aai/utils";
 import * as p from "@clack/prompts";
 //#region storage.ts

package/dist/{studio--MUV0cid.mjs → studio-CzTzPqe1.mjs}

@@ -4,7 +4,7 @@ import { n as log, t as fmtUrl } from "./_ui-u7T4YooX.mjs";
 import { s as updateProjectConfig } from "./_config-CmJOFsAP.mjs";
 import { t as resolveServerEnv } from "./_server-common-6e0QI4mq.mjs";
 import { a as resolveDeployTarget } from "./_agent-BTwZJu4P.mjs";
-import { layerScaffold } from "./_templates-FI3xPEMj.mjs";
+import { layerScaffold } from "./_templates-4WcKOjS5.mjs";
 import { a as publishStudioProject, c as studioProjectUrl, f as checkedResponse, i as projectNameFromDir, n as fetchStudioProject, o as pushStudioSource, r as listStudioProjects, s as studioProjectApiUrl, t as collectSourceFiles, u as apiRequest } from "./_studio-DR5yzZ1T.mjs";
 import path from "node:path";
 import { isRecord } from "@alexkroman1/aai/utils";

package/dist/templates/briefing-desk/agent.test.ts

@@ -0,0 +1,350 @@
+/// <reference types="vite/client" />
+
+import {
+  createToolContext,
+  type StubDelegateCall,
+  stubDelegate,
+  toolRunner,
+  withDiscoveredTools,
+} from "@alexkroman1/aai/testing";
+import { describe, expect, test } from "vitest";
+import authoredAgent from "./agent.ts";
+import type { AngleWork, Finding } from "./shared.ts";
+import {
+  angleBrief,
+  briefingSlot,
+  countWork,
+  factChecker,
+  findByAngle,
+  MAX_ANGLES,
+  MAX_FINDINGS,
+  MAX_RESEARCH_STEPS,
+  recordFinding,
+  researcher,
+} from "./shared.ts";
+
+/** A finding whose cost is irrelevant to the case at hand. */
+const NO_WORK: AngleWork = { searches: 0, reads: 0 };
+
+/**
+ * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
+ *
+ * The glob is written HERE rather than reached for from a shared helper because
+ * this file SHIPS — it is what a scaffolded project runs, so it may not import
+ * anything outside its own template.
+ */
+const agentDef = withDiscoveredTools(
+  authoredAgent,
+  import.meta.glob("./tools/*.ts", { eager: true }),
+);
+
+const run = toolRunner(agentDef);
+
+/**
+ * The desk's two subagents, faked.
+ *
+ * `stubDelegate` routes by SUBAGENT NAME, which is what tells a research run
+ * from a check — the two things this desk actually does. Nothing here runs a
+ * model or touches the network: a subagent is a model loop, and a spec that
+ * asserted on its steps would be asserting on a provider's choices. What is
+ * worth asserting is what the desk ASKS for and what it does with what comes
+ * back.
+ */
+function desk(
+  options: {
+    research?: (call: StubDelegateCall) => string | { text: string; searches?: number };
+    check?: string;
+  } = {},
+) {
+  const research = options.research ?? ((call) => `Findings for ${call.task}.`);
+  return stubDelegate({
+    researcher: (call) => {
+      const reply = research(call);
+      if (typeof reply === "string") return { text: reply };
+      return {
+        text: reply.text,
+        toolCalls: Array.from({ length: reply.searches ?? 0 }, (_unused, index) => ({
+          name: "web_search",
+          input: { query: `q${index}` },
+        })),
+      };
+    },
+    "fact-checker": options.check ?? "Confirmed: two sources say so.",
+  });
+}
+
+describe("the desk itself", () => {
+  test("has no web tools of its own — everything goes through a subagent", () => {
+    expect(authoredAgent.builtinTools ?? []).toEqual([]);
+    // And the researcher does, which is the split the template exists to show.
+    expect(researcher.builtinTools).toContain("web_search");
+    expect(factChecker.builtinTools).toEqual(["web_search"]);
+  });
+
+  test("gives the checker a tighter budget than the researcher", () => {
+    expect(factChecker.maxSteps).toBeLessThan(MAX_RESEARCH_STEPS);
+  });
+
+  test("tells each subagent that its final message is all the desk sees", () => {
+    expect(researcher.instructions).toMatch(/FINAL message/);
+  });
+});
+
+describe("research_topic", () => {
+  test("fans every angle out as its own run, each with a self-contained task", async () => {
+    const model = desk();
+    const ctx = createToolContext({ delegate: model.delegate });
+
+    await run(
+      "research_topic",
+      { topic: "home batteries", angles: ["price trend", "install lead times"] },
+      ctx,
+    );
+
+    expect(model.calls).toHaveLength(2);
+    expect(model.calls.map((call) => call.subagent.name)).toEqual(["researcher", "researcher"]);
+    expect(model.calls.map((call) => call.task)).toEqual(["price trend", "install lead times"]);
+    // The subagent has not heard the call, so the topic rides in `context`.
+    expect(model.calls[0]?.options.context).toContain("home batteries");
+  });
+
+  test("starts the runs concurrently rather than one after another", async () => {
+    let inFlight = 0;
+    let peak = 0;
+    const model = stubDelegate({
+      researcher: () => {
+        inFlight += 1;
+        peak = Math.max(peak, inFlight);
+        return "found";
+      },
+    });
+    // The fake answers synchronously, so `inFlight` is only ever 1 unless the
+    // tool really did start every run before awaiting any — which is the claim.
+    const delegate = ((sub, options) =>
+      model.delegate(sub, options).finally(() => {
+        inFlight -= 1;
+      })) as typeof model.delegate;
+
+    await run(
+      "research_topic",
+      { topic: "t", angles: ["a", "b", "c"] },
+      createToolContext({ delegate }),
+    );
+
+    expect(peak).toBe(3);
+  });
+
+  test("records what each angle concluded, and only that", async () => {
+    const model = desk({
+      research: (call) => ({ text: `Answer to ${call.task}.`, searches: 3 }),
+    });
+    const ctx = createToolContext({ delegate: model.delegate });
+
+    const result = (await run("research_topic", { topic: "t", angles: ["a"] }, ctx)) as {
+      findings: Finding[];
+    };
+
+    expect(result.findings).toEqual([
+      { angle: "a", summary: "Answer to a.", work: { searches: 3, reads: 0 } },
+    ]);
+    const board = briefingSlot.get(ctx);
+    expect(board.topic).toBe("t");
+    expect(board.findings).toEqual(result.findings);
+  });
+
+  test("one failed angle does not sink the briefing", async () => {
+    const model = stubDelegate({
+      researcher: (call) => {
+        if (call.task === "b") throw new Error("provider is having a day");
+        return `Answer to ${call.task}.`;
+      },
+    });
+    const ctx = createToolContext({ delegate: model.delegate });
+
+    const result = (await run("research_topic", { topic: "t", angles: ["a", "b", "c"] }, ctx)) as {
+      findings: { angle: string }[];
+      failed: { angle: string; error: string }[];
+      message: string;
+    };
+
+    expect(result.findings.map((one) => one.angle)).toEqual(["a", "c"]);
+    expect(result.failed).toEqual([{ angle: "b", error: "provider is having a day" }]);
+    // And the desk is told to say so rather than quietly reporting two angles.
+    expect(result.message).toMatch(/could not get to/);
+    expect(briefingSlot.get(ctx).findings).toHaveLength(2);
+  });
+
+  test("fails as a tool when every angle fails, quoting the first reason", async () => {
+    const model = stubDelegate({
+      researcher: () => {
+        throw new Error("gateway said no");
+      },
+    });
+
+    const result = await run(
+      "research_topic",
+      { topic: "t", angles: ["a", "b"] },
+      createToolContext({ delegate: model.delegate }),
+    );
+
+    expect(result).toEqual({ error: expect.stringContaining("gateway said no") });
+  });
+
+  test("refuses a call whose angles are all blank, without spending a subagent", async () => {
+    const model = desk();
+
+    const result = await run(
+      "research_topic",
+      { topic: "t", angles: ["   "] },
+      createToolContext({ delegate: model.delegate }),
+    );
+
+    expect(result).toEqual({ error: expect.stringContaining("No angles") });
+    expect(model.calls).toEqual([]);
+  });
+
+  test("accepts at most MAX_ANGLES angles", () => {
+    const schema = agentDef.tools.research_topic?.inputSchema;
+    const tooMany = { topic: "t", angles: Array.from({ length: MAX_ANGLES + 1 }, () => "a") };
+    expect(schema?.["~standard"].validate(tooMany)).toMatchObject({ issues: expect.anything() });
+  });
+});
+
+describe("verify_claim", () => {
+  test("asks the fact-checker, not the researcher", async () => {
+    const model = desk({ check: "Contradicted: the figure is 12%." });
+    const ctx = createToolContext({ delegate: model.delegate });
+
+    const result = (await run("verify_claim", { claim: "The figure is 40%." }, ctx)) as {
+      verdict: string;
+      checkedAgainst: string | null;
+    };
+
+    expect(model.calls.map((call) => call.subagent.name)).toEqual(["fact-checker"]);
+    expect(result.verdict).toBe("Contradicted: the figure is 12%.");
+    expect(result.checkedAgainst).toBeNull();
+  });
+
+  test("quotes the finding a claim came from, so the checker can see the source", async () => {
+    const model = desk();
+    const ctx = createToolContext({ delegate: model.delegate });
+    briefingSlot.update(ctx, (board) => {
+      recordFinding(board, {
+        angle: "install lead times",
+        summary: "Installers quote eight weeks.",
+        work: { searches: 2, reads: 1 },
+      });
+    });
+
+    const result = (await run(
+      "verify_claim",
+      { claim: "Installs take eight weeks.", about: "lead times" },
+      ctx,
+    )) as { checkedAgainst: string | null };
+
+    expect(model.calls[0]?.options.context).toContain("Installers quote eight weeks.");
+    expect(result.checkedAgainst).toBe("install lead times");
+  });
+
+  test("reports a failed check as a tool failure the model can recover from", async () => {
+    const model = stubDelegate({
+      "fact-checker": () => {
+        throw new Error("checker timed out");
+      },
+    });
+
+    const result = await run(
+      "verify_claim",
+      { claim: "Something." },
+      createToolContext({ delegate: model.delegate }),
+    );
+
+    expect(result).toEqual({ error: expect.stringContaining("checker timed out") });
+  });
+
+  test("refuses a blank claim without spending a subagent", async () => {
+    const model = desk();
+    const result = await run(
+      "verify_claim",
+      { claim: "  " },
+      createToolContext({ delegate: model.delegate }),
+    );
+    expect(result).toEqual({ error: expect.stringContaining("Nothing to check") });
+    expect(model.calls).toEqual([]);
+  });
+});
+
+describe("briefing_so_far", () => {
+  test("says so when there is nothing yet, and spends no subagent", async () => {
+    const ctx = createToolContext();
+    const result = (await run("briefing_so_far", {}, ctx)) as { findings: unknown[] };
+    expect(result.findings).toEqual([]);
+  });
+
+  test("adds the lookups up across every angle", async () => {
+    const ctx = createToolContext();
+    briefingSlot.update(ctx, (board) => {
+      board.topic = "t";
+      recordFinding(board, { angle: "a", summary: "A.", work: { searches: 2, reads: 1 } });
+      recordFinding(board, { angle: "b", summary: "B.", work: { searches: 3, reads: 0 } });
+    });
+
+    const result = (await run("briefing_so_far", {}, ctx)) as {
+      totalSearches: number;
+      totalReads: number;
+    };
+    expect(result.totalSearches).toBe(5);
+    expect(result.totalReads).toBe(1);
+  });
+});
+
+describe("the brief a subagent is sent", () => {
+  test("carries the topic, because the subagent has not heard the call", () => {
+    expect(angleBrief("home batteries", "price trend")).toEqual({
+      task: "price trend",
+      context: expect.stringContaining("home batteries"),
+    });
+  });
+});
+
+describe("countWork", () => {
+  test("tells searches from page reads", () => {
+    expect(
+      countWork([
+        { name: "web_search", input: {} },
+        { name: "visit_webpage", input: {} },
+        { name: "web_search", input: {} },
+      ]),
+    ).toEqual({ searches: 2, reads: 1 });
+  });
+
+  test("counts a tool it does not recognise as neither", () => {
+    // A researcher that gains a third tool must not silently inflate "searches".
+    expect(countWork([{ name: "think", input: {} }])).toEqual({ searches: 0, reads: 0 });
+  });
+});
+
+describe("the board", () => {
+  test("holds MAX_FINDINGS, dropping the oldest", () => {
+    const ctx = createToolContext();
+    briefingSlot.update(ctx, (board) => {
+      for (let index = 0; index < MAX_FINDINGS + 3; index++) {
+        recordFinding(board, { angle: `angle ${index}`, summary: "s", work: NO_WORK });
+      }
+    });
+    const board = briefingSlot.get(ctx);
+    expect(board.findings).toHaveLength(MAX_FINDINGS);
+    expect(board.findings[0]?.angle).toBe("angle 3");
+  });
+
+  test("finds an angle from a loose mention, and nothing from a blank one", () => {
+    const ctx = createToolContext();
+    briefingSlot.update(ctx, (board) => {
+      recordFinding(board, { angle: "install lead times", summary: "s", work: NO_WORK });
+    });
+    const board = briefingSlot.get(ctx);
+    expect(findByAngle(board, "lead times")?.angle).toBe("install lead times");
+    expect(findByAngle(board, "  ")).toBeUndefined();
+    expect(findByAngle(board, "battery chemistry")).toBeUndefined();
+  });
+});

package/dist/templates/briefing-desk/agent.ts

@@ -0,0 +1,30 @@
+import { agent } from "@alexkroman1/aai";
+
+/**
+ * A briefing desk you can phone: you name a subject, it puts several
+ * researchers on it at once and reads you back what they found.
+ *
+ * **It is the worked example for `ctx.delegate` — subagents.** The desk itself
+ * has NO web tools. Everything it knows comes back from a subagent run started
+ * inside a tool call: `researcher` (search + page reads, six steps) for each
+ * angle of a topic, `fact-checker` (search only, two steps, a cheaper model)
+ * for one claim at a time. `shared.ts` declares both and argues the split.
+ *
+ * **What that buys, on a phone call specifically.** A researcher may read tens
+ * of thousands of tokens of web pages; what crosses back into the conversation
+ * is its final paragraph. So the desk stays coherent over a long call — its
+ * context grows by a summary per angle rather than by everything four
+ * researchers read — and the four angles run at once, so the caller waits for
+ * the slowest rather than the sum. `tools/research_topic.ts` is where both of
+ * those actually happen.
+ *
+ * Compare `web-researcher`, which gives the search builtins to the agent
+ * itself: that is the right shape for one lookup, and the wrong one the moment
+ * a question has four sides.
+ */
+export default agent({
+  name: "Briefing Desk",
+  greeting:
+    "Briefing desk. Tell me a subject and I'll put a few researchers on it — " +
+    "try something like, what's going on with home battery prices.",
+});

package/dist/templates/briefing-desk/shared.ts

@@ -0,0 +1,200 @@
+/**
+ * The desk's two subagents, and the board of what they have found.
+ *
+ * **This template is the worked example for `ctx.delegate`.** Everything here
+ * exists to show the three things a subagent buys that `ctx.generate` cannot:
+ *
+ * 1. **A context window the caller never pays for.** `researcher` reads whole
+ *    web pages. A briefing on four angles can spend a hundred thousand tokens
+ *    doing it, and what comes back into the phone call's conversation is four
+ *    paragraphs — because {@link DelegateResult.text} is the subagent's final
+ *    message and nothing else crosses back.
+ * 2. **Parallelism.** Four angles are four independent runs, so
+ *    `tools/research_topic.ts` fans them out with one `Promise.allSettled` and
+ *    the caller waits for the slowest, not for the sum.
+ * 3. **Tools isolated by capability.** `researcher` can read the open web;
+ *    `factChecker` can only search it, on a cheaper model with a third of the
+ *    budget. Neither can reach the other's tools, and the DESK — the voice
+ *    agent the caller is talking to — has no web tools at all.
+ */
+
+import {
+  type DeepReadonly,
+  type DelegateFn,
+  type DelegateOptions,
+  type DelegateResult,
+  pushCapped,
+  type SubagentToolCall,
+  sessionSlot,
+  subagent,
+} from "@alexkroman1/aai";
+import { assemblyAILlm } from "@alexkroman1/aai/llm";
+
+/**
+ * Steps one angle may take. A budget, not a limit to be raised when an answer
+ * disappoints: a subagent told to "keep looking until sure" is a subagent whose
+ * cost nobody can quote, and the caller is on the phone. Past it the researcher
+ * is asked for its answer with its tools withheld, so a capped run still comes
+ * back with prose rather than stopping mid-chain.
+ */
+export const MAX_RESEARCH_STEPS = 6;
+
+/**
+ * The researcher, and the one line that decides whether any of this works.
+ *
+ * "Finish with a summary" is not politeness. The parent gets the subagent's
+ * FINAL message, so a run that ends by saying "Done." has thrown away
+ * everything it read and no budget recovers it — this is the failure mode the
+ * `SubagentDef.instructions` contract warns about, stated once, here.
+ */
+export const researcher = subagent({
+  name: "researcher",
+  instructions: [
+    "You are a research agent working one angle of a briefing.",
+    "",
+    "Search, then open the two or three most promising pages and read them.",
+    "Prefer primary sources and recent ones. If the sources disagree, say so",
+    "rather than picking a side.",
+    "",
+    "IMPORTANT: your FINAL message is the only thing the desk receives — it",
+    "does not see your searches, the pages you opened, or your reasoning. End",
+    "with a self-contained paragraph of what you found, naming the sources you",
+    "trusted. Three sentences is plenty; do not write a report.",
+  ].join("\n"),
+  // Read/browse. Independent of the desk's own builtins, which are none: the
+  // agent the caller talks to never touches the network.
+  builtinTools: ["web_search", "visit_webpage"],
+  maxSteps: MAX_RESEARCH_STEPS,
+});
+
+/**
+ * The fact-checker: a second ROLE, deliberately narrower than the first.
+ *
+ * Its own `llm` (cheaper and quicker — checking one sentence is not the job
+ * `researcher` does), its own budget, and search only. That split is the third
+ * reason to reach for a subagent: a capability a run does not need is one it
+ * cannot misuse.
+ */
+export const factChecker = subagent({
+  name: "fact-checker",
+  instructions: [
+    "You check ONE claim against what you can find on the web.",
+    "",
+    "Search for it. Answer in one sentence, starting with one of",
+    "'Confirmed:', 'Contradicted:' or 'Unclear:', and name what you found.",
+    "'Unclear' is a real answer — say it rather than guessing.",
+  ].join("\n"),
+  llm: assemblyAILlm({ model: "gemini-2.5-flash-lite" }),
+  builtinTools: ["web_search"],
+  maxSteps: 2,
+});
+
+/** One angle, as the desk holds it. */
+export interface Finding {
+  /** The angle the researcher was given. */
+  angle: string;
+  /** Its final message — the whole of what crossed back. */
+  summary: string;
+  /** Searches it ran and pages it opened, for narrating the wait. */
+  work: AngleWork;
+}
+
+/** What one angle COST, as the desk is willing to say it out loud. */
+export interface AngleWork {
+  searches: number;
+  reads: number;
+}
+
+/**
+ * The brief one angle is sent with.
+ *
+ * Its own function because the `context` line is the whole of what a
+ * researcher learns about the call it belongs to — a subagent's context is
+ * ISOLATED, so anything the conversation knows and the angle does not say is
+ * lost unless it is written here. A spec asserts on this rather than on a
+ * template literal buried in a tool body.
+ */
+export function angleBrief(topic: string, angle: string): DelegateOptions {
+  return { task: angle, context: `This angle belongs to a briefing on: ${topic}.` };
+}
+
+/**
+ * What a run did, read off the calls it made.
+ *
+ * {@link DelegateResult.toolCalls} carries the CALLS and not their results —
+ * the results are what stayed in the subagent's window — so this is the most
+ * the desk can honestly say about the wait. An unrecognised tool name counts
+ * as neither: a researcher that gains a third tool should not silently inflate
+ * "searches".
+ */
+export function countWork(toolCalls: readonly SubagentToolCall[]): AngleWork {
+  let searches = 0;
+  let reads = 0;
+  for (const call of toolCalls) {
+    if (call.name === "web_search") searches += 1;
+    else if (call.name === "visit_webpage") reads += 1;
+  }
+  return { searches, reads };
+}
+
+/**
+ * Run one angle and reduce it to what the board holds.
+ *
+ * Takes the DELEGATE rather than the whole tool context — the same seam
+ * `plan-and-execute` puts on `ctx.generate`. The desk's own logic is then
+ * exercised against a fake without a context at all, and the tool that fans
+ * these out stays one line per angle.
+ */
+export async function researchAngle(
+  delegate: DelegateFn,
+  topic: string,
+  angle: string,
+): Promise<Finding> {
+  const result: DelegateResult = await delegate(researcher, angleBrief(topic, angle));
+  return { angle, summary: result.text, work: countWork(result.toolCalls) };
+}
+
+/** Angles one `research_topic` call may fan out. Four researchers at once is
+ *  already four model bills; past that a caller is waiting on a queue. */
+export const MAX_ANGLES = 4;
+
+/** Findings the board holds. Older ones fall off — they ride in every prompt
+ *  the desk builds and in every recap it reads back. */
+export const MAX_FINDINGS = 12;
+
+export interface BriefingState {
+  /** What the caller asked about, as last stated. */
+  topic: string | null;
+  /** Every angle researched on this call, oldest first. */
+  findings: Finding[];
+}
+
+export function emptyBriefing(): BriefingState {
+  return { topic: null, findings: [] };
+}
+
+export const briefingSlot = sessionSlot("briefing", emptyBriefing);
+
+/** Record a finding, holding {@link MAX_FINDINGS}. */
+export function recordFinding(state: BriefingState, finding: Finding): void {
+  pushCapped(state.findings, finding, MAX_FINDINGS);
+}
+
+/**
+ * The board as a READ hands it out — deep-frozen, and typed to say so, which is
+ * what a slot's read returns.
+ */
+export type FrozenBriefing = DeepReadonly<BriefingState>;
+
+/** A finding named by what the caller would say: its angle, loosely matched. */
+export function findByAngle(
+  state: FrozenBriefing,
+  angle: string,
+): DeepReadonly<Finding> | undefined {
+  const wanted = angle.trim().toLowerCase();
+  if (wanted === "") return undefined;
+  return state.findings.find(
+    (finding) =>
+      finding.angle.toLowerCase().includes(wanted) || wanted.includes(finding.angle.toLowerCase()),
+  );
+}