@alexkroman1/aai-cli 14.0.0 → 15.1.0

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

@@ -0,0 +1,126 @@
+/**
+ * The def a DEPLOYED agent runs: authored, plus the `system-prompt.md` beside
+ * it.
+ *
+ * This template declares no `tools/` at all — every calculation is the
+ * `run_code` builtin's — so the prompt is the only thing discovery adds here,
+ * and it is what half the tests below are about. Importing `./agent.ts`
+ * directly would measure a tutor whose prompt is the framework default, i.e.
+ * an agent that was never told to compute in code.
+ */
+import agentDef from "virtual:aai/agent";
+import { toAgentConfig } from "@alexkroman1/aai/manifest";
+import { describe, expect, test } from "vitest";
+
+/**
+ * What a starter's spec may assert.
+ *
+ * `aai build` runs these tests before it bundles, so an assertion pinning this
+ * tutor's own identity — its literal name, the wording of its greeting, the
+ * model id it happens to run today — turns the first customization into a build
+ * failure in a file the author never wrote. Every test here therefore asserts a
+ * property that survives a rename, a voice, a reworded prompt and a model swap,
+ * on the RESOLVED config rather than on the def's empty fields.
+ *
+ * `run_code` is the one thing named literally, and deliberately: taking it away
+ * is not a customization of Math Buddy but a deletion of its subject — the
+ * prompt is nothing but recipes for it — and the tutor left behind does
+ * arithmetic from memory, which reads exactly like a correct answer until it is
+ * wrong.
+ *
+ * What is NOT here is anything about the code the tutor writes or the answer it
+ * comes back with: that needs a model and a sandbox, so it belongs to
+ * `agent.eval.test.ts`, which supplies both. This tier's question is the one
+ * that comes first — was the tutor handed anything to run at all.
+ */
+describe("math-buddy template", () => {
+  test("config passes manifest validation", () => {
+    // Same conversion `aai build`/`aai deploy` run — and the only thing that
+    // says this template's declared LLM descriptor is well formed before a
+    // live session tries to open one from it.
+    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("run_code is declared, and the prompt the deploy carries asks for it", () => {
+    const config = toAgentConfig(agentDef);
+    // Two halves, each of which fails silently and produces a plausible tutor.
+    // Without the declaration the model has nothing to run, so it computes in
+    // its head and says the answer with the same confidence either way. Without
+    // the prompt reaching the CONFIG — the "I edited system-prompt.md and
+    // nothing changed" failure `withSystemPrompt` exists to catch, since the
+    // file is discovered by the build rather than imported by `agent.ts` — the
+    // recipes are gone and what deploys is a general assistant that happens to
+    // have a sandbox attached. The framework default says nothing about
+    // `run_code`, which is what makes the second assertion a real check on
+    // discovery rather than a restatement of the first.
+    expect(config.builtinTools).toContain("run_code");
+    expect(config.systemPrompt).toContain("run_code");
+  });
+
+  test("whichever model this tutor runs on, the conversion carries its tuning", () => {
+    const config = toAgentConfig(agentDef);
+    if (config.mode !== "pipeline") {
+      // Switched the def to `s2s`? Then one model listens and talks, and there
+      // is no separate LLM stage left for anything to be carried on.
+      expect(config.mode).toBe("s2s");
+      expect(config.llm).toBeUndefined();
+      return;
+    }
+    if (agentDef.llm === undefined) {
+      // Dropped the declaration to take the default cascade: it still resolves
+      // to a NAMED model, because the gateway refuses an unknown id with a 400
+      // at the first session — "no model" is not a state a deploy may reach.
+      expect(config.llm?.options.model).toBeTruthy();
+      return;
+    }
+    // A model choice is the only reason this tutor declares a stage at all —
+    // a quick, cheap one, since `run_code` does the arithmetic and what is left
+    // is turn-taking speed. So the descriptor is checked whole rather than by
+    // `kind`: one that arrived with its options dropped would deploy the
+    // gateway's default model instead, quietly slower, with nothing on the line
+    // saying so. Read off the def rather than pinned, because swapping the id
+    // is the first tuning an author of this template tries.
+    expect(config.llm?.kind).toBe(agentDef.llm.kind);
+    expect(config.llm?.options).toEqual(agentDef.llm.options);
+    expect(config.llm?.options.model).toBeTruthy();
+  });
+
+  test("every stage its mode needs is filled, declared or defaulted", () => {
+    // This template's other half: it declares the LLM and nothing else, so STT
+    // and TTS are injected at parse time (see `defaultProviders`) and the tutor
+    // can still hear and speak. Asserted per MODE so it survives a swap —
+    // declare `stt`/`tts` and the rest still default; 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.mode).toBe("pipeline");
+    for (const stage of ["stt", "llm", "tts"] as const) {
+      expect(config[stage]?.kind, stage).toBe(agentDef[stage]?.kind ?? "assemblyai");
+    }
+  });
+
+  test("the caller is told what to ask, and the greeting survives the conversion", () => {
+    // A voice agent has no buttons, so the opener is the only place a caller
+    // learns that this one wants arithmetic, conversions and dice rather than
+    // conversation. It rides to the browser in `/client-config` beside `name`,
+    // so what has to hold is that there is one and the conversion carries it:
+    // a greeting lost at that boundary is replaced by the framework's generic
+    // opener, which invites the caller to ask for anything at all.
+    expect(agentDef.greeting).toBeTruthy();
+    expect(toAgentConfig(agentDef).greeting).toBe(agentDef.greeting);
+  });
+});

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

@@ -0,0 +1,127 @@
+/** The def a DEPLOYED agent runs: authored, plus what `system-prompt.md` says. */
+import agentDef from "virtual:aai/agent";
+import { AgentConfigSchema, toAgentConfig } from "@alexkroman1/aai/manifest";
+import { describe, expect, test } from "vitest";
+
+/**
+ * What a starter's spec may assert.
+ *
+ * `aai init` scaffolds this template verbatim, and `aai build` runs these tests
+ * before it bundles — so an assertion pinning Penny's own identity (her literal
+ * name, her voice, her model, the wording of a house rule) turns a user's first
+ * customization into a build failure in a file they never wrote. Every test
+ * here therefore asserts a property that survives those edits, on the RESOLVED
+ * config rather than on the def's empty fields.
+ *
+ * What is deliberately NOT here: whether Penny actually reaches for `run_code`
+ * instead of dividing in her head, whether she looks a rate up rather than
+ * quoting a remembered one, and whether she keeps the not-financial-advice
+ * caveat. Those are claims about a live model and belong to
+ * `agent.eval.test.ts`, which drives them against one. This tier asserts the
+ * WIRING those runs depend on — a template whose builtins never reached the
+ * config fails an eval as a behaviour problem, in a report nobody reads as
+ * "the tool was not there".
+ */
+describe("personal-finance template", () => {
+  test("config passes manifest validation", () => {
+    // Same conversion `aai build`/`aai deploy` run. It is also what checks the
+    // two builtin NAMES against the SDK's own enum, so a typo in
+    // `builtinTools` fails here rather than shipping an agent whose prompt
+    // commands a tool the platform never resolved.
+    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 the
+    // conversion carries it through — the studio lists a deployed agent by
+    // exactly this string, and renaming her is the first edit this template
+    // invites.
+    expect(agentDef.name).toBeTruthy();
+    expect(toAgentConfig(agentDef).name).toBe(agentDef.name);
+  });
+
+  test("every stage its mode needs is filled, declared or defaulted", () => {
+    // This template declares no provider at all — it is a prompt and two
+    // builtins — so the default all-AssemblyAI cascade is what makes it run
+    // the moment it is deployed. Asserted per MODE so it stays true after a
+    // swap: declare `stt`/`llm`/`tts` and the rest still default; 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();
+    } else if (config.mode === "text") {
+      expect(config.llm?.kind).toBeTruthy();
+    } else {
+      expect(config.mode).toBe("pipeline");
+      expect(config.stt?.kind).toBeTruthy();
+      expect(config.llm?.kind).toBeTruthy();
+      expect(config.tts?.kind).toBeTruthy();
+    }
+  });
+
+  test("both builtins survive into the config a deploy carries", () => {
+    const builtins = toAgentConfig(agentDef).builtinTools ?? [];
+
+    // `run_code` is the arithmetic rule's only mechanism. The prompt forbids
+    // Penny working ANY figure out in her head — a tip, a split, a payment, a
+    // projection — so without the builtin the rule has nothing to point at and
+    // degrades into a model inventing numbers the caller then spends money on.
+    expect(builtins).toContain("run_code");
+
+    // `fetch_json` is the only route to a number that MOVES. A rate or a coin
+    // price the model remembers is months stale and carries no source, and it
+    // arrives in exactly the confident tone a fetched one would — which is why
+    // a finance starter that cannot make a request is worse than one that
+    // declines to answer.
+    expect(builtins).toContain("fetch_json");
+
+    // Asserted on the CONFIG rather than the def because that is what a deploy
+    // ships, and because `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 entry is not a quieter Penny, it is the same Penny with
+    // no way to be right. Adding builtins beside these two is an ordinary edit;
+    // losing one is the regression.
+  });
+
+  test("every builtin the prompt tells Penny to use is one she declares", () => {
+    // The pairing this template is made of: the prose holds the endpoints and
+    // the formulas, each list headed by the tool that consumes it, and
+    // `agent.ts` holds the array that makes those tools exist. The failure 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 dropped from `agent.ts` alone leaves the endpoint list
+    // addressed to nothing — and 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 rather than a catalog restated here: this prompt also
+    // names `vs_currencies`, `include_24hr_change`, `per_person` and
+    // `annual_rate`, so matching every underscored word would redden on a
+    // formula, and a copied list of builtins goes stale the first time the SDK
+    // adds one.
+    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 leave the loop below asserting nothing, and it is also the state
+    // this template lands in when `system-prompt.md` is not applied — the
+    // framework default names no builtin, so "I edited the prompt and nothing
+    // changed" fails here instead of passing quietly with Penny's rules nowhere
+    // in her context.
+    expect(commanded.length).toBeGreaterThan(0);
+    for (const name of commanded) {
+      expect(declared, `the prompt tells Penny to use ${name}`).toContain(name);
+    }
+
+    // The converse is deliberately NOT asserted: declaring a builtin the prompt
+    // never mentions is an ordinary edit, and the model learns about it from its
+    // own tool schema rather than from the prose.
+  });
+});

package/dist/templates/support-line/agent.ts

@@ -24,4 +24,12 @@ export default agent({
   // caller's callback number, and only its reference crosses to the browser.
   syncState: supportProjection,
   greeting: `${PRODUCT} support, you're through to the automated line. What's happened?`,
+  // A support line is a PHONE line, so this one declares the carrier its number
+  // is with. Nothing serves `WS /phone` without this — the route is an
+  // allow-list, and an agent that says nothing about carriers answers none — so
+  // point a Twilio number's webhook at the deployed agent's `/phone` and the
+  // call lands in an ordinary session. `true` admits every carrier the runtime
+  // ships a codec for; a list is the narrower statement, and it is the one to
+  // copy.
+  telephony: ["twilio"],
 });

package/dist/templates/travel-concierge/routing.ts

@@ -6,7 +6,10 @@
  * `activeAssistant`, `applyPending`, `note`. Each is NAMED by a file under
  * `tools/`, which is what registers it: a tool's name is its file name, so
  * `tools/to_flight_assistant.ts` is one line handing {@link delegationTool} an
- * id, and `tools/confirm_action.ts` re-exports {@link confirmAction}.
+ * id, and `tools/confirm_action.ts` one line calling {@link confirmActionTool}.
+ * Every file in `tools/` therefore default-exports the RESULT of a call: a
+ * factory per tool rather than a shared const, so nothing here is a re-export
+ * — which is what `noExportedImports` would otherwise have to be told to allow.
  *
  * The delegation four are still generated rather than written out. The notebook
  * declares `ToFlightBookingAssistant`, `ToHotelBookingAssistant`,
@@ -77,33 +80,35 @@ export function delegationTool(id: SpecialistId): ToolDef {
  * a `done` tool will keep trying to answer things the desk has no tools for.
  * The `reason` is what the concierge is handed on the way back up.
  */
-export const completeOrEscalate = tripSlot.updateTool({
-  description:
-    "Hand the call back to the main concierge. Use this when the current desk's " +
-    "work is finished, when the caller changes the subject to something this " +
-    "desk does not handle, or when they change their mind.",
-  inputSchema: z.object({
-    reason: z
-      .string()
-      .max(300)
-      .describe("Why the call is going back — what is done, or what the caller now wants"),
-  }),
-  execute(args, trip) {
-    const left = activeAssistant(trip);
-    // `primary` stays at the bottom — the slot's `after` hook restores it if a
-    // pop ever empties the stack.
-    if (trip.dialogState.length > 1) trip.dialogState.pop();
-    note(trip, `← back to concierge: ${args.reason}`);
-    return {
-      returnedFrom: left === "primary" ? "concierge" : SPECIALISTS[left].title,
-      nowHandling: "concierge",
-      reason: args.reason,
-      instructions:
-        "You are the main concierge again. Pick up what the caller asked for; " +
-        "delegate again if it belongs to another desk.",
-    };
-  },
-});
+export function completeOrEscalateTool(): ToolDef {
+  return tripSlot.updateTool({
+    description:
+      "Hand the call back to the main concierge. Use this when the current desk's " +
+      "work is finished, when the caller changes the subject to something this " +
+      "desk does not handle, or when they change their mind.",
+    inputSchema: z.object({
+      reason: z
+        .string()
+        .max(300)
+        .describe("Why the call is going back — what is done, or what the caller now wants"),
+    }),
+    execute(args, trip) {
+      const left = activeAssistant(trip);
+      // `primary` stays at the bottom — the slot's `after` hook restores it if a
+      // pop ever empties the stack.
+      if (trip.dialogState.length > 1) trip.dialogState.pop();
+      note(trip, `← back to concierge: ${args.reason}`);
+      return {
+        returnedFrom: left === "primary" ? "concierge" : SPECIALISTS[left].title,
+        nowHandling: "concierge",
+        reason: args.reason,
+        instructions:
+          "You are the main concierge again. Pick up what the caller asked for; " +
+          "delegate again if it belongs to another desk.",
+      };
+    },
+  });
+}
 
 /**
  * `confirm_action` — the caller said yes.
@@ -121,14 +126,16 @@ export const completeOrEscalate = tripSlot.updateTool({
  * the body did NOT answer with a {@link ToolFailure}, so an application that
  * failed leaves the change staged and the caller still being asked.
  */
-export const confirmAction = gateFlow.tool({
-  description:
-    "Apply the change the caller has just confirmed out loud. Only call this " +
-    "after you have read the change back and heard a clear yes.",
-  when: "awaitingConfirmation",
-  send: { type: "SETTLED" },
-  execute: (_args, ctx) => tripSlot.update(ctx, (trip) => applyPending(trip)),
-});
+export function confirmActionTool(): ToolDef {
+  return gateFlow.tool({
+    description:
+      "Apply the change the caller has just confirmed out loud. Only call this " +
+      "after you have read the change back and heard a clear yes.",
+    when: "awaitingConfirmation",
+    send: { type: "SETTLED" },
+    execute: (_args, ctx) => tripSlot.update(ctx, (trip) => applyPending(trip)),
+  });
+}
 
 /**
  * `cancel_action` — the caller said no. Drops the staged action, changes nothing.
@@ -136,22 +143,24 @@ export const confirmAction = gateFlow.tool({
  * Gated for the same reason as `confirm_action`, and its own "nothing was
  * waiting" arm is gone with the same argument.
  */
-export const cancelAction = gateFlow.tool({
-  description:
-    "Discard the change the caller just declined. Call this when they say no, " +
-    "or when they want to change the details before confirming.",
-  when: "awaitingConfirmation",
-  send: { type: "SETTLED" },
-  execute: (_args, ctx) =>
-    tripSlot.update(ctx, (trip) => {
-      const action = trip.pending;
-      // Reachable only if the position and the payload disagree; see
-      // `applyPending`. Reported rather than thrown, mid-call.
-      if (!action) return { discarded: null, message: "Nothing was staged after all." };
-      trip.pending = null;
-      const described = describeAction(action);
-      const summary = typeof described === "string" ? described : action.kind;
-      note(trip, `Declined: ${summary}`);
-      return { discarded: summary, message: "Nothing was changed." };
-    }),
-});
+export function cancelActionTool(): ToolDef {
+  return gateFlow.tool({
+    description:
+      "Discard the change the caller just declined. Call this when they say no, " +
+      "or when they want to change the details before confirming.",
+    when: "awaitingConfirmation",
+    send: { type: "SETTLED" },
+    execute: (_args, ctx) =>
+      tripSlot.update(ctx, (trip) => {
+        const action = trip.pending;
+        // Reachable only if the position and the payload disagree; see
+        // `applyPending`. Reported rather than thrown, mid-call.
+        if (!action) return { discarded: null, message: "Nothing was staged after all." };
+        trip.pending = null;
+        const described = describeAction(action);
+        const summary = typeof described === "string" ? described : action.kind;
+        note(trip, `Declined: ${summary}`);
+        return { discarded: summary, message: "Nothing was changed." };
+      }),
+  });
+}

package/dist/templates/travel-concierge/tools/cancel_action.ts

@@ -4,4 +4,6 @@
  * gives it its name.
  */
 
-export { cancelAction as default } from "../routing.ts";
+import { cancelActionTool } from "../routing.ts";
+
+export default cancelActionTool();

package/dist/templates/travel-concierge/tools/complete_or_escalate.ts

@@ -4,4 +4,6 @@
  * gives it its name.
  */
 
-export { completeOrEscalate as default } from "../routing.ts";
+import { completeOrEscalateTool } from "../routing.ts";
+
+export default completeOrEscalateTool();

package/dist/templates/travel-concierge/tools/confirm_action.ts

@@ -4,4 +4,6 @@
  * gives it its name.
  */
 
-export { confirmAction as default } from "../routing.ts";
+import { confirmActionTool } from "../routing.ts";
+
+export default confirmActionTool();

package/dist/templates/web-researcher/agent.test.ts

@@ -0,0 +1,130 @@
+/** The def a DEPLOYED agent runs: authored, plus what `system-prompt.md` says. */
+import agentDef from "virtual:aai/agent";
+import { toAgentConfig } from "@alexkroman1/aai/manifest";
+import { describe, expect, test } from "vitest";
+import promptFile from "./system-prompt.md?raw";
+
+/**
+ * What a starter's spec may assert.
+ *
+ * `aai build` runs these tests before it bundles, so an assertion pinning the
+ * template's own identity — its literal name, its greeting, its voice, its
+ * model — turns a user's first customization into a build failure in a file
+ * they never wrote. Every test here therefore asserts a property that survives
+ * those edits, on the RESOLVED config rather than on the def's empty fields.
+ *
+ * What is left to `agent.eval.test.ts` is everything that needs a model: that
+ * Scout SEARCHES before answering a fact it is sure of, that the outlet it
+ * names appeared in results it actually read, and that the SSRF screen refuses
+ * a private address through the agent's own executor. Those are behaviour, and
+ * this tier may not reach the network at all — which is also why nothing here
+ * runs `web_search`. What a unit test can say is that the capability and the
+ * document that instructs it are both still THERE, which is the half that
+ * regresses in a diff rather than in a model.
+ *
+ * The def therefore comes from `virtual:aai/agent` rather than from
+ * `./agent.ts`: the prompt file is applied by the BUILD, so the raw default
+ * export carries the framework prompt and every claim below would be measuring
+ * an agent nobody deploys. This template has no `tools/` directory, so that
+ * import is also the file's existence check — `deployedAgent` is handed the
+ * prompt and nothing else, and refuses a call with no project files at all.
+ */
+
+/**
+ * The builtins that can reach the web.
+ *
+ * Typed by USE rather than by an annotation: `builtinTools` takes a
+ * `BuiltinTool[]`, so passing this list to `toAgentConfig` below only compiles
+ * if every name here is really a builtin — a name the SDK renames fails
+ * `pnpm typecheck` in this file instead of dropping silently out of the scan.
+ */
+const WEB_BUILTINS = ["web_search", "visit_webpage", "fetch_json", "get_page_design"] as const;
+
+describe("web-researcher 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("every stage its mode needs is filled, declared or defaulted", () => {
+    // This template declares no provider at all — the whole voice pipeline is
+    // the injected all-AssemblyAI default, which is what lets the starter run
+    // the moment it is deployed. Asserted per MODE so it survives a swap:
+    // declare `stt`/`llm`/`tts` and the rest still default; 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();
+    } else if (config.mode === "text") {
+      expect(config.llm?.kind).toBeTruthy();
+    } else {
+      expect(config.mode).toBe("pipeline");
+      expect(config.stt?.kind).toBeTruthy();
+      expect(config.llm?.kind).toBeTruthy();
+      expect(config.tts?.kind).toBeTruthy();
+    }
+  });
+
+  test("system-prompt.md is the prompt a deploy carries", () => {
+    // The build discovers the file; nothing imports it. So the failure this
+    // catches is "I edited the prompt and nothing changed" — and here it is the
+    // expensive one, because every rule that makes Scout a researcher rather
+    // than a talkative model (search first, cite what you read, treat a fetched
+    // page as data and not as instructions) lives ONLY in that file. An agent
+    // running the framework default answers plausibly, sounds fine, and cites
+    // pages it never opened.
+    //
+    // `toContain` rather than an equality: importing the file into `agent.ts`
+    // and composing it (a computed suffix, a date) is a legitimate edit, and
+    // `withSystemPrompt` leaves such a def exactly as the author built it.
+    const trimmed = promptFile.trim();
+    // Not vacuous: `toContain("")` would pass over an empty file, so the file
+    // having text in it is asserted before it is used as the needle.
+    expect(trimmed).not.toBe("");
+    expect(toAgentConfig(agentDef).systemPrompt).toContain(trimmed);
+  });
+
+  test("can search the web, and names no web tool it does not have", () => {
+    const config = toAgentConfig(agentDef);
+    const declared = new Set<string>(config.builtinTools ?? []);
+
+    // `web_search` is the template's reason to exist, and dropping it is the
+    // silent failure: an agent with no search answers from memory, which reads
+    // back exactly like an agent that searched — right up to the fabricated
+    // source its eval exists to catch.
+    expect([...declared]).toContain("web_search");
+
+    // The prompt addresses its tools BY NAME ("begins with a web_search call",
+    // "Use visit_webpage when the search snippets aren't detailed enough"), so
+    // the two halves can drift apart: a builtin dropped from `agent.ts` leaves
+    // the prompt ordering a call the model cannot make, and the model then
+    // apologizes for a tool it was told it had. Stated as an implication so
+    // either edit alone survives — retire the sentence along with the builtin
+    // and nothing here objects, and a builtin added without a mention is a
+    // free edit too. An empty scan is likewise not a failure: a prompt
+    // rewritten to DESCRIBE the tools rather than name them is fine, and the
+    // assertion above is what keeps the search itself from going away.
+    const named = WEB_BUILTINS.filter((name) => config.systemPrompt.includes(name));
+    expect(named.filter((name) => !declared.has(name))).toEqual([]);
+  });
+
+  test("the web builtins this spec scans for are the SDK's own names", () => {
+    // The other half of the `as const` above, at run time: a scan whose
+    // candidates had gone stale would report "no unbacked names" over a prompt
+    // full of them. `toAgentConfig` validates `builtinTools` against the
+    // builtin enum, so accepting the whole list is the SDK confirming every
+    // name in it.
+    expect(() => toAgentConfig({ ...agentDef, builtinTools: WEB_BUILTINS })).not.toThrow();
+  });
+});

