@alexkroman1/aai-cli 5.3.0 → 5.5.0

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

@@ -0,0 +1,182 @@
+import type { ToolContext } from "@alexkroman1/aai";
+import { describe, expect, test } from "vitest";
+import retailAgent from "./agent.ts";
+import { getState, isError } 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
+ *  deliberate edit to this file, not a silent gap. */
+const PUBLIC_TOOLS = new Set([
+  "find_user_id_by_email",
+  "find_user_id_by_name_zip",
+  "get_product_details",
+  "get_item_details",
+  "list_all_product_types",
+  "transfer_to_human_agents",
+]);
+
+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;
+}
+
+/** Minimal args satisfying each tool's schema. Deliberately plausible-shaped
+ *  but wrong — these calls are expected to fail; what is asserted is that they
+ *  still moved the UI. */
+const SAMPLE_ARGS: Record<string, Record<string, unknown>> = {
+  cancel_pending_order: { order_id: "#W0000000", reason: "no longer needed" },
+  exchange_delivered_order_items: {
+    order_id: "#W0000000",
+    item_ids: ["0000000000"],
+    new_item_ids: ["1111111111"],
+    payment_method_id: "gift_card_0000000",
+  },
+  find_user_id_by_email: { email: "nobody@example.com" },
+  find_user_id_by_name_zip: { first_name: "No", last_name: "Body", zip: "00000" },
+  get_item_details: { item_id: "0000000000" },
+  get_order_details: { order_id: "#W0000000" },
+  get_product_details: { product_id: "0000000000" },
+  get_user_details: { user_id: "nobody_0" },
+  list_all_product_types: {},
+  modify_pending_order_address: {
+    order_id: "#W0000000",
+    address1: "1 A St",
+    address2: "",
+    city: "Springfield",
+    state: "OR",
+    country: "USA",
+    zip: "97477",
+  },
+  modify_pending_order_items: {
+    order_id: "#W0000000",
+    item_ids: ["0000000000"],
+    new_item_ids: ["1111111111"],
+    payment_method_id: "gift_card_0000000",
+  },
+  modify_pending_order_payment: {
+    order_id: "#W0000000",
+    payment_method_id: "gift_card_0000000",
+  },
+  modify_user_address: {
+    user_id: "nobody_0",
+    address1: "1 A St",
+    address2: "",
+    city: "Springfield",
+    state: "OR",
+    country: "USA",
+    zip: "97477",
+  },
+  return_delivered_order_items: {
+    order_id: "#W0000000",
+    item_ids: ["0000000000"],
+    payment_method_id: "gift_card_0000000",
+  },
+  transfer_to_human_agents: { summary: "test" },
+};
+
+describe("tool registry", () => {
+  test("registers all fifteen tau2 retail tools", () => {
+    expect(registry.map(([name]) => name).sort()).toEqual(
+      [
+        "cancel_pending_order",
+        "exchange_delivered_order_items",
+        "find_user_id_by_email",
+        "find_user_id_by_name_zip",
+        "get_item_details",
+        "get_order_details",
+        "get_product_details",
+        "get_user_details",
+        "list_all_product_types",
+        "modify_pending_order_address",
+        "modify_pending_order_items",
+        "modify_pending_order_payment",
+        "modify_user_address",
+        "return_delivered_order_items",
+        "transfer_to_human_agents",
+      ].sort(),
+    );
+  });
+
+  test("every registered tool has sample args, so the sweeps below cover it", () => {
+    for (const [name] of registry) {
+      expect(SAMPLE_ARGS[name], `add SAMPLE_ARGS["${name}"]`).toBeDefined();
+    }
+  });
+
+  test("every tool declares a description the model can act on", () => {
+    for (const [name, def] of registry) {
+      expect(def.description, name).toBeTruthy();
+      expect(def.description.length, name).toBeGreaterThan(40);
+    }
+  });
+});
+
+describe("the UI-update invariant", () => {
+  // This is the one that fails if a future tool is built with tool() instead of
+  // 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;
+    await def.execute(SAMPLE_ARGS[name] ?? {}, ctx);
+    const state = getState(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();
+  });
+
+  test.each(registry)("%s logs its own registry key as its name", async (name, def) => {
+    // Catches a copy-paste where the retailTool `name` and the registry key
+    // 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);
+  });
+});
+
+describe("the authentication gate", () => {
+  test.each(registry.filter(([name]) => !PUBLIC_TOOLS.has(name)))(
+    "%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(result.error, `${name} refused for the wrong reason`).toContain(
+        "find_user_id_by_email",
+      );
+    },
+  );
+
+  test.each(registry.filter(([name]) => PUBLIC_TOOLS.has(name)))(
+    "%s does not require authentication",
+    async (name, def) => {
+      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
+      // that succeed, which is precisely the set most at risk of regressing.
+      const blockedByGate = isError(result) && result.error.includes("find_user_id_by_email");
+      expect(blockedByGate, `${name} was blocked by the auth gate`).toBe(false);
+    },
+  );
+});
+
+describe("agent config", () => {
+  test("declares a syncState projection — without it the UI never updates", () => {
+    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?.();
+    expect(a).not.toBe(b);
+  });
+});

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

