@alexkroman1/aai-cli 6.11.0 → 8.0.0

package/dist/templates/research-workflow/agent.eval.test.ts

@@ -0,0 +1,329 @@
+/// <reference types="vite/client" />
+
+// An EVAL: does this desk actually behave? Run it with `aai eval`.
+//
+// `agent.test.ts` drives the four tools against a STUBBED `ctx.workflows` and
+// the five steps against a stubbed `fetch`. Neither can say whether the AGENT —
+// a model, reading this system prompt, holding these four tools — hands the
+// work off at all, or whether the run it starts is findable afterwards. That is
+// what this file is for, and it is only possible because `describeEval` opens a
+// real workflow engine per case and hands its client to the session: before
+// that, a tool calling `ctx.workflows.start` was a tool an eval could not
+// execute.
+//
+// Two boundaries this file is careful about, because a case that implied either
+// would be the worse failure:
+//
+//   * **The engine is not durable.** No journal, no replay, no retry, and a
+//     `sleep()` is RECORDED rather than taken (which is why the review wait
+//     below is an assertion about what the body ASKED for). Nothing here says
+//     anything about resume, and `aai-cli`'s `dev-workflow.scenario.test.ts` is
+//     the tier that does.
+//   * **A step's HTTP is scripted, in BOTH modes.** The live half of an eval is
+//     the SESSION's model — which tool the desk reaches for, and when. The
+//     run's own five-to-twelve model calls and its web searches are answered
+//     from `MODEL_SCRIPT` through the published `stepFetch` slot, so a case is
+//     deterministic, free, and cannot fail on a DuckDuckGo 403 or a rate limit
+//     the engine's inert `maxRetries` could not ride out. What the researcher's
+//     search loop does with what it finds is `agent.test.ts`'s subject.
+//
+// And what no eval here can see at all: anything below the audio boundary —
+// endpointing, barge-in, whether two sentences merged into one turn.
+import { withDiscoveredTools } from "@alexkroman1/aai/testing";
+import { installStubStepFetch } from "@alexkroman1/aai/testing/vitest";
+import type { EvalToolCall, EvalWorkflows } from "@alexkroman1/aai-runtime/eval";
+import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
+import { expect } from "vitest";
+import { z } from "zod";
+import authoredAgent from "./agent.ts";
+import { research } from "./shared.ts";
+
+/**
+ * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
+ *
+ * Load-bearing, and not applied by `agent()` — the BUILD is what enumerates
+ * `tools/`, so an eval driving the raw default export would measure a desk with
+ * no tools at all and every assertion below would mean nothing. This template
+ * declares its prompt inline in `agent.ts`, so there is no `system-prompt.md`
+ * to layer on with `withSystemPrompt`.
+ *
+ * The glob is written here rather than reached for from a shared helper because
+ * this file SHIPS — see `agent.test.ts`.
+ */
+const agentDef = withDiscoveredTools(
+  authoredAgent,
+  import.meta.glob("./tools/*.ts", { eager: true }),
+);
+
+/**
+ * The key the run's steps read with `requireStepEnv`.
+ *
+ * Passed as the agent env so the eval's workflow engine publishes it: the
+ * gateway call below is answered by a fake, but `stepGenerate` asks for the key
+ * BEFORE it makes the request, so a run with no key fails on the missing
+ * credential rather than reaching the script. The ENVIRONMENT and nothing else —
+ * a template may not read a developer's CLI config.
+ */
+const EVAL_ENV = { ASSEMBLYAI_API_KEY: process.env.ASSEMBLYAI_API_KEY ?? "eval-scripted-key" };
+
+/** The one angle the scripted planner comes back with. */
+const ANGLE = "What second-hand cargo bikes actually sell for";
+
+/** The written report the scripted `writeReport` produces. */
+const REPORT_BODY =
+  "## Second-hand cargo bikes in Amsterdam\n\nAsking prices cluster between 1,200 and 2,400 EUR.";
+
+/** The two sentences the desk reads down the phone. */
+const SPOKEN_SUMMARY =
+  "Second-hand cargo bikes in Amsterdam mostly go for between one and two and a half thousand euros.";
+
+/**
+ * What the run's model calls are answered with, in the order the body asks.
+ *
+ * Six calls, and the ORDER is the assertion: brief, angles, the researcher's
+ * one action, the gap pass, the report, the spoken summary. A stage that
+ * disappeared or moved would hand a later stage an earlier reply, which is
+ * exactly what the two content assertions in "writes the report" catch.
+ *
+ * The researcher's action is `stop` on purpose: `search` and `read` go through
+ * `webSearch`/`visitWebpage`, whose fetch is the global one and not the step
+ * slot, so scripting them is not available here — a case that let them run
+ * would really search the web.
+ */
+const MODEL_SCRIPT: readonly string[] = [
+  JSON.stringify({
+    brief: "What a used cargo bike costs in Amsterdam, and where they are sold.",
+    criteria: ["typical asking prices", "where people buy them"],
+  }),
+  JSON.stringify({ angles: [ANGLE] }),
+  JSON.stringify({ action: "stop", why: "the budget is better spent elsewhere" }),
+  JSON.stringify({ angles: [] }),
+  REPORT_BODY,
+  SPOKEN_SUMMARY,
+];
+
+/** A scripted step HTTP surface, and the gate that holds its first answer. */
+type ScriptedSteps = {
+  /** Every step request, in order — the gateway calls the run really made. */
+  readonly calls: readonly { url: string; method: string }[];
+  /** Let a held first answer through. Idempotent. */
+  readonly release: () => void;
+};
+
+/**
+ * Answer the run's model calls from {@link MODEL_SCRIPT}.
+ *
+ * Through `stepFetch`'s published slot rather than `vi.stubGlobal("fetch")`,
+ * which is what a step really dials — and which leaves the SESSION's own model
+ * on the live path, so a live case still measures the agent. Anything that is
+ * not the gateway THROWS rather than answering 200: an unexpected request from
+ * a step is a finding, and a silent empty body would be read as a model that
+ * said nothing.
+ *
+ * `hold` keeps the FIRST answer pending, which is the only way to observe a run
+ * that is still going: a durable `sleep` is skipped here, so an unheld run
+ * finishes in milliseconds.
+ */
+function scriptSteps(options: { hold?: boolean } = {}): ScriptedSteps {
+  const gate = Promise.withResolvers<void>();
+  let served = 0;
+  const stub = installStubStepFetch(async (request) => {
+    if (!request.url.includes("/chat/completions")) {
+      throw new Error(`unexpected step request in an eval: ${request.method} ${request.url}`);
+    }
+    const at = served++;
+    if (options.hold === true && at === 0) await gate.promise;
+    const content = MODEL_SCRIPT[Math.min(at, MODEL_SCRIPT.length - 1)];
+    return { body: { choices: [{ message: { content } }] } };
+  });
+  return { calls: stub.calls, release: () => gate.resolve() };
+}
+
+/** `request_research`'s answer when it really started something. */
+const Started = z.object({
+  started: z.literal(true),
+  runId: z.string().min(1),
+  topic: z.string().min(1),
+});
+
+/**
+ * The run id a `request_research` call reported.
+ *
+ * Parsed rather than regexed: a tool result reaches the event stream as a
+ * serialized string, and a shape that stopped matching should fail HERE naming
+ * the field instead of handing the next assertion `undefined`.
+ */
+function startedRunId(calls: readonly EvalToolCall[]): string {
+  const call = calls.find((one) => one.name === "request_research");
+  if (call?.result === undefined) {
+    throw new Error(
+      `the desk called no request_research: ${calls.map((one) => one.name).join(", ") || "(no tools)"}`,
+    );
+  }
+  return Started.parse(JSON.parse(call.result)).runId;
+}
+
+/** Every tool call in this turn that READS a run, whichever the model picked. */
+function readbacks(calls: readonly EvalToolCall[]): readonly EvalToolCall[] {
+  return calls.filter((one) => one.name === "research_status" || one.name === "research_progress");
+}
+
+/** The one utterance every case that starts work opens with. */
+const ASK = "Please research the second-hand cargo bike market in Amsterdam for me.";
+
+/** The scripted session turn that answers {@link ASK}. */
+const START_TURN = [
+  { tool: "request_research", args: { topic: "the second-hand cargo bike market in Amsterdam" } },
+  "I've started looking into that — I'll let you know when it lands.",
+] as const;
+
+/**
+ * Let the run finish before the case ends.
+ *
+ * Not tidiness: the scripted `stepFetch` is unpublished when the test that
+ * installed it finishes, so a body still mid-flight would make its next model
+ * call against whatever the next case publishes — or against the real gateway.
+ */
+async function drain(workflows: EvalWorkflows | undefined, steps: ScriptedSteps): Promise<void> {
+  steps.release();
+  for (const run of await (workflows?.runs() ?? [])) {
+    await workflows?.settle(run.runId, research);
+  }
+}
+
+describeEval(
+  agentDef,
+  (test) => {
+    test(
+      "hands the topic to a run and answers the turn without waiting for it",
+      async ({ session, workflows }) => {
+        // Held, so the run cannot possibly have finished by the time the desk
+        // replies — which is the whole claim of the handoff shape.
+        const steps = scriptSteps({ hold: true });
+
+        const turn = await session.say(ASK);
+
+        const runId = startedRunId(turn.toolCalls);
+        expect(turn.completed).toBe(true);
+        // The topic it passed is the caller's, not a paraphrase of the prompt.
+        const asked = turn.toolCalls.find((one) => one.name === "request_research");
+        expect(String(asked?.args.topic)).toMatch(/cargo bike/i);
+
+        // The run is REAL: the engine started it, under the name the agent
+        // declares, and it is still going now that the turn has ended.
+        const runs = await (workflows?.runs() ?? []);
+        const started = runs.find((one) => one.runId === runId);
+        expect(started?.workflow).toBe("research");
+        expect(started?.status).toBe("running");
+        // And it really began work — the brief stage narrated before its model
+        // call, which is the request this case is holding.
+        expect(started?.reported.join("\n")).toMatch(/really asking/);
+
+        await drain(workflows, steps);
+      },
+      { stubReply: [...START_TURN] },
+    );
+
+    test(
+      "the run really writes the report, and asks for the review wait",
+      async ({ session, workflows }) => {
+        const steps = scriptSteps();
+
+        const turn = await session.say(ASK);
+        const runId = startedRunId(turn.toolCalls);
+        const run = await workflows?.settle(runId, research);
+
+        // What a completed run reports as `output` is what the agent reads back
+        // and what the announcement is built from, so every field is asserted.
+        expect(run?.status).toBe("completed");
+        expect(run?.output?.report).toBe(REPORT_BODY);
+        expect(run?.output?.summary).toBe(SPOKEN_SUMMARY);
+        expect(run?.output?.angles).toEqual([ANGLE]);
+        expect(run?.output?.filedAt).toBe("filed");
+
+        // The five stages, in order, off the run's own narration — which is
+        // also what `research_progress` reads back down the phone. A stage that
+        // stopped reporting is a caller who is told nothing for minutes.
+        const narration = run?.reported.join("\n") ?? "";
+        expect(narration).toMatch(/really asking/);
+        expect(narration).toMatch(/Researching 1 angle/);
+        expect(narration).toMatch(new RegExp(`Looking into: ${ANGLE}`));
+        expect(narration).toMatch(/writing it up/);
+        expect(narration).toMatch(/Writing up 1 angle/);
+        expect(run?.reported.at(-1)).toBe("Filing the findings.");
+
+        // The review wait, ASKED FOR and not taken: this engine records a
+        // durable `sleep` rather than suspending, so what a case can honestly
+        // claim is that the body asked — and that is the assertion that fails
+        // if the suspension is ever deleted.
+        expect(run?.slept).toEqual([{ duration: "30 seconds" }]);
+
+        // Six model calls, all through the step slot: the fan-out's width came
+        // from a journaled stage rather than from anything the body recomputed.
+        expect(steps.calls).toHaveLength(MODEL_SCRIPT.length);
+      },
+      { stubReply: [...START_TURN] },
+    );
+
+    test(
+      "reads the live run back rather than guessing at it",
+      async ({ session, workflows }) => {
+        const steps = scriptSteps({ hold: true });
+
+        const started = await session.say(ASK);
+        const runId = startedRunId(started.toolCalls);
+        const turn = await session.say("What's it doing right now?");
+
+        // WHICH of the two readback tools the model picks is its business —
+        // the prompt offers both — so the claim is about what it was told:
+        // either the run's own latest progress line or its status, and never
+        // an answer the desk invented.
+        const read = readbacks(turn.toolCalls);
+        expect(read.length).toBeGreaterThan(0);
+        const answered = read.map((one) => one.result ?? "").join("\n");
+        expect(answered).toMatch(/really asking|Still working on it/);
+        expect(answered).not.toMatch(/Nothing started yet/);
+
+        // The load-bearing half: that readback happened while the run was
+        // genuinely in flight, which is the only state these two tools exist
+        // for.
+        const runs = await (workflows?.runs() ?? []);
+        expect(runs.find((one) => one.runId === runId)?.status).toBe("running");
+
+        await drain(workflows, steps);
+      },
+      {
+        stubReply: [
+          ...START_TURN,
+          { tool: "research_progress", args: {} },
+          "It's still working out what the question really is.",
+        ],
+      },
+    );
+
+    test(
+      "says nothing is running when nothing is, and starts nothing to find out",
+      async ({ session, workflows }) => {
+        const steps = scriptSteps();
+
+        const turn = await session.say("Any news on that research I asked for?");
+
+        const read = readbacks(turn.toolCalls);
+        expect(read.length).toBeGreaterThan(0);
+        expect(read.map((one) => one.result ?? "").join("\n")).toMatch(/Nothing started yet/);
+        // A question is not a request: asking after work nobody asked for must
+        // not put a run — and a research pass's worth of model calls — on the
+        // account.
+        expect(await (workflows?.runs() ?? [])).toEqual([]);
+        expect(steps.calls).toEqual([]);
+      },
+      {
+        stubReply: [
+          { tool: "research_status", args: {} },
+          "Nothing has been started yet — want me to look into something?",
+        ],
+      },
+    );
+  },
+  { env: EVAL_ENV },
+);