package/dist/worker-bundler.d.ts

@@ -34,4 +34,4 @@ export type BuildWorkerOptions = {
  * @internal — build hook for aai-server/the studio; not a supported public
  * API and not covered by semver.
  */
-export declare function buildWorker(cwd: string, opts?: BuildWorkerOptions): Promise<string>;
+export declare function buildWorker(cwd: string, options?: BuildWorkerOptions): Promise<string>;

package/dist/worker-bundler.mjs

@@ -92,8 +92,8 @@ export const __aaiConfig = {
   ...toAgentConfig(__aaiAgent),
   toolSchemas: agentToolsToSchemas(__aaiAgent.tools ?? {}),
 };
-${runtime ? `export const __aaiCreateRuntime = (opts: Record<string, unknown>) =>
-  createRuntime({ ...opts, agent: __aaiAgent });
+${runtime ? `export const __aaiCreateRuntime = (options: Record<string, unknown>) =>
+  createRuntime({ ...options, agent: __aaiAgent });
 ` : ""}`;
 }
 /**
@@ -105,21 +105,21 @@ ${runtime ? `export const __aaiCreateRuntime = (opts: Record<string, unknown>) =
 * @internal — build hook for aai-server/the studio; not a supported public
 * API and not covered by semver.
 */
-async function buildWorker(cwd, opts = {}) {
+async function buildWorker(cwd, options = {}) {
 	const wrapperPath = path.join(cwd, WRAPPER_ENTRY_REL);
 	const [, toolFiles, systemPromptFile] = await Promise.all([
 		fs.mkdir(path.dirname(wrapperPath), { recursive: true }),
 		discoverToolFiles(cwd),
 		hasSystemPromptFile(cwd)
 	]);
-	await fs.writeFile(wrapperPath, wrapperEntrySource(opts.runtime !== false, toolFiles, systemPromptFile), "utf-8");
-	const plugins = opts.plugins ?? [];
+	await fs.writeFile(wrapperPath, wrapperEntrySource(options.runtime !== false, toolFiles, systemPromptFile), "utf-8");
+	const plugins = options.plugins ?? [];
 	let result;
 	try {
 		result = await withPreservedNodeEnv(() => build({
 			root: cwd,
 			logLevel: "silent",
-			...opts.configFile === false && { configFile: false },
+			...options.configFile === false && { configFile: false },
 			...plugins.length > 0 && { plugins },
 			ssr: { noExternal: true },
 			build: {
@@ -130,7 +130,7 @@ async function buildWorker(cwd, opts = {}) {
 					fileName: "worker"
 				},
 				target: "node20",
-				minify: opts.minify ? "oxc" : false,
+				minify: options.minify ? "oxc" : false,
 				write: false,
 				rollupOptions: { output: {
 					entryFileNames: "[name].js",