@alexkroman1/aai-cli 8.2.1 → 9.0.1

package/dist/templates/redline/client.tsx

@@ -28,7 +28,7 @@
 
 import "@alexkroman1/aai-ui/styles.css";
 import { plural } from "@alexkroman1/aai/utils";
-import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
+import type { WorkflowInputOf, WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import {
   Form,
   type FormValues,
@@ -62,10 +62,15 @@ const WORKFLOW = "redline";
  * thing that otherwise gets half-done in three places. Blank lines go, so a
  * trailing newline is not a requirement to cover "".
  */
-export function toInput(values: FormValues): FormValues {
+export function toInput(values: FormValues): WorkflowInputOf<typeof redline> {
   const raw = typeof values.mustCover === "string" ? values.mustCover : "";
+  // The scalars ride through as the form collected them — strings from the DOM,
+  // which the WORKFLOW's schema coerces and validates server-side. Only
+  // `mustCover` is reshaped here, because no control renders a `string[]`.
+  // The assertion is on the scalars alone and is what `submitForm` exists to
+  // avoid needing anywhere a page is not doing this reshaping deliberately.
   return {
-    ...values,
+    ...(values as Omit<WorkflowInputOf<typeof redline>, "mustCover">),
     mustCover: raw
       .split("\n")
       .map((line) => line.trim())
@@ -74,7 +79,7 @@ export function toInput(values: FormValues): FormValues {
 }
 
 function RedlineDesk() {
-  const { submit, run, pending, error, reset } = useWorkflowSubmit<Redline>(WORKFLOW);
+  const { submit, run, pending, error, reset } = useWorkflowSubmit<typeof redline>(WORKFLOW);
 
   return (
     <main className="mx-auto flex max-w-2xl flex-col gap-8 p-8">

package/dist/templates/research-workflow/agent.eval.test.ts

@@ -1,5 +1,3 @@
-/// <reference types="vite/client" />
-
 // An EVAL: does this desk actually behave? Run it with `aai eval`.
 //
 // `agent.test.ts` drives the four tools against a STUBBED `ctx.workflows` and
@@ -29,14 +27,6 @@
 //
 // And what no eval here can see at all: anything below the audio boundary —
 // endpointing, barge-in, whether two sentences merged into one turn.
-import { withDiscoveredTools } from "@alexkroman1/aai/testing";
-import { installStubStepFetch } from "@alexkroman1/aai/testing/vitest";
-import type { EvalToolCall, EvalWorkflows } from "@alexkroman1/aai-runtime/eval";
-import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
-import { expect } from "vitest";
-import { z } from "zod";
-import authoredAgent from "./agent.ts";
-import { research } from "./shared.ts";
 
 /**
  * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
@@ -50,10 +40,13 @@ import { research } from "./shared.ts";
  * The glob is written here rather than reached for from a shared helper because
  * this file SHIPS — see `agent.test.ts`.
  */
-const agentDef = withDiscoveredTools(
-  authoredAgent,
-  import.meta.glob("./tools/*.ts", { eager: true }),
-);
+import agentDef from "virtual:aai/agent";
+import { installStubStepFetch } from "@alexkroman1/aai/testing/vitest";
+import type { EvalToolCall, EvalWorkflows } from "@alexkroman1/aai-runtime/eval";
+import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
+import { expect } from "vitest";
+import { z } from "zod";
+import { research } from "./shared.ts";
 
 /**
  * The key the run's steps read with `requireStepEnv`.

package/dist/templates/research-workflow/agent.test.ts

@@ -28,14 +28,12 @@ import {
   type StubGatewayCall,
   schemaInputIssues,
   toolRunner,
-  withDiscoveredTools,
 } from "@alexkroman1/aai/testing";
 import { mockWorkflows, installStubGateway as stubGateway } from "@alexkroman1/aai/testing/vitest";
 import { visitWebpage, webSearch } from "@alexkroman1/aai/tools";
 import type { WorkflowRunSnapshot } from "@alexkroman1/aai/workflow-api";
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import { FatalError, RetryableError } from "workflow";
-import authoredAgent from "./agent.ts";
 import { research } from "./shared.ts";
 import {
   countSources,
@@ -63,18 +61,8 @@ vi.mock("@alexkroman1/aai/tools", () => ({
   visitWebpage: vi.fn(async () => ({ content: "The page body." })),
 }));
 
-/**
- * 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: it is what a scaffolded project runs, so it may not import
- * anything outside its own template, and `import.meta.glob` is expanded against
- * the file containing it either way. This is the pattern a user writes.
- */
-const agentDef = withDiscoveredTools(
-  authoredAgent,
-  import.meta.glob("./tools/*.ts", { eager: true }),
-);
+/** The def a DEPLOYED agent runs: authored, plus what `tools/` declares. */
+import agentDef from "virtual:aai/agent";
 
 /**
  * Every tool here is driven through the agent's own table, by the name the model
@@ -404,7 +392,7 @@ describe("the steps that research", () => {
 
     const note = await investigate(brief, "Tool use");
 
-    expect(webSearch).toHaveBeenCalledWith({ query: "otter tool use", max_results: 5 });
+    expect(webSearch).toHaveBeenCalledWith({ query: "otter tool use", maxResults: 5 });
     expect(visitWebpage).toHaveBeenCalledWith("https://otters.example/tools");
     expect(note.findings).toContain("crack shellfish");
     expect(note.sources).toEqual([{ title: "Otters", url: "https://otters.example/tools" }]);

package/dist/templates/research-workflow/agent.ts

@@ -69,11 +69,13 @@
  * thing that changes under `aai dev` (the key has to be in `.env`, not just your
  * shell).
  *
- * Storage is what makes it DURABLE (`aai storage enable`, Settings → Database
- * in the studio, or `DATABASE_URL` under `aai dev`) — runs and the key index
- * both live there. Without it both live in the process, so a run in flight is
- * lost when the agent restarts, redeploys or goes idle; everything below still
- * works, which is what lets you try it before provisioning anything.
+ * Runs are DURABLE on the platform with nothing to configure — they live on the
+ * platform's own database and survive a restart, a redeploy and an idle sandbox.
+ *
+ * A `DATABASE_URL` you supply (a secret when deployed, `.env` under `aai dev`)
+ * buys the key index, which is what lets `find()` resolve a run by key across a
+ * restart. Under `aai dev` with none, the runs go with the process too —
+ * everything below still works, which is what lets you try it first.
  */
 
 import { agent } from "@alexkroman1/aai";

package/dist/templates/research-workflow/workflows/research.ts

@@ -65,7 +65,13 @@ import {
   RESEARCH_SYSTEM,
 } from "./prompts.ts";
 
-/** Angles investigated at once. The far side of every one is a rate limit. */
+/**
+ * Angles investigated at once. The far side of every one is a rate limit.
+ *
+ * Inside the workflow world's default worker concurrency (three on the
+ * `DATABASE_URL` path), so this width is what really runs — see "The WINDOW is
+ * not the concurrency" in `mapConcurrent`.
+ */
 const ANGLE_CONCURRENCY = 2;
 
 /**
@@ -424,7 +430,7 @@ async function search(query: string): Promise<{ summary: string; sources: Source
   try {
     const results = await webSearch<{ results?: { title?: string; url?: string }[] }>({
       query,
-      max_results: SEARCH_RESULTS,
+      maxResults: SEARCH_RESULTS,
     });
     // The `catch` below was written for exactly this and could not reach it:
     // `webSearch` ANSWERS with `{ error }` rather than throwing, so a refused

package/dist/templates/retail/agent.eval.test.ts

@@ -1,8 +1,14 @@
-/// <reference types="vite/client" />
-
-import { withSystemPrompt } from "@alexkroman1/aai/manifest";
+/**
+ * The def a DEPLOYED agent runs: authored, plus what `tools/` declares, plus
+ * what `system-prompt.md` says.
+ *
+ * Driving the raw default export instead would measure a seventeen-tool desk
+ * with no tools and the FRAMEWORK DEFAULT prompt — and for this template that
+ * is the whole subject: the authenticate-first discipline, the three-step
+ * readback and the one-customer-per-call rule all live in that file.
+ */
+import retailAgent from "virtual:aai/agent";
 import type { SessionEvent } from "@alexkroman1/aai/protocol";
-import { withDiscoveredTools } from "@alexkroman1/aai/testing";
 // An EVAL: does this desk actually behave? Run it with `aai eval`.
 //
 // `agent.test.ts` drives each tool directly and asserts about its result;
@@ -29,27 +35,6 @@ import { type EvalSession, type EvalTurn, lastStateIn } from "@alexkroman1/aai-r
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
 import { z } from "zod";
-import authoredAgent from "./agent.ts";
-import systemPrompt from "./system-prompt.md?raw";
-
-/**
- * The def a DEPLOYED agent runs: authored, plus what `tools/` declares, plus
- * what `system-prompt.md` says.
- *
- * BOTH wrappers are load-bearing and neither is applied by `agent()` — they are
- * applied by the BUILD (`aai build` enumerates `tools/` and resolves the prompt
- * file), so an eval driving the raw default export would measure a
- * seventeen-tool desk with no tools and the FRAMEWORK DEFAULT prompt. For this
- * template that is the whole subject: the authenticate-first discipline, the
- * three-step readback and the one-customer-per-call rule are all in that file.
- *
- * The glob is written here rather than reached for from a shared helper because
- * this file SHIPS — see `registry.test.ts`.
- */
-const retailAgent = withSystemPrompt(
-  withDiscoveredTools(authoredAgent, import.meta.glob("./tools/*.ts", { eager: true })),
-  systemPrompt,
-);
 
 /** Harper Brown: exactly ONE pending order, which is what makes "cancel my
  *  pending order" unambiguous — `resolveOrder` refuses a reference that matches

package/dist/templates/retail/registry.test.ts

@@ -1,9 +1,6 @@
-/// <reference types="vite/client" />
-
 import { isToolFailure, type ToolContext } from "@alexkroman1/aai";
-import { createToolContext, withDiscoveredTools } from "@alexkroman1/aai/testing";
+import { createToolContext, deployedAgent } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
-import authoredAgent from "./agent.ts";
 import { callFlow, retailSlot } from "./store.ts";
 
 /** Tools that legitimately run before the caller is identified — the six
@@ -20,17 +17,23 @@ const PUBLIC_TOOLS = new Set([
 ]);
 
 /**
- * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
+ * The def a DEPLOYED agent runs, lowered BY HAND — the one place in the
+ * templates that still does.
  *
- * The glob is written HERE rather than reached for from a shared helper because
- * this file SHIPS: it is what a scaffolded project runs, so it may not import
- * anything outside its own template, and `import.meta.glob` is expanded against
- * the file containing it either way. This is the pattern a user writes.
+ * `virtual:aai/agent` is what every other spec imports and what a user should
+ * reach for. This file is the exception on purpose: its whole subject is the
+ * tool REGISTRY, so doing the discovery explicitly is the thing under test
+ * rather than setup around it. It is also the worked example for a project
+ * whose runner is not vitest, and so cannot register the plugin.
  */
-const retailAgent = withDiscoveredTools(
-  authoredAgent,
-  import.meta.glob("./tools/*.ts", { eager: true }),
-);
+import authoredAgent from "./agent.ts";
+import systemPrompt from "./system-prompt.md?raw";
+
+const retailAgent = deployedAgent(authoredAgent, {
+  tools: import.meta.glob("./tools/*.ts", { eager: true }),
+  systemPrompt,
+});
+
 const registry = Object.entries(retailAgent.tools);
 
 // `createToolContext()` rather than a cast: it carries a real slot store (the

package/dist/templates/solo-rpg/agent.eval.test.ts

@@ -1,5 +1,3 @@
-/// <reference types="vite/client" />
-
 // An EVAL: does the story machine actually hold? Run it with `aai eval`.
 //
 // `agent.test.ts` drives each tool directly against a context it made itself,
@@ -25,15 +23,6 @@
 // What no eval here can see: anything below the audio boundary — endpointing,
 // barge-in, a sentence split across two turns. Those need real paced audio.
 
-import { withSystemPrompt } from "@alexkroman1/aai/manifest";
-import { withDiscoveredTools } from "@alexkroman1/aai/testing";
-import { type EvalTurn, toolResultIn } from "@alexkroman1/aai-runtime/eval";
-import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
-import { expect } from "vitest";
-import { z } from "zod";
-import authoredAgent from "./agent.ts";
-import systemPrompt from "./system-prompt.md?raw";
-
 /**
  * The def a DEPLOYED agent runs, assembled the way the build assembles it: the
  * authored export, plus what `tools/` declares, plus `system-prompt.md`.
@@ -43,10 +32,11 @@ import systemPrompt from "./system-prompt.md?raw";
  * eval run against the framework default prompt would measure an agent nobody
  * deployed.
  */
-const agentDef = withSystemPrompt(
-  withDiscoveredTools(authoredAgent, import.meta.glob("./tools/*.ts", { eager: true })),
-  systemPrompt,
-);
+import agentDef from "virtual:aai/agent";
+import { type EvalTurn, toolResultIn } from "@alexkroman1/aai-runtime/eval";
+import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
+import { expect } from "vitest";
+import { z } from "zod";
 
 /**
  * What each tool this file drives answers, off the wire.

package/dist/templates/solo-rpg/agent.test.ts

@@ -1,4 +1,4 @@
-import type { Db, ToolContext, ToolDef, ToolInputSchema } from "@alexkroman1/aai";
+import type { ToolContext, ToolDef, ToolInputSchema } from "@alexkroman1/aai";
 import { isToolFailure } from "@alexkroman1/aai";
 import { createToolContext, ok } from "@alexkroman1/aai/testing";
 import { describe, expect, test, vi } from "vitest";
@@ -18,44 +18,17 @@ import {
 import actionRoll from "./tools/action_roll.ts";
 import burnMomentum from "./tools/burn_momentum.ts";
 import checkState from "./tools/check_state.ts";
-import loadGame from "./tools/load_game.ts";
 import oracle from "./tools/oracle.ts";
-import saveGame from "./tools/save_game.ts";
 import setupCharacter from "./tools/setup_character.ts";
 import updateState from "./tools/update_state.ts";
 
 // ── Test doubles ─────────────────────────────────────────────────────────────
 
-/**
- * Map-backed fake of the app database, implementing exactly the three SQL
- * statements the shared save-slot helpers emit (create table / select /
- * upsert). Values are stored parsed, the way a postgres driver returns jsonb.
- */
-function makeDb(): { db: Db; rows: Map<string, unknown> } {
-  const rows = new Map<string, unknown>();
-  const db: Db = {
-    async query<T>(sql: string, params: unknown[] = []): Promise<T[]> {
-      if (sql.startsWith("create table if not exists app_state")) return [];
-      if (sql.startsWith("select value from app_state")) {
-        const key = params[0] as string;
-        return rows.has(key) ? ([{ value: structuredClone(rows.get(key)) }] as T[]) : [];
-      }
-      if (sql.startsWith("insert into app_state")) {
-        const [key, json] = params as [string, string];
-        rows.set(key, JSON.parse(json)); // $2::jsonb — parsed like postgres would
-        return [];
-      }
-      throw new Error(`unexpected SQL in test: ${sql}`);
-    },
-  };
-  return { db, rows };
-}
-
 /** `send` is a spy rather than the recorder `createToolContext` installs,
  *  because this suite asserts call counts on it. Each call gets its own slot
  *  store, which is what makes two contexts two games. */
-function makeCtx(db: Db = makeDb().db): ToolContext {
-  return createToolContext({ db, send: vi.fn() });
+function makeCtx(): ToolContext {
+  return createToolContext({ send: vi.fn() });
 }
 
 const SETUP_ARGS = {
@@ -588,65 +561,13 @@ describe("update_state", () => {
     expect(
       params.parse({ addClockSegments: 6, updateNpcBond: 4, timeOfDay: "night" }),
     ).toBeTruthy();
-
-    const slotParams = saveGame.inputSchema!;
-    expect(() => slotParams.parse({ slot: "../../etc" })).toThrow();
-    expect(() => slotParams.parse({ slot: "a".repeat(40) })).toThrow();
-    expect(slotParams.parse({ slot: "chapter-2" })).toBeTruthy();
   });
 });
 
-// ── save_game / load_game: cross-session persistence via ctx.db ──────────────
-
-describe("save_game / load_game", () => {
-  test("a save made in one session loads in a later session", async () => {
-    const { db, rows } = makeDb();
-
-    // Session A plays and saves.
-    const sessionA = makeCtx(db);
-    const played = playingState();
-    played.playerName = "Kael";
-    played.sceneCount = 7;
-    seedPlaying(sessionA, played);
-    const saved = ok<{ saved: boolean; slot: string }>(
-      await saveGame.execute({ slot: "chapter-2" }, sessionA),
-    );
-    expect(saved.saved).toBe(true);
-    expect(saved.slot).toBe("chapter-2");
-    expect(rows.get("save:chapter-2")).toMatchObject({ playerName: "Kael", sceneCount: 7 });
-
-    // Session B (a fresh game slot, the same app db) resumes it.
-    const sessionB = makeCtx(db);
-    // `load_game` is a plain `tool()`, so its result is the union its body
-    // writes rather than a position envelope — the guard is what picks the
-    // arm, where the old `as Record<string, unknown>` picked neither.
-    const loaded = await loadGame.execute({ slot: "chapter-2" }, sessionB);
-    if (isToolFailure(loaded)) throw new Error(`load refused: ${loaded.error}`);
-    expect(loaded.loaded).toBe(true);
-    expect(loaded.playerName).toBe("Kael");
-    expect(loaded.sceneCount).toBe(7);
-    expect(gameSlot.get(sessionB).playerName).toBe("Kael");
-  });
-
-  test("loading a missing slot reports an error instead of resetting the game", async () => {
-    const ctx = makeCtx();
-    const result = await loadGame.execute({ slot: "nope" }, ctx);
-    expect(isToolFailure(result) && result.error).toMatch(/No save found/);
-  });
-
-  test("saving twice to one slot upserts — the newer save wins", async () => {
-    const { db, rows } = makeDb();
-    const ctx = makeCtx(db);
-    seedPlaying(ctx);
-    await saveGame.execute({}, ctx); // autosave
-    gameSlot.update(ctx, (game) => {
-      game.sceneCount = 9;
-    });
-    await saveGame.execute({}, ctx);
-    expect(rows.size).toBe(1);
-    expect(rows.get("save:autosave")).toMatchObject({ sceneCount: 9 });
-  });
-});
+// A `save_game / load_game` suite stood here, driving cross-session persistence
+// through a map-backed fake of `ctx.db`. Both tools are gone: `ctx.db` is gone,
+// and a shipped template cannot reach a database (see `shared.ts`). This
+// adventure is single-session now.
 
 // ── the story flow ───────────────────────────────────────────────────────────
 
@@ -655,10 +576,11 @@ describe("the story flow", () => {
     const ctx = makeCtx();
     expect(storyFlow.position(ctx).state).toBe("awaitingSetup");
 
-    // All three of these used to RUN before a character existed: `action_roll`
-    // rolled 2d6 against the stats of nobody and applied consequences to a game
-    // that was not there, and `save_game` wrote an empty campaign to a slot
-    // `load_game` would later restore over a real one.
+    // All of these used to RUN before a character existed: `action_roll` rolled
+    // 2d6 against the stats of nobody and applied consequences to a game that was
+    // not there. (`save_game` was in this list too, writing an empty campaign to a
+    // slot `load_game` would later restore over a real one — both are gone with
+    // `ctx.db`.)
     for (const call of [
       actionRoll.execute(
         { move: "clash", stat: "iron", position: "risky", effect: "standard", purpose: "swing" },
@@ -666,7 +588,6 @@ describe("the story flow", () => {
       ),
       updateState.execute({ location: "Nowhere" }, ctx),
       callNoArgs(burnMomentum, ctx),
-      saveGame.execute({}, ctx),
     ]) {
       const refusal = await call;
       expect(isToolFailure(refusal)).toBe(true);
@@ -740,37 +661,9 @@ describe("the story flow", () => {
     expect(restarted.state).toBe("playing.awaitingRoll");
   });
 
-  test("a loaded game resumes in play rather than awaiting setup", async () => {
-    const { db } = makeDb();
-    const sessionA = makeCtx(db);
-    seedPlaying(sessionA);
-    ok(await saveGame.execute({ slot: "resume" }, sessionA));
-
-    const sessionB = makeCtx(db);
-    expect(storyFlow.position(sessionB).state).toBe("awaitingSetup");
-    const loaded = await loadGame.execute({ slot: "resume" }, sessionB);
-    if (isToolFailure(loaded)) throw new Error(`load refused: ${loaded.error}`);
-    expect(loaded.state).toBe("playing.awaitingRoll");
-
-    // And the play tools are available in the resumed session.
-    ok(await updateState.execute({ location: "Back at the Docks" }, sessionB));
-  });
-
-  test("a save whose game was over resumes as over", async () => {
-    const { db } = makeDb();
-    const sessionA = makeCtx(db);
-    const dead = playingState();
-    dead.health = 0;
-    dead.spirit = 0;
-    dead.gameOver = true;
-    dead.crisisMode = true;
-    seedPlaying(sessionA, dead);
-    ok(await saveGame.execute({ slot: "ended" }, sessionA));
-
-    const sessionB = makeCtx(db);
-    const loaded = await loadGame.execute({ slot: "ended" }, sessionB);
-    if (isToolFailure(loaded)) throw new Error(`load refused: ${loaded.error}`);
-    expect(loaded.state).toBe("gameOver");
-    expect(storyFlow.position(sessionB).done).toBe(true);
-  });
+  // Two resume tests stood here — a saved game reopening in play, and one saved
+  // after the ending reopening as over. Both drove `save_game`/`load_game`, which
+  // are gone with `ctx.db`. What they proved about the FLOW (a resumed position is
+  // restored rather than recomputed) has no path left to exercise it: a session
+  // is the whole life of a game now.
 });

package/dist/templates/solo-rpg/shared.ts

@@ -1,5 +1,4 @@
-import { type DeepReadonly, dialog, sessionSlot, type ToolContext } from "@alexkroman1/aai";
-import { z } from "zod";
+import { type DeepReadonly, dialog, sessionSlot } from "@alexkroman1/aai";
 
 // ── Tuning Constants ─────────────────────────────────────────────────────────
 export const MAX_SESSION_LOG = 50;
@@ -390,7 +389,7 @@ export const gameProjection = gameSlot.projection((game) => game);
  * `storyFlow.reset` — and it is what lets `gameOver` be a genuinely `final`
  * state, which is the whole point of having one: `position().done` means the
  * story ended, and XState delivers no events to a done actor, so an `on: {
- * SETUP }` there would have been dead config that looked live. `load_game`
+ * SETUP }` there would have been dead config that looked live. A resumed run
  * resets for the same reason. `SETUP` therefore appears once, on the only state
  * that can be transitioned out of.
  */
@@ -450,65 +449,18 @@ export const storyFlow = dialog("story", storySpec);
  */
 export type FrozenGameState = DeepReadonly<GameState>;
 
-// ── Persistent save slots (ctx.db) ───────────────────────────────────────────
-// save_game / load_game are genuine cross-session persistence, so they use
-// the app's SQL database. Requires storage: `aai storage enable` (or
-// Settings → Database in the studio); under `aai dev`, set DATABASE_URL in .env.
+// ── No cross-session saves, and why ─────────────────────────────────────────
+// `save_game` / `load_game` stood here, keyed by slot name and backed by an
+// `app_state` table through `ctx.db`. Both are gone with `ctx.db` itself: the
+// platform provides tool code no database, and a template cannot reach one — the
+// scaffold ships no Postgres client, and shipped template code cannot import
+// `@alexkroman1/aai-runtime` (templates type-check under the scaffold tsconfig,
+// which that package's source is not clean under).
 //
-// Slots are keyed by name alone — the whole point of a save is loading it in
-// a LATER session, whose sessionId differs, so the key can't embed one. The
-// storage is per app, so every player of one deployment shares the slot
-// namespace; without player identity that is the price of resumability.
-export function saveSlotKey(slot?: string): string {
-  return `save:${slot ?? "autosave"}`;
-}
-
-/** The slot-name grammar, shared by save_game and load_game so a name that
- *  can be saved can always be loaded. */
-export const saveSlotParam = z
-  .string()
-  .regex(/^[A-Za-z0-9_-]{1,32}$/, "letters, digits, dashes, underscores; max 32 chars")
-  .describe("Save slot name, defaults to autosave")
-  .optional();
-
-const ENSURE_APP_STATE = `create table if not exists app_state (
-  key text primary key,
-  value jsonb not null,
-  updated_at timestamptz not null default now()
-)`;
-
-// Memoized per process (each session's tools run in a fresh sandbox, so this
-// is at most one round-trip per session); a failure clears the memo so the
-// next call retries instead of caching the error forever.
-let ensureP: Promise<unknown> | null = null;
-function ensureTable(ctx: ToolContext): Promise<unknown> {
-  ensureP ??= ctx.db.query(ENSURE_APP_STATE).catch((err) => {
-    ensureP = null;
-    throw err;
-  });
-  return ensureP;
-}
-
-/** Read one saved value. jsonb columns come back from the postgres driver
- *  already parsed, so the value needs no JSON.parse here. */
-export async function loadState<T>(ctx: ToolContext, key: string): Promise<T | null> {
-  await ensureTable(ctx);
-  const rows = await ctx.db.query<{ value: T }>("select value from app_state where key = $1", [
-    key,
-  ]);
-  return rows[0]?.value ?? null;
-}
-
-/** Upsert one value. Serialized explicitly and cast with `::jsonb` so the
- *  write is driver-agnostic about object parameters. */
-export async function saveState(ctx: ToolContext, key: string, value: unknown): Promise<void> {
-  await ensureTable(ctx);
-  await ctx.db.query(
-    "insert into app_state (key, value, updated_at) values ($1, $2::jsonb, now()) " +
-      "on conflict (key) do update set value = excluded.value, updated_at = now()",
-    [key, JSON.stringify(value)],
-  );
-}
+// So this adventure is SINGLE-SESSION: everything lives in `sessionSlot`s and
+// ends when the call does. An author who wants saves adds a client of their own
+// (`postgres`, `pg`, a provider SDK) and a `DATABASE_URL` secret — which is the
+// supported pattern, just not one a shipped template can demonstrate.
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 export function d(sides: number): number {

package/dist/templates/spoken-summary/agent.test.ts

@@ -54,7 +54,6 @@ describe("the declaration", () => {
     // The page calls `api.start("spokenSummary", …)`, so a rename here is a
     // runtime 400 rather than a compile error. This is what pins it.
     expect(Object.keys(agentDef.workflows ?? {})).toEqual(["spokenSummary"]);
-    expect(agentDef.page).toBe("static");
   });
 
   test("declares no providers and exactly the one credential its steps read", () => {

package/dist/templates/spoken-summary/agent.ts

@@ -41,10 +41,11 @@
  *   three services this uses: transcription, the LLM Gateway, and the voice.
  *   `requiredEnv` below is what makes a deploy check for it rather than letting
  *   the first run find out.
- * - **Storage** (`aai storage enable`, Settings → Database in the studio, or
- *   `DATABASE_URL` under `aai dev`). REQUIRED here, and more so than for most
- *   workflow apps: an upload's record is a row, and this app uses uploads at
- *   BOTH ends — the recording coming in and the summary going out.
+ * - **A `DATABASE_URL`** — a secret when deployed, `.env` under `aai dev`, and a
+ *   Postgres you bring since the platform provisions none. REQUIRED here, and
+ *   more so than for most workflow apps: an upload's record is a row, and this
+ *   app uses uploads at BOTH ends — the recording coming in and the summary
+ *   going out.
  *
  * ## The recording is UPLOADED, and the run carries its id
  *

package/dist/templates/spoken-summary/client.tsx

@@ -37,7 +37,6 @@ import "@alexkroman1/aai-ui/styles.css";
 // nothing — and it is what stops this file restating a shape
 // `workflows/summarize.ts` already declares.
 import { formatDuration } from "@alexkroman1/aai/utils";
-import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import {
   createWorkflowApi,
   Form,
@@ -51,9 +50,6 @@ import {
 } from "@alexkroman1/aai-ui";
 import type { spokenSummary } from "./agent.ts";
 
-/** What a completed run reports, derived from the workflow rather than restated. */
-type Summary = WorkflowOutputOf<typeof spokenSummary>;
-
 /**
  * The workflow's name, as a page starts a run by one.
  *
@@ -88,8 +84,9 @@ function captionsUrl(text: string, durationMs: number): string {
 export function App() {
   // The generic is what makes `run.status === "completed"` narrow to a TYPED
   // `run.output` instead of `unknown`.
-  const { submit, run, pending, upload, pauseUpload, resumeUpload, error } =
-    useWorkflowSubmit<Summary>(WORKFLOW, { api });
+  const { submitForm, run, pending, upload, pauseUpload, resumeUpload, error } = useWorkflowSubmit<
+    typeof spokenSummary
+  >(WORKFLOW, { api });
   const output = run?.status === "completed" ? run.output : undefined;
   // `useDownloadUrl` is the SDK's: the byte route takes the agent's bearer, so the
   // bytes have to be FETCHED and handed to the element as an object URL — and the
@@ -105,7 +102,7 @@ export function App() {
         </p>
       </header>
 
-      <Form onSubmit={submit} error={error} className="flex flex-col gap-4">
+      <Form onSubmit={submitForm} error={error} className="flex flex-col gap-4">
         {/* Every control, from the workflow's own input schema. See the module doc. */}
         <WorkflowFields workflow={WORKFLOW} />
         <SubmitButton pending={pending} pendingLabel="Working…">