package/dist/templates/research-workflow/agent.test.ts

@@ -20,18 +20,19 @@
  * builds a project and runs one.
  */
 
-import type { ToolContext, WorkflowClient, WorkflowRunSnapshot } from "@alexkroman1/aai";
+import type { WorkflowClient } from "@alexkroman1/aai";
 import {
-  createProgressStream,
   createRunSnapshot,
-  createStubWorkflows,
   createToolContext,
-  runTool,
+  parseSchemaInput,
   type StubGatewayCall,
+  schemaInputIssues,
+  toolRunner,
   withDiscoveredTools,
 } from "@alexkroman1/aai/testing";
-import { installStubGateway as stubGateway } from "@alexkroman1/aai/testing/vitest";
+import { mockWorkflows, installStubGateway as stubGateway } from "@alexkroman1/aai/testing/vitest";
 import { visitWebpage, webSearch } from "@alexkroman1/aai/tools";
+import type { WorkflowRunSnapshot } from "@alexkroman1/aai/workflow-api";
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import { FatalError, RetryableError } from "workflow";
 import authoredAgent from "./agent.ts";
@@ -75,37 +76,34 @@ const agentDef = withDiscoveredTools(
   import.meta.glob("./tools/*.ts", { eager: true }),
 );
 
-/** Every tool here is driven through the agent's own table, by the name the model calls. */
-const run = (name: string, args: Record<string, unknown>, ctx: ToolContext): Promise<unknown> =>
-  runTool(agentDef, name, args, ctx);
+/**
+ * Every tool here is driven through the agent's own table, by the name the model
+ * calls.
+ *
+ * The second parameter is args-or-context, which is `runTool`'s own shape: three
+ * of this desk's four tools take no arguments, and the `{}` those calls were
+ * obliged to pass sat between the two values a reader cares about.
+ */
+const run = toolRunner(agentDef);
 
 /**
  * A `ctx.workflows` that records `start` and answers `find` from a fixture.
  *
  * Returned WITHOUT a cast, which is the property worth keeping: a cast would
  * also stop reporting the day `WorkflowClient` grows a method, and this stub is
- * how the template's tools reach the client at all. `createStubWorkflows` is
- * what keeps that affordable — it fills in the methods this desk does not
- * drive, so the day the client does grow one, only the tests that use it change.
+ * how the template's tools reach the client at all. `mockWorkflows`
+ * (`@alexkroman1/aai/testing/vitest`) is what keeps that affordable — a `vi.fn`
+ * per method over one `runs` list, filling in what this desk does not drive, so
+ * the day the client does grow a method only the tests using it change.
+ * `stream`/`streamTail` are left rejecting on purpose: `research_progress` reads
+ * progress through `lastLine`, and composing those two by hand is the hazard
+ * `lastLine` exists to remove.
  */
 function stubWorkflows(runs: WorkflowRunSnapshot[] = []): WorkflowClient {
-  return createStubWorkflows({
-    start: vi.fn(async () => "wrun_stub"),
-    get: vi.fn(async () => runs[0]),
-    find: vi.fn(async () => runs),
-    recent: vi.fn(async () => runs),
-    cancel: vi.fn(async () => true),
-    wakeUp: vi.fn(async () => 0),
-    // A tail of 0 means "one line written", which is the case the tools read.
-    // The `-1` case is overridden per test, because it is the one that decides
-    // whether the stream is opened at all.
-    streamTail: vi.fn(async () => 0),
-    stream: vi.fn(async () => createProgressStream([])),
-    // Name only: `WorkflowDef.description` is optional, so passing it through
-    // would mean handing `description: undefined` to a field that does not
-    // accept it. Nothing here reads the description anyway.
-    listing: () => [{ name: "research" }],
-  });
+  // Name only: `WorkflowSummary.description` is optional, so passing this
+  // desk's through would mean handing `description: undefined` to a field that
+  // does not accept it. Nothing here reads the description anyway.
+  return mockWorkflows({ runs, names: ["research"] });
 }
 
 describe("the agent declares its workflow", () => {
@@ -115,13 +113,16 @@ describe("the agent declares its workflow", () => {
   });
 
   test("with an input schema, so a bad topic fails at the call site", async () => {
-    const result = await research.input?.["~standard"].validate({
-      topic: "otters",
-      requestedBy: "s",
-    });
-    expect(result?.issues).toBeUndefined();
-    const bad = await research.input?.["~standard"].validate({ topic: "no", requestedBy: "s" });
-    expect(bad?.issues).toBeDefined();
+    // `parseSchemaInput` / `schemaInputIssues` rather than a reach through
+    // `["~standard"].validate`: that is the vendor WIRE contract, and whether it
+    // answers synchronously or with a promise is the vendor's business — a
+    // missing `await` there leaves `.issues` undefined and the refusing half
+    // passes for the wrong reason.
+    const parsed = await parseSchemaInput(research.input, { topic: "otters", requestedBy: "s" });
+    expect(parsed).toMatchObject({ topic: "otters" });
+    expect(
+      await schemaInputIssues(research.input, { topic: "no", requestedBy: "s" }),
+    ).toBeDefined();
   });
 });
 
