@alexkroman1/aai-cli 13.3.0 → 15.0.0

package/dist/templates/redline/client.tsx

@@ -59,9 +59,11 @@ import "@alexkroman1/aai-ui/styles.css";
 import { plural } from "@alexkroman1/aai/utils";
 import type { WorkflowInputOf, WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import {
+  BulletList,
+  Facts,
   Form,
   type FormValues,
-  page,
+  mountPage,
   SubmitButton,
   TextAreaField,
   useWorkflowSubmit,
@@ -70,7 +72,6 @@ import {
   WorkflowProgress,
   type WorkflowRun,
 } from "@alexkroman1/aai-ui";
-import { useState } from "react";
 import type { redline } from "./agent.ts";
 
 /**
@@ -124,13 +125,10 @@ export function toInput(values: FormValues): WorkflowInputOf<typeof redline> {
 }
 
 function RedlineDesk() {
-  // Did THIS load start the run? A reload cannot have, and that is the only way
-  // the page can tell "writing what you just briefed" from "picking up where
-  // you left off" — the hook reports the run, not who asked for it.
-  const [startedHere, setStartedHere] = useState(false);
   // The reload is covered by the hook's own key — see the module doc for why
   // this desk wants the tab-scoped one it mints rather than a key of its own.
-  const { submit, run, pending, error, reset } = useWorkflowSubmit<typeof redline>(WORKFLOW);
+  const { submit, run, pending, error, reset, startedHere } =
+    useWorkflowSubmit<typeof redline>(WORKFLOW);
 
   return (
     <main className="mx-auto flex max-w-2xl flex-col gap-8 p-8">
@@ -142,13 +140,7 @@ function RedlineDesk() {
         </p>
       </header>
 
-      <Form
-        onSubmit={(values) => {
-          setStartedHere(true);
-          return submit(toInput(values));
-        }}
-        error={error}
-      >
+      <Form onSubmit={(values) => submit(toInput(values))} error={error}>
         {/* The scalars: brief, audience, rounds. Declared, not written. */}
         <WorkflowFields workflow={WORKFLOW} />
         {/* The array the schema declares and no generic control can render. */}
@@ -177,7 +169,6 @@ function RedlineDesk() {
             // The recovered run is dismissed as deliberately as one this load
             // started: `reset()` is not undone by a second lookup (the lookup
             // is a mount-time act), so Clear really does clear.
-            setStartedHere(false);
             reset();
           }}
         />
