@alexkroman1/aai-cli 14.0.0 → 15.1.0

package/dist/start.d.ts

@@ -0,0 +1,112 @@
+/**
+ * `aai start` — serve a BUILT agent from a plain Node process.
+ *
+ * The deployment counterpart of `aai dev`: no file watching, no Vite, no
+ * typecheck, no source evaluation. It loads the artifact `aai build` left at
+ * {@link WORKER_ARTIFACT_REL} — the same one `aai publish` uploads and the
+ * managed platform runs — so a self-hosted agent and a deployed one cannot
+ * behave differently.
+ *
+ * ## Why this is a command rather than a file in every project
+ *
+ * It used to be `scaffold/server.mjs`, ~300 lines of boot that `aai init`
+ * copied into every scaffolded project: worker load, env resolution, schema
+ * DDL, client-directory probing, error classification, listen, signal
+ * handlers. Shipping that as source made each of those a fact a USER's
+ * repository asserted, so improving any of them reached only projects
+ * scaffolded afterwards, and an existing project silently kept the old
+ * behaviour with nothing to report the drift.
+ *
+ * Every framework that solved this solved it the same way: the boot belongs to
+ * the framework and the project holds none of it. Next has `next start` and
+ * generates a `server.js` for `output: "standalone"` rather than asking anyone
+ * to write one. Nitro's default production preset is `node-server`, emitted
+ * into the build directory. The custom server is a documented opt-out, not the
+ * default everyone inherits — and here that opt-out is
+ * {@link createProjectServer}, which builds the server and binds nothing.
+ *
+ * ## Why the CLI rather than the runtime
+ *
+ * Booting a project needs three things at once: the runtime, the project's
+ * `.aai/` layout, and the prebuilt browser client. Only this package depends on
+ * all three — `aai-runtime` may not import `@alexkroman1/aai-ui`, and
+ * konsistent's `runtime-package-boundary` carries the install-weight argument
+ * for why that stays true. `client-dir.ts`'s own module doc records that this
+ * composition has always lived in an ENTRY POINT; this is that entry point,
+ * owned by the framework instead of copied into each project.
+ *
+ * The cost, stated because it is real: `npm start` needs `@alexkroman1/aai-cli`
+ * installed, so a production image carries a build toolchain it does not run.
+ * Next makes the same trade — `next` is a `dependency`, not a `devDependency` —
+ * and it is why the scaffold moves this package to `dependencies`.
+ */
+import type { AgentDef } from "@alexkroman1/aai";
+import { type AgentServer } from "@alexkroman1/aai-runtime";
+export { CLIENT_ARTIFACT_REL } from "./_artifacts.ts";
+/** The port `aai start` binds when neither an argument nor `PORT` says otherwise. */
+export declare const DEFAULT_START_PORT = 3000;
+/** Options for {@link createProjectServer} and {@link executeStart}. */
+export interface StartOptions {
+    /** Project root — the directory holding `agent.ts` and `.aai/`. */
+    cwd: string;
+    /** Port to bind. Defaults to `PORT`, then {@link DEFAULT_START_PORT}. */
+    port?: number | undefined;
+    /**
+     * Address to bind. Defaults to `HOST`, then loopback.
+     *
+     * Loopback is deliberate: this server has no request authentication of its
+     * own, so exposing it is an explicit act, and `HOST=0.0.0.0` is how a
+     * container says so. An EMPTY `HOST` means unset, not "every interface".
+     */
+    host?: string | undefined;
+}
+/**
+ * Load the built agent, or fail saying what to run.
+ *
+ * A `file:` URL rather than a relative specifier, because on Windows a bare
+ * POSIX-looking path is not a valid module specifier.
+ */
+export declare function loadBuiltAgent(cwd: string): Promise<AgentDef>;
+/**
+ * Build this project's {@link AgentServer} WITHOUT binding a socket.
+ *
+ * The seam a custom server is written against, and the one a serverless host
+ * needs: Vercel documents `export default <http.Server>` as its Node WebSocket
+ * shape and binds the socket itself, so such a host takes `AgentServer.node`
+ * and never calls `listen()`. `aai build --target vercel` emits an entry that
+ * does exactly this, so nothing host-specific is committed to a project.
+ *
+ * @example
+ * ```ts no-check
+ * // The entry `aai build --target vercel` bundles into
+ * // `.vercel/output/functions/index.func/` — `no-check` because this file
+ * // lives in the USER's project, where `@alexkroman1/aai-cli/start` resolves;
+ * // it cannot resolve from inside this package.
+ * import { createProjectServer } from "@alexkroman1/aai-cli/start";
+ *
+ * const server = (await createProjectServer({ cwd: import.meta.dirname })).node;
+ *
+ * export default function handler(req, res) {
+ *   server.emit("request", req, res);
+ * }
+ * ```
+ */
+export declare function createProjectServer(options: StartOptions): Promise<AgentServer>;
+/** What {@link executeStart} answers, for `--json` and for tests. */
+export interface StartResult {
+    ok: true;
+    data: {
+        name: string;
+        port: number | undefined;
+    };
+}
+/**
+ * Serve the built agent and keep serving it: bind, announce, and shut down
+ * cleanly on a signal.
+ *
+ * The signal listeners are SYNCHRONOUS. An `async` one hands its promise to
+ * `process`, which discards what a listener returns — so a `close()` that
+ * rejected would surface as an unhandled rejection, i.e. a crash with a stack
+ * trace on Ctrl-C, instead of the non-zero exit a failed shutdown should be.
+ */
+export declare function executeStart(options: StartOptions): Promise<StartResult>;

