@alexkroman1/aai-cli 6.11.0 → 7.0.0

package/dist/templates/retail/client.tsx

@@ -1,11 +1,12 @@
 import "@alexkroman1/aai-ui/styles.css";
-import type { AgentState, ChatMessage } from "@alexkroman1/aai-ui";
+import type { AgentState, ConversationItem } from "@alexkroman1/aai-ui";
 import {
   AutoScroll,
   client,
   useAgentState,
+  useConversation,
   useSession,
-  useUserTranscript,
+  useSessionSelector,
 } from "@alexkroman1/aai-ui";
 import type { ReactNode } from "react";
 import type {
@@ -217,13 +218,226 @@ function SwapOptions({ option }: { option: SwapOptionView }) {
   );
 }
 
-function App() {
+/** One line of the call: a bubble, or the tool the agent ran after it. */
+function Row({ item }: { item: ConversationItem }) {
+  if (item.kind === "tool") {
+    const { name, status } = item.toolCall;
+    return (
+      <div
+        className="self-start rounded-md px-2.5 py-1 text-[11px] font-mono flex items-center gap-2"
+        style={{
+          background: "#ffffff",
+          border: "1px solid #e4e4e7",
+          color: status === "pending" ? "#b45309" : "#71717a",
+        }}
+      >
+        <span
+          className="w-1.5 h-1.5 rounded-full inline-block"
+          style={{
+            background: status === "pending" ? "#ca8a04" : "#16a34a",
+            animation: status === "pending" ? "rt-pulse 1s ease-in-out infinite" : "none",
+          }}
+        />
+        {name}
+      </div>
+    );
+  }
+  const { role, content } = item.message;
+  return (
+    <div
+      className="rounded-lg text-[13px] max-w-[80%] px-3.5 py-2.5"
+      style={{
+        lineHeight: 1.55,
+        alignSelf: role === "assistant" ? "flex-start" : "flex-end",
+        background: role === "assistant" ? "#ffffff" : "#2563eb",
+        color: role === "assistant" ? "#18181b" : "#ffffff",
+        border: role === "assistant" ? "1px solid #e4e4e7" : "none",
+        animation: "rt-slide-in 0.2s ease-out",
+      }}
+    >
+      {content}
+    </div>
+  );
+}
+
+/**
+ * The call transcript.
+ *
+ * `useConversation()` rather than `session.messages.map(...)`. The messages
+ * were only part of it: this agent runs FIFTEEN tools and the operator could
+ * see none of them, because tool calls live in a second array this page never
+ * read — and the streaming reply and the thinking indicator were dropped along
+ * with them. The hook owns the interleave (a tool row follows the message it
+ * was anchored to), the `null`-vs-`""` transcript distinction and the
+ * thinking-suppression rule; the markup below is what this template is for.
+ *
+ * It subscribes per FIELD, so the customer file in the sidebar no longer
+ * re-renders on every partial transcript the way the whole-page `useSession()`
+ * this replaced made it.
+ */
+function Conversation() {
+  const { items, streaming, transcript, thinking } = useConversation();
+  return (
+    <>
+      <AutoScroll
+        scrollClassName="rt-scroll overflow-y-auto"
+        contentClassName="p-4 flex flex-col gap-2"
+      >
+        {items.length === 0 && streaming === null && (
+          <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.
+          </div>
+        )}
+        {items.map((item) => (
+          <Row
+            key={item.kind === "message" ? `m${item.message.id}` : item.toolCall.callId}
+            item={item}
+          />
+        ))}
+        {streaming !== null && (
+          <div
+            className="rounded-lg text-[13px] max-w-[80%] px-3.5 py-2.5 self-start"
+            style={{
+              lineHeight: 1.55,
+              background: "#ffffff",
+              color: "#18181b",
+              border: "1px solid #e4e4e7",
+            }}
+          >
+            {streaming}
+          </div>
+        )}
+        {thinking && (
+          <div className="self-start text-[11px] px-3.5" style={{ color: "#a1a1aa" }}>
+            <span style={{ animation: "rt-pulse 1.2s ease-in-out infinite" }}>· · ·</span>
+          </div>
+        )}
+      </AutoScroll>
+
+      {transcript.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" }}
+        >
+          <span
+            className="w-2 h-2 rounded-full inline-block mr-2"
+            style={{ background: "#16a34a", animation: "rt-pulse 1.5s ease-in-out infinite" }}
+          />
+          {transcript.text}
+        </div>
+      )}
+    </>
+  );
+}
+
+/** The live status dot, on its own subscription rather than a field off a
+ *  whole-page read — the header is the only thing here that wants it. */
+function StatusReadout() {
+  const state = useSessionSelector((s) => s.state);
+  return (
+    <>
+      <span
+        className="w-2 h-2 rounded-full inline-block"
+        style={{
+          background: STATE_COLORS[state],
+          animation:
+            state === "listening"
+              ? "rt-pulse 1.5s ease-in-out infinite"
+              : state === "thinking"
+                ? "rt-pulse 0.8s ease-in-out infinite"
+                : "none",
+        }}
+        title={state}
+      />
+      <span className="text-[11px] font-normal" style={{ color: "#a1a1aa" }}>
+        {state}
+      </span>
+    </>
+  );
+}
+
+/**
+ * The fatal-error banner.
+ *
+ * `role="alert"` is the part a hand-rolled banner leaves out and the part that
+ * matters: per the `fatalError` latch in the session core this is the only
+ * remaining signal — the status readout beside it goes back to reading like a
+ * live call — and a screen reader is never told an unannounced one appeared.
+ * `ConsoleShell` carries it, and this template's two-pane page cannot use that
+ * shell as its frame; the attribute is what it is here for.
+ */
+function ErrorBanner() {
+  const error = useSessionSelector((s) => s.error);
+  if (!error) return null;
+  return (
+    <div
+      role="alert"
+      className="px-4 py-2 text-xs"
+      style={{ background: "#fef2f2", color: "#b91c1c", borderTop: "1px solid #fecaca" }}
+    >
+      {error.message} ({error.code})
+    </div>
+  );
+}
+
+/** The call controls: the one place a whole-session read is what is wanted —
+ *  `started`, `running` and three methods, in three buttons. */
+function CallControls({ productCount }: { productCount: number }) {
   const session = useSession();
-  // `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.
+  return (
+    <div
+      className="flex items-center gap-2 px-4 py-3"
+      style={{ background: "#ffffff", borderTop: "1px solid #e4e4e7" }}
+    >
+      {!session.started ? (
+        <button
+          type="button"
+          className="px-4 py-2 border-none rounded-md text-xs font-semibold cursor-pointer text-white"
+          style={{ background: "#2563eb" }}
+          onClick={() => session.start()}
+        >
+          Start call
+        </button>
+      ) : (
+        <>
+          <button
+            type="button"
+            className="px-4 py-2 border-none rounded-md text-xs font-semibold cursor-pointer"
+            style={{
+              background: session.running ? "#e4e4e7" : "#2563eb",
+              color: session.running ? "#18181b" : "#ffffff",
+            }}
+            onClick={() => session.toggle()}
+          >
+            {session.running ? "Hold" : "Resume"}
+          </button>
+          {/* end() hangs up and flips `started` back, so the UI
+              returns to "Start call" and the next start is a brand-new
+              session (fresh store, greeting included). reset() would
+              keep the call live — the buttons never toggle back. */}
+          <button
+            type="button"
+            className="px-4 py-2 border-none rounded-md text-xs font-semibold cursor-pointer text-white"
+            style={{ background: "#dc2626" }}
+            onClick={() => session.end()}
+          >
+            End
+          </button>
+        </>
+      )}
+      <div className="flex-1" />
+      <span className="text-[10px] tabular-nums" style={{ color: "#a1a1aa" }}>
+        {productCount} products
+      </span>
+    </div>
+  );
+}
+
+function App() {
+  // The agent's own store, projected by `syncState` after every tool call —
+  // the only subscription at this level now. The session reads that used to sit
+  // beside it moved into the four components above, so a partial transcript no
+  // longer re-renders the customer file.
   const view = useAgentState<StoreView>(EMPTY_VIEW);
 
   const lastAction = view.activity.at(-1);
@@ -242,22 +456,7 @@ function App() {
           <div className="flex items-center gap-2.5 text-base font-semibold">
             <span style={{ color: "#2563eb" }}>◆</span>
             Retail Support
-            <span
-              className="w-2 h-2 rounded-full inline-block"
-              style={{
-                background: STATE_COLORS[session.state],
-                animation:
-                  session.state === "listening"
-                    ? "rt-pulse 1.5s ease-in-out infinite"
-                    : session.state === "thinking"
-                      ? "rt-pulse 0.8s ease-in-out infinite"
-                      : "none",
-              }}
-              title={session.state}
-            />
-            <span className="text-[11px] font-normal" style={{ color: "#a1a1aa" }}>
-              {session.state}
-            </span>
+            <StatusReadout />
           </div>
           <span
             className="px-2.5 py-1 rounded text-[10px] font-semibold uppercase tracking-wider"
@@ -280,99 +479,9 @@ function App() {
             className="flex flex-col overflow-hidden"
             style={{ borderRight: "1px solid #e4e4e7" }}
           >
-            <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.
-                </div>
-              )}
-              {session.messages.map((message: ChatMessage, index: number) => (
-                <div
-                  key={index}
-                  className="rounded-lg text-[13px] max-w-[80%] px-3.5 py-2.5"
-                  style={{
-                    lineHeight: 1.55,
-                    alignSelf: message.role === "assistant" ? "flex-start" : "flex-end",
-                    background: message.role === "assistant" ? "#ffffff" : "#2563eb",
-                    color: message.role === "assistant" ? "#18181b" : "#ffffff",
-                    border: message.role === "assistant" ? "1px solid #e4e4e7" : "none",
-                    animation: "rt-slide-in 0.2s ease-out",
-                  }}
-                >
-                  {message.content}
-                </div>
-              ))}
-            </AutoScroll>
-
-            {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" }}
-              >
-                <span
-                  className="w-2 h-2 rounded-full inline-block mr-2"
-                  style={{ background: "#16a34a", animation: "rt-pulse 1.5s ease-in-out infinite" }}
-                />
-                {userTranscript}
-              </div>
-            )}
-            {session.error && (
-              <div
-                className="px-4 py-2 text-xs"
-                style={{ background: "#fef2f2", color: "#b91c1c", borderTop: "1px solid #fecaca" }}
-              >
-                {session.error.message} ({session.error.code})
-              </div>
-            )}
-
-            <div
-              className="flex items-center gap-2 px-4 py-3"
-              style={{ background: "#ffffff", borderTop: "1px solid #e4e4e7" }}
-            >
-              {!session.started ? (
-                <button
-                  type="button"
-                  className="px-4 py-2 border-none rounded-md text-xs font-semibold cursor-pointer text-white"
-                  style={{ background: "#2563eb" }}
-                  onClick={() => session.start()}
-                >
-                  Start call
-                </button>
-              ) : (
-                <>
-                  <button
-                    type="button"
-                    className="px-4 py-2 border-none rounded-md text-xs font-semibold cursor-pointer"
-                    style={{
-                      background: session.running ? "#e4e4e7" : "#2563eb",
-                      color: session.running ? "#18181b" : "#ffffff",
-                    }}
-                    onClick={() => session.toggle()}
-                  >
-                    {session.running ? "Hold" : "Resume"}
-                  </button>
-                  {/* end() hangs up and flips `started` back, so the UI
-                      returns to "Start call" and the next start is a brand-new
-                      session (fresh store, greeting included). reset() would
-                      keep the call live — the buttons never toggle back. */}
-                  <button
-                    type="button"
-                    className="px-4 py-2 border-none rounded-md text-xs font-semibold cursor-pointer text-white"
-                    style={{ background: "#dc2626" }}
-                    onClick={() => session.end()}
-                  >
-                    End
-                  </button>
-                </>
-              )}
-              <div className="flex-1" />
-              <span className="text-[10px] tabular-nums" style={{ color: "#a1a1aa" }}>
-                {view.productCount} products
-              </span>
-            </div>
+            <Conversation />
+            <ErrorBanner />
+            <CallControls productCount={view.productCount} />
           </div>
 
           {/* Sidebar: the customer file */}

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

