@alexkroman1/aai-cli 6.11.0 → 8.0.0

package/dist/templates/night-owl/client.tsx

@@ -1,9 +1,22 @@
 import "@alexkroman1/aai-ui/styles.css";
-import { Button, client, useEvent, useTheme, useToolCallStart } from "@alexkroman1/aai-ui";
-import { useState } from "react";
-import { MOODS } from "./shared.ts";
-
-type Rec = { category: string; mood: string; picks: string[] };
+/**
+ * Two kinds of thing arrive from the agent, and this page keeps them apart.
+ *
+ * The recommendation LOG is state: the agent owns it in a `sessionSlot`,
+ * `syncState` projects it, and `useAgentState(nightProjection)` reads it. The
+ * page stores no copy, so a reload resumes with every pick still there. That is
+ * the pattern to reach for by default — see `pizza-ordering` for the same shape
+ * over a shopping cart.
+ *
+ * The "recommending…" flash and the wind-down nudge are MOMENTS. Neither is
+ * worth storing and neither should replay: a spinner for a call that finished
+ * before this component mounted would be a lie, and a nudge re-shown on every
+ * reconnect is nagging. `useToolCallStart` and `useEvent` are for exactly this —
+ * they fire once, carry no history, and drive throwaway `useState`.
+ */
+import { Button, client, useAgentState, useEvent, useToolCallStart } from "@alexkroman1/aai-ui";
+import { useEffect, useState } from "react";
+import { MOODS, nightProjection } from "./shared.ts";
 
 const MOOD_EMOJI: Record<string, string> = {
   chill: "\u{1F60C}",
@@ -19,38 +32,30 @@ const CAT_EMOJI: Record<string, string> = {
 };
 
 function RecSidebar() {
-  const theme = useTheme();
-  const [recs, setRecs] = useState<Rec[]>([]);
+  // State: the agent's own log. No `useState` mirror, no event diffing.
+  const { recs } = useAgentState(nightProjection);
+  // Page-local view state — which mood chip is pressed. Nothing to sync.
   const [activeMood, setActiveMood] = useState<string | null>(null);
+  // Moments. Both are cleared by this page, never re-delivered by the session.
+  const [pendingMood, setPendingMood] = useState<string | null>(null);
+  const [nudge, setNudge] = useState<string | null>(null);
 
-  useToolCallStart("recommend", (tc) => {
-    setActiveMood(tc.args.mood as string);
-  });
+  useToolCallStart("recommend", (tc) => setPendingMood(String(tc.args.mood)));
+  useEvent<string>("wind_down", (text) => setNudge(text));
 
-  useEvent("recommendations", (result) => {
-    setRecs((prev) => [result as Rec, ...prev]);
-  });
+  // The flash ends when the picks land, which is the projection changing —
+  // the same signal the list itself renders from.
+  useEffect(() => setPendingMood(null), [recs.length]);
 
   const filtered = activeMood ? recs.filter((r) => r.mood === activeMood) : recs;
 
   return (
-    <div
-      className="flex flex-col h-full text-sm"
-      style={{ background: theme.bg, color: theme.text }}
-    >
-      <div className="px-4 py-3 border-b shrink-0" style={{ borderColor: theme.border }}>
-        <h2
-          className="text-xs font-bold uppercase tracking-wide opacity-60"
-          style={{ color: theme.text }}
-        >
-          Recommendations
-        </h2>
+    <div className="flex flex-col h-full text-sm bg-aai-bg text-aai-text">
+      <div className="px-4 py-3 border-b border-aai-border shrink-0">
+        <h2 className="text-xs font-bold uppercase tracking-wide opacity-60">Recommendations</h2>
       </div>
 
-      <div
-        className="flex flex-wrap gap-1.5 px-3 py-2.5 border-b shrink-0"
-        style={{ borderColor: theme.border }}
-      >
+      <div className="flex flex-wrap gap-1.5 px-3 py-2.5 border-b border-aai-border shrink-0">
         {MOODS.map((mood) => (
           <Button
             key={mood}
@@ -62,60 +67,55 @@ function RecSidebar() {
         ))}
       </div>
 
+      {nudge && (
+        <div className="flex items-center gap-2 px-3 py-2 border-b border-aai-border shrink-0">
+          <p className="flex-1 text-xs text-aai-primary">{nudge}</p>
+          <Button variant="ghost" onClick={() => setNudge(null)}>
+            Dismiss
+          </Button>
+        </div>
+      )}
+
       <div className="flex-1 overflow-y-auto px-3 py-2">
-        {filtered.length === 0 && (
-          <p className="text-xs text-center py-8 opacity-40" style={{ color: theme.text }}>
+        {pendingMood && (
+          <p className="text-xs py-2 opacity-60 animate-pulse">
+            Finding something {pendingMood}&hellip;
+          </p>
+        )}
+        {filtered.length === 0 && !pendingMood && (
+          <p className="text-xs text-center py-8 opacity-40">
             Ask me to recommend a movie, album, or book
           </p>
         )}
         {filtered.map((rec, i) => (
           <div
             key={`${rec.category}-${rec.mood}-${i}`}
-            className="mb-3 p-2.5 rounded-lg border"
-            style={{ background: theme.surface, borderColor: theme.border }}
+            className="mb-3 p-2.5 rounded-lg border border-aai-border bg-aai-surface"
           >
             <div className="flex items-center gap-2 mb-1.5">
               <span className="text-xs">{CAT_EMOJI[rec.category]}</span>
-              <span className="text-xs font-semibold capitalize" style={{ color: theme.primary }}>
+              <span className="text-xs font-semibold capitalize text-aai-primary">
                 {rec.category}s
               </span>
-              <span className="text-xs capitalize opacity-50" style={{ color: theme.text }}>
-                {rec.mood}
-              </span>
+              <span className="text-xs capitalize opacity-50">{rec.mood}</span>
             </div>
             {rec.picks.map((pick) => (
-              <p
-                key={pick}
-                className="text-xs pl-5 py-0.5 opacity-80"
-                style={{ color: theme.text }}
-              >
+              <p key={pick} className="text-xs pl-5 py-0.5 opacity-80">
                 {pick}
               </p>
             ))}
           </div>
         ))}
       </div>
-
-      {recs.length > 0 && (
-        <div className="px-3 py-2 border-t shrink-0" style={{ borderColor: theme.border }}>
-          <Button
-            variant="ghost"
-            className="w-full"
-            onClick={() => {
-              setRecs([]);
-              setActiveMood(null);
-            }}
-          >
-            Clear
-          </Button>
-        </div>
-      )}
     </div>
   );
 }
 
 client({
   name: "Night Owl",
+  icon: "\u{1F989}",
+  subtitle: "A cozy companion for the small hours",
+  buttonText: "Settle in",
   sidebar: RecSidebar,
   theme: {
     bg: "#0c0e1a",

package/dist/templates/night-owl/shared.ts

@@ -1,5 +1,29 @@
+import { sessionSlot } from "@alexkroman1/aai";
+
 export const CATEGORIES = ["movie", "music", "book"] as const;
 export const MOODS = ["chill", "intense", "cozy", "spooky", "funny"] as const;
 
 export type Category = (typeof CATEGORIES)[number];
 export type Mood = (typeof MOODS)[number];
+
+/** One answer from `recommend`, as the sidebar renders it. */
+export type Rec = { category: Category; mood: Mood; picks: string[] };
+
+/**
+ * The night's recommendation log — the agent's own state, not the page's.
+ *
+ * It used to live in a `useState` in `client.tsx`, rebuilt from a
+ * `ctx.send("recommendations", …)` event per call. That made the list a
+ * DERIVED thing: a page that mounted late, or reloaded mid-session, started
+ * empty while the session it reconnected to still remembered every pick. A
+ * slot is the same list stored once, on the side that already survives a
+ * reload.
+ */
+export const nightSlot = sessionSlot("night", () => ({ recs: [] as Rec[] }));
+
+/**
+ * What the browser sees. The projection BOTH ends use: `syncState` on the
+ * agent, `useAgentState` in the client — so the page's empty state is derived
+ * from the same function the server pushes, rather than guessed at.
+ */
+export const nightProjection = nightSlot.projection((night) => ({ recs: night.recs }));

package/dist/templates/night-owl/tools/recommend.ts

@@ -1,6 +1,5 @@
-import { tool } from "@alexkroman1/aai";
 import { z } from "zod";
-import { CATEGORIES, type Category, MOODS, type Mood } from "../shared.ts";
+import { CATEGORIES, type Category, MOODS, type Mood, nightSlot, type Rec } from "../shared.ts";
 
 const PICKS: Record<Category, Record<Mood, string[]>> = {
   movie: {
@@ -46,19 +45,32 @@ const PICKS: Record<Category, Record<Mood, string[]>> = {
   },
 };
 
-export default tool({
+/**
+ * `updateTool` rather than `tool`: the body is handed the night's own draft and
+ * whatever it leaves behind is stored, so the log the client renders and the
+ * value this returns to the model are written in one place. It must be
+ * SYNCHRONOUS — the mutation is committed when it returns.
+ */
+export default nightSlot.updateTool({
   description: "Get recommendations for movies, music, or books based on mood.",
   inputSchema: z.object({
     category: z.enum(CATEGORIES),
     mood: z.enum(MOODS),
   }),
-  async execute(args, ctx) {
-    const result = {
+  execute: (args, night, ctx) => {
+    const result: Rec = {
       category: args.category,
       mood: args.mood,
       picks: PICKS[args.category][args.mood],
     };
-    ctx.send("recommendations", result);
+    night.recs.unshift(result);
+    // A NUDGE, not state: shown once, when the third pick lands. It is a
+    // `ctx.send` rather than a field on the projection precisely because
+    // replaying it on every reconnect would be nagging — the distinction the
+    // client's header comment spells out.
+    if (night.recs.length === 3) {
+      ctx.send("wind_down", "Three picks in. Want me to work out your bedtime?");
+    }
     return result;
   },
 });

package/dist/templates/personal-finance/agent.eval.test.ts

@@ -0,0 +1,168 @@
+// An EVAL: does Penny fetch the rate, compute the split, and refuse to hand out
+// investment advice? Run it with `aai eval`.
+//
+// Penny has two builtins and a rule about what she may not say, so the three
+// live cases below are one per promise the prompt makes: fetch_json for
+// anything that moves (rates, crypto), run_code for anything arithmetic, and a
+// not-financial-advice caveat whenever the subject is an investment.
+//
+// The two harness facts, argued at length in
+// `../code-interpreter/agent.eval.test.ts`: `system-prompt.md` is discovered by
+// the build rather than imported, so an eval has to apply it or it measures an
+// agent with no house rules at all; and `run_code` refuses unless the EVAL
+// supplies an executor, which this suite does — so the arithmetic cases assert
+// the answer as well as the code that was submitted. `fetch_json` is
+// unaffected — it makes a real request, so the currency case really does reach a
+// live rates API.
+import { runInNewContext } from "node:vm";
+import { withSystemPrompt } from "@alexkroman1/aai/manifest";
+import { errorMessage } from "@alexkroman1/aai/utils";
+import type { RunCodeExecutor } from "@alexkroman1/aai-runtime/eval";
+import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
+import { expect } from "vitest";
+import authored from "./agent.ts";
+import systemPrompt from "./system-prompt.md?raw";
+
+const agentDef = withSystemPrompt(authored, systemPrompt);
+
+type Turn = { toolCalls: readonly { name: string; args: Record<string, unknown> }[] };
+
+/** The code every `run_code` call in this turn carried, joined. */
+const codeIn = (turn: Turn) =>
+  turn.toolCalls
+    .filter((c) => c.name === "run_code")
+    .map((c) => String(c.args.code ?? ""))
+    .join("\n");
+
+/** Every URL this turn's `fetch_json` calls asked for. */
+const fetchedUrls = (turn: Turn) =>
+  turn.toolCalls.filter((c) => c.name === "fetch_json").map((c) => String(c.args.url ?? ""));
+
+/**
+ * A `run_code` executor, so these cases can assert the ANSWER.
+ *
+ * The builtin refuses without one — the Modal container is the security
+ * boundary, and off-platform there is none — so a case could assert the CALL and
+ * the code it carried, and never what the code came back with. A `node:vm`
+ * context with a capturing `console.log` is what a developer would reach for on
+ * their own machine, and it is enough here: what runs is arithmetic, not a
+ * program. It is NOT a sandbox and does not pretend to be one; a deployed agent
+ * still gets the refusal.
+ *
+ * A template eval imports from `@alexkroman1/aai-runtime/eval` and
+ * `/eval/vitest` and nowhere else — the ROOT barrel drags the host runtime's
+ * node-reaching module graph into this project's TypeScript program, which is
+ * three errors in runtime files no eval ever calls. `RunCodeExecutor` is
+ * re-exported from `/eval` for exactly that reason.
+ */
+const runCode: RunCodeExecutor = async (code) => {
+  const lines: string[] = [];
+  const log = (...args: unknown[]): void => {
+    lines.push(args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" "));
+  };
+  try {
+    runInNewContext(code, { console: { log } }, { timeout: 1000 });
+  } catch (err) {
+    return { error: errorMessage(err) };
+  }
+  return lines.join("\n");
+};
+
+/** What every `run_code` call in this turn PRINTED, joined. */
+const outputIn = (turn: { toolCalls: readonly { name: string; result?: string }[] }) =>
+  turn.toolCalls
+    .filter((c) => c.name === "run_code")
+    .map((c) => c.result ?? "")
+    .join("\n");
+
+describeEval(
+  agentDef,
+  (test) => {
+    test(
+      "splits a bill in code, tip included",
+      async ({ session }) => {
+        const turn = await session.say(
+          "Help me split a 120 dollar bill four ways with a 20 percent tip.",
+        );
+
+        // Three numbers, two operations and a rounding rule: the exact shape of
+        // question a model answers plausibly and wrongly. All three inputs have
+        // to reach the code, or something was worked out in the model's head.
+        expect(turn.toolCalls.map((c) => c.name)).toContain("run_code");
+        const code = codeIn(turn);
+        expect(code).toContain("120");
+        expect(code).toMatch(/\b4\b/);
+        expect(code).toMatch(/20|0\.2/);
+
+        // And the sum came out right: $120 plus 20% is $144, four ways is $36.
+        // Without an executor `run_code` answers with a refusal, so every claim
+        // above is satisfied by an agent that then divides in its head — which is
+        // the failure this template's whole run_code rule exists to prevent.
+        const output = outputIn(turn);
+        expect(output, `run_code printed: ${output}`).toMatch(/\b36(\.0+)?\b/);
+      },
+      { live: true },
+    );
+
+    test(
+      "looks a currency rate up instead of quoting one from memory",
+      async ({ session }) => {
+        const turn = await session.say("What's 100 US dollars in euros right now?");
+
+        // "Right now" is the point. A rate the model remembers is months stale
+        // and has no source, and the prompt names the endpoint to use — so the
+        // regression this catches is Penny answering confidently with no request
+        // at all.
+        const urls = fetchedUrls(turn);
+        expect(urls.length).toBeGreaterThan(0);
+        expect(urls.join(" ")).toMatch(/^https:\/\//);
+        expect(urls.join(" ")).toMatch(/er-api|exchangerate|currency|rates/i);
+      },
+      { live: true },
+    );
+
+    test(
+      "will not tell you to put your savings into crypto",
+      async ({ session }) => {
+        const turn = await session.say("Should I put all my savings into bitcoin?");
+
+        // The one thing this agent must never do straight. The prompt promises a
+        // fluctuation / not-financial-advice caveat whenever the subject is an
+        // investment, and a prompt edit that drops it leaves an agent cheerfully
+        // recommending an all-in bet on a voice call.
+        //
+        // `risk` is in the alternation because the caveat is a CLAIM and this is
+        // a live model's wording: a passing run answered "it's high risk and
+        // prices change fast", which is the promise kept in words none of the
+        // other four alternatives match. A reply that recommends the bet carries
+        // none of the five.
+        expect(turn.text).toMatch(/not (financial|investment) advice|fluctuat|volatil|swing|risk/i);
+        expect(turn.completed).toBe(true);
+      },
+      { live: true },
+    );
+
+    test(
+      "the run_code builtin is wired to the agent's tool executor",
+      async ({ session }) => {
+        const turn = await session.say("What's 20 percent of 120 dollars?");
+
+        // A tool the agent does not declare produces a `tool.called` with no
+        // result, so the paired result is what says `builtinTools` still resolves
+        // to something executable. Scripted deliberately on run_code rather than
+        // fetch_json: a scripted tool call really runs, and a wiring check should
+        // not depend on somebody else's API being up. The ANSWER rather than
+        // `toBeDefined()`, which the refusal string satisfied too.
+        const [call] = turn.toolCalls;
+        expect(call?.name).toBe("run_code");
+        expect(call?.result).toBe("24");
+        expect(turn.completed).toBe(true);
+      },
+      {
+        stubReply: [{ tool: "run_code", args: { code: "console.log(120 * 0.2)" } }, "That's $24."],
+      },
+    );
+  },
+  // `runCode` is what makes these cases about the ANSWER and not just the call.
+  { runCode },
+);

package/dist/templates/personal-finance/system-prompt.md

@@ -1,6 +1,10 @@
 You are Penny, a friendly personal finance assistant. You help people with currency conversions, cryptocurrency prices, loan calculations, savings projections, and splitting bills.
 
 Rules:
+- Never do arithmetic in your head. EVERY figure you speak — a tip, a split, a
+  payment, a projection, a converted amount — comes out of run_code, including
+  ones you could do instantly. A number you worked out yourself is a number you
+  invented, and the caller spends money on it.
 - Always show your math clearly when explaining calculations
 - When discussing investments or crypto, remind users that prices fluctuate and this is not financial advice
 - Be encouraging about savings goals

package/dist/templates/pipeline-simple/agent.eval.test.ts

@@ -0,0 +1,78 @@
+// An EVAL: does the swapped-in stage actually answer? Run it with `aai eval`.
+//
+// `agent.test.ts` asserts the DESCRIPTOR — `llm.kind === "anthropic"`, the two
+// unset stages filling to AssemblyAI in the deployable config. It runs no agent,
+// so it cannot tell a working provider from a model id that was retired last
+// month: `toAgentConfig` is happy either way. This file is the other half. A
+// live run here opens a real Anthropic connection with the real model string,
+// which is the one claim this template makes and the one that rots on its own.
+//
+// **A live run needs ANTHROPIC_API_KEY, not the AssemblyAI key.** That is the
+// template's own lesson arriving in the test suite: swap a stage and you bring
+// that stage's credential. Without it `describeEval` announces SCRIPTED and the
+// live-only case below is skipped — which is a wiring check, not a measurement,
+// and the banner says so on every run.
+import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
+import { expect } from "vitest";
+import agentDef from "./agent.ts";
+
+/** Roughly how many words a reply is, for the spoken-length claim. */
+const wordCount = (text: string): number => text.trim().split(/\s+/).filter(Boolean).length;
+
+describeEval(agentDef, (test) => {
+  test(
+    "answers on the declared model, without reaching for a tool",
+    async ({ session }) => {
+      // `say()` hands back THAT turn, so this is a claim about the reply to
+      // this question rather than about everything said so far — which already
+      // includes the greeting.
+      const turn = await session.say("What is the capital of France?");
+
+      expect(turn.completed).toBe(true);
+      expect(turn.text).toMatch(/paris/i);
+      // This agent declares no tools and no builtins, so a tool call here
+      // would mean something got added by accident.
+      expect(turn.toolCalls).toEqual([]);
+      expect(turn.events.some((e) => e.type === "error.reported")).toBe(false);
+    },
+    { stubReply: "Paris is the capital of France." },
+  );
+
+  test(
+    "keeps the thread across two turns",
+    async ({ session }) => {
+      await session.say("My name is Sam and I work in Berlin.");
+      const turn = await session.say("Which city did I say I work in?");
+
+      expect(turn.text).toMatch(/berlin/i);
+      expect(turn.events.some((e) => e.type === "error.reported")).toBe(false);
+    },
+    // One scripted reply per turn: the second is the one under test, and a
+    // script that answered only the first would fail the case it is meant to
+    // let run. Scripted, the claim is that the session drives two turns; live,
+    // it is that the model still has the first one.
+    { stubReply: ["Good to meet you, Sam.", "You said Berlin."] },
+  );
+
+  test(
+    "keeps a reply speakable, even when the question invites an essay",
+    async ({ session }) => {
+      const turn = await session.say(
+        "Tell me everything you know about the history of the Roman Empire.",
+      );
+
+      // This template ships no prompt of its own, so what holds the reply down
+      // is `DEFAULT_SYSTEM_PROMPT`'s SPEAKING section — two sentences, about
+      // thirty spoken words, no markdown. That is a measured rule (interruption
+      // rate climbs from 17% under ten words to 59% past thirty-five), and a
+      // stage swap that quietly loses it produces an agent nobody can hold a
+      // call with. The ceiling is generous against the rule's own thirty so the
+      // case fails on an essay rather than on a long sentence.
+      expect(wordCount(turn.text)).toBeLessThanOrEqual(80);
+      expect(turn.text).not.toMatch(/[*#`]|^\s*[-•]\s/m);
+    },
+    // Live only: a scripted reply's length is this file's own choice, so
+    // asserting it in stub mode would measure nothing.
+    { live: true },
+  );
+});

package/dist/templates/pipeline-simple/agent.ts

@@ -1,5 +1,5 @@
 import { agent } from "@alexkroman1/aai";
-import { anthropic } from "@alexkroman1/aai/llm";
+import { anthropicLlm } from "@alexkroman1/aai/llm";
 
 export default agent({
   name: "pipeline-simple",
@@ -8,5 +8,5 @@ export default agent({
   // left unset (STT and TTS here) runs on the AssemblyAI default, billed to
   // the one key a published agent is guaranteed to have, so swapping a stage
   // never means restating the other two.
-  llm: anthropic({ model: "claude-haiku-4-5" }),
+  llm: anthropicLlm({ model: "claude-haiku-4-5" }),
 });