@@ -184,7 +185,7 @@ describe("request_research", () => {
 describe("research_status", () => {
   test("says nothing was started when the key has no runs", async () => {
     const ctx = createToolContext({ workflows: stubWorkflows([]) });
-    const result = await run("research_status", {}, ctx);
+    const result = await run("research_status", ctx);
     expect(result).toMatchObject({ runs: [], note: "Nothing started yet." });
   });
 
@@ -197,7 +198,7 @@ describe("research_status", () => {
       }),
     ];
     const ctx = createToolContext({ workflows: stubWorkflows(runs) });
-    const result = (await run("research_status", {}, ctx)) as { runs: string[] };
+    const result = (await run("research_status", ctx)) as { runs: string[] };
     expect(result.runs[0]).toContain("Otters use tools.");
     expect(result.runs[0]).toContain("3 sources");
   });
@@ -206,7 +207,7 @@ describe("research_status", () => {
     const ctx = createToolContext({
       workflows: stubWorkflows([createRunSnapshot({ workflow: "research", status: "running" })]),
     });
-    const result = (await run("research_status", {}, ctx)) as { runs: string[] };
+    const result = (await run("research_status", ctx)) as { runs: string[] };
     expect(result.runs[0]).toContain("Still working on it.");
   });
 
@@ -215,14 +216,14 @@ describe("research_status", () => {
       createRunSnapshot({ workflow: "research", status: "failed", error: "model unavailable" }),
     ];
     const ctx = createToolContext({ workflows: stubWorkflows(runs) });
-    const result = (await run("research_status", {}, ctx)) as { runs: string[] };
+    const result = (await run("research_status", ctx)) as { runs: string[] };
     expect(result.runs[0]).toContain("model unavailable");
   });
 
   test("bounds how many past runs it reads aloud", async () => {
     const workflows = stubWorkflows([]);
     const ctx = createToolContext({ workflows });
-    await run("research_status", {}, ctx);
+    await run("research_status", ctx);
     // A voice reply cannot be a list of twenty runs.
     expect(workflows.find).toHaveBeenCalledWith(research, ctx.sessionId, { limit: 3 });
   });