@@ -0,0 +1,158 @@
+import { describe, expect, test } from "vitest";
+import { normalizeItemId, normalizeOrderId, resolveOrder, resolveVariantId } from "./resolve.ts";
+import { createDefaultState, findProduct, isError } from "./store.ts";
+
+function stateFor(userId: string) {
+  const state = createDefaultState();
+  state.authenticatedUserId = userId;
+  return state;
+}
+
+describe("normalizeOrderId", () => {
+  test("accepts every form STT plausibly produces", () => {
+    for (const spoken of [
+      "#W5866402",
+      "W5866402",
+      "w5866402",
+      "W 5866402",
+      "w-5866402",
+      "5866402",
+      " #w 586 6402 ",
+    ]) {
+      expect(normalizeOrderId(spoken), spoken).toBe("#W5866402");
+    }
+  });
+});
+
+describe("normalizeItemId", () => {
+  test("strips spoken separators from a digit run", () => {
+    expect(normalizeItemId("3909406921")).toBe("3909406921");
+    expect(normalizeItemId("390 940 6921")).toBe("3909406921");
+    expect(normalizeItemId("3909-406-921")).toBe("3909406921");
+  });
+});
+
+describe("resolveOrder — canonical ids", () => {
+  test("resolves the caller's own order in any spoken form", () => {
+    const state = stateFor("olivia_ito_3591");
+    for (const spoken of ["#W5866402", "W 5866402", "5866402"]) {
+      const order = resolveOrder(state, spoken);
+      expect(isError(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);
+  });
+});
+
+describe("resolveOrder — shorthand", () => {
+  test("a single delivered order resolves from a status word", () => {
+    const state = stateFor("olivia_ito_3591");
+    for (const spoken of ["the delivered one", "my delivered order", "delivered"]) {
+      const order = resolveOrder(state, spoken);
+      expect(isError(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");
+    for (const id of ["#W5442520", "#W7941031", "#W3657213"]) {
+      expect(result.error).toContain(id);
+    }
+  });
+
+  test("an ordinal picks one out of several pending orders", () => {
+    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");
+  });
+
+  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");
+  });
+
+  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");
+  });
+
+  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");
+    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);
+  });
+
+  test("unresolvable input is refused before authentication too", () => {
+    const state = createDefaultState();
+    expect(isError(resolveOrder(state, "my pending order"))).toBe(true);
+  });
+});
+
+describe("resolveVariantId", () => {
+  const state = createDefaultState();
+  function teaKettle() {
+    const product = findProduct(state, "9832717871");
+    if (isError(product)) throw new Error(product.error);
+    return product;
+  }
+
+  test("passes a canonical item id through", () => {
+    expect(resolveVariantId(teaKettle(), "3909406921")).toBe("3909406921");
+    expect(resolveVariantId(teaKettle(), "390 940 6921")).toBe("3909406921");
+  });
+
+  test("refuses an item id belonging to a different product", () => {
+    expect(isError(resolveVariantId(teaKettle(), "4725166838"))).toBe(true);
+  });
+
+  test("matches a spoken option phrase", () => {
+    // 3738831434 is the only stainless steel 1.5 liter kettle. The seed's
+    // capacity value is the digit form "1.5 liters" — the matcher is a plain
+    // substring test, so the spoken text has to contain it verbatim, not the
+    // spelled-out "one point five liters" an STT transcript never produces
+    // for a written spec like this either.
+    const result = resolveVariantId(teaKettle(), "the stainless steel 1.5 liters");
+    expect(result).toBe("3738831434");
+  });
+
+  test("an ambiguous phrase lists the candidates with their options", () => {
+    const result = resolveVariantId(teaKettle(), "glass");
+    if (!isError(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);
+  });
+
+  test("availableOnly excludes unavailable variants from matching", () => {
+    // 6454334990 is glass / 1.5 liters / induction and unavailable. "glass"
+    // is required in the phrase too — capacity + stovetop alone also match
+    // the available stainless-steel 1.5L induction variant (3738831434) at
+    // the same score, which would make the "loose" match ambiguous instead
+    // of the unique glass one this test needs.
+    const loose = resolveVariantId(teaKettle(), "glass 1.5 liters induction");
+    expect(loose).toBe("6454334990");
+    const strict = resolveVariantId(teaKettle(), "glass 1.5 liters induction", {
+      availableOnly: true,
+    });
+    expect(strict).not.toBe("6454334990");
+  });
+});

package/dist/templates/retail/resolve.ts

@@ -0,0 +1,158 @@
+import type { Order, OrderStatus, Product, RetailState } from "./shared.ts";
+import { authenticatedUser, type ErrorResult, isError } from "./store.ts";
+
+/** `#W5866402` from anything STT plausibly produces for it. */
+export function normalizeOrderId(spoken: string): string {
+  const compact = spoken.toUpperCase().replace(/[^A-Z0-9]/g, "");
+  return `#W${compact.replace(/^W/, "")}`;
+}
+
+/** Item ids are 10 digits; callers read them in groups. */
+export function normalizeItemId(spoken: string): string {
+  return spoken.replace(/\D/g, "");
+}
+
+/** 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[]][] = [
+  ["delivered", ["delivered"]],
+  ["pending", ["pending"]],
+  ["processed", ["processed"]],
+  ["cancelled", ["cancelled"]],
+  ["canceled", ["cancelled"]],
+  ["returned", ["return requested"]],
+  ["exchanged", ["exchange requested"]],
+];
+
+function describeOrder(order: Order): string {
+  const items = order.items.map((i) => i.name).join(", ");
+  return `${order.order_id} (${order.status}: ${items})`;
+}
+
+/**
+ * Resolve a spoken order reference against the authenticated customer's orders.
+ *
+ * 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 {
+  const user = authenticatedUser(state);
+  if (isError(user)) return user;
+
+  const owned = user.orders
+    .map((id) => state.store.orders[id])
+    .filter((o): o is Order => o !== undefined);
+
+  if (LOOKS_LIKE_ORDER_ID.test(spoken)) {
+    const orderId = normalizeOrderId(spoken);
+    const match = owned.find((o) => o.order_id === orderId);
+    return match ?? { error: `Order ${orderId} was not found on this customer's account.` };
+  }
+
+  const text = spoken.toLowerCase();
+  const statusEntry = STATUS_WORDS.find(([word]) => text.includes(word));
+  const candidates = statusEntry ? owned.filter((o) => statusEntry[1].includes(o.status)) : owned;
+
+  if (candidates.length === 0) {
+    const have = [...new Set(owned.map((o) => o.status))].join(", ");
+    return {
+      error: `This customer has no ${statusEntry?.[0] ?? "matching"} order. They have: ${have}.`,
+    };
+  }
+
+  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("; ")}.`,
+  };
+}
+
+/**
+ * Resolve a spoken variant reference within one product: a 10-digit item id, or
+ * an option phrase like "the blue medium".
+ */
+export function resolveVariantId(
+  product: Product,
+  spoken: string,
+  opts: { availableOnly?: boolean } = {},
+): string | ErrorResult {
+  if (LOOKS_LIKE_ITEM_ID.test(spoken)) {
+    const itemId = normalizeItemId(spoken);
+    const variant = product.variants[itemId];
+    if (!variant) {
+      return {
+        error: `Item ${itemId} is not a variant of ${product.name} (${product.product_id}). Its variants are: ${Object.values(
+          product.variants,
+        )
+          .map((v) => `${v.item_id} (${Object.values(v.options).join(", ")})`)
+          .join("; ")}.`,
+      };
+    }
+    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 };
+  });
+
+  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("; ")}.`,
+  };
+}