@alexkroman1/aai-cli 5.13.2 → 6.1.0

package/dist/templates/retail/agent.ts

@@ -1,23 +1,6 @@
 import { agent } from "@alexkroman1/aai";
-import type { StateSlot } from "./shared.ts";
 import { storeView } from "./shared.ts";
-import { createDefaultState } from "./store.ts";
-import systemPrompt from "./system-prompt.md?raw";
-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";
-import { findUserIdByNameZip } from "./tools/find_user_id_by_name_zip.ts";
-import { getItemDetails } from "./tools/get_item_details.ts";
-import { getOrderDetails } from "./tools/get_order_details.ts";
-import { getProductDetails } from "./tools/get_product_details.ts";
-import { getUserDetails } from "./tools/get_user_details.ts";
-import { listAllProductTypes } from "./tools/list_all_product_types.ts";
-import { modifyPendingOrderAddress } from "./tools/modify_pending_order_address.ts";
-import { modifyPendingOrderItems } from "./tools/modify_pending_order_items.ts";
-import { modifyPendingOrderPayment } from "./tools/modify_pending_order_payment.ts";
-import { modifyUserAddress } from "./tools/modify_user_address.ts";
-import { returnDeliveredOrderItems } from "./tools/return_delivered_order_items.ts";
-import { transferToHumanAgents } from "./tools/transfer_to_human_agents.ts";
+import { retailSlot } from "./store.ts";
 
 export default agent({
   name: "Retail Support",
@@ -26,44 +9,21 @@ export default agent({
   // filled from the all-AssemblyAI pipeline at parse time. Only `stt` is
   // overridden below; `llm` and `tts` take the defaults.
 
-  // The store lives in ctx.state, one pristine copy per session — callers must
-  // not see each other's cancellations. Wrapped in the `StateSlot` shape
-  // `store.ts`'s `getState`/`shared.ts`'s `storeView` both key off — `agent()`
-  // infers its session-state type parameter from BOTH `state` and `syncState`,
-  // and `StateSlot`'s `retail` field is optional (a "weak type"), so handing
-  // it a bare `RetailState` with no properties in common fails that inference
-  // rather than an ordinary structural check.
-  state: (): StateSlot => ({ retail: createDefaultState() }),
+  // The store lives in one `sessionSlot` (`store.ts`), a pristine copy per
+  // session — callers must not see each other's cancellations. Nothing declares
+  // it here: the slot installs itself on first access, and its `projection`
+  // below is what gives a session that has run no tool something to render.
 
   // One projection pushed after every tool call. It is a projection, not a
   // flag, because the state holds all six seeded customers and only the
   // authenticated one may reach the browser.
-  syncState: storeView,
+  syncState: retailSlot.projection(storeView),
 
   // Callers read order numbers and ten-digit item numbers in bursts with pauses
   // inside one utterance ("W seven six seven … eight oh seven two"). The default
   // pipeline's `max_turn_silence` already tolerates that; reach for
   // `assemblyAIStt({ maxTurnSilenceMs })` only if your callers pause longer.
-  systemPrompt,
   greeting:
     "Thanks for calling. Before I can look anything up I'll need to find your account — " +
     "what's the email address on it?",
-
-  tools: {
-    cancel_pending_order: cancelPendingOrder,
-    exchange_delivered_order_items: exchangeDeliveredOrderItems,
-    find_user_id_by_email: findUserIdByEmail,
-    find_user_id_by_name_zip: findUserIdByNameZip,
-    get_item_details: getItemDetails,
-    get_order_details: getOrderDetails,
-    get_product_details: getProductDetails,
-    get_user_details: getUserDetails,
-    list_all_product_types: listAllProductTypes,
-    modify_pending_order_address: modifyPendingOrderAddress,
-    modify_pending_order_items: modifyPendingOrderItems,
-    modify_pending_order_payment: modifyPendingOrderPayment,
-    modify_user_address: modifyUserAddress,
-    return_delivered_order_items: returnDeliveredOrderItems,
-    transfer_to_human_agents: transferToHumanAgents,
-  },
 });

package/dist/templates/retail/authenticate.ts

@@ -1,5 +1,5 @@
+import type { ToolFailure } from "@alexkroman1/aai";
 import type { RetailState, User } from "./shared.ts";
-import type { ErrorResult } from "./store.ts";
 
 export interface AuthResult {
   user_id: string;
@@ -16,7 +16,7 @@ export interface AuthResult {
  * order you want. Re-running a finder for the SAME customer succeeds, because a
  * caller repeating their email should not hit an error.
  */
-export function authenticateAs(state: RetailState, user: User): AuthResult | ErrorResult {
+export function authenticateAs(state: RetailState, user: User): AuthResult | ToolFailure {
   const current = state.authenticatedUserId;
   if (current && current !== user.user_id) {
     return {

package/dist/templates/retail/client.tsx

@@ -1,8 +1,13 @@
 import "@alexkroman1/aai-ui/styles.css";
-import type { ChatMessage } from "@alexkroman1/aai-ui";
-import { client, useAgentState, useSession } from "@alexkroman1/aai-ui";
+import type { AgentState, ChatMessage } from "@alexkroman1/aai-ui";
+import {
+  AutoScroll,
+  client,
+  useAgentState,
+  useSession,
+  useUserTranscript,
+} from "@alexkroman1/aai-ui";
 import type { ReactNode } from "react";
-import { useEffect, useRef } from "react";
 import type {
   OrderStatus,
   OrderView,
@@ -10,7 +15,7 @@ import type {
   StoreView,
   SwapOptionView,
 } from "./shared.ts";
-import { DEMO_PERSONAS, storeView } from "./shared.ts";
+import { DEMO_PERSONAS, emptyRetailState, storeView } from "./shared.ts";
 
 const CSS = `
 @keyframes rt-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.45; } }
@@ -38,15 +43,30 @@ const statusColors: Record<string, string> = {
 } satisfies Record<OrderStatus, string>;
 
 // The sidebar before the first tool call, derived from the projection itself so
-// a new StoreView field can't miss the pre-first-call render.
-const EMPTY_VIEW: StoreView = storeView({});
+// a new StoreView field can't miss the pre-first-call render. Built from
+// `emptyRetailState` rather than `retailSlot.projection(...)(undefined)`,
+// because the slot's factory lives in `store.ts` and pulls the 107 KB seed —
+// importing it here would ship the whole catalog to the browser.
+const EMPTY_VIEW: StoreView = storeView(emptyRetailState());
 
-function stateColor(state: string): string {
-  if (state === "listening" || state === "ready") return "#16a34a";
-  if (state === "thinking") return "#ca8a04";
-  if (state === "speaking") return "#2563eb";
-  return "#a1a1aa";
-}
+// The dot's colour per session state, as an EXHAUSTIVE map rather than an
+// if-chain with a grey default.
+//
+// The palette is this template's own — every client here paints the same six
+// states in its own colours, so the SDK has nothing to share but the union. What
+// the SDK does own is `AgentState`, and `satisfies Record<AgentState, string>`
+// is what borrows it: a state added there stops compiling here, where the
+// `state === "…"` chain this replaced answered a new state with a silent grey
+// badge in three separate files and no way to notice.
+const STATE_COLORS = {
+  disconnected: "#a1a1aa",
+  connecting: "#a1a1aa",
+  ready: "#16a34a",
+  listening: "#16a34a",
+  thinking: "#ca8a04",
+  speaking: "#2563eb",
+  error: "#a1a1aa",
+} satisfies Record<AgentState, string>;
 
 function Panel({ title, children }: { title: string; children: ReactNode }) {
   return (
@@ -193,13 +213,12 @@ function SwapOptions({ option }: { option: SwapOptionView }) {
 
 function App() {
   const session = useSession();
-  const messagesEndRef = useRef<HTMLDivElement>(null);
+  // `speaking` and `text` in place of a `userTranscript !== null` check: `null`
+  // is silence and `""` is speech detected with no words back yet, and reading
+  // them as one falsy value hides the indicator at the start of every turn.
+  const { speaking, text: userTranscript } = useUserTranscript();
   // The agent's own store, projected by `syncState` after every tool call.
-  const view = useAgentState<StoreView>() ?? EMPTY_VIEW;
-
-  useEffect(() => {
-    messagesEndRef.current?.scrollIntoView({ behavior: "smooth" });
-  }, [session.messages]);
+  const view = useAgentState<StoreView>(EMPTY_VIEW);
 
   const lastAction = view.activity.at(-1);
 
@@ -220,7 +239,7 @@ function App() {
             <span
               className="w-2 h-2 rounded-full inline-block"
               style={{
-                background: stateColor(session.state),
+                background: STATE_COLORS[session.state],
                 animation:
                   session.state === "listening"
                     ? "rt-pulse 1.5s ease-in-out infinite"
@@ -255,7 +274,10 @@ function App() {
             className="flex flex-col overflow-hidden"
             style={{ borderRight: "1px solid #e4e4e7" }}
           >
-            <div className="rt-scroll flex-1 overflow-y-auto p-4 flex flex-col gap-2">
+            <AutoScroll
+              scrollClassName="rt-scroll overflow-y-auto"
+              contentClassName="p-4 flex flex-col gap-2"
+            >
               {session.messages.length === 0 && (
                 <div className="text-center p-10 text-[13px]" style={{ color: "#a1a1aa" }}>
                   Press start, then read one of the emails from “Who to be” to the agent.
@@ -277,10 +299,9 @@ function App() {
                   {message.content}
                 </div>
               ))}
-              <div ref={messagesEndRef} />
-            </div>
+            </AutoScroll>
 
-            {session.userTranscript !== null && (
+            {speaking && (
               <div
                 className="flex items-center px-4 py-2 text-xs italic min-h-8"
                 style={{ background: "#fafafa", borderTop: "1px solid #e4e4e7", color: "#71717a" }}
@@ -289,7 +310,7 @@ function App() {
                   className="w-2 h-2 rounded-full inline-block mr-2"
                   style={{ background: "#16a34a", animation: "rt-pulse 1.5s ease-in-out infinite" }}
                 />
-                {session.userTranscript === "" ? "…" : session.userTranscript}
+                {userTranscript}
               </div>
             )}
             {session.error && (

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

@@ -1,7 +1,10 @@
-import type { ToolContext } from "@alexkroman1/aai";
+/// <reference types="vite/client" />
+
+import { isToolFailure, type ToolContext } from "@alexkroman1/aai";
+import { createToolContext, withDiscoveredTools } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
-import retailAgent from "./agent.ts";
-import { getState, isError } from "./store.ts";
+import authoredAgent from "./agent.ts";
+import { retailSlot } from "./store.ts";
 
 /** Tools that legitimately run before the caller is identified. Everything
  *  else must refuse. Listed here so ADDING an unauthenticated tool is a
@@ -15,18 +18,24 @@ const PUBLIC_TOOLS = new Set([
   "transfer_to_human_agents",
 ]);
 
-const registry = Object.entries(retailAgent.tools ?? {});
+/**
+ * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
+ *
+ * The glob is written HERE rather than reached for from a shared helper because
+ * this file SHIPS: it is what a scaffolded project runs, so it may not import
+ * anything outside its own template, and `import.meta.glob` is expanded against
+ * the file containing it either way. This is the pattern a user writes.
+ */
+const retailAgent = withDiscoveredTools(
+  authoredAgent,
+  import.meta.glob("./tools/*.ts", { eager: true }),
+);
+const registry = Object.entries(retailAgent.tools);
 
-let sessionCounter = 0;
-function makeCtx(): ToolContext {
-  return {
-    sessionId: `registry-test-${++sessionCounter}`,
-    send: () => {},
-    env: {},
-    state: {},
-    messages: [],
-  } as unknown as ToolContext;
-}
+// `createToolContext()` rather than a cast: it carries a real slot store (the
+// same storability check and freeze the deployed one applies), and each call is a
+// distinct session, which is what these per-tool cases assume.
+const makeCtx = (): ToolContext => createToolContext();
 
 /** Minimal args satisfying each tool's schema. Deliberately plausible-shaped
  *  but wrong — these calls are expected to fail; what is asserted is that they
@@ -126,9 +135,9 @@ describe("the UI-update invariant", () => {
   // retailTool(): it would work, and the sidebar would sit still through it.
   test.each(registry)("%s increments callSeq and logs activity", async (name, def) => {
     const ctx = makeCtx();
-    const before = getState(ctx).callSeq;
+    const before = retailSlot.get(ctx).callSeq;
     await def.execute(SAMPLE_ARGS[name] ?? {}, ctx);
-    const state = getState(ctx);
+    const state = retailSlot.get(ctx);
     expect(state.callSeq, `${name} did not bump callSeq`).toBe(before + 1);
     expect(state.activity.at(-1)?.tool, `${name} logged the wrong tool name`).toBe(name);
     expect(state.activity.at(-1)?.summary).toBeTruthy();
@@ -139,7 +148,7 @@ describe("the UI-update invariant", () => {
     // disagree — the activity feed would then attribute calls to the wrong tool.
     const ctx = makeCtx();
     await def.execute(SAMPLE_ARGS[name] ?? {}, ctx);
-    expect(getState(ctx).activity.at(-1)?.tool).toBe(name);
+    expect(retailSlot.get(ctx).activity.at(-1)?.tool).toBe(name);
   });
 });
 
@@ -148,8 +157,8 @@ describe("the authentication gate", () => {
     "%s refuses before the caller is identified",
     async (name, def) => {
       const result = await def.execute(SAMPLE_ARGS[name] ?? {}, makeCtx());
-      expect(isError(result), `${name} did not refuse`).toBe(true);
-      if (!isError(result)) return;
+      expect(isToolFailure(result), `${name} did not refuse`).toBe(true);
+      if (!isToolFailure(result)) return;
       expect(result.error, `${name} refused for the wrong reason`).toContain(
         "find_user_id_by_email",
       );
@@ -162,9 +171,9 @@ describe("the authentication gate", () => {
       const result = await def.execute(SAMPLE_ARGS[name] ?? {}, makeCtx());
       // A public tool may still fail on its own (deliberately bogus) arguments;
       // it must not fail on the GATE. Written as one unconditional assertion —
-      // an `if (isError(result))` wrapper would pass vacuously for the tools
+      // an `if (isToolFailure(result))` wrapper would pass vacuously for the tools
       // that succeed, which is precisely the set most at risk of regressing.
-      const blockedByGate = isError(result) && result.error.includes("find_user_id_by_email");
+      const blockedByGate = isToolFailure(result) && result.error.includes("find_user_id_by_email");
       expect(blockedByGate, `${name} was blocked by the auth gate`).toBe(false);
     },
   );
@@ -175,10 +184,16 @@ describe("agent config", () => {
     expect(typeof retailAgent.syncState).toBe("function");
   });
 
-  test("declares a state factory, so sessions do not share a store", () => {
-    expect(typeof retailAgent.state).toBe("function");
-    const a = retailAgent.state?.();
-    const b = retailAgent.state?.();
+  // The slot owns the default now — there is no `state` factory on the agent to
+  // forget to declare, which is what four of five slot-backed templates used to.
+  // What still has to hold is that the factory really is called per session: the
+  // 107 KB seed is one module-level object, so a shared clone would let one
+  // caller's cancellation show up in another's.
+  test("the slot's factory clones the seed, so sessions do not share a store", () => {
+    const a = retailSlot.create();
+    const b = retailSlot.create();
     expect(a).not.toBe(b);
+    expect(a.store.orders).not.toBe(b.store.orders);
+    expect(a.store).toEqual(b.store);
   });
 });

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

@@ -1,6 +1,7 @@
+import { isToolFailure } from "@alexkroman1/aai";
 import { describe, expect, test } from "vitest";
 import { normalizeItemId, normalizeOrderId, resolveOrder, resolveVariantId } from "./resolve.ts";
-import { createDefaultState, findProduct, isError } from "./store.ts";
+import { createDefaultState, findProduct } from "./store.ts";
 
 function stateFor(userId: string) {
   const state = createDefaultState();
@@ -39,13 +40,13 @@ describe("resolveOrder — canonical ids", () => {
     const state = stateFor("olivia_ito_3591");
     for (const spoken of ["#W5866402", "W 5866402", "5866402"]) {
       const order = resolveOrder(state, spoken);
-      expect.soft(isError(order) ? null : order.order_id, spoken).toBe("#W5866402");
+      expect.soft(isToolFailure(order) ? null : order.order_id, spoken).toBe("#W5866402");
     }
   });
 
   test("refuses another customer's order id", () => {
     const state = stateFor("olivia_ito_3591");
-    expect(isError(resolveOrder(state, "#W4316152"))).toBe(true);
+    expect(isToolFailure(resolveOrder(state, "#W4316152"))).toBe(true);
   });
 });
 
@@ -54,14 +55,14 @@ describe("resolveOrder — shorthand", () => {
     const state = stateFor("olivia_ito_3591");
     for (const spoken of ["the delivered one", "my delivered order", "delivered"]) {
       const order = resolveOrder(state, spoken);
-      expect.soft(isError(order) ? null : order.order_id, spoken).toBe("#W5866402");
+      expect.soft(isToolFailure(order) ? null : order.order_id, spoken).toBe("#W5866402");
     }
   });
 
   test("three pending orders make bare 'my pending order' ambiguous, and it lists them", () => {
     const state = stateFor("olivia_ito_3591");
     const result = resolveOrder(state, "my pending order");
-    if (!isError(result)) throw new Error("expected ambiguity");
+    if (!isToolFailure(result)) throw new Error("expected ambiguity");
     for (const id of ["#W5442520", "#W7941031", "#W3657213"]) {
       expect.soft(result.error, `ambiguity message omits ${id}`).toContain(id);
     }
@@ -71,38 +72,38 @@ describe("resolveOrder — shorthand", () => {
     const state = stateFor("olivia_ito_3591");
     const first = resolveOrder(state, "my first pending order");
     const second = resolveOrder(state, "the second pending order");
-    expect(isError(first) ? null : first.order_id).toBe("#W5442520");
-    expect(isError(second) ? null : second.order_id).toBe("#W7941031");
+    expect(isToolFailure(first) ? null : first.order_id).toBe("#W5442520");
+    expect(isToolFailure(second) ? null : second.order_id).toBe("#W7941031");
   });
 
   test("'last' picks the final one", () => {
     const state = stateFor("olivia_ito_3591");
     const result = resolveOrder(state, "my last pending order");
-    expect(isError(result) ? null : result.order_id).toBe("#W3657213");
+    expect(isToolFailure(result) ? null : result.order_id).toBe("#W3657213");
   });
 
   test("a bare ordinal with no status word indexes all of the caller's orders", () => {
     const state = stateFor("emma_smith_8564");
     const result = resolveOrder(state, "the first one");
-    expect(isError(result) ? null : result.order_id).toBe("#W2417020");
+    expect(isToolFailure(result) ? null : result.order_id).toBe("#W2417020");
   });
 
   test("a status the caller has none of says what they do have", () => {
     const state = stateFor("harper_brown_7363");
     const result = resolveOrder(state, "my cancelled order");
-    if (!isError(result)) throw new Error("expected refusal");
+    if (!isToolFailure(result)) throw new Error("expected refusal");
     expect(result.error).toContain("delivered");
     expect(result.error).toContain("pending");
   });
 
   test("an out-of-range ordinal is refused, not clamped", () => {
     const state = stateFor("emma_smith_8564");
-    expect(isError(resolveOrder(state, "the fourth pending order"))).toBe(true);
+    expect(isToolFailure(resolveOrder(state, "the fourth pending order"))).toBe(true);
   });
 
   test("unresolvable input is refused before authentication too", () => {
     const state = createDefaultState();
-    expect(isError(resolveOrder(state, "my pending order"))).toBe(true);
+    expect(isToolFailure(resolveOrder(state, "my pending order"))).toBe(true);
   });
 });
 
@@ -110,7 +111,7 @@ describe("resolveVariantId", () => {
   const state = createDefaultState();
   function teaKettle() {
     const product = findProduct(state, "9832717871");
-    if (isError(product)) throw new Error(product.error);
+    if (isToolFailure(product)) throw new Error(product.error);
     return product;
   }
 
@@ -120,7 +121,7 @@ describe("resolveVariantId", () => {
   });
 
   test("refuses an item id belonging to a different product", () => {
-    expect(isError(resolveVariantId(teaKettle(), "4725166838"))).toBe(true);
+    expect(isToolFailure(resolveVariantId(teaKettle(), "4725166838"))).toBe(true);
   });
 
   test("matches a spoken option phrase", () => {
@@ -135,13 +136,13 @@ describe("resolveVariantId", () => {
 
   test("an ambiguous phrase lists the candidates with their options", () => {
     const result = resolveVariantId(teaKettle(), "glass");
-    if (!isError(result)) throw new Error("expected ambiguity");
+    if (!isToolFailure(result)) throw new Error("expected ambiguity");
     expect(result.error).toContain("glass");
     expect(result.error.match(/\d{10}/g)?.length).toBeGreaterThan(1);
   });
 
   test("a phrase matching nothing is refused", () => {
-    expect(isError(resolveVariantId(teaKettle(), "titanium"))).toBe(true);
+    expect(isToolFailure(resolveVariantId(teaKettle(), "titanium"))).toBe(true);
   });
 
   test("availableOnly excludes unavailable variants from matching", () => {

package/dist/templates/retail/resolve.ts

@@ -1,5 +1,17 @@
+/**
+ * Spoken references to this store's things.
+ *
+ * The generic half — reading digits out of an utterance, reading a position out
+ * of one, and the never-guess contract that turns a list of candidates into one
+ * of them or into a failure that lists them — is `resolveOne`, `spokenDigits`
+ * and `spokenOrdinal` (`@alexkroman1/aai`). What stays here is the STORE's
+ * vocabulary: what an order id looks like when a caller reads it aloud, which
+ * words name a status, and what a variant's options are matched against.
+ */
+
+import { isToolFailure, resolveOne, spokenDigits, type ToolFailure } from "@alexkroman1/aai";
 import type { Order, OrderStatus, Product, RetailState } from "./shared.ts";
-import { authenticatedUser, type ErrorResult, isError } from "./store.ts";
+import { authenticatedUser } from "./store.ts";
 
 /** `#W5866402` from anything STT plausibly produces for it. */
 export function normalizeOrderId(spoken: string): string {
@@ -9,27 +21,13 @@ export function normalizeOrderId(spoken: string): string {
 
 /** Item ids are 10 digits; callers read them in groups. */
 export function normalizeItemId(spoken: string): string {
-  return spoken.replace(/\D/g, "");
+  return spokenDigits(spoken);
 }
 
 /** A digit run long enough to be an id rather than an ordinal. */
 const LOOKS_LIKE_ORDER_ID = /\d[\d\s-]{5,}/;
 const LOOKS_LIKE_ITEM_ID = /(?:\d[\s-]*){8,}/;
 
-const ORDINALS: Record<string, number> = {
-  first: 0,
-  "1st": 0,
-  second: 1,
-  "2nd": 1,
-  third: 2,
-  "3rd": 2,
-  fourth: 3,
-  "4th": 3,
-  fifth: 4,
-  "5th": 4,
-  last: -1,
-};
-
 /** Spoken status words → the statuses they select. `pending` deliberately
  *  excludes `pending (item modified)`, which no tool will accept anyway. */
 const STATUS_WORDS: [string, OrderStatus[]][] = [
@@ -53,9 +51,9 @@ function describeOrder(order: Order): string {
  * Ambiguity is always an error listing the candidates, never a guess — the
  * consequence of guessing here is cancelling the wrong order.
  */
-export function resolveOrder(state: RetailState, spoken: string): Order | ErrorResult {
+export function resolveOrder(state: RetailState, spoken: string): Order | ToolFailure {
   const user = authenticatedUser(state);
-  if (isError(user)) return user;
+  if (isToolFailure(user)) return user;
 
   const owned = user.orders
     .map((id) => state.store.orders[id])
@@ -71,6 +69,9 @@ export function resolveOrder(state: RetailState, spoken: string): Order | ErrorR
   const statusEntry = STATUS_WORDS.find(([word]) => text.includes(word));
   const candidates = statusEntry ? owned.filter((o) => statusEntry[1].includes(o.status)) : owned;
 
+  // The empty case is the store's to answer, not `resolveOne`'s: "no cancelled
+  // order" is only useful said alongside the statuses this customer DOES have,
+  // which is what lets the model ask its next question without another tool call.
   if (candidates.length === 0) {
     const have = [...new Set(owned.map((o) => o.status))].join(", ");
     return {
@@ -78,28 +79,9 @@ export function resolveOrder(state: RetailState, spoken: string): Order | ErrorR
     };
   }
 
-  const ordinalWord = Object.keys(ORDINALS).find((word) => new RegExp(`\\b${word}\\b`).test(text));
-  if (ordinalWord) {
-    const index = ORDINALS[ordinalWord] ?? 0;
-    const picked = index === -1 ? candidates.at(-1) : candidates[index];
-    if (!picked) {
-      return {
-        error: `There is no ${ordinalWord} such order — the customer has ${candidates.length}: ${candidates
-          .map(describeOrder)
-          .join("; ")}.`,
-      };
-    }
-    return picked;
-  }
-
-  const only = candidates[0];
-  if (candidates.length === 1 && only) return only;
-
-  return {
-    error: `That is ambiguous — ${candidates.length} orders match. Ask which one: ${candidates
-      .map(describeOrder)
-      .join("; ")}.`,
-  };
+  // A position, then exactly-one, then an ambiguity that lists them — and never
+  // a guess, because the consequence here is cancelling the wrong order.
+  return resolveOne(candidates, spoken, { label: "order", describe: describeOrder });
 }
 
 /**
@@ -110,7 +92,7 @@ export function resolveVariantId(
   product: Product,
   spoken: string,
   opts: { availableOnly?: boolean } = {},
-): string | ErrorResult {
+): string | ToolFailure {
   if (LOOKS_LIKE_ITEM_ID.test(spoken)) {
     const itemId = normalizeItemId(spoken);
     const variant = product.variants[itemId];
@@ -126,33 +108,16 @@ export function resolveVariantId(
     return itemId;
   }
 
-  const text = spoken.toLowerCase();
   const pool = Object.values(product.variants).filter((v) => !opts.availableOnly || v.available);
 
-  let best = 0;
-  const scored = pool.map((variant) => {
-    const score = Object.values(variant.options).filter((value) =>
-      text.includes(value.toLowerCase()),
-    ).length;
-    best = Math.max(best, score);
-    return { variant, score };
+  // A variant is named by its OPTIONS ("the blue medium"), so the score is how
+  // many of them the caller said. Everything after that — no match, one match, a
+  // tie — is `resolveOne`'s, and a tie is answered rather than broken.
+  const picked = resolveOne(pool, spoken, {
+    label: `${product.name} option`,
+    describe: (v) => `${v.item_id} (${Object.values(v.options).join(", ")})`,
+    score: (variant, text) =>
+      Object.values(variant.options).filter((value) => text.includes(value.toLowerCase())).length,
   });
-
-  if (best === 0) {
-    return {
-      error: `No ${product.name} option matches "${spoken}". Options available: ${pool
-        .map((v) => `${v.item_id} (${Object.values(v.options).join(", ")})`)
-        .join("; ")}.`,
-    };
-  }
-
-  const winners = scored.filter((s) => s.score === best);
-  const winner = winners[0]?.variant;
-  if (winners.length === 1 && winner) return winner.item_id;
-
-  return {
-    error: `"${spoken}" matches ${winners.length} ${product.name} options. Ask which: ${winners
-      .map((s) => `${s.variant.item_id} (${Object.values(s.variant.options).join(", ")})`)
-      .join("; ")}.`,
-  };
+  return isToolFailure(picked) ? picked : picked.item_id;
 }