@@ -233,40 +234,40 @@ describe("research_progress", () => {
     const workflows = stubWorkflows([
       createRunSnapshot({ workflow: "research", status: "running" }),
     ]);
-    vi.mocked(workflows.stream).mockResolvedValue(createProgressStream(["Found 3 sources."]));
-    const ctx = createToolContext({ workflows });
-    const result = await run("research_progress", {}, ctx);
+    vi.mocked(workflows.lastLine).mockResolvedValue("Found 3 sources.");
+    const result = await run("research_progress", createToolContext({ workflows }));
     expect(result).toMatchObject({ progress: "Found 3 sources." });
   });
 
   test("asks for the LAST line, not the whole log", async () => {
-    // A voice reply cannot recite every line the run has written.
+    // A voice reply cannot recite every line the run has written. `lastLine` is
+    // the whole request — the bound that keeps an empty channel from hanging
+    // belongs to the method, so nothing here composes `streamTail` and `stream`.
     const workflows = stubWorkflows([
       createRunSnapshot({ workflow: "research", status: "running" }),
     ]);
-    vi.mocked(workflows.stream).mockResolvedValue(createProgressStream(["a"]));
-    await run("research_progress", {}, createToolContext({ workflows }));
-    expect(workflows.stream).toHaveBeenCalledWith("wrun_1", { startIndex: -1 });
+    vi.mocked(workflows.lastLine).mockResolvedValue("a");
+    await run("research_progress", createToolContext({ workflows }));
+    expect(workflows.lastLine).toHaveBeenCalledWith("wrun_1");
   });
 
