@alexkroman1/aai-cli 6.11.0 → 7.0.0

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"');
+  });
 });