package/dist/start.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import { n as log } from "./_ui-DCt4qZrk.mjs";
+import { n as WORKER_ARTIFACT_REL, t as CLIENT_ARTIFACT_REL } from "./_artifacts-BJOYGQPp.mjs";
+import { n as resolveServerEnv, t as DEPLOY_ENV_FILES } from "./_server-common-De0haHr9.mjs";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { createAgentServer, ensureSessionStateSchema, ensureWorkflowJournalSchema, withHostCredentialFallback } from "@alexkroman1/aai-runtime";
+import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
+//#region src/start.ts
+/**
+* `aai start` — serve a BUILT agent from a plain Node process.
+*
+* The deployment counterpart of `aai dev`: no file watching, no Vite, no
+* typecheck, no source evaluation. It loads the artifact `aai build` left at
+* {@link WORKER_ARTIFACT_REL} — the same one `aai publish` uploads and the
+* managed platform runs — so a self-hosted agent and a deployed one cannot
+* behave differently.
+*
+* ## Why this is a command rather than a file in every project
+*
+* It used to be `scaffold/server.mjs`, ~300 lines of boot that `aai init`
+* copied into every scaffolded project: worker load, env resolution, schema
+* DDL, client-directory probing, error classification, listen, signal
+* handlers. Shipping that as source made each of those a fact a USER's
+* repository asserted, so improving any of them reached only projects
+* scaffolded afterwards, and an existing project silently kept the old
+* behaviour with nothing to report the drift.
+*
+* Every framework that solved this solved it the same way: the boot belongs to
+* the framework and the project holds none of it. Next has `next start` and
+* generates a `server.js` for `output: "standalone"` rather than asking anyone
+* to write one. Nitro's default production preset is `node-server`, emitted
+* into the build directory. The custom server is a documented opt-out, not the
+* default everyone inherits — and here that opt-out is
+* {@link createProjectServer}, which builds the server and binds nothing.
+*
+* ## Why the CLI rather than the runtime
+*
+* Booting a project needs three things at once: the runtime, the project's
+* `.aai/` layout, and the prebuilt browser client. Only this package depends on
+* all three — `aai-runtime` may not import `@alexkroman1/aai-ui`, and
+* konsistent's `runtime-package-boundary` carries the install-weight argument
+* for why that stays true. `client-dir.ts`'s own module doc records that this
+* composition has always lived in an ENTRY POINT; this is that entry point,
+* owned by the framework instead of copied into each project.
+*
+* The cost, stated because it is real: `npm start` needs `@alexkroman1/aai-cli`
+* installed, so a production image carries a build toolchain it does not run.
+* Next makes the same trade — `next` is a `dependency`, not a `devDependency` —
+* and it is why the scaffold moves this package to `dependencies`.
+*/
+/** The port `aai start` binds when neither an argument nor `PORT` says otherwise. */
+const DEFAULT_START_PORT = 3e3;
+/**
+* Load the built agent, or fail saying what to run.
+*
+* A `file:` URL rather than a relative specifier, because on Windows a bare
+* POSIX-looking path is not a valid module specifier.
+*/
+async function loadBuiltAgent(cwd) {
+	const workerPath = path.join(cwd, WORKER_ARTIFACT_REL);
+	if (!existsSync(workerPath)) throw new Error(`No built agent at ${WORKER_ARTIFACT_REL}. Run \`aai build\` first — the scaffold's \`prestart\` script normally does it for you.`);
+	return (await import(pathToFileURL(workerPath).href)).default;
+}
+/**
+* Static assets to serve at `/`: this project's own built UI when it has one,
+* otherwise the prebuilt default client that ships inside `@alexkroman1/aai-ui`.
+*
+* A `client.tsx` that has not been BUILT is worth saying out loud — the server
+* would otherwise serve the default UI and look like it had ignored the file.
+*/
+function resolveClientDir(cwd) {
+	const built = path.join(cwd, CLIENT_ARTIFACT_REL);
+	if (existsSync(path.join(built, "index.html"))) return built;
+	if (existsSync(path.join(cwd, "client.tsx"))) log.warn("client.tsx is not built — serving the default UI. Run `aai build` first.");
+	return defaultClientDir();
+}
+/**
+* Build this project's {@link AgentServer} WITHOUT binding a socket.
+*
+* The seam a custom server is written against, and the one a serverless host
+* needs: Vercel documents `export default <http.Server>` as its Node WebSocket
+* shape and binds the socket itself, so such a host takes `AgentServer.node`
+* and never calls `listen()`. `aai build --target vercel` emits an entry that
+* does exactly this, so nothing host-specific is committed to a project.
+*
+* @example
+* ```ts no-check
+* // The entry `aai build --target vercel` bundles into
+* // `.vercel/output/functions/index.func/` — `no-check` because this file
+* // lives in the USER's project, where `@alexkroman1/aai-cli/start` resolves;
+* // it cannot resolve from inside this package.
+* import { createProjectServer } from "@alexkroman1/aai-cli/start";
+*
+* const server = (await createProjectServer({ cwd: import.meta.dirname })).node;
+*
+* export default function handler(req, res) {
+*   server.emit("request", req, res);
+* }
+* ```
+*/
+async function createProjectServer(options) {
+	const { cwd } = options;
+	const agent = await loadBuiltAgent(cwd);
+	const env = await resolveServerEnv(cwd, void 0, DEPLOY_ENV_FILES);
+	if (env.DATABASE_URL) {
+		await ensureSessionStateSchema({
+			url: env.DATABASE_URL,
+			logger: console
+		});
+		await ensureWorkflowJournalSchema({
+			url: env.DATABASE_URL,
+			logger: console
+		});
+	} else log.warn("No DATABASE_URL: session state and durable runs live in THIS process's memory.\nOne replica is fine. Behind a load balancer, enable sticky sessions so a reconnect (the client re-dials with ?sessionId=) reaches the same process — or set DATABASE_URL and let every replica share the state.");
+	return createAgentServer({
+		agent,
+		env,
+		providerEnv: withHostCredentialFallback(env),
+		clientDir: resolveClientDir(cwd),
+		...process.env.PUBLIC_URL?.trim() ? { publicUrl: process.env.PUBLIC_URL.trim() } : {}
+	});
+}
+/**
+* Serve the built agent and keep serving it: bind, announce, and shut down
+* cleanly on a signal.
+*
+* The signal listeners are SYNCHRONOUS. An `async` one hands its promise to
+* `process`, which discards what a listener returns — so a `close()` that
+* rejected would surface as an unhandled rejection, i.e. a crash with a stack
+* trace on Ctrl-C, instead of the non-zero exit a failed shutdown should be.
+*/
+async function executeStart(options) {
+	const agent = await loadBuiltAgent(options.cwd);
+	const server = await createProjectServer(options);
+	const port = options.port ?? Number(process.env.PORT ?? 3e3);
+	const host = options.host ?? (process.env.HOST?.trim() || void 0);
+	await server.listen(port, host);
+	log.info(`${agent.name} listening on http://${host ?? "127.0.0.1"}:${server.port}`);
+	for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => {
+		server.close().then(() => process.exit(0), (error) => {
+			log.error(`shutdown failed: ${error instanceof Error ? error.message : String(error)}`);
+			process.exit(1);
+		});
+	});
+	return {
+		ok: true,
+		data: {
+			name: agent.name,
+			port: server.port
+		}
+	};
+}
+//#endregion
+export { CLIENT_ARTIFACT_REL, DEFAULT_START_PORT, createProjectServer, executeStart, loadBuiltAgent };