-  test("a run that has written nothing yet says so WITHOUT opening the stream", async () => {
-    // Not a shortcut: an empty progress channel is never closed, so reading one
-    // would wait for a line that arrives whenever the next step writes — i.e.
-    // the tool hangs instead of answering. The tail is how that is known.
+  test("a run that has written nothing yet says so", async () => {
+    // `lastLine` resolves `undefined` for an empty channel, and this is the arm
+    // the tool branches on. That an empty channel does not HANG — it is never
+    // closed, so a stream opened on one waits for a line that may never come —
+    // is `lastLine`'s own guarantee now, and `aai`'s to test.
     const workflows = stubWorkflows([
       createRunSnapshot({ workflow: "research", status: "running" }),
     ]);
-    vi.mocked(workflows.streamTail).mockResolvedValue(-1);
-    const result = await run("research_progress", {}, createToolContext({ workflows }));
+    const result = await run("research_progress", createToolContext({ workflows }));
     expect(result).toMatchObject({ note: "Started, nothing to report yet." });
-    expect(workflows.stream).not.toHaveBeenCalled();
   });
 
   test("says nothing was started when the key has no runs", async () => {
     const workflows = stubWorkflows([]);
-    const result = await run("research_progress", {}, createToolContext({ workflows }));
+    const result = await run("research_progress", createToolContext({ workflows }));
     expect(result).toMatchObject({ note: "Nothing started yet." });
-    expect(workflows.stream).not.toHaveBeenCalled();
+    expect(workflows.lastLine).not.toHaveBeenCalled();
   });
 });
 
