@alexkroman1/aai-cli 5.14.0 → 6.1.0

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

@@ -0,0 +1,248 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The durable half of the link digest: a `"use workflow"` body and its steps,
+ * and the steps really read the page and really call a model.
+ *
+ * The rules are the same ones `research-workflow/workflows/research.ts` spells out
+ * — the body is replayed from the top on every resume, so it holds no live
+ * handle and makes no undurable decision, and a step's arguments and return
+ * value cross a queue and so must be JSON-shaped and small. Read that file for
+ * the full argument, including where the API key comes from (a step is handed no
+ * `ToolContext`, so `requireStepEnv` is what makes an authenticated call
+ * possible at all). What THIS one adds is the case where NOBODY IS WAITING.
+ *
+ * A voice agent's run is started by a caller who is on the line. This one is
+ * started by a form: the page has the `runId` and the tab may be closed the
+ * instant after, which is exactly why the surface is an HTTP API over a durable
+ * run rather than a request that holds a socket open.
+ *
+ * ## Two steps, because they fail differently
+ *
+ * `fetchArticle` reaches a stranger's web server; `summarize` reaches the model.
+ * Splitting them is what makes a rate-limited model call replay the FETCH from
+ * the journal instead of hammering someone's site again — and it is why the
+ * 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 { FatalError, sleep } from "workflow";
+import { z } from "zod";
+
+/** How long the digest sits before it is filed, so the wait is visible in dev. */
+const SETTLE = "10 seconds";
+
+/**
+ * Characters of article text carried between the two steps.
+ *
+ * The cap is the pass-an-id-not-a-payload rule meeting a case where the payload
+ * IS the work: the text has to cross the queue, so it is bounded rather than
+ * trusted. 24k characters is several thousand words — past where an extra page
+ * of boilerplate changes the summary.
+ */
+const MAX_ARTICLE_CHARS = 24_000;
+
+/** Points the digest reduces a page to. */
+const POINTS = 3;
+
+/** The page fetch's deadline. HTTP has none of its own, and a hung step never ends. */
+const FETCH_TIMEOUT_MS = 30_000;
+
+/** What one digest pass produces. Small and JSON-shaped, like every step result. */
+export type Digest = {
+  url: string;
+  headline: string;
+  points: string[];
+};
+
+/**
+ * The shape the model is asked for, as something that CHECKS rather than
+ * something the compiler is told to believe.
+ *
+ * `stepGenerateJson` validates against this and throws plainly when the reply
+ * misses — which is what a retry is for, since a model that answered with prose
+ * may well obey on the next attempt. Before the SDK took the schema, this was a
+ * hand-written `isDigestShape` guard beside a hand-written fence stripper.
+ */
+const DigestReply = z.object({
+  headline: z.string().trim().min(1),
+  points: z.array(z.string()).min(1),
+});
+
+/** What the page actually said, on its way from one step to the next. */
+export type Article = {
+  url: string;
+  /** The `<title>`, or the hostname when there is none. */
+  title: string;
+  /** Readable text, capped — see {@link MAX_ARTICLE_CHARS}. */
+  text: string;
+};
+
+/**
+ * Fetch a link, summarize it, and file the result.
+ *
+ * Whatever this returns is what a completed run reports as `output` — so it is
+ * literally the page's render model, and `WorkflowOutputOf<typeof digest>` in
+ * `client.tsx` is that type, derived rather than restated.
+ */
+export async function digestFlow(input: { url: string }) {
+  "use workflow";
+
+  const article = await fetchArticle(input.url);
+  const digest = await summarize(article);
+
+  // Suspended, not blocked: the sandbox is free to exit here and the run
+  // resumes when it comes due. Nothing about the code changes if it is
+  // `"6 hours"` — which is the interesting version, and the one that makes an
+  // overnight digest a digest rather than a slow request.
+  await sleep(SETTLE);
+
+  return { ...digest, filedAt: await file(digest) };
+}
+
+/**
+ * Read the page.
+ *
+ * A step, so it runs once per successful execution and its result is journaled;
+ * a replay returns that result instead of fetching again — which matters here
+ * more than usual, because the far side is somebody else's web server.
+ */
+export async function fetchArticle(url: string): Promise<Article> {
+  "use step";
+
+  const { hostname } = new URL(url);
+  await report(`Reading ${hostname}…`);
+
+  // `stepFetch`, not `fetch`, and the rule has no exception for a step that
+  // makes only one request: the global pins nothing, so it offers h2 in ALPN
+  // and a server that takes it multiplexes every concurrent request from this
+  // process onto ONE connection — and a capacity limit then arrives as a stream
+  // 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, {
+    // 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);
+  if (text.length < 200) {
+    // Not transient: the same URL returns the same near-empty page on a retry.
+    // A JS-rendered site is the usual cause and no number of attempts fixes it.
+    // A direct `FatalError`, not `throwFatalStepError`: nothing is being
+    // classified here and there is no cause to preserve — this step has simply
+    // decided, and the helper is for the `catch` block where the linter would
+    // (rightly) want the original error kept.
+    throw new FatalError(`${hostname} returned no readable text — is the page rendered in JS?`);
+  }
+  return { url, title: extractTitle(html) ?? hostname, text };
+}
+
+/**
+ * Reduce the page to a headline and a few points.
+ *
+ * Separate from the fetch on purpose: a rate-limited model call replays the
+ * fetch from the journal rather than hitting a stranger's server again. The
+ * whole Node runtime is available here, unlike in the body.
+ */
+export async function summarize(article: Article): Promise<Digest> {
+  "use step";
+
+  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(
+    `Title: ${article.title}\nURL: ${article.url}\n\n${article.text}`,
+    {
+      schema: DigestReply,
+      system:
+        `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,
+    headline: parsed.headline,
+    points: parsed.points.slice(0, POINTS),
+  };
+}
+
+/** A rate limit — and a model that ignored the format — are both expected here. */
+summarize.maxRetries = 5;
+
+/**
+ * File the digest.
+ *
+ * Separate from `summarize` on purpose: two steps mean a crash between them
+ * replays the expensive half for free and re-issues only the cheap one.
+ * Returning the timestamp rather than reading a clock in the BODY is the same
+ * rule — a step's result is journaled and therefore stable across replays,
+ * where `Date.now()` in the body would change on every one.
+ */
+export async function file(_digest: Digest): Promise<string> {
+  "use step";
+
+  await report("Filing the digest.");
+  // A real desk would write the digest to its database here. The stub writes
+  // nothing, which is what the `_` says — and it is a stub because `ctx.db` is
+  // the half of a tool context a step still cannot reach.
+  return new Date().toISOString();
+}
+
+// ---- Pure helpers -----------------------------------------------------------
+
+/** 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;
+}
+
+/**
+ * Reduce HTML to the text a model should read.
+ *
+ * Deliberately crude, and the crudeness is the honest part: a real extractor is
+ * a readability implementation and a dependency, where this is four `replace`
+ * calls that get most of an article. What it MUST do is drop `<script>` and
+ * `<style>` CONTENT — stripping tags alone leaves a page's JavaScript in the
+ * prompt, which is both expensive and a way to smuggle instructions past the
+ * reader.
+ */
+export function extractText(html: string): string {
+  return decodeEntities(
+    html
+      .replace(/<(script|style|noscript|template)[^>]*>[\s\S]*?<\/\1>/gi, " ")
+      .replace(/<!--[\s\S]*?-->/g, " ")
+      .replace(/<[^>]+>/g, " "),
+  )
+    .replace(/\s+/g, " ")
+    .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/math-buddy/agent.ts

@@ -1,6 +1,5 @@
 import { agent } from "@alexkroman1/aai";
 import { assemblyAILlm } from "@alexkroman1/aai/llm";
-import systemPrompt from "./system-prompt.md?raw";
 
 export default agent({
   name: "Math Buddy",
@@ -10,7 +9,6 @@ export default agent({
   // and TTS stay on the AssemblyAI defaults. (The string shorthand
   // `llm: "gemini-2.5-flash-lite"` desugars to this same descriptor.)
   llm: assemblyAILlm({ model: "gemini-2.5-flash-lite" }),
-  systemPrompt,
   greeting:
     "Hey, I'm Math Buddy. Try asking me something like, what's 127 times 849, convert 5 miles to kilometers, or roll 3 twenty-sided dice.",
   builtinTools: ["run_code"],

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

@@ -0,0 +1,80 @@
+/// <reference types="vite/client" />
+
+import { toAgentConfig } from "@alexkroman1/aai/manifest";
+import { createToolContext, runTool, withDiscoveredTools } from "@alexkroman1/aai/testing";
+import { describe, expect, test } from "vitest";
+import authoredAgent from "./agent.ts";
+import { CATEGORIES, MOODS } from "./shared.ts";
+
+/**
+ * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
+ *
+ * The glob is written HERE rather than reached for from a shared helper because
+ * this file SHIPS — a scaffolded project has no repo helper to import.
+ */
+const agentDef = withDiscoveredTools(
+  authoredAgent,
+  import.meta.glob("./tools/*.ts", { eager: true }),
+);
+
+describe("night-owl template", () => {
+  test("config passes manifest validation", () => {
+    // Same conversion `aai build`/`aai deploy` run.
+    expect(() => toAgentConfig(agentDef)).not.toThrow();
+  });
+
+  test("declares run_code, which is the other half of the template", () => {
+    // The sleep-time arithmetic is the builtin's job, not a tool's — that split
+    // IS this template's subject, so a dropped builtin leaves the agent doing
+    // mental arithmetic out loud.
+    expect(agentDef.builtinTools).toContain("run_code");
+  });
+
+  test("recommend is discovered from tools/", () => {
+    expect(Object.keys(agentDef.tools ?? {})).toEqual(["recommend"]);
+  });
+});
+
+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);
+    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.
+    const ctx = createToolContext();
+    const result = await runTool(agentDef, "recommend", { category: "book", mood: "spooky" }, ctx);
+    expect(ctx.sent).toEqual([{ event: "recommendations", data: result }]);
+  });
+
+  test("every category/mood pair the schema admits has picks behind it", async () => {
+    // The table is hand-written and the schema is generated from the same two
+    // const arrays, so a category added to `shared.ts` and forgotten in the
+    // table is a `TypeError` on the first call — the exact failure this
+    // 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(),
+        );
+        expect((result as { picks: string[] }).picks, `${category}/${mood}`).not.toHaveLength(0);
+      }
+    }
+  });
+
+  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();
+  });
+});

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

@@ -1,75 +1,8 @@
-import { agent, tool } from "@alexkroman1/aai";
-import { z } from "zod";
-import { CATEGORIES, type Category, MOODS, type Mood } from "./shared.ts";
-
-const PICKS: Record<Category, Record<Mood, string[]>> = {
-  movie: {
-    chill: ["Lost in Translation", "The Grand Budapest Hotel", "Amelie"],
-    intense: ["Inception", "Interstellar", "The Dark Knight"],
-    cozy: ["When Harry Met Sally", "The Holiday", "Paddington 2"],
-    spooky: ["The Shining", "Get Out", "Hereditary"],
-    funny: ["The Big Lebowski", "Airplane!", "Superbad"],
-  },
-  music: {
-    chill: ["Khruangbin — Con Todo El Mundo", "Tycho — Dive", "Bonobo — Migration"],
-    intense: ["Radiohead — OK Computer", "Tool — Lateralus", "Deftones — White Pony"],
-    cozy: [
-      "Norah Jones — Come Away with Me",
-      "Iron & Wine — Our Endless Numbered Days",
-      "Bon Iver — For Emma, Forever Ago",
-    ],
-    spooky: [
-      "Portishead — Dummy",
-      "Massive Attack — Mezzanine",
-      "Boards of Canada — Music Has the Right to Children",
-    ],
-    funny: [
-      "Weird Al — Running with Scissors",
-      "Flight of the Conchords — S/T",
-      "Tenacious D — S/T",
-    ],
-  },
-  book: {
-    chill: ["Norwegian Wood — Murakami", "The Alchemist — Coelho", "Siddhartha — Hesse"],
-    intense: ["Blood Meridian — McCarthy", "House of Leaves — Danielewski", "Neuromancer — Gibson"],
-    cozy: [
-      "The House in the Cerulean Sea — Klune",
-      "A Man Called Ove — Backman",
-      "Anxious People — Backman",
-    ],
-    spooky: [
-      "The Haunting of Hill House — Jackson",
-      "Mexican Gothic — Moreno-Garcia",
-      "The Turn of the Screw — James",
-    ],
-    funny: ["Good Omens — Pratchett & Gaiman", "Hitchhiker's Guide — Adams", "Catch-22 — Heller"],
-  },
-};
+import { agent } from "@alexkroman1/aai";
 
 export default agent({
   name: "Night Owl",
-  systemPrompt:
-    "You are Night Owl, a cozy evening companion. You help people wind down, recommend entertainment, and share interesting facts about the night sky. Keep your tone warm and relaxed. Use short, conversational responses.\n\nUse run_code for sleep calculations:\n- Each sleep cycle is 90 minutes, plus 15 minutes to fall asleep\n- Bedtime = wake_time - (cycles * 90 + 15) minutes\n- If result is negative, add 1440 (24 hours in minutes)\n- Format as HH:MM",
   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"],
-
-  tools: {
-    recommend: tool({
-      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 = {
-          category: args.category,
-          mood: args.mood,
-          picks: PICKS[args.category][args.mood],
-        };
-        ctx.send("recommendations", result);
-        return result;
-      },
-    }),
-  },
 });

package/dist/templates/night-owl/system-prompt.md

@@ -0,0 +1,10 @@
+You are Night Owl, a cozy evening companion. You help people wind down,
+recommend entertainment, and share interesting facts about the night sky. Keep
+your tone warm and relaxed. Use short, conversational responses.
+
+Use run_code for sleep calculations:
+
+- Each sleep cycle is 90 minutes, plus 15 minutes to fall asleep
+- Bedtime = wake_time - (cycles \* 90 + 15) minutes
+- If result is negative, add 1440 (24 hours in minutes)
+- Format as HH:MM

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

@@ -0,0 +1,64 @@
+import { tool } from "@alexkroman1/aai";
+import { z } from "zod";
+import { CATEGORIES, type Category, MOODS, type Mood } from "../shared.ts";
+
+const PICKS: Record<Category, Record<Mood, string[]>> = {
+  movie: {
+    chill: ["Lost in Translation", "The Grand Budapest Hotel", "Amelie"],
+    intense: ["Inception", "Interstellar", "The Dark Knight"],
+    cozy: ["When Harry Met Sally", "The Holiday", "Paddington 2"],
+    spooky: ["The Shining", "Get Out", "Hereditary"],
+    funny: ["The Big Lebowski", "Airplane!", "Superbad"],
+  },
+  music: {
+    chill: ["Khruangbin — Con Todo El Mundo", "Tycho — Dive", "Bonobo — Migration"],
+    intense: ["Radiohead — OK Computer", "Tool — Lateralus", "Deftones — White Pony"],
+    cozy: [
+      "Norah Jones — Come Away with Me",
+      "Iron & Wine — Our Endless Numbered Days",
+      "Bon Iver — For Emma, Forever Ago",
+    ],
+    spooky: [
+      "Portishead — Dummy",
+      "Massive Attack — Mezzanine",
+      "Boards of Canada — Music Has the Right to Children",
+    ],
+    funny: [
+      "Weird Al — Running with Scissors",
+      "Flight of the Conchords — S/T",
+      "Tenacious D — S/T",
+    ],
+  },
+  book: {
+    chill: ["Norwegian Wood — Murakami", "The Alchemist — Coelho", "Siddhartha — Hesse"],
+    intense: ["Blood Meridian — McCarthy", "House of Leaves — Danielewski", "Neuromancer — Gibson"],
+    cozy: [
+      "The House in the Cerulean Sea — Klune",
+      "A Man Called Ove — Backman",
+      "Anxious People — Backman",
+    ],
+    spooky: [
+      "The Haunting of Hill House — Jackson",
+      "Mexican Gothic — Moreno-Garcia",
+      "The Turn of the Screw — James",
+    ],
+    funny: ["Good Omens — Pratchett & Gaiman", "Hitchhiker's Guide — Adams", "Catch-22 — Heller"],
+  },
+};
+
+export default tool({
+  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 = {
+      category: args.category,
+      mood: args.mood,
+      picks: PICKS[args.category][args.mood],
+    };
+    ctx.send("recommendations", result);
+    return result;
+  },
+});

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

@@ -1,9 +1,7 @@
 import { agent } from "@alexkroman1/aai";
-import systemPrompt from "./system-prompt.md?raw";
 
 export default agent({
   name: "Penny",
-  systemPrompt,
   greeting:
     "Hey, I'm Penny, your personal finance helper. Try asking me something like, what's 100 dollars in euros, what's the price of bitcoin, or help me split a 120 dollar bill four ways with 20 percent tip.",
   builtinTools: ["run_code", "fetch_json"],