@@ -193,15 +184,16 @@ function Rounds({ rounds }: { rounds: Redline["rounds"] }) {
     <ol className="flex flex-col gap-3">
       {rounds.map((entry) => (
         <li key={entry.round} className="flex flex-col gap-1 border-l pl-4">
-          <p className="text-xs uppercase tracking-[1.2px] opacity-60">
-            Round {entry.round} · {entry.critique.score}/10 ·{" "}
-            {entry.critique.verdict === "ship" ? "ship it" : "revise"}
-          </p>
-          <ul className="flex list-disc flex-col gap-1 pl-5 text-sm">
-            {entry.critique.notes.map((note) => (
-              <li key={note}>{note}</li>
-            ))}
-          </ul>
+          <Facts
+            size="xs"
+            className="uppercase tracking-[1.2px]"
+            items={[
+              `Round ${entry.round}`,
+              `${entry.critique.score}/10`,
+              entry.critique.verdict === "ship" ? "ship it" : "revise",
+            ]}
+          />
+          <BulletList items={entry.critique.notes} size="sm" />
         </li>
       ))}
     </ol>
@@ -224,7 +216,7 @@ function RunPanel({ run, onClear }: { run: WorkflowRun<Redline>; onClear: () =>
       {/* The run's own narration — the complement of the status line, which is
           `running` for a run's whole life, so a one-round redline and a
           three-round one look identical while they happen. These lines come from
-          the run itself (`report()` in `workflows/redline.ts`), and they REPLAY,
+          the run itself (`stepReport()` in `workflows/redline.ts`), and they REPLAY,
           so a reload mid-run catches up rather than starting from whatever
           arrives next. */}
       <WorkflowProgress runId={run.runId} />
@@ -233,20 +225,30 @@ function RunPanel({ run, onClear }: { run: WorkflowRun<Redline>; onClear: () =>
           without a cast. */}
       {run.status === "completed" && (
         <>
-          <p className="text-xs opacity-60">
-            {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"}
-          </p>
+          {/* Which of the two stop conditions ended the loop is the one thing a
+              reader cannot infer from the round count alone, so it is a fact of
+              its own rather than something left to the round count. */}
+          <Facts
+            size="xs"
+            items={[
+              `${run.output.words} words`,
+              `${run.output.roundsRun} ${plural(run.output.roundsRun, "round")}`,
+              run.output.shipped ? "the critic stopped it" : "the round budget stopped it",
+            ]}
+          />
           <Rounds rounds={run.output.rounds} />
           <article className="whitespace-pre-wrap text-sm leading-relaxed">
             {run.output.draft}
           </article>
         </>
       )}
-      {run.status === "failed" && <p className="text-red-600">{run.error}</p>}
+      {/* `role="alert"`, the same contract `<Form>` gives the submit error: this
+          is the outcome the reader waited minutes for. */}
+      {run.status === "failed" && (
+        <p role="alert" className="text-red-600">
+          {run.error}
+        </p>
+      )}
     </section>
   );
 }
@@ -263,4 +265,4 @@ function RunPanel({ run, onClear }: { run: WorkflowRun<Redline>; onClear: () =>
  */
 const STATUS_LINE = { ...WORKFLOW_STATUS_LABELS, running: "Writing…" };
 
-page({ name: "Redline", component: RedlineDesk });
+mountPage({ name: "Redline", component: RedlineDesk });

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

@@ -32,12 +32,12 @@
  * three functions read more tidily than one.
  */
 
-import type { WorkflowCtx } from "@alexkroman1/aai";
-import { report } from "@alexkroman1/aai/step";
+import type { WorkflowContext } from "@alexkroman1/aai";
+import { stepReport } from "@alexkroman1/aai/step";
 import {
   FatalError,
-  stepGenerateClassified,
-  stepGenerateJsonClassified,
+  stepGenerateJsonOrFail,
+  stepGenerateOrFail,
 } from "@alexkroman1/aai/step-errors";
 import { countWords } from "@alexkroman1/aai/utils";
 import { z } from "zod";
@@ -98,7 +98,7 @@ export interface Round {
  * the page's render model — and `WorkflowOutputOf<typeof redline>` in
  * `client.tsx` is that type, derived rather than restated.
  */
-export async function redlineFlow(input: RedlineInput, ctx: WorkflowCtx) {
+export async function redlineFlow(input: RedlineInput, ctx: WorkflowContext) {
   // The three `maxAttempts` below were `maxRetries` properties on the functions
   // (3, 5, 3 — retries AFTER the first attempt, so 4, 6, 4 in all). The policy
   // is an argument to the CALL now, which is where it belongs: the same function
@@ -153,12 +153,12 @@ export async function writeDraft(input: RedlineInput): Promise<string> {
     );
   }
 
-  await report(`Writing the first draft for ${input.audience}.`);
+  await stepReport(`Writing the first draft for ${input.audience}.`);
   // No empty-reply guard here or in `reviseDraft`, and that is not an omission:
   // `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 stepGenerateClassified(briefBlock(input), { system: WRITER_SYSTEM });
+  const draft = await stepGenerateOrFail(briefBlock(input), { system: WRITER_SYSTEM });
   return draft.trim();
 }
 
@@ -175,14 +175,14 @@ export async function critiqueDraft(
   input: RedlineInput,
   round: number,
 ): Promise<Critique> {
-  await report(`Round ${round}: reading it back critically.`);
+  await stepReport(`Round ${round}: reading it back critically.`);
   // `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 stepGenerateJsonClassified(
-    `${briefBlock(input)}\n\nThe submission:\n${draft}`,
-    { schema: CritiqueReply, system: CRITIC_SYSTEM },
-  );
+  const parsed = await stepGenerateJsonOrFail(`${briefBlock(input)}\n\nThe submission:\n${draft}`, {
+    schema: CritiqueReply,
+    system: CRITIC_SYSTEM,
+  });
 
   const critique: Critique = {
     verdict: parsed.verdict,
@@ -192,7 +192,7 @@ export async function critiqueDraft(
     score: clampScore(parsed.score),
     notes: parsed.notes.slice(0, MAX_NOTES),
   };
-  await report(
+  await stepReport(
     critique.verdict === "ship"
       ? `Round ${round}: the critic would ship it (${critique.score}/10).`
       : `Round ${round}: ${critique.notes.length} note(s) to address (${critique.score}/10).`,
@@ -207,8 +207,8 @@ export async function reviseDraft(
   input: RedlineInput,
   round: number,
 ): Promise<string> {
-  await report(`Round ${round}: revising.`);
-  const revised = await stepGenerateClassified(
+  await stepReport(`Round ${round}: revising.`);
+  const revised = await stepGenerateOrFail(
     [
       briefBlock(input),
       `Your current draft:\n${draft}`,
@@ -241,8 +241,8 @@ export function clampScore(score: number): number {
 // 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
+// is the caller's call — so `stepGenerateOrFail` and
+// `stepGenerateJsonOrFail` (`@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

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

@@ -29,7 +29,7 @@
 // endpointing, barge-in, whether two sentences merged into one turn.
 
 import agentDef from "virtual:aai/agent";
-import { stubGatewayRoute } from "@alexkroman1/aai/testing";
+import { routeStepFetch, stubGatewayRoute } from "@alexkroman1/aai/testing";
 import { installStubStepFetch } from "@alexkroman1/aai/testing/vitest";
 import { type EvalToolCall, type EvalWorkflows, toolResultIn } from "@alexkroman1/aai-runtime/eval";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
@@ -132,11 +132,11 @@ type ScriptedSteps = {
 function scriptSteps(options: { hold?: boolean } = {}): ScriptedSteps {
   const gate = Promise.withResolvers<void>();
   const model = stubGatewayRoute(MODEL_SCRIPT);
+  // Throwing on an unrecognised request is `routeStepFetch`'s default and is
+  // what this file wants: every step here is a model call.
+  const route = routeStepFetch([model.route]);
   const stub = installStubStepFetch(async (request) => {
-    const answered = model.route(request);
-    if (answered === undefined) {
-      throw new Error(`unexpected step request in an eval: ${request.method} ${request.url}`);
-    }
+    const answered = route(request);
     // `model.calls` has already recorded this one, so a length of 1 IS the first
     // answer — and holding after the route rather than before it keeps the reply
     // this returns the one the script owed that call.

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

@@ -16,7 +16,7 @@
  * exported async function, so its prompt handling, its parsing and its
  * `FatalError` guards are all testable without an engine.
  *
- * The BODY is driven here only through `createWorkflowCtx`, which records what
+ * The BODY is driven here only through `createWorkflowContext`, which records what
  * it asked for and replays nothing. That is a choice rather than a limit now:
  * `runWorkflow` from `@alexkroman1/aai-runtime/testing` will run this body on
  * the real engine, and `link-digest` is the template that shows it — three
@@ -31,13 +31,16 @@ import { FatalError, RetryableError } from "@alexkroman1/aai/step-errors";
 import {
   createRunSnapshot,
   createToolContext,
-  createWorkflowCtx,
+  createWorkflowContext,
   parseSchemaInput,
   type StubGatewayCall,
   schemaInputIssues,
   toolRunner,
 } from "@alexkroman1/aai/testing";
-import { mockWorkflows, installStubGateway as stubGateway } from "@alexkroman1/aai/testing/vitest";
+import {
+  installStubWorkflows,
+  installStubGateway as stubGateway,
+} from "@alexkroman1/aai/testing/vitest";
 import { visitWebpage, webSearch } from "@alexkroman1/aai/tools";
 import type { WorkflowRunSnapshot } from "@alexkroman1/aai/workflow-api";
 import { runWorkflow } from "@alexkroman1/aai-runtime/testing";
@@ -89,7 +92,7 @@ const run = toolRunner(agentDef);
  *
  * 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. `mockWorkflows`
+ * how the template's tools reach the client at all. `installStubWorkflows`
  * (`@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.
@@ -101,7 +104,7 @@ function stubWorkflows(runs: WorkflowRunSnapshot[] = []): WorkflowClient {
   // 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"] });
+  return installStubWorkflows({ runs, names: ["research"] });
 }
 
 describe("the agent declares its workflow", () => {
@@ -445,7 +448,7 @@ describe("the steps that research", () => {
     // could not have said differently.
     // `planAngles`' result is what the fan-out iterates, so it is supplied
     // rather than run — the rest of the body needs no page and no model.
-    const ctx = createWorkflowCtx({
+    const ctx = createWorkflowContext({
       runSteps: false,
       // Every step the body READS needs a value: with `runSteps: false` nothing
       // runs, so this is the skeleton of a run rather than a run. That is the
@@ -556,7 +559,7 @@ describe("the steps that research", () => {
 /**
  * `researchFlow` itself, on the real replay engine.
  *
- * The block above drives this body through `createWorkflowCtx`, which records
+ * The block above drives this body through `createWorkflowContext`, which records
  * what it ASKED for and replays nothing — right for the retry policy and the
  * step order, and silent about the desk's actual promise: **answer the caller
  * now, finish the work later**. `runWorkflow`

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

@@ -35,7 +35,7 @@
  *
  * ## Every stage REPORTS, and the report goes two places
  *
- * `report()` (`@alexkroman1/aai/step`) writes to the run's own stream — which
+ * `stepReport()` (`@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,9 +49,9 @@
  * researcher CONCLUDED, which is exactly what the step returns.
  */
 
-import type { WorkflowCtx } from "@alexkroman1/aai";
-import { mapConcurrent, report } from "@alexkroman1/aai/step";
-import { stepGenerateClassified, stepGenerateJsonClassified } from "@alexkroman1/aai/step-errors";
+import type { WorkflowContext } from "@alexkroman1/aai";
+import { mapConcurrent, stepReport } from "@alexkroman1/aai/step";
+import { stepGenerateJsonOrFail, stepGenerateOrFail } from "@alexkroman1/aai/step-errors";
 import { visitWebpage, webSearch } from "@alexkroman1/aai/tools";
 import { errorMessage, isToolFailure, plural } from "@alexkroman1/aai/utils";
 import { z } from "zod";
@@ -107,7 +107,7 @@ export type Source = { title: string; url: string };
 
 // ---- What each stage's model call has to come back as ------------------------
 //
-// `stepGenerateJsonClassified` validates against these, so a reply that missed
+// `stepGenerateJsonOrFail` 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
@@ -212,7 +212,7 @@ export type Findings = {
  */
 export async function researchFlow(
   input: { topic: string; requestedBy: string },
-  ctx: WorkflowCtx,
+  ctx: WorkflowContext,
 ) {
   const brief = await ctx.step("writeBrief", () => writeBrief(input.topic));
   const angles = await ctx.step("planAngles", () => planAngles(brief));
@@ -270,11 +270,11 @@ export async function researchFlow(
  * later model call.
  */
 export async function writeBrief(topic: string): Promise<Brief> {
-  await report(`Working out what "${topic}" is really asking.`);
-  const parsed = await stepGenerateJsonClassified(
-    `Research request, as the caller said it: ${topic}`,
-    { system: BRIEF_SYSTEM, schema: BriefReply },
-  );
+  await stepReport(`Working out what "${topic}" is really asking.`);
+  const parsed = await stepGenerateJsonOrFail(`Research request, as the caller said it: ${topic}`, {
+    system: BRIEF_SYSTEM,
+    schema: BriefReply,
+  });
   return { brief: parsed.brief || topic, criteria: parsed.criteria.slice(0, MAX_ANGLES) };
 }
 
@@ -286,7 +286,7 @@ export async function writeBrief(topic: string): Promise<Brief> {
  * asking the model again and getting a different one.
  */
 export async function planAngles(brief: Brief): Promise<string[]> {
-  const parsed = await stepGenerateJsonClassified(briefText(brief), {
+  const parsed = await stepGenerateJsonOrFail(briefText(brief), {
     system: PLAN_SYSTEM,
     schema: AnglesReply,
   });
@@ -294,10 +294,10 @@ export async function planAngles(brief: Brief): Promise<string[]> {
   if (angles.length === 0) {
     // Nothing to fan out over is a plan failure, not an empty result: the brief
     // itself is the one angle that is always available.
-    await report("No angles came back; researching the brief itself.");
+    await stepReport("No angles came back; researching the brief itself.");
     return [brief.brief];
   }
-  await report(`Researching ${angles.length} ${plural(angles.length, "angle")}.`);
+  await stepReport(`Researching ${angles.length} ${plural(angles.length, "angle")}.`);
   return angles;
 }
 
@@ -309,7 +309,7 @@ export async function planAngles(brief: Brief): Promise<string[]> {
  * at the end, which is where it becomes small enough to journal.
  */
 export async function investigate(brief: Brief, angle: string): Promise<Note> {
-  await report(`Looking into: ${angle}`);
+  await stepReport(`Looking into: ${angle}`);
   const seen: string[] = [];
   const sources: Source[] = [];
 
@@ -323,7 +323,7 @@ export async function investigate(brief: Brief, angle: string): Promise<Note> {
       continue;
     }
     if (action.action === "read" && action.url) {
-      await report(`Reading ${hostname(action.url)}`);
+      await stepReport(`Reading ${hostname(action.url)}`);
       seen.push(`PAGE ${action.url}\n${await readPage(action.url)}`);
       continue;
     }
@@ -335,8 +335,6 @@ export async function investigate(brief: Brief, angle: string): Promise<Note> {
   return await compress(angle, seen, sources);
 }
 
-/** UNUSED-ORPHAN-MARKER Retries beyond the default: the far side is a search engine and a model. */
-
 /**
  * The supervisor's second look.
  *
@@ -346,12 +344,12 @@ export async function investigate(brief: Brief, angle: string): Promise<Note> {
  */
 export async function findGaps(brief: Brief, notes: readonly Note[]): Promise<string[]> {
   if (notes.length === 0) return [];
-  const parsed = await stepGenerateJsonClassified(
+  const parsed = await stepGenerateJsonOrFail(
     `${briefText(brief)}\n\nWhat came back:\n${notes.map(noteText).join("\n\n")}`,
     { system: GAPS_SYSTEM, schema: AnglesReply },
   );
   const gaps = parsed.angles.slice(0, MAX_ANGLES - 1);
-  await report(
+  await stepReport(
     gaps.length === 0
       ? "The brief is covered; writing it up."
       : `Following up ${gaps.length} ${plural(gaps.length, "gap")}.`,
@@ -371,12 +369,12 @@ export async function writeReport(
   brief: Brief,
   notes: readonly Note[],
 ): Promise<{ report: string; summary: string }> {
-  await report(`Writing up ${notes.length} ${plural(notes.length, "angle")}.`);
-  const written = await stepGenerateClassified(
+  await stepReport(`Writing up ${notes.length} ${plural(notes.length, "angle")}.`);
+  const written = await stepGenerateOrFail(
     `${briefText(brief)}\n\nFindings:\n${notes.map(noteText).join("\n\n")}`,
     { system: REPORT_SYSTEM },
   );
-  const summary = await stepGenerateClassified(`Topic: ${topic}\n\nReport:\n${written}`, {
+  const summary = await stepGenerateOrFail(`Topic: ${topic}\n\nReport:\n${written}`, {
     system: BRIEF_SUMMARY_SYSTEM,
   });
   return { report: written, summary };
@@ -390,7 +388,7 @@ export async function writeReport(
  * parameters carry `_` for the same reason.
  */
 export async function file(_requestedBy: string, _topic: string): Promise<string> {
-  await report("Filing the findings.");
+  await stepReport("Filing the findings.");
   return "filed";
 }
 
@@ -406,7 +404,7 @@ async function nextAction(
   seen: readonly string[],
   left: number,
 ): Promise<Action> {
-  return await stepGenerateJsonClassified(
+  return await stepGenerateJsonOrFail(
     `${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")),
@@ -423,7 +421,7 @@ async function nextAction(
  * pages exist" and gets run again, differently worded, until the budget is gone.
  */
 async function search(query: string): Promise<{ summary: string; sources: Source[] }> {
-  await report(`Searching: ${query}`);
+  await stepReport(`Searching: ${query}`);
   try {
     const results = await webSearch<{ results?: { title?: string; url?: string }[] }>({
       query,
@@ -445,7 +443,7 @@ async function search(query: string): Promise<{ summary: string; sources: Source
     };
   } catch (err: unknown) {
     const summary = `That search failed: ${errorMessage(err)}`;
-    await report(summary);
+    await stepReport(summary);
     return { summary, sources: [] };
   }
 }
@@ -475,7 +473,7 @@ 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 stepGenerateJsonClassified(`Angle: ${angle}\n\n${seen.join("\n\n")}`, {
+  const parsed = await stepGenerateJsonOrFail(`Angle: ${angle}\n\n${seen.join("\n\n")}`, {
     system: COMPRESS_SYSTEM,
     schema: CompressReply,
   });
@@ -492,11 +490,11 @@ async function compress(angle: string, seen: readonly string[], sources: Source[
 //
 // 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`
+// `stepGenerateOrFail` and `stepGenerateJsonOrFail`
 // (`@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
+// `stepGenerateJsonOrFail` 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.

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

@@ -1,6 +1,6 @@
 import type { ToolContext } from "@alexkroman1/aai";
 import { isToolFailure } from "@alexkroman1/aai";
-import { createToolContext, ok } from "@alexkroman1/aai/testing";
+import { createToolContext, expectToolOk } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import type { AuthResult } from "./authenticate.ts";
 import type { StagedResult } from "./pending.ts";
@@ -32,7 +32,7 @@ function makeCtx(): ToolContext {
 /** A context already authenticated as `userId`, via the real tool. */
 async function authedCtx(email: string): Promise<ToolContext> {
   const ctx = makeCtx();
-  ok<AuthResult>(await findUserIdByEmail.execute({ email }, ctx));
+  expectToolOk<AuthResult>(await findUserIdByEmail.execute({ email }, ctx));
   return ctx;
 }
 
@@ -47,19 +47,19 @@ async function authedCtx(email: string): Promise<ToolContext> {
  * would let this gate pass while carrying nothing to confirm.
  */
 async function confirmed<R = unknown>(staged: unknown, ctx: ToolContext): Promise<R> {
-  const stage = ok<StagedResult>(staged);
+  const stage = expectToolOk<StagedResult>(staged);
   // A throw rather than an `expect`, which biome's `noMisplacedAssertion`
   // rightly refuses outside a test body. A staged change with no sentence to
   // read back is the one shape that would let the gate pass while carrying
   // nothing to confirm, so it stops the spec here rather than downstream.
   if (stage.read_back.length === 0) throw new Error(`${stage.staged} staged with no readback`);
-  return ok<R>(await confirmChange.execute({}, ctx));
+  return expectToolOk<R>(await confirmChange.execute({}, ctx));
 }
 
 describe("authentication", () => {
   test("find_user_id_by_email is case-insensitive and authenticates the session", async () => {
     const ctx = makeCtx();
-    const result = ok<AuthResult>(
+    const result = expectToolOk<AuthResult>(
       await findUserIdByEmail.execute({ email: "OLIVIA.ITO5204@EXAMPLE.COM" }, ctx),
     );
     expect(result.user_id).toBe("olivia_ito_3591");
@@ -81,7 +81,7 @@ describe("authentication", () => {
 
   test("find_user_id_by_name_zip is case-insensitive on names and exact on zip", async () => {
     const ctx = makeCtx();
-    const found = ok<AuthResult>(
+    const found = expectToolOk<AuthResult>(
       await findUserIdByNameZip.execute(
         { first_name: "aarav", last_name: "ANDERSON", zip: "19031" },
         ctx,
@@ -97,13 +97,13 @@ describe("authentication", () => {
   });
 
   test("two customers share a first name — the zip is what separates them", async () => {
-    const a = ok<AuthResult>(
+    const a = expectToolOk<AuthResult>(
       await findUserIdByNameZip.execute(
         { first_name: "Aarav", last_name: "Anderson", zip: "19031" },
         makeCtx(),
       ),
     );
-    const b = ok<AuthResult>(
+    const b = expectToolOk<AuthResult>(
       await findUserIdByNameZip.execute(
         { first_name: "Aarav", last_name: "Gonzalez", zip: "78268" },
         makeCtx(),
@@ -172,7 +172,7 @@ interface ProductTypesResult {
 describe("read tools", () => {
   test("get_user_details returns the caller's profile with gift-card balances", async () => {
     const ctx = await authedCtx("olivia.ito5204@example.com");
-    const result = ok<UserDetailsResult>(
+    const result = expectToolOk<UserDetailsResult>(
       await getUserDetails.execute({ user_id: "olivia_ito_3591" }, ctx),
     );
     expect(result.email).toBe("olivia.ito5204@example.com");
@@ -189,7 +189,7 @@ describe("read tools", () => {
 
   test("get_order_details resolves shorthand and sets focus", async () => {
     const ctx = await authedCtx("olivia.ito5204@example.com");
-    const result = ok<OrderDetailsResult>(
+    const result = expectToolOk<OrderDetailsResult>(
       await getOrderDetails.execute({ order_id: "the delivered one" }, ctx),
     );
     expect(result.order_id).toBe("#W5866402");
@@ -203,7 +203,7 @@ describe("read tools", () => {
   });
 
   test("get_product_details lists variants and needs no authentication", async () => {
-    const result = ok<ProductDetailsResult>(
+    const result = expectToolOk<ProductDetailsResult>(
       await getProductDetails.execute({ product_id: "9832717871" }, makeCtx()),
     );
     expect(result.name).toBe("Tea Kettle");
@@ -217,7 +217,7 @@ describe("read tools", () => {
   });
 
   test("get_item_details resolves an item without knowing its product", async () => {
-    const result = ok<ItemDetailsResult>(
+    const result = expectToolOk<ItemDetailsResult>(
       await getItemDetails.execute({ item_id: "3909406921" }, makeCtx()),
     );
     expect(result.price).toBe(98.25);
@@ -225,7 +225,9 @@ describe("read tools", () => {
   });
 
   test("list_all_product_types returns all 50, sorted by name", async () => {
-    const result = ok<ProductTypesResult>(await listAllProductTypes.execute({}, makeCtx()));
+    const result = expectToolOk<ProductTypesResult>(
+      await listAllProductTypes.execute({}, makeCtx()),
+    );
     expect(Object.keys(result.products)).toHaveLength(50);
     const names = Object.keys(result.products);
     // localeCompare, not the default lexicographic sort — the tool sorts for a
@@ -1148,7 +1150,7 @@ interface TransferResult {
 
 describe("transfer_to_human_agents", () => {
   test("works without authentication — the escape hatch cannot be gated", async () => {
-    const result = ok<TransferResult>(
+    const result = expectToolOk<TransferResult>(
       await transferToHumanAgents.execute(
         { summary: "Caller wants to dispute a charge from 2019." },
         makeCtx(),
@@ -1160,7 +1162,7 @@ describe("transfer_to_human_agents", () => {
 
   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));
+    expectToolOk(await transferToHumanAgents.execute({ summary: "wants a human" }, ctx));
 
     const at = callFlow.position(ctx);
     expect(at.state).toBe("transferred");