@@ -276,7 +277,7 @@ describe("file_it_now", () => {
       createRunSnapshot({ workflow: "research", status: "running" }),
     ]);
     vi.mocked(workflows.wakeUp).mockResolvedValue(1);
-    const result = await run("file_it_now", {}, createToolContext({ workflows }));
+    const result = await run("file_it_now", createToolContext({ workflows }));
     expect(workflows.wakeUp).toHaveBeenCalledWith("wrun_1");
     expect(result).toMatchObject({ filed: true });
   });
@@ -288,13 +289,13 @@ describe("file_it_now", () => {
       createRunSnapshot({ workflow: "research", status: "running" }),
     ]);
     vi.mocked(workflows.wakeUp).mockResolvedValue(0);
-    const result = await run("file_it_now", {}, createToolContext({ workflows }));
+    const result = await run("file_it_now", createToolContext({ workflows }));
     expect(result).toMatchObject({ filed: false });
   });
 
   test("says nothing was started when the key has no runs", async () => {
     const workflows = stubWorkflows([]);
-    const result = await run("file_it_now", {}, createToolContext({ workflows }));
+    const result = await run("file_it_now", createToolContext({ workflows }));
     expect(result).toMatchObject({ note: "Nothing started yet." });
     expect(workflows.wakeUp).not.toHaveBeenCalled();
   });

