@alexkroman1/aai-cli 13.1.0 → 13.3.0

package/dist/templates/spoken-summary/agent.test.ts

@@ -55,13 +55,22 @@ describe("the declaration", () => {
   test("is a workflow app with the one workflow the page starts by name", () => {
     // The page calls `api.start("spokenSummary", …)`, so a rename here is a
     // runtime 400 rather than a compile error. This is what pins it.
-    expect(Object.keys(agentDef.workflows ?? {})).toEqual(["spokenSummary"]);
+    // `toContain` rather than an exact key list: adding a second workflow is an
+    // invited edit and must not redden a test the author did not write. The
+    // NAME is still pinned, deliberately — the page starts a run by this
+    // string, so renaming the key is a runtime 400 rather than a compile
+    // error, and this pin is the only thing that says so. Rename it here and
+    // in `client.tsx` together.
+    expect(Object.keys(agentDef.workflows ?? {})).toContain("spokenSummary");
+    expect(agentDef.workflows?.spokenSummary).toBe(spokenSummary);
   });
 
-  test("declares no providers and exactly the one credential its steps read", () => {
+  test("declares the credential its steps read, so a deploy checks for it", () => {
     // A workflow app has no session, so nothing else in its config could name
     // one — and one AssemblyAI key covers transcription, the model and the voice.
-    expect(agentDef.requiredEnv).toEqual(["ASSEMBLYAI_API_KEY"]);
+    // `toContain`, so adding a step that reads a second credential and
+    // declaring it here does not fail this test.
+    expect(agentDef.requiredEnv).toContain("ASSEMBLYAI_API_KEY");
   });
 
   test("takes the recording as an UPLOAD, which is what makes the form a file picker", () => {
@@ -257,15 +266,20 @@ describe("the whole run", () => {
    * spec cannot pass because the fake and the step agree on a typo.
    */
   function stubProvider(reply: { headline: string; points: string[]; spoken: string }) {
+    // The model leg goes through `stubGatewayRoute` for the same reason, which
+    // this helper used to claim and not do: it hand-typed the completion
+    // envelope and recognised a model call by `llm-gateway`, the HOST. That is a
+    // property of one deployment rather than of the request — `stepGenerate`
+    // dials `${gatewayUrl ?? ASSEMBLYAI_LLM_GATEWAY_URL}/chat/completions`, so a
+    // caller pointing `gatewayUrl` at an OpenAI-compatible proxy of their own
+    // stops matching and the transcription fake answers a 404 to a model call.
+    const model = stubGatewayRoute(JSON.stringify(reply));
     return installStubTranscribe({
       audioUrl: "https://cdn/aai/1",
       jobIdPrefix: "t_",
       text: "we ship tuesday and two bugs are left",
       durationSec: 42,
-      otherwise: (request) =>
-        request.url.includes("llm-gateway")
-          ? { body: { choices: [{ message: { content: JSON.stringify(reply) } }] } }
-          : undefined,
+      otherwise: (request) => model.route(request),
     });
   }
 

package/dist/templates/spoken-summary/client.tsx

@@ -37,14 +37,15 @@
  * in React state — so a refresh lost it while the recording carried on being
  * transcribed, summarized and spoken. The bytes were already stored, so the
  * expensive half had happened; what an empty form invites is somebody uploading
- * the recording again and paying for all four legs twice. `key` is the handle
- * that survives a reload, `recover: true` is what reads it back, and the upload
- * half is already the SDK's — picking the same file again sends only the windows
- * that did not land.
+ * the recording again and paying for all four legs twice. Both halves are the
+ * SDK's now and this page writes neither: `useWorkflowSubmit` records the run
+ * under a correlation KEY it keeps for this page and asks for it again on the
+ * next load, and picking the same file again sends only the windows that did
+ * not land.
  *
- * **The key is `useRunKey()`** — opaque, and in `sessionStorage`, which is the
- * same lifetime as that upload recall, so both halves of a reload make the same
- * promise. What that rules out is a `?key=` parameter, and it is worth being
+ * **That key is `useRunKey()`'s** — opaque, and in `sessionStorage`, which is
+ * the same lifetime as the upload recall, so both halves of a reload make the
+ * same promise. What it rules out is a `?key=` parameter, and it is worth being
  * plain about the trade because this template exists to produce something
  * sendable: a summary you can listen to is exactly the sort of thing somebody
  * forwards, and a URL is how people forward things. But there is no per-user
@@ -57,9 +58,9 @@
  * the recording would be worse again: two people summarizing one file would
  * recover each other's runs.
  *
- * A real app with accounts passes the account's own id instead, and then a
- * summary follows the person to another device — a promise only a login can
- * keep.
+ * A real app with accounts passes the account's own id as `key` instead, and
+ * then a summary follows the person to another device — a promise only a login
+ * can keep.
  */
 
 import "@alexkroman1/aai-ui/styles.css";
@@ -74,7 +75,6 @@ import {
   SubmitButton,
   UploadProgressBar,
   useDownloadUrl,
-  useRunKey,
   useWorkflowSubmit,
   WorkflowFields,
   WorkflowProgress,
@@ -128,20 +128,16 @@ function captionsUrl(text: string, durationMs: number): string {
 }
 
 export function App() {
-  // This tab's handle on its own summaries, in the store the upload recall uses
-  // — see the module doc for why a `?key=` is the wrong trade here.
-  const key = useRunKey();
   // Did THIS load start the run? A reload cannot have, and that is the only way
   // the page can tell "working on what you just sent" from "picking up where
   // you left off" — the hook reports the run, not who asked for it.
   const [startedHere, setStartedHere] = useState(false);
   // The generic is what makes `run.status === "completed"` narrow to a TYPED
-  // `run.output` instead of `unknown`. Neither half of the recovery is useful
-  // alone: without `key` there is nothing to find the run by, and without
-  // `recover` the key is only ever written.
+  // `run.output` instead of `unknown`. The reload is the hook's own doing — see
+  // the module doc for why the key it mints is the right one for this page.
   const { submitForm, run, pending, upload, pauseUpload, resumeUpload, error } = useWorkflowSubmit<
     typeof spokenSummary
-  >(WORKFLOW, { api, key, recover: true });
+  >(WORKFLOW, { api });
   const output = run?.status === "completed" ? run.output : undefined;
   // `useDownloadUrl` is the SDK's: the byte route takes the agent's bearer, so the
   // bytes have to be FETCHED and handed to the element as an object URL — and the

package/dist/templates/support-line/agent.eval.test.ts

@@ -27,7 +27,13 @@
 
 /** The def a DEPLOYED agent runs — see `agent.test.ts` on why the glob is here. */
 import agentDef from "virtual:aai/agent";
-import { type EvalSession, toolResultIn } from "@alexkroman1/aai-runtime/eval";
+import {
+  describeToolCalls,
+  describeTurn,
+  type EvalSession,
+  statesIn,
+  toolResultIn,
+} from "@alexkroman1/aai-runtime/eval";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
 import { z } from "zod";
@@ -71,13 +77,14 @@ const Lookup = z.object({
   error: z.string().optional(),
 });
 
-/** Every `syncState` frame, in stream order. */
+/**
+ * Every `syncState` frame, in stream order.
+ *
+ * `statesIn` reads an EVENT LIST rather than a session, which is what lets a
+ * case slice the stream first; the schema above is what it takes one for.
+ */
 function frames(session: EvalSession) {
-  return session
-    .events()
-    .flatMap((event) =>
-      event.type === "state.updated" ? [ProjectedSupport.parse(event.state)] : [],
-    );
+  return statesIn(session.events(), ProjectedSupport);
 }
 
 /**
@@ -109,10 +116,10 @@ describeEval(agentDef, (test) => {
       // The reply rides in the message, because the failure that matters here is
       // a turn that SPOKE without looking anything up — "let me check that for
       // you" and then nothing, or worse, a notice period from memory.
-      expect(
-        asked.length,
-        `tools called: [${turn.toolCalls.map((c) => c.name).join(", ")}]; said: ${turn.text}`,
-      ).toBe(1);
+      // `describeTurn` is that sentence, and it says the two things a
+      // hand-built one left out: "called no tools" rather than an empty
+      // bracket, and whether the reply was cancelled.
+      expect(asked.length, describeTurn(turn)).toBe(1);
 
       for (const payload of lookups(session)) {
         // Three legal outcomes, and the invariant that spans them: an answer the
@@ -142,13 +149,9 @@ describeEval(agentDef, (test) => {
       await session.say("Yes please, log that one — my callback number is 07700 900123.");
 
       const logged = session.toolCalls().find((call) => call.name === "log_ticket");
-      expect(
-        logged,
-        `tools called: ${session
-          .toolCalls()
-          .map((c) => c.name)
-          .join(", ")}`,
-      ).toBeDefined();
+      // The claim spans both turns, so the message does too: `describeToolCalls`
+      // over the session's own list, where `describeTurn` would describe one.
+      expect(logged, describeToolCalls(session.toolCalls())).toBeDefined();
       expect(logged?.result).toMatch(/TCK\d{4}/);
 
       const latest = frames(session).at(-1);
@@ -189,10 +192,7 @@ describeEval(agentDef, (test) => {
       const turn = await session.say("How much notice do I have to give to cancel my contract?");
 
       const [payload] = lookups(session);
-      expect(
-        payload,
-        `tools called: [${turn.toolCalls.map((c) => c.name).join(", ")}]; said: ${turn.text}`,
-      ).toBeDefined();
+      expect(payload, describeTurn(turn)).toBeDefined();
       // The whole verdict in the message: `grounded: undefined` on its own does
       // not say whether the lookup failed, or ran and refused.
       const verdict = JSON.stringify(payload);
@@ -238,10 +238,7 @@ describeEval(agentDef, (test) => {
       );
 
       const [payload] = lookups(session);
-      expect(
-        payload,
-        `tools called: [${turn.toolCalls.map((c) => c.name).join(", ")}]; said: ${turn.text}`,
-      ).toBeDefined();
+      expect(payload, describeTurn(turn)).toBeDefined();
       // Withheld, not softened: `answer: null` is the tool refusing to hand the
       // model something to read out, and the guidance is the exit the grading
       // apparatus needs — a support line that can only answer will answer wrong.

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

@@ -143,15 +143,19 @@ function wavFile(
   return head;
 }
 
-describe("the agent declares its three workflows and nothing else", () => {
+describe("the agent declares its three workflows", () => {
   test("under the names the REST route resolves them by", () => {
     // The page starts a run by these strings, so a rename is a runtime 400 rather
     // than a compile error — which is what makes pinning them worth a test.
-    expect(Object.keys(agentDef.workflows ?? {})).toEqual([
-      "transcribe",
-      "transcribeStream",
-      "transcribeBatch",
-    ]);
+    // `arrayContaining` rather than an exact key list: a fourth desk of your own
+    // is an invited edit and must not redden a test you did not write. These
+    // three NAMES stay pinned, deliberately — the page starts a run by each
+    // string, so renaming one is a runtime 400 rather than a compile error, and
+    // this is the only thing that says so. Rename here and in `client.tsx`
+    // together.
+    expect(Object.keys(agentDef.workflows ?? {})).toEqual(
+      expect.arrayContaining(["transcribe", "transcribeStream", "transcribeBatch"]),
+    );
     expect(agentDef.workflows?.transcribe).toBe(transcribe);
     expect(agentDef.workflows?.transcribeStream).toBe(transcribeStream);
     expect(agentDef.workflows?.transcribeBatch).toBe(transcribeBatch);
@@ -168,8 +172,12 @@ describe("the agent declares its three workflows and nothing else", () => {
   });
 
   test("with no tools, because the interface is the page and the API", () => {
-    // The point of the template: a workflow app needs no conversation. A tool
-    // reappearing here would mean the voice path had crept back in.
+    // A PIN, deliberately, and the one assertion in this file you are expected
+    // to edit rather than satisfy. `workflowApp()` declares no session, so a
+    // tool has no conversation to be called from — a name appearing here means
+    // the voice path crept back in and the tool will never run. If you want a
+    // voice agent that STARTS a workflow, `research-workflow` is that template,
+    // and this line is what tells you you are on the wrong one.
     expect(Object.keys(agentDef.tools ?? {})).toEqual([]);
   });
 
@@ -779,6 +787,16 @@ describe("transcribeSegment", () => {
     expect(decoded).toContain('name="audio"; filename="segment-0.wav"');
     // The WAV really rides in the part, header and all.
     expect(decoded).toContain("RIFF");
+    // And the header is CONTIGUOUS with its samples, which is what the two-chunk
+    // form (`[wavHeader(…), window]`) has to preserve and the only thing it could
+    // plausibly lose: the part's payload is exactly the 44 bytes plus the window,
+    // with nothing between them and nothing appended. A body that grew or shrank
+    // here is a file the endpoint decodes into confident nonsense rather than
+    // refusing.
+    const latin = new TextDecoder("latin1").decode(sent);
+    const from = latin.indexOf("RIFF");
+    const to = latin.lastIndexOf("\r\n--");
+    expect(to - from).toBe(44 + (SEGMENT.end - SEGMENT.start));
   });
 
   test("sends the DOWNSAMPLED window when the recording is heavier than 16 kHz mono", async () => {

package/dist/templates/transcription-workflow/client.tsx

@@ -153,15 +153,17 @@
  * ## A reload keeps two of the three runs, and the third CANNOT be kept
  *
  * The run id lives in React state, so a refresh loses it while the fan-out
- * carries on. `key` is the handle that survives that and `recover: true` is what
- * reads it back — and here it is a decision PER MODE rather than per page:
+ * carries on. A correlation KEY is the handle that survives that, and
+ * `useWorkflowSubmit` keeps one and asks for its newest run on mount — which
+ * here lands differently PER MODE:
  *
  * - **"After it uploads"** and **"Let the provider do it"** recover. Their input
  *   names a recording that is already stored, so a later load adopting the run
  *   is adopting something complete: the transcript arrives, the progress log
  *   replays, and nobody is asked to send a 600 MB file a second time.
  * - **"While it uploads" does not, and the hook REFUSES the option rather than
- *   ignoring it.** That run's input names an upload id this page load minted and
+ *   ignoring it** — `useWorkflowStream` omits `recover` from its options type
+ *   and mints no key. That run's input names an upload id this page load minted and
  *   is still filling, so a later load could only adopt a run waiting for bytes
  *   nobody is sending — and it is worse than useless: `workflows/stream.ts`
  *   fails a run whose upload stops growing (`MAX_IDLE_POLLS`), so the reload
@@ -171,10 +173,11 @@
  * The MODE is remembered too, and that is not decoration: without it a reload
  * opens on the default flow while the recovered run sits behind a radio nobody
  * pressed, so the reader sees an empty form and starts a second run — the exact
- * thing the key exists to prevent. The KEY is `useRunKey()`, which owns the
- * minting, the storage and the argument for the key being opaque rather than a
- * `?key=` parameter; `recover.ts` owns the mode, which is this page's own
- * concept, and the validation on the way back out of storage that turning a
+ * thing the key exists to prevent. The KEY is the hook's own — `use-run-key.ts`
+ * owns the minting, the storage and the argument for it being opaque rather
+ * than a `?key=` parameter, and the two submit hooks here share one because the
+ * slot is keyed by the PAGE; `recover.ts` owns the mode, which is this page's
+ * own concept, and the validation on the way back out of storage that turning a
  * stored string into a workflow name obliges.
  *
  * Two smaller consequences worth knowing. Both recovering hooks look up on
@@ -193,7 +196,6 @@ import {
   page,
   SubmitButton,
   UploadProgressBar,
-  useRunKey,
   useWorkflowRuns,
   useWorkflowStream,
   useWorkflowSubmit,
@@ -268,9 +270,6 @@ function TranscriptionDesk() {
   // piece of state for all three hooks, because it describes the UPLOAD and every
   // mode has one — see the module doc.
   const [parallel, setParallel] = useState(true);
-  // This tab's handle on its own runs — minted once and remembered, which is
-  // what a later load produces to find the run again.
-  const key = useRunKey();
   // Did THIS load press Transcribe? A reload cannot have, and it is the only way
   // the page can tell "working on what you just sent" from "picking up where you
   // left off" — the hooks report the run, not who asked for it.
@@ -279,22 +278,16 @@ function TranscriptionDesk() {
   // and that costs nothing here: none of them does anything until its `submit` is
   // called, and `useWorkflowRun` underneath them holds no id until then either.
   //
-  // `recover` is a constant `true` on the two that take it rather than
-  // `mode === …`: the lookup is a MOUNT-time act, so arming it when a mode is
-  // picked would re-adopt a run the reader had just cleared. The streaming hook
-  // takes neither half — it refuses `recover` by type, and recording a key it
-  // will never read back would be config nothing uses.
+  // The two submit hooks recover unconditionally rather than on `mode === …`:
+  // the lookup is a MOUNT-time act, so arming it when a mode is picked would
+  // re-adopt a run the reader had just cleared. They share ONE key without
+  // saying so — the hook's slot is keyed by the page — and `find` is scoped by
+  // workflow as well as by key, so the two modes recover separate runs. The
+  // streaming hook has neither half: it refuses `recover` by type, and mints no
+  // key it would never read back.
   const streamed = useWorkflowStream<typeof transcribe>(WORKFLOWS.streaming, { parallel });
-  const stored = useWorkflowSubmit<typeof transcribe>(WORKFLOWS.classic, {
-    parallel,
-    key,
-    recover: true,
-  });
-  const batched = useWorkflowSubmit<typeof transcribe>(WORKFLOWS.batch, {
-    parallel,
-    key,
-    recover: true,
-  });
+  const stored = useWorkflowSubmit<typeof transcribe>(WORKFLOWS.classic, { parallel });
+  const batched = useWorkflowSubmit<typeof transcribe>(WORKFLOWS.batch, { parallel });
   // The batch flow uploads the same way the classic one does — the id comes from the
   // store — so it is the SAME hook against a different workflow. Only the streaming
   // mode needs the other one, because only it needs the id before the bytes.

package/dist/templates/transcription-workflow/workflows/normalize.ts

@@ -159,7 +159,16 @@ export async function normalizeRecording(uploadId: string): Promise<NormalizedRe
       const source = join(dir, "source");
       const converted = join(dir, "converted.wav");
 
-      await readUploadToFile(uploadId, source, { size: stored.size });
+      // NO `size`, though `stored.size` is right there — and that is the whole
+      // difference between this copy being one window at a time and being
+      // `STEP_FILE_READ_CONCURRENCY` of them. Passing `size` means "I am judging
+      // completeness myself", which is what a body polling a still-arriving
+      // upload needs and is the opposite of what happened above: this step has
+      // already called `requireCompleteUpload`, so the file IS whole and the
+      // windows may land in any order. Omitting it lets `readUploadToFile`
+      // establish that for itself and fan out. The cost is one metadata round
+      // trip, against the dozens of window reads it overlaps.
+      await readUploadToFile(uploadId, source);
 
       // What it WAS, for the progress line. Worth one ffprobe: "converted 41
       // minutes of aac" is a line that explains the run's shape, where

package/dist/templates/transcription-workflow/workflows/sync-api.ts

@@ -52,7 +52,10 @@ export function elapsed(ms: number): string {
  * `bytes` must be a whole file, header included — the endpoint decodes each
  * request independently, so a headerless tail is bytes it will refuse. Both
  * callers arrive at that differently: one re-attaches a header to a window it
- * read, the other is handed parts that already carry one.
+ * read, the other is handed parts that already carry one. A LIST is a whole
+ * file too: the segment caller passes `[wavHeader(...), window]` so the two are
+ * concatenated straight into the request body rather than into an intermediate
+ * buffer that doubles the segment's footprint.
  *
  * `stepTranscribeSyncClassified` — the SDK's own `stepTranscribeSync` plus
  * `throwStepError`, and nothing else — is the whole of what this adds to the SDK
@@ -68,7 +71,7 @@ export function elapsed(ms: number): string {
  *   log has in front of them.
  */
 export async function transcribeWav(
-  bytes: Uint8Array,
+  bytes: Uint8Array | readonly Uint8Array[],
   filename: string,
   label: string,
 ): Promise<string> {

package/dist/templates/transcription-workflow/workflows/transcribe.ts

@@ -66,12 +66,12 @@
 import type { WorkflowCtx } from "@alexkroman1/aai";
 import {
   emit,
-  encodeWav,
   mapConcurrent,
   readUpload,
   report,
   requireCompleteUpload,
   uploadInfo,
+  wavHeader,
 } from "@alexkroman1/aai/step";
 import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
 import { countWords, formatDuration, plural } from "@alexkroman1/aai/utils";
@@ -358,13 +358,20 @@ export async function transcribeSegment(
   // answers better — and getting it wrong is a whole transcript in the wrong
   // language. Add one back only for a desk that really knows.
   //
-  // `encodeWav` is what makes a WINDOW decodable: the endpoint decodes each
+  // A HEADER is what makes a WINDOW decodable: the endpoint decodes each
   // request independently, so a slice of the middle of a recording is a headerless
   // tail until one is put back on it. The streaming flow needs no equivalent — its
   // parts were cut with a header each. The header is the SDK's rather than this
   // template's: a `WavFormat` is structurally a `PcmFormat`, and 22 lines of
   // `DataView` writes with a comment about which of the two declared lengths a
   // decoder trusts is not a thing worth a second copy of.
+  // It goes down as its own CHUNK rather than through `encodeWav`, which is a
+  // MEMORY decision and not a speed one: `encodeWav` allocates `44 + N` and
+  // copies the segment into it, and `multipartBody` then allocates the body and
+  // copies that again — so the audio was resident three times at the moment the
+  // request went out, on a fan-out whose width is set by exactly that peak (see
+  // `MAX_SEGMENT_CONCURRENCY`). Header and samples are contiguous on the wire
+  // either way; this holds `44 + N` once, ~3 MB per in-flight 16 kHz segment.
   // Down to 16 kHz mono BEFORE the header goes on, because the endpoint's budget
   // is 30 seconds of wall clock and that covers the upload. At 48 kHz stereo this
   // window is 17.66 MB and the same audio is 2.94 MB normalized — six times the
@@ -382,12 +389,12 @@ export async function transcribeSegment(
   // identical answer. BOTH flows can reach it, which is newer than it looks:
   // the check used to hang off the resampler, so a 12-bit recording already at
   // 16 kHz mono — light for both flows, and therefore converted by neither —
-  // sailed past it into an unclassified `RangeError` from `encodeWav`.
+  // sailed past it into an unclassified `RangeError` from the header writer.
   const light = fatalOnUnsupported(() => downsampleSegment(audio.bytes, format));
 
   const { value: text, ms } = await timed(() =>
     transcribeWav(
-      encodeWav(light.bytes, light.format),
+      [wavHeader(light.format, light.bytes.byteLength), light.bytes],
       `segment-${segment.index}.wav`,
       `Segment ${segment.index} (${formatDuration(segment.startMs)})`,
     ),

package/dist/templates/travel-concierge/agent.eval.test.ts

@@ -29,7 +29,15 @@
  * tools and read as a model that refuses to act.
  */
 import agentDef from "virtual:aai/agent";
-import { type EvalSession, type EvalTurn, lastStateIn } from "@alexkroman1/aai-runtime/eval";
+import {
+  callsIn,
+  describeTurn,
+  type EvalSession,
+  type EvalToolCall,
+  lastStateIn,
+  toolNames,
+  turnCalling,
+} from "@alexkroman1/aai-runtime/eval";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
 import { z } from "zod";
@@ -76,33 +84,17 @@ function framesBeforeConfirm(session: EvalSession): z.infer<typeof ProjectedTrip
 const tripState = (session: EvalSession) => lastStateIn(session.events(), ProjectedTrip);
 
 /**
- * Drive a whole call, one caller line at a time, and hand back every turn.
+ * A call that really STAGED — it answered with the read-back rather than with a
+ * gate's refusal.
  *
- * The cases below assert about the turn a MECHANISM fired in rather than about
- * turn one, because how many turns a desk takes to get there is the model's
- * business and it moved when the desk gate landed: the flight desk's brief says
- * to search before quoting anything, so measured live this concierge now spends
- * its first turn on `to_flight_assistant` and `search_flights` and reads the
- * fare back before it stages. A case pinned to turn one is a flake with a
- * misleading name — the same argument `retail`'s eval carries.
+ * Passed to `turnCalling` as its `where`, so the turn a case reads is the one
+ * the MECHANISM fired in rather than turn one: how many turns a desk spends
+ * getting there is the model's business and it moved when the desk gate landed
+ * — the flight desk's brief says to search before quoting anything, so measured
+ * live this concierge spends its first turn on `to_flight_assistant` and
+ * `search_flights` and reads the fare back before it stages.
  */
-async function sayAll(session: EvalSession, lines: readonly string[]): Promise<EvalTurn[]> {
-  const turns: EvalTurn[] = [];
-  for (const line of lines) turns.push(await session.say(line));
-  return turns;
-}
-
-/** Every tool call of the call so far, flattened, in order. */
-const callsIn = (turns: readonly EvalTurn[]) => turns.flatMap((turn) => turn.toolCalls);
-
-/** The turn a named tool STAGED something in — the call that answered with the
- *  read-back rather than with a gate's refusal. */
-const stagingTurn = (turns: readonly EvalTurn[], tool: string) =>
-  turns.find((turn) =>
-    turn.toolCalls.some(
-      (call) => call.name === tool && /awaitingConfirmation/.test(call.result ?? ""),
-    ),
-  );
+const stagedSomething = (call: EvalToolCall) => /awaitingConfirmation/.test(call.result ?? "");
 
 describeEval(agentDef, (test) => {
   test(
@@ -112,28 +104,25 @@ describeEval(agentDef, (test) => {
       // a read-back: what is asserted below is that the turn which staged did
       // not also apply, so a line the model could read as consent ("correct",
       // "that's right") would be measuring the caller instead of the desk.
-      const turns = await sayAll(session, [
+      const turns = await session.sayAll([
         "Move my ticket to flight LX52, the Wednesday one.",
         "I want the Wednesday LX52 instead of the flight I'm on now.",
         "Put me on LX52 on Wednesday, please.",
       ]);
 
-      const staging = stagingTurn(turns, "update_ticket");
+      // A desk that talks its way through three turns without staging fails
+      // HERE — the failure this case caught while the flight desk's brief had
+      // the read-back before the staging — and `turnCalling`'s throw names
+      // every turn's tool list AND tells the two findings apart: no
+      // `update_ticket` at all, or calls that were all refused by the desk gate.
+      const staging = turnCalling(turns, "update_ticket", stagedSomething);
       const attempts = callsIn(turns).filter((call) => call.name === "update_ticket");
-      // Named with the whole call, tools AND text: "expected undefined to be
-      // defined" says nothing about a desk that talked its way through three
-      // turns without staging, which is exactly the failure this case caught
-      // while the flight desk's brief had the read-back before the staging.
-      expect(
-        staging,
-        turns
-          .map(
-            (turn, i) =>
-              `turn ${i + 1}: [${turn.toolCalls.map((c) => c.name).join(", ")}] said: ${turn.text}`,
-          )
-          .join("\n"),
-      ).toBeDefined();
-      const staged = staging?.toolCalls.find((call) => call.name === "update_ticket");
+      // The staging call itself, by INDEX, because what follows it in the same
+      // turn is the subject of the assertion below.
+      const stagedAt = staging.toolCalls.findIndex(
+        (call) => call.name === "update_ticket" && stagedSomething(call),
+      );
+      const staged = staging.toolCalls[stagedAt];
       // The tool answered with the read-back rather than with a receipt.
       expect(staged?.result).toMatch(/awaitingConfirmation/);
       // Any attempt that did NOT stage is the DESK GATE refusing:
@@ -154,14 +143,7 @@ describeEval(agentDef, (test) => {
       // refusal is the subject), and it then stages properly. That is a wasted
       // step rather than an unasked-for change, and folding the two together
       // would fail this case for the behaviour the next one proves is safe.
-      // Narrowed first: `indexOf` takes a value, and `staged` is optional — the
-      // rewrite Biome offers for `findIndex` over an identity is UNSAFE for
-      // exactly that reason, and the assertion above is what makes an absent
-      // staging call a failure rather than a slice from 0.
-      const stagedAt = staged === undefined ? -1 : (staging?.toolCalls.indexOf(staged) ?? -1);
-      expect(staging?.toolCalls.slice(stagedAt + 1).map((call) => call.name) ?? []).not.toContain(
-        "confirm_action",
-      );
+      expect(toolNames(staging.toolCalls.slice(stagedAt + 1))).not.toContain("confirm_action");
 
       const views = framesBeforeConfirm(session);
       const waiting = views.filter((view) => view.pending !== null);
@@ -212,7 +194,7 @@ describeEval(agentDef, (test) => {
       // it applies in is its own business — the flight desk's brief has it
       // search first — and saying yes repeatedly is what makes "once each"
       // below a claim about the MECHANISM rather than about the model's pacing.
-      await sayAll(session, [
+      await session.sayAll([
         "Move my ticket to flight LX52, the Wednesday one.",
         "Correct — LX52 on Wednesday. Please move my ticket to it.",
         "Yes, that's right — go ahead and change it.",
@@ -231,7 +213,7 @@ describeEval(agentDef, (test) => {
       );
       // Staged first, applied second, once each. Reversed — or a confirm with no
       // stage — is the regression this template's whole shape exists to prevent.
-      expect(effective.map((call) => call.name)).toEqual(["update_ticket", "confirm_action"]);
+      expect(toolNames(effective)).toEqual(["update_ticket", "confirm_action"]);
       // Everything else has to be a GATE refusing, and nothing else: the desk
       // gate turns away an `update_ticket` issued before
       // `to_flight_assistant`, and the confirmation gate turns away a
@@ -277,10 +259,9 @@ describeEval(agentDef, (test) => {
       // below and `indexOf` on a possibly-undefined find is worse than both.
       const handoffAt = turn.toolCalls.findIndex((call) => call.name === "to_hotel_assistant");
       const handoff = turn.toolCalls[handoffAt];
-      expect(
-        handoff,
-        `tools called: [${turn.toolCalls.map((c) => c.name).join(", ")}]; said: ${turn.text}`,
-      ).toBeDefined();
+      // `describeTurn` is the message a bare `toBeDefined()` failure leaves
+      // out: what this turn reached for, and what it said instead.
+      expect(handoff, describeTurn(turn)).toBeDefined();
       // The brief IS the tool result, which is the whole port of their
       // per-assistant prompt onto a session whose prompt is fixed at connect.
       expect(handoff?.result).toMatch(/hotel desk/);