package/dist/{studio-CpHlNHUZ.mjs → studio-C_zuRC_z.mjs}

@@ -3,9 +3,9 @@ import { a as ok, t as CliError } from "./_output-DBP9Op_d.mjs";
 import { n as log, t as fmtUrl } from "./_ui-DCt4qZrk.mjs";
 import { l as formatCappedList } from "./_utils-D5JGcjiW.mjs";
 import { s as updateProjectConfig } from "./_config-DYzC6WMD.mjs";
-import { t as resolveServerEnv } from "./_server-common-vILJp3it.mjs";
+import { n as resolveServerEnv } from "./_server-common-De0haHr9.mjs";
 import { o as resolveDeployTarget } from "./_agent-BzUeqOdj.mjs";
-import { layerScaffold } from "./_templates-CK4oKoeX.mjs";
+import { layerScaffold } from "./_templates-CIlJ3Vay.mjs";
 import { a as publishStudioProject, c as studioProjectUrl, f as checkedResponse, i as projectNameFromDir, n as fetchStudioProject, o as pushStudioSource, r as listStudioProjects, s as studioProjectApiUrl, t as collectSourceFiles, u as apiRequest } from "./_studio-DnR_BqFp.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";

package/dist/templates/briefing-desk/agent.eval.test.ts

