@alexkroman1/aai-cli 6.11.0 → 8.0.0

package/dist/templates/retail/cancel.ts

@@ -0,0 +1,116 @@
+/**
+ * Cancelling a pending order, as a PLAN and an APPLY.
+ *
+ * The split is what the confirmation gate is built out of, and it is the same
+ * split in all seven mutating actions here: `plan*` validates everything and
+ * computes the effect without touching the store, `apply*` performs it and
+ * cannot fail. A staged plan is what the caller says yes to, so the validation
+ * has to happen BEFORE the readback — a "yes" followed by a refusal is the one
+ * sequence this gate exists to make impossible.
+ */
+
+import { isToolFailure, type ToolFailure } from "@alexkroman1/aai";
+import { creditRefund, REFUND_DELAY_NOTE, REFUND_IMMEDIATE_NOTE } from "./refund.ts";
+import { resolveOrder } from "./resolve.ts";
+import type { RetailState } from "./shared.ts";
+import { authenticatedUser, money } from "./store.ts";
+
+/** The only two reasons the store records. */
+export const CANCEL_REASONS = ["no longer needed", "ordered by mistake"] as const;
+export type CancelReason = (typeof CANCEL_REASONS)[number];
+
+/**
+ * A validated cancellation, holding only storable primitives.
+ *
+ * No `Order` or `PaymentMethod` reference: a plan is written into the session
+ * slot and rides across turns, so a live object here would alias the store and
+ * a persisted session could not carry it. Ids and amounts are enough, and
+ * looking them up again at apply time is what keeps {@link applyCancel}
+ * total.
+ */
+export interface CancelPlan {
+  /** The sentence the agent reads back before asking for a yes. */
+  readBack: string;
+  orderId: string;
+  reason: CancelReason;
+  refunds: { methodId: string; amount: number }[];
+  total: number;
+}
+
+export function planCancel(
+  state: RetailState,
+  spokenOrderId: string,
+  reason: CancelReason,
+): CancelPlan | ToolFailure {
+  const user = authenticatedUser(state);
+  if (isToolFailure(user)) return user;
+
+  const order = resolveOrder(state, spokenOrderId);
+  if (isToolFailure(order)) return order;
+
+  // The enum makes this unreachable from a well-formed call; it stays because
+  // the reason is the one field a caller supplies in free speech, and an LLM
+  // tool call arrives untyped.
+  if (!CANCEL_REASONS.includes(reason)) {
+    return {
+      error: `'${reason}' is not an accepted cancellation reason. It must be 'no longer needed' or 'ordered by mistake'.`,
+    };
+  }
+
+  // Exactly 'pending'. A 'pending (item modified)' order has spent its one
+  // modification and is past cancelling.
+  if (order.status !== "pending") {
+    return {
+      error: `Order ${order.order_id} is ${order.status}, and only a pending order can be cancelled.`,
+    };
+  }
+
+  const refunds = order.payment_history
+    .filter((payment) => payment.transaction_type === "payment")
+    .map((payment) => ({ methodId: payment.payment_method_id, amount: payment.amount }));
+  const total = money(refunds.reduce((sum, refund) => sum + refund.amount, 0));
+
+  const items = order.items.map((item) => item.name).join(", ");
+  const destinations = [...new Set(refunds.map((refund) => refund.methodId))].join(" and ");
+  return {
+    readBack:
+      `cancel order ${order.order_id} (${items}) as '${reason}' and refund ` +
+      `$${total.toFixed(2)} to ${destinations}`,
+    orderId: order.order_id,
+    reason,
+    refunds,
+    total,
+  };
+}
+
+/** The effect. Total by construction: every id in the plan was resolved from
+ *  this same store, and nothing between staging and confirming can remove one. */
+export function applyCancel(state: RetailState, plan: CancelPlan) {
+  const order = state.store.orders[plan.orderId];
+  const user = order ? state.store.users[order.user_id] : undefined;
+  let immediate = false;
+
+  if (order && user) {
+    for (const refund of plan.refunds) {
+      immediate = creditRefund(user, refund.methodId, refund.amount).immediate || immediate;
+      order.payment_history.push({
+        transaction_type: "refund",
+        amount: refund.amount,
+        payment_method_id: refund.methodId,
+      });
+    }
+    order.status = "cancelled";
+    order.cancel_reason = plan.reason;
+  }
+
+  return {
+    order_id: plan.orderId,
+    status: "cancelled" as const,
+    cancel_reason: plan.reason,
+    refunded: plan.total,
+    refund_immediate: immediate,
+    message: `Order ${plan.orderId} is cancelled and $${plan.total.toFixed(2)} is being refunded. ${
+      immediate ? REFUND_IMMEDIATE_NOTE : REFUND_DELAY_NOTE
+    }`,
+  };
+}

package/dist/templates/retail/client.tsx

@@ -1,17 +1,19 @@
 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 {
   OrderStatus,
   OrderView,
   PaymentMethodView,
+  PendingView,
   StoreView,
   SwapOptionView,
 } from "./shared.ts";
