@alexkroman1/aai-cli 6.11.0 → 7.0.0

package/dist/templates/link-digest/client.tsx

@@ -7,83 +7,70 @@
  * is the same — the same `client.tsx` filename, React, Tailwind, and the same
  * theme tokens the voice components read.
  *
- * What replaces `useSession()` is three things: `createWorkflowApi()` to start a
- * run, `useWorkflowRun()` to watch its STATUS, and `useWorkflowProgress()` to
- * read what it has WRITTEN. The API is durable, so the `runId` is the whole
- * state — it survives a reload, a different device, or `curl`.
+ * What replaces `useSession()` is `useWorkflowSubmit()`: it starts the run,
+ * follows its STATUS, and hands back the controls bound to it — `wake`, `cancel`
+ * and `reset`. The API is durable, so the `runId` is the whole state — it
+ * survives a reload, a different device, or `curl`.
+ *
+ * ## The FORM here is still written by hand, deliberately
+ *
+ * This is the template that shows the primitives raw. `redline` and
+ * `transcription-workflow` declare their forms — `<Form>` + `<WorkflowFields>`
+ * renders one control per scalar the schema declares — and that is what most
+ * pages should do. This one writes its single `<input>` itself, so a reader can
+ * see what the declared layer is standing on: an ordinary `onSubmit` handing an
+ * object to `submit()`.
  *
  * ## Status and progress are different questions
  *
- * `useWorkflowRun` answers "where has this got to" from the world's own record —
- * pending, running, completed. `useWorkflowProgress` answers "what is it doing"
- * from what the run wrote itself (`report()` in `workflows/digest.ts`). A page
- * with only the first shows "Working…" for the length of the run; a page with
- * only the second cannot tell a finished run from a quiet one. Both are cheap:
- * one stream each, ended by the agent when there is nothing left to say.
+ * `useWorkflowSubmit` answers "where has this got to" from the world's own
+ * record — pending, running, completed. `<WorkflowProgress>` answers "what is it
+ * doing" from what the run wrote itself (`report()` in `workflows/digest.ts`). A
+ * page with only the first shows "Working…" for the length of the run; a page
+ * with only the second cannot tell a finished run from a quiet one. Both are
+ * cheap: one stream each, ended by the agent when there is nothing left to say.
  *
  * Progress also REPLAYS — chunks are retained with the run — so a reload mid-run
- * catches up rather than starting from whatever arrives next. This page renders
- * only the newest line, because on a page this small that is the whole of what a
- * status wants; `transcription-workflow` renders the full log, where a fan-out makes
- * the history worth seeing.
+ * catches up rather than starting from whatever arrives next. `lines={1}` is
+ * what narrows it to the newest line, because on a page this small that is the
+ * whole of what a status wants; `transcription-workflow` renders the full log,
+ * where a fan-out makes the history worth seeing.
  */
 
-import { createWorkflowApi, page, useWorkflowProgress, useWorkflowRun } from "@alexkroman1/aai-ui";
+import { page, useWorkflowSubmit, WorkflowProgress } from "@alexkroman1/aai-ui";
 import "@alexkroman1/aai-ui/styles.css";
 // ERASED at build time, so naming the agent's own type costs the browser bundle
 // nothing — and it is what stops this file restating a shape `workflows/
 // digest.ts` already declares.
-import type { WorkflowOutputOf } from "@alexkroman1/aai";
-// The one runtime import from the SDK a browser bundle wants: `/utils` is the
-// zod-free subpath, so it costs a few hundred bytes rather than the root
-// barrel's module graph.
-import { errorMessage } from "@alexkroman1/aai/utils";
+import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import { useState } from "react";
 import type { digest } from "./agent.ts";
 
 /** What a completed run reports, derived from the workflow rather than restated. */
 type Digest = WorkflowOutputOf<typeof digest>;
 