@@ -0,0 +1,156 @@
+// An EVAL: does the desk really DELEGATE, or does it brief you from memory?
+//
+// `agent.test.ts` settles what each tool does once it has been called — it
+// hands `researchAngle` a `stubDelegate` and asserts on the board. What it
+// cannot settle is the two things this template exists to demonstrate: that the
+// MODEL turns "tell me about home battery prices" into ONE `research_topic`
+// call carrying several angles rather than one call per angle, and that nothing
+// the caller hears came from a web tool the DESK holds — because it holds none.
+//
+// Run it with `aai eval`. Without a provider key every case runs against a
+// SCRIPTED model (its `stubReply`), which proves the wiring and nothing about
+// the choice — so the two claims above are `{ live: true }` and the recap case,
+// whose whole point is that it spends no model at all, is not.
+
+/**
+ * The def a DEPLOYED agent runs: authored, plus what `tools/` declares, plus
+ * its PROMPT.
+ *
+ * Taken from `virtual:aai/agent` rather than a hand-written glob: the plugin
+ * expands it against THIS file's own directory, so the spec needs no glob and
+ * no shared helper — which matters because this file SHIPS, and a scaffolded
+ * project has no repo helper to import. `agent.ts` here is three fields, so an
+ * eval driving it alone would measure an agent with no tools and the FRAMEWORK
+ * DEFAULT prompt — i.e. a desk that has never heard of a researcher, on which
+ * every claim below would pass or fail for the wrong reason. The reasoning is
+ * spelled out in `../code-interpreter/agent.eval.test.ts`.
+ */
+import agentDef from "virtual:aai/agent";
+import { describeTurn, toolNames, toolResultIn } from "@alexkroman1/aai-runtime/eval";
+import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
+import { expect } from "vitest";
+import { z } from "zod";
+import { MAX_ANGLES } from "./shared.ts";
+
+/**
+ * Every tool the desk declares — the two that reach the outside world through a
+ * subagent, and the recap that reaches nothing.
+ *
+ * Named here because the isolation claim is stated as a NEGATIVE — no
+ * `web_search`, no `visit_webpage` — and a negative over a hand-typed list is
+ * the assertion that goes quietly true when a tool is renamed. Every call the
+ * desk makes must be one of these three names.
+ */
+const DESK_TOOLS: readonly string[] = ["research_topic", "verify_claim", "briefing_so_far"];
+
+/**
+ * What `research_topic` answers with, as a schema rather than a cast.
+ *
+ * `toolResultIn` takes one for the reason `night-owl`'s spec records: a result
+ * that stopped carrying `findings` FAILS here naming the field, where a cast
+ * hands the assertions `undefined` and fails a line later on something
+ * unrelated.
+ */
+const BriefingResult = z.object({
+  topic: z.string(),
+  findings: z.array(z.object({ angle: z.string(), summary: z.string() })),
+  failed: z.array(z.object({ angle: z.string() })),
+});
+
+/** What `briefing_so_far` answers with on an EMPTY board. */
+const EmptyRecap = z.object({
+  topic: z.null(),
+  findings: z.array(z.unknown()).length(0),
+  message: z.string(),
+});
+
+/** What `verify_claim` answers with. */
+const Verdict = z.object({ claim: z.string(), verdict: z.string() });
+
+describeEval(agentDef, (test) => {
+  test(
+    "a recap on an empty board costs no researcher",
+    async ({ session }) => {
+      const turn = await session.say("What have you got for me so far?");
+
+      // The one tool here that spends no model at all, and the case that can
+      // therefore run against a script: the desk answers the recap out of its
+      // own slot. A desk that reached for `research_topic` to find out what it
+      // already knows is the regression — it bills the caller for four
+      // researchers to answer "nothing yet".
+      expect(toolNames(turn.toolCalls), describeTurn(turn)).toEqual(["briefing_so_far"]);
+      // And the slot really resolved: an empty board reports itself as empty
+      // rather than throwing or answering with a half-built shape.
+      expect(toolResultIn(turn.toolCalls, "briefing_so_far", EmptyRecap).topic).toBeNull();
+    },
+    {
+      stubReply: [
+        { tool: "briefing_so_far", args: {} },
+        "Nothing yet — tell me a subject and I'll put some researchers on it.",
+      ],
+    },
+  );
+
+  test(
+    "fans one subject out across angles in a SINGLE call",
+    async ({ session }) => {
+      const turn = await session.say("What's going on with home battery prices?");
+
+      // One call carrying several angles, never one call per angle. That is the
+      // whole economic claim of the template — the angles run in parallel, so
+      // the caller waits for the slowest rather than the sum — and a desk that
+      // called the tool three times in a row would satisfy any assertion that
+      // merely counted angles.
+      const calls = turn.toolCalls.filter((call) => call.name === "research_topic");
+      expect(calls, describeTurn(turn)).toHaveLength(1);
+      const angles = z.array(z.string()).parse(calls[0]?.args.angles);
+      expect(angles.length).toBeGreaterThan(1);
+      expect(angles.length).toBeLessThanOrEqual(MAX_ANGLES);
+      // Each angle stands on its own — the prompt's rule, and the one a
+      // researcher cannot recover from, having heard none of this call. A bare
+      // "the same for Europe" is a handful of characters; a self-contained
+      // question is a sentence.
+      for (const angle of angles) expect(angle.length).toBeGreaterThan(15);
+
+      // What came back is what the researchers concluded, not what the desk
+      // believes: every finding carries prose, and the board holds the topic.
+      const result = toolResultIn(turn.toolCalls, "research_topic", BriefingResult);
+      expect(result.findings).not.toEqual([]);
+      for (const finding of result.findings) expect(finding.summary.length).toBeGreaterThan(40);
+
+      // The isolation claim, and the reason this template is not
+      // `web-researcher`: the desk has NO web tools, so anything it says about
+      // the world crossed back out of a subagent. A `web_search` in this list
+      // would mean the builtins had leaked onto the parent.
+      expect(toolNames(turn.toolCalls).filter((name) => !DESK_TOOLS.includes(name))).toEqual([]);
+      expect(turn.text).not.toBe("");
+    },
+    // Live only: a script cannot choose the angles, and choosing them is the
+    // measurement. It also cannot run a subagent — the researcher resolves a
+    // model of its own from `shared.ts`, which the turn's stub never covers.
+    { live: true },
+  );
+
+  test(
+    "checks a claim the caller pushes back on instead of defending it",
+    async ({ session }) => {
+      const turn = await session.say(
+        "Someone told me home batteries pay for themselves in two years. " +
+          "Is that right? Check it for me.",
+      );
+
+      // `verify_claim` is the cheaper subagent on the narrower surface, and
+      // reaching for it rather than answering is the prompt's rule that a live
+      // model actually has to keep. The claim it forwards must be the sentence
+      // it was given, not a keyword — a fact-checker handed "batteries" answers
+      // confidently about nothing.
+      const calls = turn.toolCalls.filter((call) => call.name === "verify_claim");
+      expect(calls, describeTurn(turn)).toHaveLength(1);
+      const verdict = toolResultIn(turn.toolCalls, "verify_claim", Verdict);
+      expect(verdict.claim.split(/\s+/).length).toBeGreaterThan(3);
+      expect(verdict.verdict).not.toBe("");
+      expect(toolNames(turn.toolCalls).filter((name) => !DESK_TOOLS.includes(name))).toEqual([]);
+    },
+    { live: true },
+  );
+});

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

