@alexkroman1/aai-cli 6.11.0 → 8.0.0

package/dist/scaffold/package.json

@@ -10,20 +10,23 @@
     "start": "node server.mjs",
     "build": "aai build",
     "test": "aai test",
+    "eval": "aai eval",
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^6.11.0",
-    "@alexkroman1/aai-ui": "^6.11.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",
     "tailwindcss": "^4.0.0",
     "workflow": "4.8.2",
+    "xstate": "^5.32.5",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^6.11.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

@@ -17,7 +17,7 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { parseEnv } from "node:util";
-import { createAgentServer, withHostCredentialFallback } from "@alexkroman1/aai/runtime";
+import { createAgentServer, withHostCredentialFallback } from "@alexkroman1/aai-runtime";
 import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
 
 const root = path.dirname(fileURLToPath(import.meta.url));
@@ -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-BuMuFR4B.mjs → secret-Ct34kdgU.mjs}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 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-U3jhKlA3.mjs";
-import { t as secretRequest } from "./_slug-api-BxrsJXVI.mjs";
+import { f as checkedResponse, p as isStringArray } from "./_studio-DR5yzZ1T.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-DzRZ-eCw.mjs → storage-i_79ZwAR.mjs}

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 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-U3jhKlA3.mjs";
-import { n as slugRequest } from "./_slug-api-BxrsJXVI.mjs";
+import { f as checkedResponse } from "./_studio-DR5yzZ1T.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-BCNUpDgP.mjs → studio-CzTzPqe1.mjs}

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { a as ok, t as CliError } from "./_output-CKkmWs7i.mjs";
 import { n as log, t as fmtUrl } from "./_ui-u7T4YooX.mjs";
-import { s as updateProjectConfig } from "./_config-D_s09e7g.mjs";
+import { s as updateProjectConfig } from "./_config-CmJOFsAP.mjs";
 import { t as resolveServerEnv } from "./_server-common-6e0QI4mq.mjs";
-import { a as resolveDeployTarget } from "./_agent-DpH2pBJd.mjs";
-import { layerScaffold } from "./_templates-Dxb_P2Wz.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-U3jhKlA3.mjs";
+import { a as resolveDeployTarget } from "./_agent-BTwZJu4P.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";
 import { mkdir, readdir, writeFile } from "node:fs/promises";

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.",
+});