-/**
- * Hoisted out of the component deliberately.
- *
- * `useWorkflowRun` holds the client in a ref precisely so a fresh object per
- * render cannot restart its watch, but building one in render is still a new
- * `fetch` closure every time and reads as though it were free.
- */
-const api = createWorkflowApi();
-
 export function App() {
   const [url, setUrl] = useState("");
-  const [runId, setRunId] = useState<string>();
-  const [error, setError] = useState<string>();
   // The generic is what makes `run.status === "completed"` narrow to a TYPED
-  // `run.output` instead of `unknown`.
-  const { run, polling } = useWorkflowRun<Digest>(runId, { api });
-  // What the run has SAID, as against where it has got to. Defaults to `string`,
-  // which is what `report()` writes.
-  const { latest, supported } = useWorkflowProgress(runId, { api });
+  // `run.output` instead of `unknown`. `error` is the agent's own sentence for a
+  // rejected input, which is better copy than anything this page could write, and
+  // `wake` is bound to whatever run the hook is following — the whole reason this
+  // page no longer holds a `createWorkflowApi()` of its own.
+  const { submit, run, pending, error, wake } = useWorkflowSubmit<Digest>("digest");
 
-  const submit = async (event: React.FormEvent) => {
+  // `submit()` resolves as soon as the run exists — deliberately not when it
+  // finishes. That is the whole mechanism: the digest sleeps for a while, and
+  // this page is free to be closed in the meantime.
+  const onSubmit = (event: React.FormEvent) => {
     event.preventDefault();
-    setError(undefined);
-    try {
-      // Resolves as soon as the run exists — deliberately not when it finishes.
-      // That is the whole mechanism: the digest sleeps for a while, and this
-      // page is free to be closed in the meantime.
-      setRunId(await api.start("digest", { url }));
-    } catch (err) {
-      // The agent's own sentence: an input failing the workflow's schema names
-      // the issue, which is better copy than anything this page could write.
-      setError(errorMessage(err));
-    }
+    void submit({ url });
   };
 
   return (
     <main className="mx-auto flex max-w-2xl flex-col gap-6 p-8">
       <h1 className="text-2xl font-medium">Link Digest</h1>
 
-      <form onSubmit={submit} className="flex gap-2">
+      <form onSubmit={onSubmit} className="flex gap-2">
         <input
           type="url"
           required
@@ -92,34 +79,33 @@ export function App() {
           placeholder="https://example.com/article"
           className="flex-1 rounded-md border px-3 py-2"
         />
-        <button type="submit" disabled={polling} className="rounded-md border px-4 py-2">
-          {polling ? "Working…" : "Digest"}
+        <button type="submit" disabled={pending} className="rounded-md border px-4 py-2">
+          {pending ? "Working…" : "Digest"}
         </button>
       </form>
 
       {error !== undefined && <p className="text-red-600">{error}</p>}
 
-      {/* A run that has not settled says so. `polling` is not derivable from the
+      {/* A run that has not settled says so. `pending` is not derivable from the
           snapshot alone — an id the agent never knew leaves `run` undefined,
           which would otherwise read as "still waiting" forever. */}
-      {polling && <p>You can close this tab — the run continues without it.</p>}
-
-      {/* The run's own narration, newest line only — see the module doc.
+      {pending && <p>You can close this tab — the run continues without it.</p>}
 
-          `supported` is what keeps this from being blank forever on an agent
-          deployed before progress streams existed: "wrote nothing yet" and
-          "serves no stream" are indistinguishable from `progress` alone. */}
-      {supported && latest !== undefined && <p className="text-sm opacity-70">{latest}</p>}
+      {/* The run's own narration, newest line only. `lines={1}` is the window;
+          everything else — the replay, and the "serves no stream" case that is
+          otherwise indistinguishable from "wrote nothing yet" — belongs to the
+          component. */}
+      <WorkflowProgress runId={run?.runId} lines={1} className="text-sm opacity-70" />
 
       {/* The counterpart of the `sleep` in `workflows/digest.ts`. Without it the
           only handle on a sleeping run is `cancel`, so "file it now" and "throw
           it away" would be the same button. `wake` answering 0 means the run had
           already moved past its wait, which is why nothing here treats that as a
           failure. */}
-      {runId !== undefined && polling && (
+      {pending && (
         <button
           type="button"
-          onClick={() => void api.wake(runId)}
+          onClick={() => void wake()}
           className="self-start rounded-md border px-3 py-1 text-sm"
         >
           File it now

package/dist/templates/link-digest/workflows/digest.ts

@@ -24,8 +24,9 @@
  * fetched text crosses a queue between them, which is what the cap on it is for.
  */
 
-import { throwStepError, toStepError } from "@alexkroman1/aai/step-errors";
-import { report, stepFetch, stepGenerateJson } from "@alexkroman1/aai/utils";
+import { report } from "@alexkroman1/aai/step";
+import { stepFetchOk, stepGenerateJsonClassified } from "@alexkroman1/aai/step-errors";
+import { decodeHtmlEntities } from "@alexkroman1/aai/utils";
 import { FatalError, sleep } from "workflow";
 import { z } from "zod";
 
@@ -120,18 +121,18 @@ export async function fetchArticle(url: string): Promise<Article> {
   // reset with no HTTP status, which `toStepError` below has nothing to read.
   // It also reports a connection failure with its whole `cause` chain instead
   // of a bare `TypeError: fetch failed`. Redirects are followed by default.
-  const response = await stepFetch(url, {
+  // `stepFetchOk` rather than `stepFetch` + an `ok` check: it makes the
+  // retryable/terminal split for us — a 404 or a 403 answers the same way on
+  // the fourth attempt, while a rate limit is exactly what retries are for, and
+  // its `Retry-After` reaches the DevKit's schedule instead of the default
+  // backoff. It also puts the server's own error text in the message.
+  const response = await stepFetchOk(url, {
     // Some sites answer a bare request with a challenge page; asking for HTML
     // at least says what we want. Nothing here defeats a real bot wall, and a
     // template pretending otherwise would be the dishonest version.
     headers: { Accept: "text/html,application/xhtml+xml" },
     signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
   });
-  // The retryable/terminal split, for the page we were pointed at: a 404 or a
-  // 403 answers the same way on the fourth attempt, while a rate limit is
-  // exactly what retries are for — and `toStepError` is what carries its
-  // `Retry-After` into the DevKit's schedule instead of the default backoff.
-  if (!response.ok) throw toStepError(response, `GET ${url} failed: HTTP ${response.status}`);
 
   const html = await response.text();
   const text = extractText(html);
@@ -159,12 +160,13 @@ export async function summarize(article: Article): Promise<Digest> {
 
   await report("Pulling out the claims worth keeping.");
 
-  // `stepGenerateJson` unwraps the fence a model puts around JSON, parses it,
-  // and validates it against `DigestReply` — and throws PLAINLY when any of
-  // those misses, which is the whole retry policy in one distinction: a model
-  // that answered with prose may answer correctly on the next attempt, where a
-  // 401 will not. `throwStepError` is what makes the 401 half terminal.
-  const parsed = await stepGenerateJson(
+  // `stepGenerateJsonClassified` unwraps the fence a model puts around JSON,
+  // parses it, and validates it against `DigestReply` — and throws PLAINLY when
+  // any of those misses, which is the whole retry policy in one distinction: a
+  // model that answered with prose may answer correctly on the next attempt,
+  // where a 401 will not. The `Classified` suffix is what makes the 401 half
+  // terminal: it is `stepGenerateJson` with `throwStepError` already applied.
+  const parsed = await stepGenerateJsonClassified(
     `Title: ${article.title}\nURL: ${article.url}\n\n${article.text}`,
     {
       schema: DigestReply,
@@ -172,7 +174,7 @@ export async function summarize(article: Article): Promise<Digest> {
         `You digest articles. Reply with JSON only: {"headline": string, "points": string[]}. ` +
         `Give exactly ${POINTS} points. No markdown fence, no preamble.`,
     },
-  ).catch(throwStepError);
+  );
 
   return {
     url: article.url,
@@ -208,7 +210,7 @@ export async function file(_digest: Digest): Promise<string> {
 /** The document's `<title>`, when it has one. */
 export function extractTitle(html: string): string | undefined {
   const title = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html)?.[1];
-  return title ? decodeEntities(title).replace(/\s+/g, " ").trim() || undefined : undefined;
+  return title ? decodeHtmlEntities(title).replace(/\s+/g, " ").trim() || undefined : undefined;
 }
 
 /**
@@ -222,7 +224,7 @@ export function extractTitle(html: string): string | undefined {
  * reader.
  */
 export function extractText(html: string): string {
-  return decodeEntities(
+  return decodeHtmlEntities(
     html
       .replace(/<(script|style|noscript|template)[^>]*>[\s\S]*?<\/\1>/gi, " ")
       .replace(/<!--[\s\S]*?-->/g, " ")
@@ -232,17 +234,3 @@ export function extractText(html: string): string {
     .trim()
     .slice(0, MAX_ARTICLE_CHARS);
 }
-
-/** The five entities that survive tag-stripping often enough to matter. */
-function decodeEntities(text: string): string {
-  return (
-    text
-      .replace(/&lt;/g, "<")
-      .replace(/&gt;/g, ">")
-      .replace(/&quot;/g, '"')
-      .replace(/&#0?39;|&apos;/g, "'")
-      .replace(/&nbsp;/g, " ")
-      // `&amp;` LAST, or `&amp;lt;` decodes twice into a `<` the page never had.
-      .replace(/&amp;/g, "&")
-  );
-}

package/dist/templates/night-owl/agent.test.ts

@@ -1,10 +1,16 @@
 /// <reference types="vite/client" />
 
 import { toAgentConfig } from "@alexkroman1/aai/manifest";
-import { createToolContext, runTool, withDiscoveredTools } from "@alexkroman1/aai/testing";
+import {
+  createToolContext,
+  parseToolInput,
+  toolInputIssues,
+  toolRunner,
+  withDiscoveredTools,
+} from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import authoredAgent from "./agent.ts";
-import { CATEGORIES, MOODS } from "./shared.ts";
+import { CATEGORIES, MOODS, nightProjection, nightSlot } from "./shared.ts";
 
 /**
  * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
@@ -17,6 +23,14 @@ const agentDef = withDiscoveredTools(
   import.meta.glob("./tools/*.ts", { eager: true }),
 );
 
+/**
+ * `runTool` takes the context in the ARGUMENTS' place when a tool needs none,
+ * so `toolRunner`'s second parameter takes either — which is why it is one
+ * signature rather than an overload pair. An omitted context is a fresh one,
+ * i.e. a distinct session with an empty slot.
+ */
+const run = toolRunner(agentDef);
+
 describe("night-owl template", () => {
   test("config passes manifest validation", () => {
     // Same conversion `aai build`/`aai deploy` run.
@@ -33,22 +47,53 @@ describe("night-owl template", () => {
   test("recommend is discovered from tools/", () => {
     expect(Object.keys(agentDef.tools ?? {})).toEqual(["recommend"]);
   });
+
+  test("the projection an untouched session pushes is an empty log", () => {
+    // What `useAgentState(nightProjection)` reads before the first tool call —
+    // derived from the slot's own default rather than guessed at in the page.
+    expect(nightProjection()).toEqual({ recs: [] });
+  });
 });
 
 describe("recommend", () => {
   test("answers with picks for the category and mood asked for", async () => {
-    const ctx = createToolContext();
-    const result = await runTool(agentDef, "recommend", { category: "movie", mood: "cozy" }, ctx);
+    const result = await run("recommend", { category: "movie", mood: "cozy" });
     expect(result).toMatchObject({ category: "movie", mood: "cozy" });
     expect((result as { picks: string[] }).picks.length).toBeGreaterThan(0);
   });
 
-  test("pushes the same picks to the client, which is what the page renders", async () => {
-    // `ctx.send` is the only reason this tool takes a context at all: the
-    // client renders the picks rather than waiting to hear them read aloud.
+  test("the picks land in the session's own log, newest first", async () => {
+    // The log is STATE, not an event stream: `syncState` pushes this projection
+    // after every tool call, so a page that reloads mid-session resumes with it
+    // rather than starting empty.
+    const ctx = createToolContext();
+    const first = await run("recommend", { category: "book", mood: "spooky" }, ctx);
+    const second = await run("recommend", { category: "music", mood: "chill" }, ctx);
+    expect(nightProjection(nightSlot.get(ctx))).toEqual({ recs: [second, first] });
+  });
+
+  test("two calls with no shared context are two sessions", async () => {
+    // The other half of the same rule, and the one that bites: an omitted
+    // context is a FRESH session, so nothing accumulates across these calls.
     const ctx = createToolContext();
-    const result = await runTool(agentDef, "recommend", { category: "book", mood: "spooky" }, ctx);
-    expect(ctx.sent).toEqual([{ event: "recommendations", data: result }]);
+    await run("recommend", { category: "book", mood: "cozy" });
+    expect(nightSlot.get(ctx).recs).toHaveLength(0);
+  });
+
+  test("the wind-down nudge is sent once, on the third pick", async () => {
+    // A moment rather than state, which is why it is a `ctx.send` the page
+    // consumes with `useEvent` and not a field on the projection: re-delivering
+    // it on every reconnect would be nagging.
+    const ctx = createToolContext();
+    await run("recommend", { category: "movie", mood: "cozy" }, ctx);
+    await run("recommend", { category: "music", mood: "cozy" }, ctx);
+    expect(ctx.sent).toEqual([]);
+    await run("recommend", { category: "book", mood: "cozy" }, ctx);
+    expect(ctx.sent).toEqual([
+      { event: "wind_down", data: "Three picks in. Want me to work out your bedtime?" },
+    ]);
+    await run("recommend", { category: "movie", mood: "chill" }, ctx);
+    expect(ctx.sent).toHaveLength(1);
   });
 
   test("every category/mood pair the schema admits has picks behind it", async () => {
@@ -58,23 +103,29 @@ describe("recommend", () => {
     // package's guide records three shipped tools having.
     for (const category of CATEGORIES) {
       for (const mood of MOODS) {
-        const result = await runTool(
-          agentDef,
-          "recommend",
-          { category, mood },
-          createToolContext(),
-        );
+        const result = await run("recommend", { category, mood });
         expect((result as { picks: string[] }).picks, `${category}/${mood}`).not.toHaveLength(0);
       }
     }
   });
 
+  test("the schema accepts a category/mood pair from the enums", async () => {
+    const parsed = await parseToolInput<{ category: string; mood: string }>(agentDef, "recommend", {
+      category: "movie",
+      mood: "cozy",
+    });
+    expect(parsed).toEqual({ category: "movie", mood: "cozy" });
+  });
+
   test("a mood outside the enum is refused by the schema", async () => {
     // The wire boundary: an LLM tool call is untyped, so the schema is the only
     // thing between a hallucinated mood and an index into `undefined`.
-    const schema = agentDef.tools?.recommend?.inputSchema;
-    if (!schema) throw new Error("recommend has no input schema");
-    const bad = await schema["~standard"].validate({ category: "movie", mood: "melancholy" });
-    expect(bad.issues).toBeDefined();
+    // `toolInputIssues` is the SDK's own ask — `~standard` is a vendor wire
+    // contract, and the detail a hand-rolled version gets wrong first is that
+    // `.validate` may be sync or async, so a missing `await` leaves `.issues`
+    // undefined and the negative test passes for the wrong reason.
+    expect(
+      await toolInputIssues(agentDef, "recommend", { category: "movie", mood: "melancholy" }),
+    ).toBeDefined();
   });
 });

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

@@ -1,7 +1,12 @@
 import { agent } from "@alexkroman1/aai";
+import { nightProjection } from "./shared.ts";
 
 export default agent({
   name: "Night Owl",
+  // The night's recommendation log, pushed to the client after every tool
+  // call. The page renders `useAgentState(nightProjection)` and keeps no copy
+  // of its own, so a reload resumes with the list intact.
+  syncState: nightProjection,
   greeting:
     "Hey there, night owl. Try asking me for a cozy movie recommendation, or tell me what time you need to wake up and I'll calculate the best time to fall asleep.",
   builtinTools: ["run_code"],

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 }));