@@ -0,0 +1,103 @@
+/** The def a DEPLOYED agent runs: authored, plus the `system-prompt.md` beside it. */
+import agentDef from "virtual:aai/agent";
+import { AgentConfigSchema, toAgentConfig } from "@alexkroman1/aai/manifest";
+import { describe, expect, test } from "vitest";
+
+/**
+ * What this starter's spec may assert.
+ *
+ * Renaming Coda, giving her a voice, swapping a stage or switching the whole
+ * thing to speech-to-speech are the first edits this template invites — and
+ * `aai build` runs these tests before it bundles, so an assertion that pins the
+ * template's own identity turns the first customization into a build failure in
+ * a file the author never wrote. Every test here asserts a property that
+ * survives those edits, on the RESOLVED config rather than on the def's empty
+ * fields.
+ *
+ * What it may NOT assert is whether `run_code` actually RUNS: the builtin is
+ * sandbox-only, so off-platform it declines rather than evaluating
+ * model-written JavaScript in the host process. That is right, and it leaves
+ * "Coda reached for code, and the code came back with 107823" to
+ * `agent.eval.test.ts`, which supplies an executor of its own. What is reachable
+ * in memory is the pairing the template is built on — the builtin it asks for
+ * and the prompt that commands it — and that is what the last two tests are.
+ */
+describe("code-interpreter template", () => {
+  test("config passes manifest validation", () => {
+    // Same conversion `aai build`/`aai deploy` run.
+    expect(() => toAgentConfig(agentDef)).not.toThrow();
+  });
+
+  test("exports an agent the platform can name", () => {
+    // Not the literal: what has to hold is that there IS a name and that the
+    // conversion carries it through — `AgentName` refuses a blank one, and the
+    // studio lists a deployed agent by exactly this string.
+    expect(agentDef.name).toBeTruthy();
+    expect(toAgentConfig(agentDef).name).toBe(agentDef.name);
+  });
+
+  test("whatever mode it ends up in, there is a model to call the tool with", () => {
+    // A builtin is something a MODEL reaches for, so this template is only
+    // itself while some stage can issue a tool call. Asserted per MODE so it
+    // survives the swaps above: declare `stt`/`llm`/`tts` and the rest still
+    // default to the all-AssemblyAI cascade (which is why the def declares no
+    // provider at all and still runs); declare `s2s` and there is no cascade to
+    // fill, which is the one thing that must never happen by fallthrough.
+    const config = toAgentConfig(agentDef);
+    if (config.mode === "s2s") {
+      expect(config.s2s?.kind).toBeTruthy();
+      expect(config.stt).toBeUndefined();
+      expect(config.tts).toBeUndefined();
+      return;
+    }
+    expect(config.llm?.kind).toBeTruthy();
+    if (config.mode === "pipeline") {
+      expect(config.stt?.kind).toBeTruthy();
+      expect(config.tts?.kind).toBeTruthy();
+    }
+  });
+
+  test("run_code survives into the config a deploy carries", () => {
+    // The template's whole capability, asserted on the CONFIG rather than the
+    // def because that is what a deploy ships. `DEFAULT_BUILTIN_TOOLS` is
+    // EMPTY — a builtin is something an agent asks for, never something it has
+    // to notice and switch off — so a dropped `builtinTools` is not a degraded
+    // Coda, it is an agent whose prompt forbids mental arithmetic and leaves it
+    // nothing else to do. Adding builtins beside it is fine; losing this one is
+    // the regression.
+    expect(toAgentConfig(agentDef).builtinTools ?? []).toContain("run_code");
+  });
+
+  test("every builtin the prompt commands by name is one the agent declares", () => {
+    // The pairing that makes this template work, and the failure it catches is
+    // silent in both directions: a prompt commanding `fetch_json` at an agent
+    // that never declared it produces a model apologizing for a tool it cannot
+    // see, and a builtin renamed in `agent.ts` alone leaves the CRITICAL RULES
+    // addressed to nothing. Neither shows up in a diff of either file.
+    const config = toAgentConfig(agentDef);
+    const declared = config.builtinTools ?? [];
+
+    // Which snake_case tokens in the prose are TOOL NAMES is a question for the
+    // SDK's own schema, not for a list restated here: a catalog copied into a
+    // spec goes stale, and matching every underscored word would redden on a
+    // prompt that names a variable in one of its examples.
+    const isBuiltin = (name: string) =>
+      AgentConfigSchema.safeParse({ ...config, builtinTools: [name] }).success;
+    const commanded = [
+      ...new Set(config.systemPrompt.match(/\b[a-z][a-z0-9]*(?:_[a-z0-9]+)+\b/g) ?? []),
+    ].filter(isBuiltin);
+
+    // Non-vacuity, and it earns its keep twice: a prompt naming no builtin at
+    // all would make the loop below assert nothing, and it is also the state a
+    // template gets into when `system-prompt.md` is not applied — the framework
+    // default names no builtin, so an agent running on it lands here rather
+    // than passing quietly with the CRITICAL RULES nowhere in its context.
+    expect(commanded.length).toBeGreaterThan(0);
+    for (const name of commanded) {
+      expect(declared, `the prompt commands ${name}`).toContain(name);
+    }
+    // The converse is deliberately NOT asserted: declaring a builtin the prompt
+    // never mentions is an ordinary edit, and the model is told about it by its
+    // own tool schema.
+  });
+});

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

