@alexkroman1/aai-cli 5.14.0 → 6.1.0

package/dist/templates/travel-concierge/client.tsx

@@ -0,0 +1,161 @@
+import "@alexkroman1/aai-ui/styles.css";
+import { AutoScroll, client, useAgentState, useTheme } from "@alexkroman1/aai-ui";
+import type { TripView } from "./shared.ts";
+import { SPECIALIST_IDS, SPECIALISTS, tripSlot, tripView } from "./shared.ts";
+
+// Derived from the projection so a new TripView field cannot silently miss the
+// pre-first-tool-call render.
+const EMPTY_TRIP: TripView = tripSlot.projection(tripView)(undefined);
+
+const DESKS = ["primary", ...SPECIALIST_IDS] as const;
+
+function deskLabel(id: (typeof DESKS)[number]): string {
+  return id === "primary" ? "concierge" : SPECIALISTS[id].title;
+}
+
+/**
+ * The dialog stack, rendered. This is the panel that earns its place: the
+ * caller cannot see which desk is holding the call, and neither can a reader of
+ * the transcript — the whole delegation mechanism is otherwise invisible.
+ */
+function DeskStrip({ active }: { active: TripView["assistant"] }) {
+  const theme = useTheme();
+  return (
+    <div className="flex flex-wrap gap-1.5">
+      {DESKS.map((id) => {
+        const on = id === active;
+        return (
+          <span
+            key={id}
+            className="rounded-full px-2.5 py-1 text-[11px] font-medium capitalize"
+            style={{
+              background: on ? theme.primary : theme.surface,
+              color: on ? theme.bg : theme.text,
+              opacity: on ? 1 : 0.55,
+            }}
+          >
+            {deskLabel(id)}
+          </span>
+        );
+      })}
+    </div>
+  );
+}
+
+function ItinerarySidebar() {
+  const theme = useTheme();
+  const trip = useAgentState<TripView>(EMPTY_TRIP);
+
+  return (
+    <div className="flex flex-col gap-4 p-4 h-full min-h-0" style={{ color: theme.text }}>
+      <div className="flex flex-col gap-2">
+        <h3 className="text-sm font-bold opacity-60 uppercase tracking-wide">{trip.passenger}</h3>
+        <DeskStrip active={trip.assistant} />
+      </div>
+
+      {/* The staged action — the browser half of the confirmation gate. What is
+          on screen is exactly what the concierge just asked out loud. */}
+      {trip.pending && (
+        <div
+          className="rounded-lg p-3 text-sm"
+          style={{ background: theme.surface, border: `1px solid ${theme.primary}` }}
+        >
+          <p className="text-[11px] font-bold uppercase tracking-wide opacity-60">
+            Waiting on your yes
+          </p>
+          <p className="mt-1 capitalize">{trip.pending}</p>
+        </div>
+      )}
+
+      <div className="flex flex-col gap-2">
+        <p className="text-[11px] font-bold uppercase tracking-wide opacity-60">Ticket</p>
+        {trip.ticket ? (
+          <div className="rounded-lg p-3" style={{ background: theme.surface }}>
+            <p className="text-sm font-medium">
+              {trip.ticket.flightId} · {trip.ticket.route}
+            </p>
+            <p className="text-xs opacity-60">
+              {trip.ticket.departs} · ref {trip.ticket.reference}
+            </p>
+          </div>
+        ) : (
+          <p className="text-sm opacity-50">No ticket — cancelled on this call.</p>
+        )}
+      </div>
+
+      {trip.bookings.length > 0 && (
+        <div className="flex flex-col gap-2">
+          <p className="text-[11px] font-bold uppercase tracking-wide opacity-60">Booked</p>
+          {trip.bookings.map((booking) => (
+            <div
+              key={booking.reference}
+              className="flex items-center justify-between gap-3 rounded-lg p-3"
+              style={{ background: theme.surface }}
+            >
+              <div className="min-w-0">
+                <p className="truncate text-sm">{booking.summary}</p>
+                <p className="text-xs opacity-60">{booking.reference}</p>
+              </div>
+              <span className="text-sm font-bold" style={{ color: theme.primary }}>
+                ${booking.price.toLocaleString("en-US")}
+              </span>
+            </div>
+          ))}
+          <div
+            className="flex justify-between border-t pt-2 text-sm font-bold"
+            style={{ borderColor: theme.border }}
+          >
+            <span>Total</span>
+            <span style={{ color: theme.primary }}>${trip.total.toLocaleString("en-US")}</span>
+          </div>
+        </div>
+      )}
+
+      <div className="flex min-h-0 flex-1 flex-col gap-2">
+        <p className="text-[11px] font-bold uppercase tracking-wide opacity-60">Call log</p>
+        <AutoScroll
+          scrollClassName="overflow-y-auto min-h-0"
+          contentClassName="flex flex-col gap-1 pr-1"
+        >
+          {trip.log.length === 0 ? (
+            <p className="text-xs opacity-40">Nothing yet.</p>
+          ) : (
+            trip.log.map((entry, index) => (
+              // The log is append-only and capped, so the index is stable for
+              // an entry's lifetime — there is no reorder to lose.
+              <p key={`${index}-${entry}`} className="text-xs opacity-70">
+                {entry}
+              </p>
+            ))
+          )}
+        </AutoScroll>
+      </div>
+    </div>
+  );
+}
+
+client({
+  name: "Swiss Air Concierge",
+  sidebar: ItinerarySidebar,
+  theme: {
+    bg: "#0d1117",
+    primary: "#e35d5b",
+    text: "#eef2f6",
+    surface: "#161d27",
+    border: "#232c38",
+  },
+  tools: {
+    to_flight_assistant: { icon: "\u{2708}", label: "Flight desk" },
+    to_hotel_assistant: { icon: "\u{1F3E8}", label: "Hotel desk" },
+    to_car_rental_assistant: { icon: "\u{1F697}", label: "Car desk" },
+    to_excursion_assistant: { icon: "\u{1F5FA}", label: "Excursions desk" },
+    complete_or_escalate: { icon: "\u{21A9}", label: "Back to concierge" },
+    confirm_action: { icon: "\u{2705}", label: "Applying change" },
+    cancel_action: { icon: "\u{274C}", label: "Discarding change" },
+    update_ticket: { icon: "\u{1F39F}", label: "Staging ticket change" },
+    cancel_ticket: { icon: "\u{1F5D1}", label: "Staging cancellation" },
+    book_hotel: { icon: "\u{1F6CF}", label: "Staging hotel" },
+    book_car_rental: { icon: "\u{1F511}", label: "Staging car" },
+    book_excursion: { icon: "\u{1F3AB}", label: "Staging excursion" },
+  },
+});

