@alexkroman1/aai-cli 8.2.1 → 9.0.0

package/dist/templates/briefing-desk/shared.ts

@@ -45,11 +45,11 @@ export const MAX_RESEARCH_STEPS = 6;
  * "Finish with a summary" is not politeness. The parent gets the subagent's
  * FINAL message, so a run that ends by saying "Done." has thrown away
  * everything it read and no budget recovers it — this is the failure mode the
- * `SubagentDef.instructions` contract warns about, stated once, here.
+ * `SubagentDef.systemPrompt` contract warns about, stated once, here.
  */
 export const researcher = subagent({
   name: "researcher",
-  instructions: [
+  systemPrompt: [
     "You are a research agent working one angle of a briefing.",
     "",
     "Search, then open the two or three most promising pages and read them.",
@@ -77,7 +77,7 @@ export const researcher = subagent({
  */
 export const factChecker = subagent({
   name: "fact-checker",
-  instructions: [
+  systemPrompt: [
     "You check ONE claim against what you can find on the web.",
     "",
     "Search for it. Answer in one sentence, starting with one of",

package/dist/templates/call-audit/agent.eval.test.ts

@@ -101,7 +101,14 @@ const describeWorkflowEvalWithFfmpeg: typeof describeWorkflowEval = (agent, defi
   if ((process.env.AAI_REQUIRE_FFMPEG ?? "") !== "") {
     throw new Error(`AAI_REQUIRE_FFMPEG is set but no ffmpeg was found.\n${HOW_TO}`);
   }
-  console.warn(`\n[skipped: no ffmpeg] ${agent.name} eval not run.\n${HOW_TO}\n`);
+  // A direct stderr write, not `console.warn`: vitest intercepts `console`, and
+  // which reporter it hands the capture to is chosen for you — unset
+  // `reporters` resolves to vitest's AGENT reporter when it detects one, and
+  // that reporter prints a passing file's output nowhere. A skip passes. So the
+  // announcement that keeps this skip from being silent was dropped for exactly
+  // the reader most likely to miss it. `announceEvalMode` in the SDK carries the
+  // measurement.
+  process.stderr.write(`\n[skipped: no ffmpeg] ${agent.name} eval not run.\n${HOW_TO}\n`);
   skipSuite(agent.name, () => {
     // Named `test`, not aliased: Biome's `noMisplacedAssertion` matches the
     // CALLEE IDENTIFIER, so an `expect` inside a `vitestTest(…)` is an error.

package/dist/templates/call-audit/agent.test.ts

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

package/dist/templates/call-audit/agent.ts

@@ -57,9 +57,10 @@
  *   `aai secret put ASSEMBLYAI_API_KEY` once deployed. `requiredEnv` below is what
  *   makes a deploy check for it rather than letting the first run find out. One key
  *   covers transcription, the model and the voice alike.
- * - **Storage** (`aai storage enable`, Settings → Database in the studio, or
- *   `DATABASE_URL` under `aai dev`). REQUIRED, unlike most workflow apps: an
- *   upload's record is a row, and this desk both reads an upload and writes two.
+ * - **A `DATABASE_URL`** — a secret when deployed, `.env` under `aai dev`, and a
+ *   Postgres you bring since the platform provisions none. REQUIRED, unlike most
+ *   workflow apps: an upload's record is a row, and this desk both reads an
+ *   upload and writes two.
  * - **ffmpeg** — every deployed guest's image installs it (and `ffprobe` with it).
  *   Under `aai dev` it is whatever is on `PATH`, or what `AAI_FFMPEG_PATH` /
  *   `AAI_FFPROBE_PATH` name. That is the one place dev/prod parity is partial, so

package/dist/templates/call-audit/client.tsx

@@ -29,7 +29,6 @@ import "@alexkroman1/aai-ui/styles.css";
 // nothing — and it is what stops this file restating a shape `workflows/audit.ts`
 // already declares.
 import { formatBytes, formatDuration } from "@alexkroman1/aai/utils";
-import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import {
   createWorkflowApi,
   Form,
@@ -43,9 +42,6 @@ import {
 } from "@alexkroman1/aai-ui";
 import type { audit } from "./agent.ts";
 
-/** What a completed run reports, derived from the workflow rather than restated. */
-type Audit = WorkflowOutputOf<typeof audit>;
-
 /**
  * The workflow's name, as a page starts a run by one.
  *
@@ -91,8 +87,9 @@ function Findings({ title, items }: { title: string; items: 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<Audit>(WORKFLOW, { api });
+  const { submitForm, run, pending, upload, pauseUpload, resumeUpload, error } = useWorkflowSubmit<
+    typeof audit
+  >(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
@@ -109,7 +106,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="Auditing…">

package/dist/templates/call-audit/workflows/audit.ts

@@ -78,7 +78,16 @@ import { transcribeSpan } from "./sync-api.ts";
  * template measured as the point where the endpoint starts returning `503`s. So
  * the byte bound never binds and what is left is the endpoint's own knee, which it
  * measured at 32. Its `BYTES_IN_FLIGHT` and `MAX_SEGMENT_CONCURRENCY` docs carry
- * both measurements; this is the one number that survives them.
+ * both measurements; this is the one number that survives them. *
+ * **What EXECUTES at this width is the world's call, not this number's.**
+ * `mapConcurrent` bounds how many step calls the body has in flight; how many
+ * run at once is the workflow world's worker concurrency, which on the
+ * `DATABASE_URL` path defaults to three — so on a default deployment a width
+ * above three is inert while still costing a queued job per item. That makes
+ * this the FAR SIDE's knee and the width to use once an operator has raised
+ * the ceiling, not a promise about a stock deployment. See "The WINDOW is not
+ * the concurrency" in `@alexkroman1/aai/step`'s `mapConcurrent`; the numbers
+ * above were measured against the endpoint and say nothing about that layer.
  */
 export const SEGMENT_CONCURRENCY = 32;
 

package/dist/templates/code-interpreter/agent.eval.test.ts

@@ -19,19 +19,14 @@
 // model-written JavaScript in the host process. That is right, and it left this
 // template's whole subject assertable as a CALL and never as an answer: a
 // `toBeDefined()` on the result is satisfied by the refusal itself. So the suite
-// passes `runCode` (below) — a developer's own machine may, a deployment may
-// not — and every case here asserts BOTH halves: that Coda reached for code, and
-// what the code came back with.
-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";
+// passes `createVmRunCode()` — a developer's own machine may evaluate generated
+// code, a deployment may not — and every case here asserts BOTH halves: that
+// Coda reached for code, and what the code came back with.
+
+import agentDef from "virtual:aai/agent";
+import { createVmRunCode, toolResultsIn } 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);
 
 /** The code every `run_code` call in this turn carried, joined. */
 const codeIn = (turn: { toolCalls: readonly { name: string; args: Record<string, unknown> }[] }) =>
@@ -45,37 +40,13 @@ const codeIn = (turn: { toolCalls: readonly { name: string; args: Record<string,
  *
  * 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.
+ * the code it carried, and never what the code came back with.
+ * `createVmRunCode()` is a `node:vm` context with a capturing `console.log`,
+ * which 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.
  */
-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");
+const runCode = createVmRunCode();
 
 describeEval(
   agentDef,
@@ -97,7 +68,7 @@ describeEval(
         // none, `run_code` answers "only available in the sandboxed runtime", so
         // every claim above passes for an agent that then does the sum in its
         // head — which is the exact regression the CRITICAL RULE exists to stop.
-        const output = outputIn(turn);
+        const output = toolResultsIn(turn.toolCalls, "run_code").join("\n");
         expect(output, `run_code printed: ${output}`).toContain("107823");
 
         // "Report RESULTS, never intentions": the call goes out before Coda says
@@ -129,7 +100,7 @@ describeEval(
         // Greenwich (measured: this printed "Friday"). Asserting the weekday
         // would measure the machine running the eval. The two arithmetic cases
         // in this suite have no such dependency and do assert their answers.
-        const output = outputIn(turn);
+        const output = toolResultsIn(turn.toolCalls, "run_code").join("\n");
         expect(output, `run_code printed: ${output}`).not.toMatch(
           /only available in the sandboxed runtime/,
         );

package/dist/templates/dispatch-center/agent.eval.test.ts

@@ -1,8 +1,20 @@
-/// <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.
+ *
+ * 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 twelve-tool
+ * desk with no tools and the FRAMEWORK DEFAULT prompt. For this template that
+ * is the whole subject: "location is always the first priority", the radio
+ * style and "never leave a critical incident without a resource" are all in
+ * that file.
+ *
+ * The glob is written here rather than reached for from a shared helper because
+ * this file SHIPS — it is what a scaffolded project runs.
+ */
+import dispatchAgent from "virtual:aai/agent";
 import type { SessionEvent } from "@alexkroman1/aai/protocol";
-import { withDiscoveredTools } from "@alexkroman1/aai/testing";
 // An EVAL: does the desk actually behave? Run it with `aai eval`.
 //
 // `agent.test.ts` drives each tool directly. What it cannot ask is whether the
@@ -26,28 +38,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 twelve-tool
- * desk with no tools and the FRAMEWORK DEFAULT prompt. For this template that
- * is the whole subject: "location is always the first priority", the radio
- * style and "never leave a critical incident without a resource" are all in
- * that file.
- *
- * The glob is written here rather than reached for from a shared helper because
- * this file SHIPS — it is what a scaffolded project runs.
- */
-const dispatchAgent = withSystemPrompt(
-  withDiscoveredTools(authoredAgent, import.meta.glob("./tools/*.ts", { eager: true })),
-  systemPrompt,
-);
 
 /** The six tools gated on `working` — the ones that refuse until something has
  *  been logged. Listed here so ADDING an ungated mutating tool is a deliberate

package/dist/templates/embedded-assets/agent.eval.test.ts

@@ -1,5 +1,3 @@
-/// <reference types="vite/client" />
-
 // An EVAL: does the FAQ bot actually look things up?
 //
 // `agent.test.ts` scores the search index directly, which settles what
@@ -12,16 +10,6 @@
 // SCRIPTED model (its `stubReply`) — the real session and the real tools, a
 // fake reply — which proves the wiring and says nothing about the discipline.
 
-import { withSystemPrompt } from "@alexkroman1/aai/manifest";
-import { withDiscoveredTools } from "@alexkroman1/aai/testing";
-import { 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 { faqs } from "./shared.ts";
-import systemPrompt from "./system-prompt.md?raw";
-
 /**
  * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
  *
@@ -36,10 +24,12 @@ import systemPrompt from "./system-prompt.md?raw";
  * drives it measures a different agent than the one that deploys, and every
  * tool-choice claim below then passes or fails for the wrong reason.
  */
-const agentDef = withSystemPrompt(
-  withDiscoveredTools(authoredAgent, import.meta.glob("./tools/*.ts", { eager: true })),
-  systemPrompt,
-);
+import agentDef from "virtual:aai/agent";
+import { toolResultIn } from "@alexkroman1/aai-runtime/eval";
+import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
+import { expect } from "vitest";
+import { z } from "zod";
+import { faqs } from "./shared.ts";
 
 /**
  * A knowledge-base HIT, as the model saw it — `tool.completed` carries it

package/dist/templates/embedded-assets/agent.test.ts

@@ -1,22 +1,9 @@
-/// <reference types="vite/client" />
-
-import { toolRunner, withDiscoveredTools } from "@alexkroman1/aai/testing";
+/** The def a DEPLOYED agent runs: authored, plus what `tools/` declares. */
+import agentDef from "virtual:aai/agent";
+import { toolRunner } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
-import authoredAgent from "./agent.ts";
 import { faqs, searchable } 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 `../../_discovery.ts` to import,
- * and `import.meta.glob` is expanded against the file containing it either way.
- */
-const agentDef = withDiscoveredTools(
-  authoredAgent,
-  import.meta.glob("./tools/*.ts", { eager: true }),
-);
-
 /**
  * Both tools here are stateless, so no call passes a context: `runTool` builds
  * a fresh one, which is a distinct session with empty slots — right for a tool

package/dist/templates/health-assistant/agent.eval.test.ts

@@ -1,5 +1,3 @@
-/// <reference types="vite/client" />
-
 // An EVAL: does the desk read the label, or does it remember?
 //
 // `agent.test.ts` drives both tools against a faked openFDA, which settles the
@@ -21,15 +19,6 @@
 // unreachable openFDA reads as a drug that could not be resolved, which this
 // template already refuses on).
 
-import { withSystemPrompt } from "@alexkroman1/aai/manifest";
-import { withDiscoveredTools } from "@alexkroman1/aai/testing";
-import { 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: authored, plus what `tools/` declares.
  *
@@ -44,10 +33,11 @@ import systemPrompt from "./system-prompt.md?raw";
  * drives it measures a different agent than the one that deploys, and every
  * tool-choice claim below then passes or fails for the wrong reason.
  */
-const agentDef = withSystemPrompt(
-  withDiscoveredTools(authoredAgent, import.meta.glob("./tools/*.ts", { eager: true })),
-  systemPrompt,
-);
+import agentDef from "virtual:aai/agent";
+import { toolResultIn } from "@alexkroman1/aai-runtime/eval";
+import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
+import { expect } from "vitest";
+import { z } from "zod";
 
 /** The drugs an interaction check was actually asked about, lowercased. */
 const drugsIn = (args: Record<string, unknown>): string[] =>

package/dist/templates/health-assistant/agent.test.ts

@@ -1,9 +1,6 @@
-/// <reference types="vite/client" />
-
 import { isToolFailure } from "@alexkroman1/aai";
-import { toolInputIssues, toolRunner, withDiscoveredTools } from "@alexkroman1/aai/testing";
+import { toolInputIssues, toolRunner } from "@alexkroman1/aai/testing";
 import { beforeEach, describe, expect, test, vi } from "vitest";
-import authoredAgent from "./agent.ts";
 import { excerptAround, type FdaLabel, toDrugInfo } from "./fda.ts";
 
 /**
@@ -24,16 +21,8 @@ vi.mock("./fda.ts", async (importOriginal) => ({
 const { fetchFdaLabel } = await import("./fda.ts");
 const label = vi.mocked(fetchFdaLabel);
 
-/**
- * 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 }),
-);
+/** The def a DEPLOYED agent runs: authored, plus what `tools/` declares. */
+import agentDef from "virtual:aai/agent";
 
 /**
  * Every tool here takes arguments and none of them touches session state, so no

package/dist/templates/infocom-adventure/agent.eval.test.ts

@@ -1,5 +1,3 @@
-/// <reference types="vite/client" />
-
 // An EVAL: does the game engine actually keep its world? Run it with `aai eval`.
 //
 // `agent.test.ts` drives the tools directly, one call at a time, against a
@@ -21,16 +19,6 @@
 // What no eval here can see: anything below the audio boundary — endpointing,
 // barge-in, two commands merging into one turn. 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 { DEFAULT_GAME_STATE } from "./shared.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`.
@@ -41,10 +29,12 @@ import systemPrompt from "./system-prompt.md?raw";
  * `game_state_take` — an eval run against the framework default prompt measures
  * 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";
+import { DEFAULT_GAME_STATE } from "./shared.ts";
 
 /**
  * What each of the three tools this file drives answers, off the wire.

package/dist/templates/infocom-adventure/agent.test.ts

@@ -1,21 +1,7 @@
-/// <reference types="vite/client" />
-
-import { createToolContext, toolRunner, withDiscoveredTools } from "@alexkroman1/aai/testing";
+/** The def a DEPLOYED agent runs: authored, plus what `tools/` declares. */
+import agentDef from "virtual:aai/agent";
+import { createToolContext, toolRunner } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
-import authoredAgent from "./agent.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: 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 }),
-);
 
 import { DEFAULT_GAME_STATE, gameSlot, MAX_HISTORY, REPORTED_HISTORY } from "./shared.ts";
 

package/dist/templates/link-digest/agent.test.ts

@@ -28,20 +28,6 @@ import agentDef, { digest } from "./agent.ts";
 import { extractText, extractTitle, fetchArticle, summarize } from "./workflows/digest.ts";
 
 describe("the agent declares itself a workflow app", () => {
-  test("its front door is a page, not a microphone", () => {
-    // Not decoration: `createServer` declines `/websocket` with a reason for a
-    // static agent, and telephony defaults off.
-    expect(agentDef.page).toBe("static");
-  });
-
-  test("it declares no voice pipeline and no tools, because nothing talks", () => {
-    expect(agentDef.stt).toBeUndefined();
-    expect(agentDef.llm).toBeUndefined();
-    expect(agentDef.tts).toBeUndefined();
-    expect(agentDef.s2s).toBeUndefined();
-    expect(agentDef.tools).toEqual({});
-  });
-
   test("under the name the page starts a run by", () => {
     // `api.start("digest", …)` in client.tsx names this key. Nothing else
     // records it, so a rename here is a 400 there rather than a compile error.

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

@@ -44,11 +44,15 @@
  * doc for the one 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
- * correlation-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 —
- * which is fine while you are building one.
+ * Runs are DURABLE on the platform with nothing to configure — a deployed app's
+ * runs live on the platform's own database and survive a restart, a redeploy and
+ * an idle sandbox.
+ *
+ * A `DATABASE_URL` (a secret when deployed, `.env` under `aai dev`) still buys
+ * one thing here: the correlation-key index, which is what lets `find()` resolve
+ * a run by key. Without one that index is in memory, so it is forgotten on a
+ * restart even though the runs themselves are not. Under `aai dev` with no
+ * `DATABASE_URL` the runs go too — fine while you are building.
  */
 
 import { workflow, workflowApp } from "@alexkroman1/aai";

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

@@ -42,13 +42,9 @@ 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/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>;
-
 export function App() {
   const [url, setUrl] = useState("");
   // The generic is what makes `run.status === "completed"` narrow to a TYPED
@@ -56,7 +52,7 @@ export function App() {
   // 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, run, pending, error, wake } = useWorkflowSubmit<typeof digest>("digest");
 
   // `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
@@ -76,7 +72,13 @@ export function App() {
           required
           value={url}
           onChange={(e) => setUrl(e.target.value)}
-          placeholder="https://example.com/article"
+          // A REAL article, because a placeholder is a suggestion and this one
+          // gets typed. `https://example.com/article` 404s, and the bare
+          // `example.com` a reader trims it to has no prose on it — so the first
+          // run of the template failed with the agent's own
+          // "returned no readable text — is the page rendered in JS?", which
+          // reads as the template being broken rather than the URL being empty.
+          placeholder="https://en.wikipedia.org/wiki/Speech_recognition"
           className="flex-1 rounded-md border px-3 py-2"
         />
         <button type="submit" disabled={pending} className="rounded-md border px-4 py-2">

package/dist/templates/math-buddy/agent.eval.test.ts

@@ -12,16 +12,11 @@
 // different agent; and `run_code` refuses unless the EVAL supplies an executor,
 // which this suite does — so the cases below assert the answer the code came
 // back with as well as the code the tutor wrote.
-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 agentDef from "virtual:aai/agent";
+import { createVmRunCode, toolResultsIn } 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);
 
 /** The code every `run_code` call in this turn carried, joined. */
 const codeIn = (turn: { toolCalls: readonly { name: string; args: Record<string, unknown> }[] }) =>
@@ -35,37 +30,13 @@ const codeIn = (turn: { toolCalls: readonly { name: string; args: Record<string,
  *
  * 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.
+ * the code it carried, and never what the code came back with.
+ * `createVmRunCode()` is a `node:vm` context with a capturing `console.log`,
+ * which 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.
  */
-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");
+const runCode = createVmRunCode();
 
 describeEval(
   agentDef,
@@ -84,7 +55,7 @@ describeEval(
         expect(code).toMatch(/1\.60|1\.61|0\.621|8\.04/);
         // And the factor was applied rather than merely mentioned: five miles is
         // 8.0467 km, so whatever rounding the tutor chose the answer starts 8.0.
-        const output = outputIn(turn);
+        const output = toolResultsIn(turn.toolCalls, "run_code").join("\n");
         expect(output, `run_code printed: ${output}`).toMatch(/8\.0/);
       },
       { live: true },
@@ -108,7 +79,7 @@ describeEval(
         // face of a twenty-sided die. `Math.random` in the code says the tutor
         // asked for a roll; this says it GOT one — a `run_code` that refused
         // prints a sentence with no dice in it at all.
-        const output = outputIn(turn);
+        const output = toolResultsIn(turn.toolCalls, "run_code").join("\n");
         const rolled = [...output.matchAll(/\d+/g)].map((m) => Number(m[0]));
         expect(rolled.length, `run_code printed: ${output}`).toBeGreaterThanOrEqual(3);
         for (const face of rolled) {