@alexkroman1/aai-cli 6.10.1 → 7.0.0

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:

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

@@ -35,7 +35,7 @@
  *
  * ## Every stage REPORTS, and the report goes two places
  *
- * `report()` (`@alexkroman1/aai/utils`) writes to the run's own stream — which
+ * `report()` (`@alexkroman1/aai/step`) writes to the run's own stream — which
  * `research_progress` reads back down the phone and a page renders — and to the
  * server log, with the attempt number appended past the first. A pass that is
  * retrying and one that is working print the same sentences otherwise.
@@ -49,16 +49,10 @@
  * researcher CONCLUDED, which is exactly what the step returns.
  */
 
-import { throwStepError } from "@alexkroman1/aai/step-errors";
+import { mapConcurrent, report } from "@alexkroman1/aai/step";
+import { stepGenerateClassified, stepGenerateJsonClassified } from "@alexkroman1/aai/step-errors";
 import { visitWebpage, webSearch } from "@alexkroman1/aai/tools";
-import {
-  errorMessage,
-  isToolFailure,
-  mapInBatches,
-  report,
-  stepGenerate,
-  stepGenerateJson,
-} from "@alexkroman1/aai/utils";
+import { errorMessage, isToolFailure, plural } from "@alexkroman1/aai/utils";
 import { sleep } from "workflow";
 import { z } from "zod";
 import {
@@ -108,9 +102,9 @@ export type Source = { title: string; url: string };
 
 // ---- What each stage's model call has to come back as ------------------------
 //
-// `stepGenerateJson` validates against these, so a reply that missed is a plain
-// throw and therefore a retry — where the hand-rolled `askJson<T>()` this
-// replaces returned a value the compiler believed and nothing checked. They are
+// `stepGenerateJsonClassified` validates against these, so a reply that missed
+// is a plain throw and therefore a retry — where the hand-rolled `askJson<T>()`
+// this replaces returned a value the compiler believed and nothing checked. They are
 // deliberately LENIENT wherever the old hand-written coercion was: a model that
 // put one number in an array of strings should cost that element, not the whole
 // pass.
@@ -221,12 +215,14 @@ export async function researchFlow(input: { topic: string; requestedBy: string }
   // failed angle fails the RUN: its finished siblings are already journaled, so
   // the resume replays them for free and re-issues only what is missing, where
   // catching here would file a report with a silent hole in it.
-  const first = await mapInBatches(angles, ANGLE_CONCURRENCY, (angle) => investigate(brief, angle));
+  const first = await mapConcurrent(angles, ANGLE_CONCURRENCY, (angle) =>
+    investigate(brief, angle),
+  );
 
   // The supervisor's second look. Usually empty — a second wave costs the caller
   // minutes, and the prompt says so.
   const gaps = await findGaps(brief, first);
-  const second = await mapInBatches(gaps, ANGLE_CONCURRENCY, (angle) => investigate(brief, angle));
+  const second = await mapConcurrent(gaps, ANGLE_CONCURRENCY, (angle) => investigate(brief, angle));
 
   const notes = [...first, ...second];
   const written = await writeReport(input.topic, brief, notes);
@@ -261,10 +257,9 @@ export async function writeBrief(topic: string): Promise<Brief> {
   "use step";
 
   await report(`Working out what "${topic}" is really asking.`);
-  const parsed = await askJson(
+  const parsed = await stepGenerateJsonClassified(
     `Research request, as the caller said it: ${topic}`,
-    BRIEF_SYSTEM,
-    BriefReply,
+    { system: BRIEF_SYSTEM, schema: BriefReply },
   );
   return { brief: parsed.brief || topic, criteria: parsed.criteria.slice(0, MAX_ANGLES) };
 }
@@ -279,7 +274,10 @@ export async function writeBrief(topic: string): Promise<Brief> {
 export async function planAngles(brief: Brief): Promise<string[]> {
   "use step";
 
-  const parsed = await askJson(briefText(brief), PLAN_SYSTEM, AnglesReply);
+  const parsed = await stepGenerateJsonClassified(briefText(brief), {
+    system: PLAN_SYSTEM,
+    schema: AnglesReply,
+  });
   const angles = parsed.angles.slice(0, MAX_ANGLES);
   if (angles.length === 0) {
     // Nothing to fan out over is a plan failure, not an empty result: the brief
@@ -287,7 +285,7 @@ export async function planAngles(brief: Brief): Promise<string[]> {
     await report("No angles came back; researching the brief itself.");
     return [brief.brief];
   }
-  await report(`Researching ${angles.length} angle${angles.length === 1 ? "" : "s"}.`);
+  await report(`Researching ${angles.length} ${plural(angles.length, "angle")}.`);
   return angles;
 }
 
@@ -341,16 +339,15 @@ export async function findGaps(brief: Brief, notes: readonly Note[]): Promise<st
   "use step";
 
   if (notes.length === 0) return [];
-  const parsed = await askJson(
+  const parsed = await stepGenerateJsonClassified(
     `${briefText(brief)}\n\nWhat came back:\n${notes.map(noteText).join("\n\n")}`,
-    GAPS_SYSTEM,
-    AnglesReply,
+    { system: GAPS_SYSTEM, schema: AnglesReply },
   );
   const gaps = parsed.angles.slice(0, MAX_ANGLES - 1);
   await report(
     gaps.length === 0
       ? "The brief is covered; writing it up."
-      : `Following up ${gaps.length} gap${gaps.length === 1 ? "" : "s"}.`,
+      : `Following up ${gaps.length} ${plural(gaps.length, "gap")}.`,
   );
   return gaps;
 }
@@ -369,12 +366,14 @@ export async function writeReport(
 ): Promise<{ report: string; summary: string }> {
   "use step";
 
-  await report(`Writing up ${notes.length} angle${notes.length === 1 ? "" : "s"}.`);
-  const written = await ask(
+  await report(`Writing up ${notes.length} ${plural(notes.length, "angle")}.`);
+  const written = await stepGenerateClassified(
     `${briefText(brief)}\n\nFindings:\n${notes.map(noteText).join("\n\n")}`,
-    REPORT_SYSTEM,
+    { system: REPORT_SYSTEM },
   );
-  const summary = await ask(`Topic: ${topic}\n\nReport:\n${written}`, BRIEF_SUMMARY_SYSTEM);
+  const summary = await stepGenerateClassified(`Topic: ${topic}\n\nReport:\n${written}`, {
+    system: BRIEF_SUMMARY_SYSTEM,
+  });
   return { report: written, summary };
 }
 
@@ -404,12 +403,11 @@ async function nextAction(
   seen: readonly string[],
   left: number,
 ): Promise<Action> {
-  return await askJson(
+  return await stepGenerateJsonClassified(
     `${briefText(brief)}\n\nYour angle: ${angle}\n` +
       `Actions left: ${left}\n\n` +
       (seen.length === 0 ? "You have not looked at anything yet." : seen.join("\n\n")),
-    RESEARCH_SYSTEM,
-    ActionReply,
+    { system: RESEARCH_SYSTEM, schema: ActionReply },
   );
 }
 
@@ -474,11 +472,10 @@ async function compress(angle: string, seen: readonly string[], sources: Source[
   if (seen.length === 0) {
     return { angle, findings: "Nothing was found on this angle.", sources: [] };
   }
-  const parsed = await askJson(
-    `Angle: ${angle}\n\n${seen.join("\n\n")}`,
-    COMPRESS_SYSTEM,
-    CompressReply,
-  );
+  const parsed = await stepGenerateJsonClassified(`Angle: ${angle}\n\n${seen.join("\n\n")}`, {
+    system: COMPRESS_SYSTEM,
+    schema: CompressReply,
+  });
   return {
     angle,
     findings: parsed.findings ?? seen.join("\n\n"),
@@ -489,31 +486,17 @@ async function compress(angle: string, seen: readonly string[], sources: Source[
 }
 
 // ---- Model plumbing ---------------------------------------------------------
-
-/**
- * `stepGenerate`, with this desk's retry POLICY on top.
- *
- * The SDK classifies the gateway's failure (`StepGenerateError.retryable`) and
- * stops there, deliberately: whether a terminal failure should burn the step's
- * remaining attempts is the caller's call. `throwStepError` is that call made
- * one way — terminal stays terminal, and a rate limit becomes a `RetryableError`
- * carrying the delay the gateway itself named.
- */
-async function ask(prompt: string, system: string): Promise<string> {
-  return await stepGenerate(prompt, { system }).catch(throwStepError);
-}
-
-/**
- * The same call, for a stage whose reply is JSON of a known shape.
- *
- * `stepGenerateJson` owns the four things every such stage used to re-derive —
- * unwrap the fence, parse, reject a non-object, check the shape — and throws
- * PLAINLY when any of them misses, which is what makes a malformed reply a
- * retry rather than a failure.
- */
-async function askJson<S extends z.ZodType>(prompt: string, system: string, schema: S) {
-  return await stepGenerateJson(prompt, { system, schema }).catch(throwStepError);
-}
+//
+// There is none left, and its absence is the point. This desk carried an `ask()`
+// and an `askJson()` whose whole body was `.catch(throwStepError)`; the SDK's
+// `stepGenerateClassified` and `stepGenerateJsonClassified`
+// (`@alexkroman1/aai/step-errors`) ARE that call — the `/step` one with the
+// gateway's verdict classified, so a terminal failure stays terminal and a rate
+// limit becomes a `RetryableError` carrying the delay the gateway itself named.
+// `stepGenerateJsonClassified` also owns the four things every JSON stage used
+// to re-derive — unwrap the fence, parse, reject a non-object, check the shape —
+// and throws PLAINLY when any of them misses, which is what makes a malformed
+// reply a retry rather than a failure.
 
 // ---- Pure helpers -----------------------------------------------------------
 

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

@@ -1,10 +1,10 @@
 import type { ToolContext } from "@alexkroman1/aai";
 import { isToolFailure } from "@alexkroman1/aai";
-import { createToolContext } from "@alexkroman1/aai/testing";
+import { createToolContext, ok } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import type { AuthResult } from "./authenticate.ts";
 import type { Address } from "./shared.ts";
-import { retailSlot } from "./store.ts";
+import { callFlow, retailSlot } from "./store.ts";
 import cancelPendingOrder from "./tools/cancel_pending_order.ts";
 import exchangeDeliveredOrderItems from "./tools/exchange_delivered_order_items.ts";
 import findUserIdByEmail from "./tools/find_user_id_by_email.ts";
@@ -27,27 +27,6 @@ function makeCtx(): ToolContext {
   return createToolContext();
 }
 
-/**
- * The success half of a tool result, or a thrown failure carrying the tool's
- * own message.
- *
- * `ToolDef["execute"]`'s public signature always returns `unknown` — the wire
- * type is fixed so any tool is assignable to `ToolDef`, whatever its body
- * really returns — so every test that reads a field back off a result needed a
- * cast. There were EIGHTEEN of them here, each the same three lines, which is
- * the shape the repo's guides call a missing typed seam: a concentration of
- * identical casts is one narrowing that belongs in one helper, not a cast per
- * assertion. This is that helper, and it is the file's only cast.
- *
- * It also removes the second half of the boilerplate: a `ToolFailure` fails the
- * test HERE, naming what the tool refused, rather than surfacing three lines
- * later as `undefined` on a field nobody assigned.
- */
-function ok<T>(result: unknown): T {
-  if (isToolFailure(result)) throw new Error(`tool refused: ${result.error}`);
-  return result as T;
-}
-
 /** A context already authenticated as `userId`, via the real tool. */
 async function authedCtx(email: string): Promise<ToolContext> {
   const ctx = makeCtx();
@@ -63,6 +42,8 @@ describe("authentication", () => {
     );
     expect(result.user_id).toBe("olivia_ito_3591");
     expect(retailSlot.get(ctx).authenticatedUserId).toBe("olivia_ito_3591");
+    // Two facts, two homes: the store latches WHO, the flow holds WHETHER.
+    expect(callFlow.position(ctx).state).toBe("serving");
   });
 
   test("an unknown email is refused and leaves the session unauthenticated", async () => {
@@ -70,6 +51,9 @@ describe("authentication", () => {
     const result = await findUserIdByEmail.execute({ email: "nobody@example.com" }, ctx);
     expect(isToolFailure(result)).toBe(true);
     expect(retailSlot.get(ctx).authenticatedUserId).toBeNull();
+    // `IDENTIFIED` is not sent when the body answers a `ToolFailure`, so a
+    // lookup that found nobody cannot leave the call one step ahead of itself.
+    expect(callFlow.position(ctx).state).toBe("identifying");
   });
 
   test("find_user_id_by_name_zip is case-insensitive on names and exact on zip", async () => {
@@ -121,6 +105,9 @@ describe("authentication", () => {
     );
     expect(isToolFailure(switched) && switched.error.toLowerCase()).toContain("one customer");
     expect(retailSlot.get(ctx).authenticatedUserId).toBe("olivia_ito_3591");
+    // The tool is legal in `serving` — the refusal comes from `authenticateAs`,
+    // not from the gate — so the call stays exactly where it was.
+    expect(callFlow.position(ctx).state).toBe("serving");
   });
 
   test("switching via name + zip is refused too — both doors, one lock", async () => {
@@ -1090,4 +1077,20 @@ describe("transfer_to_human_agents", () => {
     expect(isToolFailure(result)).toBe(false);
     expect(result.transferred).toBe(true);
   });
+
+  test("the handoff is terminal, so the call cannot be worked afterwards", async () => {
+    const ctx = await authedCtx("olivia.ito5204@example.com");
+    ok(await transferToHumanAgents.execute({ summary: "wants a human" }, ctx));
+
+    const at = callFlow.position(ctx);
+    expect(at.state).toBe("transferred");
+    expect(at.done).toBe(true);
+
+    // The policy's "say nothing else after that" used to be enforced by
+    // nothing: every tool stayed callable, so a model that kept going kept
+    // acting on a call it had given away.
+    const refused = await getUserDetails.execute({ user_id: "olivia_ito_3591" }, ctx);
+    expect(isToolFailure(refused)).toBe(true);
+    expect(isToolFailure(refused) && refused.error).toContain('"transferred"');
+  });
 });