package/dist/templates/travel-concierge/routing.ts

@@ -0,0 +1,138 @@
+/**
+ * The dialog-stack tools: delegate, escalate, confirm, cancel.
+ *
+ * These four shapes are the customer-support tutorial's control plane, and the
+ * DEFINITIONS live together here because they share this module's helpers —
+ * `activeAssistant`, `applyPending`, `note`. Each is NAMED by a file under
+ * `tools/`, which is what registers it: a tool's name is its file name, so
+ * `tools/to_flight_assistant.ts` is one line handing {@link delegationTool} an
+ * id, and `tools/confirm_action.ts` re-exports {@link confirmAction}.
+ *
+ * The delegation four are still generated rather than written out. The notebook
+ * declares `ToFlightBookingAssistant`, `ToHotelBookingAssistant`,
+ * `ToBookCarRental` and `ToBookExcursion` as four pydantic classes differing
+ * only in the docstring, and the whole content of one is an entry in
+ * {@link SPECIALISTS} — so the factory stays and the files name its instances,
+ * which is a different thing from four near-identical tool bodies. A domain tool
+ * — one that searches or books something — is written in its own file, because
+ * each of those really is different work.
+ */
+
+import type { ToolDef } from "@alexkroman1/aai";
+import { z } from "zod";
+import {
+  activeAssistant,
+  applyPending,
+  describeAction,
+  note,
+  SPECIALISTS,
+  type SpecialistId,
+  tripSlot,
+} from "./shared.ts";
+
+/**
+ * `to_<specialist>_assistant` — push a desk onto the dialog stack.
+ *
+ * The result IS the specialist's brief. A voice session's system prompt is
+ * fixed at connect, so there is no swapping it the way their graph swaps the
+ * runnable; handing the brief back as the tool result puts it in the last thing
+ * the model reads before it speaks, which is the same effect by a route that
+ * works on a live call. `request` exists for the same reason theirs does: the
+ * specialist needs what the caller actually asked for, not just that they were
+ * transferred.
+ */
+export function delegationTool(id: SpecialistId): ToolDef {
+  const specialist = SPECIALISTS[id];
+  return tripSlot.updateTool({
+    description:
+      `Hand the call to the ${specialist.title}. Use this as soon as the caller ` +
+      "raises something that desk owns — do not answer it yourself. Do not " +
+      "mention the transfer; the caller should hear one continuous conversation.",
+    inputSchema: z.object({
+      request: z
+        .string()
+        .max(500)
+        .describe("What the caller asked for, in their own words where possible"),
+    }),
+    execute(args, trip) {
+      // Re-entering a desk the call is already on would grow the stack without
+      // bound over a long call; the brief is still worth re-reading.
+      if (activeAssistant(trip) !== id) trip.dialogState.push(id);
+      note(trip, `→ ${specialist.title}: ${args.request}`);
+      return {
+        desk: specialist.title,
+        instructions: specialist.instructions,
+        request: args.request,
+      };
+    },
+  });
+}
+
+/**
+ * `complete_or_escalate` — pop back to the concierge.
+ *
+ * Kept under its original name because the name is load-bearing: it covers BOTH
+ * "this desk is finished" and "this desk cannot help", and a model offered only
+ * a `done` tool will keep trying to answer things the desk has no tools for.
+ * The `reason` is what the concierge is handed on the way back up.
+ */
+export const completeOrEscalate = tripSlot.updateTool({
+  description:
+    "Hand the call back to the main concierge. Use this when the current desk's " +
+    "work is finished, when the caller changes the subject to something this " +
+    "desk does not handle, or when they change their mind.",
+  inputSchema: z.object({
+    reason: z
+      .string()
+      .max(300)
+      .describe("Why the call is going back — what is done, or what the caller now wants"),
+  }),
+  execute(args, trip) {
+    const left = activeAssistant(trip);
+    // `primary` stays at the bottom — the slot's `after` hook restores it if a
+    // pop ever empties the stack.
+    if (trip.dialogState.length > 1) trip.dialogState.pop();
+    note(trip, `← back to concierge: ${args.reason}`);
+    return {
+      returnedFrom: left === "primary" ? "concierge" : SPECIALISTS[left].title,
+      nowHandling: "concierge",
+      reason: args.reason,
+      instructions:
+        "You are the main concierge again. Pick up what the caller asked for; " +
+        "delegate again if it belongs to another desk.",
+    };
+  },
+});
+
+/**
+ * `confirm_action` — the caller said yes.
+ *
+ * This is the only tool in the template that changes a booking. Their graph
+ * halts before a sensitive tool and resumes on approval; the halt here is that
+ * every sensitive tool stages instead of acting, so the approval has somewhere
+ * to arrive.
+ */
+export const confirmAction = tripSlot.updateTool({
+  description:
+    "Apply the change the caller has just confirmed out loud. Only call this " +
+    "after you have read the change back and heard a clear yes.",
+  execute(_args, trip) {
+    return applyPending(trip);
+  },
+});
+
+/** `cancel_action` — the caller said no. Drops the staged action, changes nothing. */
+export const cancelAction = tripSlot.updateTool({
+  description:
+    "Discard the change the caller just declined. Call this when they say no, " +
+    "or when they want to change the details before confirming.",
+  execute(_args, trip) {
+    const action = trip.pending;
+    if (!action) return { message: "Nothing was waiting for confirmation." };
+    trip.pending = null;
+    const described = describeAction(action);
+    const summary = typeof described === "string" ? described : action.kind;
+    note(trip, `Declined: ${summary}`);
+    return { discarded: summary, message: "Nothing was changed." };
+  },
+});