@@ -62,9 +62,32 @@
  * 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.
+ *
+ * ## Two things that are only ever true for a MOMENT
+ *
+ * The Copy button and the reply to "File it now" are both a word that appears
+ * and then goes away, and both used to be the sort of thing a page writes with
+ * a `useState` and a bare `setTimeout` — which gets two things wrong that only
+ * show up on the second click (a second flash has its window cut short by the
+ * first one's timer) and on unmount (a `setState` into a torn-down tree). They
+ * are `useCopy` and `useFlash` from `@alexkroman1/aai-ui`.
+ *
+ * Reach for `useCopy` when the moment is a clipboard write — it keys the flash
+ * by the copied TEXT, so on a page with several copy buttons only the one
+ * clicked lights up, and it reports a REFUSED write as `"Failed"` rather than
+ * doing nothing visible (there is no clipboard at all on an insecure origin).
+ * Reach for `useFlash` for any other transient word; here it carries what
+ * `wake()` answered, which is a number and not a failure at 0.
  */
 
-import { BulletList, mountPage, useWorkflowSubmit, WorkflowProgress } from "@alexkroman1/aai-ui";
+import {
+  BulletList,
+  mountPage,
+  useCopy,
+  useFlash,
+  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/
@@ -90,8 +113,22 @@ function pendingNote(startedHere: boolean, found: boolean): string {
   return "Still working on the digest this tab started earlier. Reloading is safe.";
 }
 
+/** The digest as one pasteable block — a headline and its bullets. */
+function asText(headline: string, points: readonly string[]): string {
+  return [headline, ...points.map((point) => `- ${point}`)].join("\n");
+}
+
 export function App() {
   const [url, setUrl] = useState("");
+  // One copier for the page. It would be one per GROUP of copy buttons on a
+  // bigger page — the flash is shared, so clicking a second row clears the
+  // first row's "Copied", which is what stops two rows both claiming to be on
+  // the clipboard.
+  const copier = useCopy();
+  // `wake()` resolves with how many sleeps it ended, and 0 is an ANSWER (the
+  // run had already moved past its wait) rather than a failure — so the button
+  // says which happened, for a moment, and then goes back to being a button.
+  const woken = useFlash<string>();
   // The generic is what makes `run.status === "completed"` narrow to a TYPED
   // `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
@@ -168,10 +205,14 @@ export function App() {
       {pending && (
         <button
           type="button"
-          onClick={() => void wake()}
+          onClick={() => {
+            void wake().then((count) =>
+              woken.flash(count > 0 ? "Filing it now" : "Already past its wait"),
+            );
+          }}
           className="self-start rounded-md border px-3 py-1 text-sm"
         >
-          File it now
+          {woken.value ?? "File it now"}
         </button>
       )}
 
@@ -189,6 +230,17 @@ export function App() {
           <h2 className="text-xl">{run.output.headline}</h2>
           <BulletList items={run.output.points} />
           <p className="text-sm opacity-70">Filed {run.output.filedAt}</p>
+          {/* The whole digest as plain text, which is what somebody pasting it
+              into a note wants. `copier.label` is the button's own text: it
+              reads "Copy" until it is clicked, then "Copied" — or "Failed",
+              which is the case a hand-rolled version silently drops. */}
+          <button
+            type="button"
+            onClick={() => copier.copy(asText(run.output.headline, run.output.points))}
+            className="self-start rounded-md border px-3 py-1 text-sm"
+          >
+            {copier.label(asText(run.output.headline, run.output.points))}
+          </button>
         </article>
       )}
     </main>