@@ -154,6 +156,42 @@ function OrderCard({ order, focused }: { order: OrderView; focused: boolean }) {
 
 /** Character select. Rendered before authentication, because a user with no
  *  email to give cannot start the conversation at all. */
+/**
+ * The change waiting on the caller's word.
+ *
+ * The one panel that renders BECAUSE nothing has happened. A staged change is
+ * the agent's promise about what it is going to do, so showing it beside the
+ * orders it has not touched is what lets a watcher catch a readback that does
+ * not match the request — which is the failure the whole gate is aimed at, and
+ * the one nobody can see from a transcript alone.
+ */
+function PendingChange({ pending }: { pending: PendingView }) {
+  return (
+    <div
+      className="rounded-lg p-3"
+      style={{
+        background: "#fffbeb",
+        border: "1px solid #fcd34d",
+        animation: "rt-slide-in 180ms ease-out",
+      }}
+    >
+      <div
+        className="text-[10px] font-semibold uppercase tracking-wider mb-1.5 flex items-center gap-1.5"
+        style={{ color: "#b45309" }}
+      >
+        <span style={{ animation: "rt-pulse 1.4s ease-in-out infinite" }}>●</span>
+        Awaiting the caller's yes
+      </div>
+      <div className="text-xs leading-relaxed" style={{ color: "#78350f" }}>
+        {pending.readBack}
+      </div>
+      <div className="text-[10px] mt-1.5" style={{ color: "#a16207" }}>
+        Nothing has changed yet — {pending.kind}
+      </div>
+    </div>
+  );
+}
+
 function PersonaList() {
   return (
     <div className="flex flex-col gap-2">
@@ -217,13 +255,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 +493,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 +516,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 */}
@@ -380,6 +526,8 @@ function App() {
             className="rt-scroll overflow-y-auto p-3 flex flex-col gap-3"
             style={{ background: "#f4f4f5" }}
           >
+            {view.pending && <PendingChange pending={view.pending} />}
+
             {!view.customer && (
               <Panel title="Who to be">
                 <PersonaList />

package/dist/templates/retail/payment.ts

@@ -0,0 +1,107 @@
+/**
+ * Changing which payment method a pending order is charged to, as a plan and an
+ * apply (see `cancel.ts` for why every mutating action is split that way).
+ */
+
+import { isToolFailure, type ToolFailure } from "@alexkroman1/aai";
+import { resolveOrder } from "./resolve.ts";
+import type { RetailState } from "./shared.ts";
+import { authenticatedUser, findPaymentMethod, isGiftCard, money } from "./store.ts";
+
+export interface PaymentPlan {
+  readBack: string;
+  orderId: string;
+  /** Where the order is charged after the change. */
+  newMethodId: string;
+  /** Where the original charge goes back to. */
+  oldMethodId: string;
+  amount: number;
+}
+
+export function planPayment(
+  state: RetailState,
+  spokenOrderId: string,
+  newMethodId: string,
+): PaymentPlan | ToolFailure {
+  const user = authenticatedUser(state);
+  if (isToolFailure(user)) return user;
+
+  const order = resolveOrder(state, spokenOrderId);
+  if (isToolFailure(order)) return order;
+
+  if (!order.status.startsWith("pending")) {
+    return {
+      error: `Order ${order.order_id} is ${order.status}, and only a pending order's payment method can be changed.`,
+    };
+  }
+
+  const newMethod = findPaymentMethod(user, newMethodId);
+  if (isToolFailure(newMethod)) return newMethod;
+
+  const original = order.payment_history[0];
+  if (order.payment_history.length !== 1 || original?.transaction_type !== "payment") {
+    return {
+      error: `Order ${order.order_id} does not have exactly one payment on record, so its payment method cannot be changed.`,
+    };
+  }
+  if (original.payment_method_id === newMethodId) {
+    return {
+      error: `Order ${order.order_id} is already paid with ${newMethodId}. The new method must be different.`,
+    };
+  }
+
+  const amount = original.amount;
+  if (isGiftCard(newMethod) && newMethod.balance < amount) {
+    return {
+      error: `Gift card ${newMethodId}'s balance ($${newMethod.balance.toFixed(2)}) does not cover the $${amount.toFixed(2)} order total.`,
+    };
+  }
+
+  return {
+    readBack:
+      `charge order ${order.order_id} — $${amount.toFixed(2)} — to ${newMethodId} instead, ` +
+      `refunding ${original.payment_method_id}`,
+    orderId: order.order_id,
+    newMethodId,
+    oldMethodId: original.payment_method_id,
+    amount,
+  };
+}
+
+export function applyPayment(state: RetailState, plan: PaymentPlan) {
+  const order = state.store.orders[plan.orderId];
+  const user = order ? state.store.users[order.user_id] : undefined;
+
+  if (order && user) {
+    order.payment_history.push(
+      {
+        transaction_type: "payment",
+        amount: plan.amount,
+        payment_method_id: plan.newMethodId,
+      },
+      {
+        transaction_type: "refund",
+        amount: plan.amount,
+        payment_method_id: plan.oldMethodId,
+      },
+    );
+
+    const newMethod = user.payment_methods[plan.newMethodId];
+    if (newMethod && isGiftCard(newMethod)) {
+      newMethod.balance = money(newMethod.balance - plan.amount);
+    }
+    const oldMethod = user.payment_methods[plan.oldMethodId];
+    if (oldMethod && isGiftCard(oldMethod)) {
+      oldMethod.balance = money(oldMethod.balance + plan.amount);
+    }
+  }
+
+  return {
+    order_id: plan.orderId,
+    status: order?.status ?? "pending",
+    amount: plan.amount,
+    paid_with: plan.newMethodId,
+    refunded_to: plan.oldMethodId,
+    message: `Order ${plan.orderId} is now charged to ${plan.newMethodId}, and $${plan.amount.toFixed(2)} is going back to ${plan.oldMethodId}.`,
+  };
+}