@@ -4,11 +4,12 @@ import { isToolFailure, type ToolContext } from "@alexkroman1/aai";
 import { createToolContext, withDiscoveredTools } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import authoredAgent from "./agent.ts";
-import { retailSlot } from "./store.ts";
+import { callFlow, 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
- *  deliberate edit to this file, not a silent gap. */
+/** Tools that legitimately run before the caller is identified — the six
+ *  declaring `when: BEFORE_TRANSFER`. 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",
@@ -37,6 +38,15 @@ const registry = Object.entries(retailAgent.tools);
 // distinct session, which is what these per-tool cases assume.
 const makeCtx = (): ToolContext => createToolContext();
 
+/** A context whose call flow is in `serving`, so a `when: "serving"` tool can
+ *  reach its body. Moved through the FLOW rather than by writing
+ *  `authenticatedUserId`, because the gate reads the machine. */
+function servingCtx(): ToolContext {
+  const ctx = makeCtx();
+  callFlow.send(ctx, { type: "IDENTIFIED" });
+  return ctx;
+}
+
 /** 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. */
@@ -134,7 +144,10 @@ 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();
+    // `serving`, so the flow gate is not what these calls are testing: the
+    // point is that a tool which reaches its BODY moves the sidebar. A refused
+    // call deliberately does not — see `store.test.ts`.
+    const ctx = servingCtx();
     const before = retailSlot.get(ctx).callSeq;
     await def.execute(SAMPLE_ARGS[name] ?? {}, ctx);
     const state = retailSlot.get(ctx);
@@ -146,7 +159,7 @@ describe("the UI-update invariant", () => {
   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();
+    const ctx = servingCtx();
     await def.execute(SAMPLE_ARGS[name] ?? {}, ctx);
     expect(retailSlot.get(ctx).activity.at(-1)?.tool).toBe(name);
   });
@@ -159,6 +172,11 @@ describe("the authentication gate", () => {
       const result = await def.execute(SAMPLE_ARGS[name] ?? {}, makeCtx());
       expect(isToolFailure(result), `${name} did not refuse`).toBe(true);
       if (!isToolFailure(result)) return;
+      // The refusal is `callFlow`'s: it names the position, and quotes the
+      // state's instruction — which names the two tools that get out of it.
+      expect(result.error, `${name} refused without naming the position`).toContain(
+        '"identifying"',
+      );
       expect(result.error, `${name} refused for the wrong reason`).toContain(
         "find_user_id_by_email",
       );
@@ -197,3 +215,17 @@ describe("agent config", () => {
     expect(a.store).toEqual(b.store);
   });
 });
+
+describe("the transfer is terminal", () => {
+  test.each(registry)("%s refuses once the call is with a human", async (name, def) => {
+    const ctx = servingCtx();
+    callFlow.send(ctx, { type: "TRANSFERRED" });
+
+    const result = await def.execute(SAMPLE_ARGS[name] ?? {}, ctx);
+    // EVERY tool, the six public ones and `transfer_to_human_agents` itself
+    // included: nothing declares itself legal in the final state. Before the
+    // flow, the policy's "say nothing else after that" was enforced by nothing.
+    expect(isToolFailure(result), `${name} still ran after the handoff`).toBe(true);
+    expect(isToolFailure(result) && result.error, name).toContain('"transferred"');
+  });
+});

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

@@ -1,9 +1,11 @@
 import { isToolFailure, type ToolContext } from "@alexkroman1/aai";
-import { createToolContext } from "@alexkroman1/aai/testing";
+import { createToolContext, ok, okPosition } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import { z } from "zod";
 import {
   authenticatedUser,
+  BEFORE_TRANSFER,
+  callFlow,
   createDefaultState,
   findItem,
   findOrder,
@@ -163,15 +165,16 @@ describe("retailTool", () => {
     name: "echo",
     description: "test tool",
     inputSchema: z.object({ value: z.string() }),
-    requiresAuth: false,
+    when: BEFORE_TRANSFER,
     summary: (args) => `echoed ${args.value}`,
     execute: (args) => ({ echoed: args.value }),
   });
 
   const gated = retailTool({
     name: "gated",
-    description: "test tool needing auth",
+    description: "test tool needing an identified customer",
     inputSchema: z.object({}),
+    when: "serving",
     summary: () => "ran",
     execute: () => ({ ok: true }),
   });
@@ -180,11 +183,15 @@ describe("retailTool", () => {
     name: "failing",
     description: "test tool that returns an error",
     inputSchema: z.object({}),
-    requiresAuth: false,
+    when: BEFORE_TRANSFER,
     summary: () => "should not be used",
     execute: () => ({ error: "nope" }),
   });
 
+  /** Put the call where a `when: "serving"` tool can run, through the flow
+   *  rather than by writing the store — the gate reads the machine. */
+  const serve = (ctx: ToolContext) => callFlow.send(ctx, { type: "IDENTIFIED" });
+
   test("increments callSeq and logs activity on every call", async () => {
     const ctx = makeCtx();
     await echo.execute({ value: "a" }, ctx);
@@ -203,27 +210,43 @@ describe("retailTool", () => {
     expect(retailSlot.get(ctx).callSeq).toBeGreaterThan(first);
   });
 
-  test("defaults to requiring authentication and does not run execute when blocked", async () => {
+  test("a tool gated on serving refuses while the caller is unidentified", async () => {
     const ctx = makeCtx();
     const result = await gated.execute({}, ctx);
-    expect(isToolFailure(result) && result.error).toContain("find_user_id_by_email");
+    expect(isToolFailure(result)).toBe(true);
+    // The refusal is the SDK's, so it names the position and quotes the
+    // state's own instruction — where `requiresAuth` answered one fixed
+    // sentence that could not say where the call was.
+    expect(isToolFailure(result) && result.error).toContain('"identifying"');
+    expect(isToolFailure(result) && result.error).toMatch(/user id/);
   });
 
-  test("a blocked call is still logged and still bumps callSeq", async () => {
+  test("a refused call touches nothing, callSeq included", async () => {
     const ctx = makeCtx();
     await gated.execute({}, ctx);
     const state = retailSlot.get(ctx);
-    expect(state.callSeq).toBe(1);
-    expect(state.activity[0]?.summary).toContain("blocked");
+    // The gate short-circuits before the wrapper's body, so a blocked call no
+    // longer records an activity entry — the trade `retailTool`'s doc names.
+    // What it buys is that a refusal cannot half-write the store.
+    expect(state.callSeq).toBe(0);
+    expect(state.activity).toEqual([]);
   });
 
-  test("runs once authenticated", async () => {
+  test("runs once the flow says serving", async () => {
     const ctx = makeCtx();
-    retailSlot.update(ctx, (state) => {
-      state.authenticatedUserId = "olivia_ito_3591";
-    });
-    const result = await gated.execute({}, ctx);
-    expect(result).toEqual({ ok: true });
+    serve(ctx);
+    expect(ok(await gated.execute({}, ctx))).toEqual({ ok: true });
+  });
+
+  test("the result carries the position the call landed in", async () => {
+    const ctx = makeCtx();
+    serve(ctx);
+    // `okPosition` rather than a cast to `{ instruction?: string }`: it keeps
+    // the envelope this test is about, and a refusal fails here naming what the
+    // flow said instead of reading `undefined` off a field nobody assigned.
+    const answered = okPosition<{ ok: boolean }>(await gated.execute({}, ctx));
+    expect(answered).toMatchObject({ state: "serving", done: false });
+    expect(answered.instruction).toMatch(/one identified customer/);
   });
 
   test("an error result is logged as an error, not through summary()", async () => {
@@ -232,6 +255,21 @@ describe("retailTool", () => {
     expect(retailSlot.get(ctx).activity[0]?.summary).toBe("error: nope");
   });
 
+  test("a body that failed does not move the call", async () => {
+    const ctx = makeCtx();
+    const moves = retailTool({
+      name: "moves",
+      description: "test tool that would identify the caller and fails instead",
+      inputSchema: z.object({}),
+      when: BEFORE_TRANSFER,
+      send: { type: "IDENTIFIED" },
+      summary: () => "moved",
+      execute: () => ({ error: "no such customer" }),
+    });
+    expect(isToolFailure(await moves.execute({}, ctx))).toBe(true);
+    expect(callFlow.position(ctx).state).toBe("identifying");
+  });
+
   test("activity is capped so a long call cannot grow the payload", async () => {
     const ctx = makeCtx();
     for (let i = 0; i < 15; i++) await echo.execute({ value: String(i) }, ctx);
@@ -249,3 +287,32 @@ describe("retailTool", () => {
     expect(new Set(state.activity.map((a) => a.seq)).size).toBe(state.activity.length);
   });
 });
+
+describe("the call flow", () => {
+  test("a fresh call is identifying, and nothing is latched", () => {
+    const ctx = makeCtx();
+    expect(callFlow.position(ctx).state).toBe("identifying");
+    expect(retailSlot.get(ctx).authenticatedUserId).toBeNull();
+  });
+
+  test("transferred is final, so every tool refuses after the handoff", async () => {
+    const ctx = makeCtx();
+    const anywhere = retailTool({
+      name: "anywhere",
+      description: "legal in every state but the terminal one",
+      inputSchema: z.object({}),
+      when: BEFORE_TRANSFER,
+      summary: () => "ran",
+      execute: () => ({ ok: true }),
+    });
+    expect(ok(await anywhere.execute({}, ctx))).toEqual({ ok: true });
+
+    const at = callFlow.send(ctx, { type: "TRANSFERRED" });
+    expect(at.state).toBe("transferred");
+    expect(at.done).toBe(true);
+
+    const refused = await anywhere.execute({}, ctx);
+    expect(isToolFailure(refused)).toBe(true);
+    expect(isToolFailure(refused) && refused.error).toContain('"transferred"');
+  });
+});