package/dist/templates/research-workflow/tools/research_progress.ts

@@ -10,17 +10,14 @@ export default tool({
     // has WRITTEN (`getWritable()` in `workflows/research.ts`). Between "still
     // working on it" and a finished summary there is otherwise nothing to say.
     //
-    // `streamTail` FIRST, and not as an optimization: a progress channel is
-    // never closed — no step knows it is the last one — so reading a stream
-    // with nothing in it waits forever rather than ending. `-1` is "nothing
-    // written yet", and it is the only safe way to learn that.
-    if ((await ctx.workflows.streamTail(latest.runId)) < 0) {
-      return { note: "Started, nothing to report yet." };
-    }
-    // A negative `startIndex` reads from the END, which is what a voice reply
-    // wants — the last line, not a recital of the whole log.
-    const stream = await ctx.workflows.stream(latest.runId, { startIndex: -1 });
-    for await (const line of stream) return { progress: String(line) };
-    return { note: "Started, nothing to report yet." };
+    // `lastLine` rather than `streamTail` + `stream` composed here: a progress
+    // channel is never closed — no step knows it is the last one — so a stream
+    // opened on a run that has written nothing waits forever, which down a phone
+    // is a turn that stops with no error and nothing in a log. The bound that
+    // prevents it belongs to the method now, and `undefined` is "nothing yet".
+    const line = await ctx.workflows.lastLine(latest.runId);
+    return line === undefined
+      ? { note: "Started, nothing to report yet." }
+      : { progress: String(line) };
   },
 });

package/dist/templates/research-workflow/tools/research_status.ts

@@ -1,9 +1,6 @@
-import {
-  isTerminal,
-  tool,
-  type WorkflowOutputOf,
-  type WorkflowRunSnapshot,
-} from "@alexkroman1/aai";
+import { tool } from "@alexkroman1/aai";
+import { plural } from "@alexkroman1/aai/utils";
+import { isTerminal, type WorkflowRunOf } from "@alexkroman1/aai/workflow-api";
 import { research } from "../shared.ts";
 
 /** How many past runs the status tool will look at. Newest first. */
@@ -12,17 +9,18 @@ const RECENT_RUNS = 3;
 /**
  * One line a voice agent can read aloud about a run.
  *
- * `WorkflowOutputOf` is what names the output type — the same helper a page uses
- * to type `run.output`, and the reason this signature does not have to reach
- * past the declaration into the body's own return type.
+ * `WorkflowRunOf` is the snapshot with its output already typed — the
+ * `WorkflowRunSnapshot<WorkflowOutputOf<typeof research>>` this file used to
+ * compose by hand, which cost a three-name import for one type. Still the
+ * discriminated union, so `isTerminal` below narrows exactly as it did.
  */
-function describeRun(run: WorkflowRunSnapshot<WorkflowOutputOf<typeof research>>): string {
+function describeRun(run: WorkflowRunOf<typeof research>): string {
   // `isTerminal` narrows to the three finished statuses, which is what makes
   // `run.output` and `run.error` reachable without a cast.
   if (!isTerminal(run)) return "Still working on it.";
   switch (run.status) {
     case "completed":
-      return `Done: ${run.output.summary} (${run.output.sources} sources)`;
+      return `Done: ${run.output.summary} (${run.output.sources} ${plural(run.output.sources, "source")})`;
     case "failed":
       return `That one failed: ${run.error}`;
     default: