@alexkroman1/aai-cli 6.11.0 → 7.0.0

package/dist/templates/recap-workflow/tools/request_recap.ts

@@ -1,4 +1,5 @@
-import { isTerminal, tool } from "@alexkroman1/aai";
+import { tool } from "@alexkroman1/aai";
+import { isTerminal } from "@alexkroman1/aai/workflow-api";
 import { z } from "zod";
 import { recap, SAMPLE_RECORDING } from "../shared.ts";
 

package/dist/templates/recap-workflow/workflows/recap.ts

@@ -55,7 +55,7 @@
  * Everything the desk claims to do. `submitRecording`, `checkTranscript` and
  * `discardTranscript` are AssemblyAI's pre-recorded API (`POST`, `GET` and
  * `DELETE` on `/v2/transcript`), and `summarize` is a real model call through
- * `stepGenerate`. The BATCH API is what makes the polling port honest: it
+ * `stepGenerateJsonClassified`. The BATCH API is what makes the polling port honest: it
  * answers with a job id in milliseconds and finishes minutes later, so the wait
  * is the provider's, not a `setTimeout` this template chose. (Its sibling
  * `transcription-workflow` takes the other endpoint — the sync one, which answers in
@@ -67,17 +67,14 @@
  * just your shell.
  */
 
-import { throwStepError, toStepError } from "@alexkroman1/aai/step-errors";
+import { report, requireStepEnv, stepFetch } from "@alexkroman1/aai/step";
 import {
-  errorMessage,
-  isRecord,
-  omitUndefined,
-  report,
-  requireStepEnv,
-  stepFetch,
-  stepGenerateJson,
-  stepTranscribeSubmit,
-} from "@alexkroman1/aai/utils";
+  stepFetchOk,
+  stepGenerateJsonClassified,
+  stepTranscribeSubmitClassified,
+  toStepError,
+} from "@alexkroman1/aai/step-errors";
+import { errorMessage, isRecord, omitUndefined } from "@alexkroman1/aai/utils";
 import { createHook, FatalError, sleep } from "workflow";
 import { z } from "zod";
 import { retentionToken } from "./tokens.ts";
@@ -151,7 +148,7 @@ const POINTS = 3;
 /**
  * The shape the model must answer in.
  *
- * `stepGenerateJson` validates against this and throws PLAINLY when the reply
+ * `stepGenerateJsonClassified` validates against this and throws PLAINLY when the reply
  * misses, which is the retry policy in one distinction: a model that answered in
  * prose may answer correctly next time, where a 401 will not. `spoken` is the
  * field this template exists for — without it the announced turn has nothing to
@@ -257,7 +254,7 @@ export async function recapFlow(input: { url: string; requestedBy: string }) {
  * to completion in a worker, where the body is what may suspend. Splitting it
  * out keeps `recapFlow` readable and costs nothing, since the WDK transform
  * rewrites a step's DECLARATION rather than its call sites, so a step called
- * from a helper is still a real step (`mapInBatches` rests on the same
+ * from a helper is still a real step (`mapConcurrent` rests on the same
  * property).
  *
  * The loop is deterministic despite looking like it is not: every branch turns
@@ -359,13 +356,14 @@ export async function submitRecording(url: string): Promise<{ id: string }> {
 
   await report(`Submitting ${new URL(url).hostname} for transcription…`);
 
-  // `stepTranscribeSubmit` owns the endpoint, the raw-key auth, the PLURAL
-  // `speech_models` field and the failure classification. `speaker_labels` is
-  // this desk's own request, which is what `params` is for — the async API's
+  // `stepTranscribeSubmitClassified` owns the endpoint, the raw-key auth, the
+  // PLURAL `speech_models` field and the failure classification — the
+  // `Classified` suffix being that last part: it is `stepTranscribeSubmit` with
+  // `throwStepError` already applied, so a provider refusal stays terminal and a
+  // rate limit waits out the delay the provider itself named. `speaker_labels`
+  // is this desk's own request, which is what `params` is for — the async API's
   // surface is large and the SDK deliberately does not mirror it.
-  return await stepTranscribeSubmit(url, { params: { speaker_labels: true } }).catch(
-    throwStepError,
-  );
+  return await stepTranscribeSubmitClassified(url, { params: { speaker_labels: true } });
 }
 
 /**
@@ -467,19 +465,20 @@ export async function summarize(url: string, transcript: TranscriptState): Promi
     throw new FatalError("That recording came back with no speech in it.");
   }
 
-  // `stepGenerateJson` unwraps the fence a model puts around JSON however firmly
-  // it is told not to, parses it, and validates it — all four things this step
-  // used to re-derive. `throwStepError` is what makes a terminal gateway failure
-  // (a bad key, a rejected request) stop rather than burn the remaining
-  // attempts, where a reply that missed the SHAPE throws plainly and retries.
-  const parsed = await stepGenerateJson(text, {
+  // `stepGenerateJsonClassified` unwraps the fence a model puts around JSON
+  // however firmly it is told not to, parses it, and validates it — all four
+  // things this step used to re-derive. The `Classified` half is what makes a
+  // terminal gateway failure (a bad key, a rejected request) stop rather than
+  // burn the remaining attempts, where a reply that missed the SHAPE throws
+  // plainly and retries.
+  const parsed = await stepGenerateJsonClassified(text, {
     schema: RecapReply,
     system:
       "You write up recordings for someone who will hear the result on a phone call. " +
       `Reply with JSON only: {"headline": string, "points": string[], "spoken": string}. ` +
       `Give exactly ${POINTS} points. "spoken" is ONE sentence, under 30 words, ` +
       "written to be read aloud. No markdown fence, no preamble.",
-  }).catch(throwStepError);
+  });
 
   return {
     url,
@@ -519,27 +518,24 @@ async function request(
   url: string,
   init: { method?: string; body?: string } = {},
 ): Promise<Response> {
-  // `stepFetch`, not `fetch`: it pins HTTP/1.1, so several concurrent runs (and
-  // this workflow POLLS, so one run is many requests) get a socket each rather
-  // than N streams on one connection — and a connection failure arrives as a
-  // `StepTransportError` naming its cause instead of a bare
+  // Through `stepFetch`, not `fetch`: it pins HTTP/1.1, so several concurrent
+  // runs (and this workflow POLLS, so one run is many requests) get a socket
+  // each rather than N streams on one connection — and a connection failure
+  // arrives as a `StepTransportError` naming its cause instead of a bare
   // `TypeError: fetch failed`, which for a template whose whole subject is
   // durability is the difference between a diagnosable resume and a mystery.
   // `sdk/step-fetch.ts` carries the measurements.
-  const response = await stepFetch(url, {
+  // `stepFetchOk` makes the three-way retry decision: a 401 or a 400 answers the
+  // same way on the fourth attempt and burns the step, a 429 or a 5xx is what
+  // retries are for, and a `Retry-After` the provider named is waited out rather
+  // than replaced by the DevKit's one-second default — which matters here more
+  // than usual, because a fan-out of segments hits a rate limit together. The
+  // DELETE below stays on plain `stepFetch`, because there a 404 is a SUCCESS.
+  return await stepFetchOk(url, {
     ...init,
     headers: { authorization: requireStepEnv(API_KEY_ENV), "content-type": "application/json" },
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
   });
-  // The three-way retry decision, made by the SDK: a 401 or a 400 answers the
-  // same way on the fourth attempt and burns the step, a 429 or a 5xx is what
-  // retries are for, and a `Retry-After` the provider named is waited out rather
-  // than replaced by the DevKit's one-second default — which matters here more
-  // than usual, because a fan-out of segments hits a rate limit together.
-  if (!response.ok) {
-    throw toStepError(response, `${init.method ?? "GET"} ${url} failed: HTTP ${response.status}`);
-  }
-  return response;
 }
 
 /** A string field of a JSON body, when it really is one. */

package/dist/templates/redline/agent.test.ts

@@ -17,6 +17,7 @@
  * of that lives.
  */
 
+import { parseSchemaInput, schemaInputIssues } from "@alexkroman1/aai/testing";
 import { installStubGateway as stubGateway } from "@alexkroman1/aai/testing/vitest";
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import { FatalError } from "workflow";
@@ -24,7 +25,6 @@ import agentDef, { MAX_ROUNDS, redline } from "./agent.ts";
 import {
   briefBlock,
   clampScore,
-  countWords,
   critiqueDraft,
   MAX_NOTES,
   type RedlineInput,
@@ -70,30 +70,37 @@ describe("the agent declares itself a workflow app", () => {
 });
 
 describe("the input schema", () => {
-  const validate = (value: unknown) => redline.input?.["~standard"].validate(value);
+  // `schemaInputIssues` / `parseSchemaInput` rather than a local 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 every refusing test below
+  // passes for the wrong reason.
+  const issues = (value: unknown) => schemaInputIssues(redline.input, value, "redline");
 
   test("caps the rounds at the CALL SITE rather than on the bill", async () => {
-    const tooMany = await validate({ ...INPUT, rounds: MAX_ROUNDS + 1 });
-    expect(tooMany?.issues).toBeDefined();
+    expect(await issues({ ...INPUT, rounds: MAX_ROUNDS + 1 })).toBeDefined();
   });
 
   test("defaults the rounds and the required points, so the form need not", async () => {
-    const result = await validate({ brief: INPUT.brief, audience: "engineers" });
-    if (!result || result.issues) throw new Error("expected valid input");
-    expect(result.value).toMatchObject({ rounds: 2, mustCover: [] });
+    const parsed = await parseSchemaInput(
+      redline.input,
+      { brief: INPUT.brief, audience: "engineers" },
+      "redline",
+    );
+    expect(parsed).toMatchObject({ rounds: 2, mustCover: [] });
   });
 
   test("rejects an audience outside the enum — which is also what makes it a select", async () => {
     // `<WorkflowFields>` renders a `z.enum` as a `<SelectField>`; the same
     // declaration is what stops an API caller inventing a fifth audience.
-    expect((await validate({ ...INPUT, audience: "cats" }))?.issues).toBeDefined();
+    expect(await issues({ ...INPUT, audience: "cats" })).toBeDefined();
   });
 
   test("declares mustCover as an array, which is what the page renders by hand", async () => {
     // The mixed-form case: `<WorkflowFields>` renders scalars only, so client.tsx
     // writes this field itself and maps a textarea into it.
-    expect((await validate({ ...INPUT, mustCover: "one point" }))?.issues).toBeDefined();
-    expect((await validate({ ...INPUT, mustCover: ["one point"] }))?.issues).toBeUndefined();
+    expect(await issues({ ...INPUT, mustCover: "one point" })).toBeDefined();
+    expect(await issues({ ...INPUT, mustCover: ["one point"] })).toBeUndefined();
   });
 });
 
@@ -111,11 +118,6 @@ describe("pure helpers", () => {
     expect(briefBlock({ ...INPUT, mustCover: [] })).toContain("nothing specific");
   });
 
-  test("countWords ignores surrounding and repeated whitespace", () => {
-    expect(countWords("  one  two\nthree ")).toBe(3);
-    expect(countWords("   ")).toBe(0);
-  });
-
   test("clampScore holds a model's number inside the range it was given", () => {
     expect(clampScore(12)).toBe(10);
     expect(clampScore(0)).toBe(1);

package/dist/templates/redline/client.tsx

@@ -27,7 +27,8 @@
  */
 
 import "@alexkroman1/aai-ui/styles.css";
-import type { WorkflowOutputOf } from "@alexkroman1/aai";
+import { plural } from "@alexkroman1/aai/utils";
+import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import {
   Form,
   type FormValues,
@@ -35,6 +36,7 @@ import {
   SubmitButton,
   TextAreaField,
   useWorkflowSubmit,
+  WORKFLOW_STATUS_LABELS,
   WorkflowFields,
   WorkflowProgress,
   type WorkflowRun,
@@ -150,8 +152,8 @@ function RunPanel({ run, onClear }: { run: WorkflowRun<Redline>; onClear: () =>
       {run.status === "completed" && (
         <>
           <p className="text-xs opacity-60">
-            {run.output.words} words · {run.output.roundsRun} round
-            {run.output.roundsRun === 1 ? "" : "s"} ·{" "}
+            {run.output.words} words · {run.output.roundsRun}{" "}
+            {plural(run.output.roundsRun, "round")} ·{" "}
             {/* Which of the two stop conditions ended the loop is the one thing
                 a reader cannot infer from the round count alone. */}
             {run.output.shipped ? "the critic stopped it" : "the round budget stopped it"}
@@ -170,15 +172,13 @@ function RunPanel({ run, onClear }: { run: WorkflowRun<Redline>; onClear: () =>
 /**
  * One line describing where a run has got to.
  *
- * A `Record` keyed by the status union rather than a switch, so a status added
- * to the SDK is a compile error here instead of falling through a `default:`.
+ * The SDK's map with the one label this desk wants differently: `running` is
+ * "Writing…" here because that is what the run is doing. Spreading a COMPLETE
+ * `Record<WorkflowRunStatus, string>` cannot drop a key, so the exhaustiveness
+ * the hand-written copy was written for survives — and now lives at the SDK
+ * boundary, where a status added upstream is one compile error rather than one
+ * per page.
  */
-const STATUS_LINE: Record<WorkflowRun["status"], string> = {
-  pending: "Queued",
-  running: "Writing…",
-  completed: "Done",
-  failed: "Failed",
-  cancelled: "Cancelled",
-};
+const STATUS_LINE = { ...WORKFLOW_STATUS_LABELS, running: "Writing…" };
 
 page({ name: "Redline", component: RedlineDesk });

package/dist/templates/redline/workflows/redline.ts

@@ -31,8 +31,9 @@
  * three functions read more tidily than one.
  */
 
-import { throwStepError } from "@alexkroman1/aai/step-errors";
-import { report, stepGenerate, stepGenerateJson } from "@alexkroman1/aai/utils";
+import { report } from "@alexkroman1/aai/step";
+import { stepGenerateClassified, stepGenerateJsonClassified } from "@alexkroman1/aai/step-errors";
+import { countWords } from "@alexkroman1/aai/utils";
 import { FatalError } from "workflow";
 import { z } from "zod";
 import { CRITIC_SYSTEM, REVISER_SYSTEM, WRITER_SYSTEM } from "./prompts.ts";
@@ -145,7 +146,7 @@ export async function writeDraft(input: RedlineInput): Promise<string> {
   // `stepGenerate` already refuses an empty completion, as a RETRYABLE
   // `StepGenerateError` — which is the right answer, and one a hand-written
   // check would have to re-derive.
-  const draft = await ask(briefBlock(input), { system: WRITER_SYSTEM });
+  const draft = await stepGenerateClassified(briefBlock(input), { system: WRITER_SYSTEM });
   return draft.trim();
 }
 
@@ -168,10 +169,10 @@ export async function critiqueDraft(
   // `stepGenerateJson` owns the fence, the parse, the non-object case and the
   // shape — and throws PLAINLY when any of them misses, unlike the fatal one
   // above: a model that answered with prose may well obey on the next attempt.
-  const parsed = await stepGenerateJson(`${briefBlock(input)}\n\nThe submission:\n${draft}`, {
-    schema: CritiqueReply,
-    system: CRITIC_SYSTEM,
-  }).catch(throwStepError);
+  const parsed = await stepGenerateJsonClassified(
+    `${briefBlock(input)}\n\nThe submission:\n${draft}`,
+    { schema: CritiqueReply, system: CRITIC_SYSTEM },
+  );
 
   const critique: Critique = {
     verdict: parsed.verdict,
@@ -199,7 +200,7 @@ export async function reviseDraft(
   "use step";
 
   await report(`Round ${round}: revising.`);
-  const revised = await ask(
+  const revised = await stepGenerateClassified(
     [
       briefBlock(input),
       `Your current draft:\n${draft}`,
@@ -221,11 +222,6 @@ export function briefBlock(input: RedlineInput): string {
   return [`Brief: ${input.brief}`, `Audience: ${input.audience}`, must].join("\n\n");
 }
 
-export function countWords(text: string): number {
-  const trimmed = text.trim();
-  return trimmed.length === 0 ? 0 : trimmed.split(/\s+/).length;
-}
-
 /** Scores arrive from a model, so they arrive out of range often enough. */
 export function clampScore(score: number): number {
   if (!Number.isFinite(score)) return 0;
@@ -233,24 +229,16 @@ export function clampScore(score: number): number {
 }
 
 // ---- The model call ---------------------------------------------------------
-
-/**
- * `stepGenerate`, with this desk's retry POLICY on top.
- *
- * The SDK classifies the gateway's failure (`StepGenerateError.retryable`) and
- * stops there: whether a terminal failure should burn the step's remaining
- * attempts is the caller's call. `throwStepError`
- * (`@alexkroman1/aai/step-errors`) is that call made one way — terminal stays
- * terminal, and a rate limit becomes a `RetryableError` carrying the delay the
- * gateway itself named, which beats `RetryableError`'s own one-second default.
- *
- * This desk used to carry that mapping itself, as did `research-workflow` and
- * `link-digest`; it is one import now, and the delay is no longer the one line
- * only this template remembered.
- */
-async function ask(prompt: string, opts: { system: string }): Promise<string> {
-  return await stepGenerate(prompt, opts).catch(throwStepError);
-}
+//
+// There is no local `ask()` any more, and its absence is the point. The SDK
+// classifies the gateway's failure (`StepGenerateError.retryable`) and stops
+// there — whether a terminal failure should burn the step's remaining attempts
+// is the caller's call — so `stepGenerateClassified` and
+// `stepGenerateJsonClassified` (`@alexkroman1/aai/step-errors`) are that call
+// made one way: terminal stays terminal, and a rate limit becomes a
+// `RetryableError` carrying the delay the gateway itself named, which beats
+// `RetryableError`'s own one-second default. Three templates each wrapped the
+// raw `/step` call to say that; the wrapper is a suffix on the import now.
 
 /** A rate limit — and a model that ignored the format — are both expected. */
 critiqueDraft.maxRetries = 5;

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