@alexkroman1/aai-cli 5.14.0 → 6.1.0

package/dist/templates/dispatch-center/tools/incident_update_status.ts

@@ -1,8 +1,8 @@
-import { isToolFailure, tool } from "@alexkroman1/aai";
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { assertNotResolved, dispatchSlot, findIncident, logEvent } from "../shared.ts";
 
-export const incidentUpdateStatus = tool({
+export default dispatchSlot.updateTool({
   description: "Update an incident's status (en_route, on_scene, resolved, escalated).",
   inputSchema: z.object({
     incidentId: z.string().max(20).describe("The incident ID"),
@@ -16,53 +16,51 @@ export const incidentUpdateStatus = tool({
       .describe("Updated casualty numbers")
       .optional(),
   }),
-  async execute(args, ctx) {
-    return dispatchSlot.update(ctx, (state) => {
-      const inc = findIncident(state, args.incidentId);
-      if (isToolFailure(inc)) return inc;
-      const blocked = assertNotResolved(inc, `set status to ${args.status}`);
-      if (blocked) return blocked;
+  execute(args, state) {
+    const inc = findIncident(state, args.incidentId);
+    if (isToolFailure(inc)) return inc;
+    const blocked = assertNotResolved(inc, `set status to ${args.status}`);
+    if (blocked) return blocked;
 
-      inc.status = args.status;
-      logEvent(inc, `Status → ${args.status}${args.notes ? `: ${args.notes}` : ""}`);
+    inc.status = args.status;
+    logEvent(inc, `Status → ${args.status}${args.notes ? `: ${args.notes}` : ""}`);
 
-      if (args.casualtyUpdate) {
-        if (args.casualtyUpdate.confirmed !== undefined) {
-          inc.casualties.confirmed = args.casualtyUpdate.confirmed;
-        }
-        if (args.casualtyUpdate.treated !== undefined) {
-          inc.casualties.treated = args.casualtyUpdate.treated;
-        }
+    if (args.casualtyUpdate) {
+      if (args.casualtyUpdate.confirmed !== undefined) {
+        inc.casualties.confirmed = args.casualtyUpdate.confirmed;
       }
+      if (args.casualtyUpdate.treated !== undefined) {
+        inc.casualties.treated = args.casualtyUpdate.treated;
+      }
+    }
 
-      // Only touch resources still assigned to THIS incident — a unit that
-      // radioed available and was re-dispatched elsewhere belongs to its
-      // new incident now.
-      const ownResources = state.resources.filter((r) => r.assignedIncident === inc.id);
+    // Only touch resources still assigned to THIS incident — a unit that
+    // radioed available and was re-dispatched elsewhere belongs to its
+    // new incident now.
+    const ownResources = state.resources.filter((r) => r.assignedIncident === inc.id);
 
-      if (args.status === "resolved") {
-        for (const r of ownResources) {
-          r.status = "returning";
-          r.assignedIncident = null;
-          r.eta = null;
-        }
-        inc.assignedResources = [];
-        logEvent(inc, "All resources released — incident closed");
+    if (args.status === "resolved") {
+      for (const r of ownResources) {
+        r.status = "returning";
+        r.assignedIncident = null;
+        r.eta = null;
       }
+      inc.assignedResources = [];
+      logEvent(inc, "All resources released — incident closed");
+    }
 
-      if (args.status === "en_route" || args.status === "on_scene") {
-        for (const r of ownResources) {
-          r.status = args.status;
-          if (args.status === "on_scene") r.eta = null;
-        }
+    if (args.status === "en_route" || args.status === "on_scene") {
+      for (const r of ownResources) {
+        r.status = args.status;
+        if (args.status === "on_scene") r.eta = null;
       }
+    }
 
-      return {
-        incidentId: args.incidentId,
-        newStatus: args.status,
-        timeline: inc.timeline.slice(-5).map((t) => t.event),
-        casualties: inc.casualties,
-      };
-    });
+    return {
+      incidentId: args.incidentId,
+      newStatus: args.status,
+      timeline: inc.timeline.slice(-5).map((t) => t.event),
+      casualties: inc.casualties,
+    };
   },
 });

package/dist/templates/dispatch-center/tools/ops_dashboard.ts

@@ -1,12 +1,9 @@
-import { tool } from "@alexkroman1/aai";
 import { dispatchSlot, incidentAgeMinutes, resourceBrief, resourceUtilization } from "../shared.ts";
 
-export const opsDashboard = tool({
+export default dispatchSlot.tool({
   description:
     "Get the full operational dashboard: alert level, resource utilization, active incidents, and available resources.",
-  async execute(_args, ctx) {
-    const state = dispatchSlot.get(ctx);
-
+  execute(_args, state) {
     const activeIncidents = Object.values(state.incidents)
       .filter((i) => i.status !== "resolved")
       .sort((a, b) => b.triageScore - a.triageScore);

package/dist/templates/dispatch-center/tools/ops_protocols.ts

@@ -2,7 +2,7 @@ import { tool } from "@alexkroman1/aai";
 import { z } from "zod";
 import { getApplicableProtocols, INCIDENT_TYPES, SEVERITIES } from "../shared.ts";
 
-export const opsProtocols = tool({
+export default tool({
   description: "Look up step-by-step response protocols for a given incident type and severity.",
   inputSchema: z.object({
     incidentType: z.enum(INCIDENT_TYPES).describe("Type of incident"),

package/dist/templates/dispatch-center/tools/ops_run_scenario.ts

@@ -1,4 +1,3 @@
-import { tool } from "@alexkroman1/aai";
 import { z } from "zod";
 import type { Incident, IncidentType, Severity } from "../shared.ts";
 import { calculateTriageScore, createIncident, dispatchSlot } from "../shared.ts";
@@ -117,33 +116,31 @@ const scenarios = {
 type ScenarioName = keyof typeof scenarios;
 const SCENARIO_NAMES = Object.keys(scenarios) as [ScenarioName, ...ScenarioName[]];
 
-export const opsRunScenario = tool({
+export default dispatchSlot.updateTool({
   description: "Run a training scenario that creates simulated incidents for dispatch practice.",
   inputSchema: z.object({
     scenario: z.enum(SCENARIO_NAMES).describe("Scenario type to simulate"),
   }),
-  async execute(args, ctx) {
-    return dispatchSlot.update(ctx, (state) => {
-      const s = scenarios[args.scenario];
+  execute(args, state) {
+    const s = scenarios[args.scenario];
 
-      const created: string[] = [];
-      for (const scenarioInc of s.incidents) {
-        const fullInc = createIncident(state, {
-          ...scenarioInc,
-          callerName: "Scenario",
-          callerPhone: "N/A",
-          triageScore: calculateTriageScore(scenarioInc.severity, scenarioInc.type, 0, 0),
-          timeline: [{ time: Date.now(), event: `SCENARIO: ${scenarioInc.description}` }],
-        });
-        created.push(fullInc.id);
-      }
+    const created: string[] = [];
+    for (const scenarioInc of s.incidents) {
+      const fullInc = createIncident(state, {
+        ...scenarioInc,
+        callerName: "Scenario",
+        callerPhone: "N/A",
+        triageScore: calculateTriageScore(scenarioInc.severity, scenarioInc.type, 0, 0),
+        timeline: [{ time: Date.now(), event: `SCENARIO: ${scenarioInc.description}` }],
+      });
+      created.push(fullInc.id);
+    }
 
-      return {
-        scenario: args.scenario,
-        narrative: s.narrative,
-        incidentsCreated: created,
-        message: `SCENARIO ACTIVE: ${s.narrative}. ${created.length} incidents created. Awaiting dispatch orders.`,
-      };
-    });
+    return {
+      scenario: args.scenario,
+      narrative: s.narrative,
+      incidentsCreated: created,
+      message: `SCENARIO ACTIVE: ${s.narrative}. ${created.length} incidents created. Awaiting dispatch orders.`,
+    };
   },
 });

package/dist/templates/dispatch-center/tools/resources_dispatch.ts

@@ -1,4 +1,4 @@
-import { isToolFailure, tool } from "@alexkroman1/aai";
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import type { Resource } from "../shared.ts";
 import {
@@ -9,7 +9,7 @@ import {
   recommendResources,
 } from "../shared.ts";
 
-export const resourcesDispatch = tool({
+export default dispatchSlot.updateTool({
   description:
     "Dispatch units to an incident. Can auto-dispatch recommended resources or manually specify callsigns.",
   inputSchema: z.object({
@@ -30,68 +30,66 @@ export const resourcesDispatch = tool({
       .describe("Dispatch priority — affects simulated ETA")
       .optional(),
   }),
-  async execute(args, ctx) {
-    return dispatchSlot.update(ctx, (state) => {
-      const inc = findIncident(state, args.incidentId);
-      if (isToolFailure(inc)) return inc;
-      const blocked = assertNotResolved(inc, "dispatch resources");
-      if (blocked) return blocked;
+  execute(args, state) {
+    const inc = findIncident(state, args.incidentId);
+    if (isToolFailure(inc)) return inc;
+    const blocked = assertNotResolved(inc, "dispatch resources");
+    if (blocked) return blocked;
 
-      const dispatched: { callsign: string; type: string; eta: number }[] = [];
-      const failed: { callsign: string; reason: string }[] = [];
+    const dispatched: { callsign: string; type: string; eta: number }[] = [];
+    const failed: { callsign: string; reason: string }[] = [];
 
-      // The literal "auto" callsign means the same thing as autoDispatch.
-      const wantsAuto =
-        args.autoDispatch || args.callsigns?.some((cs) => cs.toLowerCase() === "auto");
+    // The literal "auto" callsign means the same thing as autoDispatch.
+    const wantsAuto =
+      args.autoDispatch || args.callsigns?.some((cs) => cs.toLowerCase() === "auto");
 
-      let resourcesToDispatch: Resource[] = [];
+    let resourcesToDispatch: Resource[] = [];
 
-      if (wantsAuto) {
-        resourcesToDispatch = recommendResources(inc.type, inc.severity, state);
-      } else if (args.callsigns) {
-        for (const cs of args.callsigns) {
-          const r = state.resources.find((r) => r.callsign.toLowerCase() === cs.toLowerCase());
-          if (!r) {
-            failed.push({ callsign: cs, reason: "Not found" });
-            continue;
-          }
-          if (r.status !== "available") {
-            failed.push({ callsign: cs, reason: `Currently ${r.status}` });
-            continue;
-          }
-          resourcesToDispatch.push(r);
+    if (wantsAuto) {
+      resourcesToDispatch = recommendResources(inc.type, inc.severity, state);
+    } else if (args.callsigns) {
+      for (const cs of args.callsigns) {
+        const r = state.resources.find((r) => r.callsign.toLowerCase() === cs.toLowerCase());
+        if (!r) {
+          failed.push({ callsign: cs, reason: "Not found" });
+          continue;
         }
+        if (r.status !== "available") {
+          failed.push({ callsign: cs, reason: `Currently ${r.status}` });
+          continue;
+        }
+        resourcesToDispatch.push(r);
       }
+    }
 
-      const etaBase = args.priority === "emergency" ? 3 : args.priority === "priority" ? 6 : 10;
+    const etaBase = args.priority === "emergency" ? 3 : args.priority === "priority" ? 6 : 10;
 
-      for (const r of resourcesToDispatch) {
-        const eta = etaBase + Math.floor(Math.random() * 5);
-        r.status = "dispatched";
-        r.assignedIncident = args.incidentId;
-        r.eta = eta;
-        inc.assignedResources.push(r.id);
-        dispatched.push({ callsign: r.callsign, type: r.type, eta });
-        logEvent(inc, `Dispatched ${r.callsign} — ETA ${eta} min`);
-      }
+    for (const r of resourcesToDispatch) {
+      const eta = etaBase + Math.floor(Math.random() * 5);
+      r.status = "dispatched";
+      r.assignedIncident = args.incidentId;
+      r.eta = eta;
+      inc.assignedResources.push(r.id);
+      dispatched.push({ callsign: r.callsign, type: r.type, eta });
+      logEvent(inc, `Dispatched ${r.callsign} — ETA ${eta} min`);
+    }
 
-      if (dispatched.length > 0) {
-        inc.status = "dispatched";
-      }
+    if (dispatched.length > 0) {
+      inc.status = "dispatched";
+    }
 
-      const availableCount = state.resources.filter((r) => r.status === "available").length;
+    const availableCount = state.resources.filter((r) => r.status === "available").length;
 
-      return {
-        incidentId: args.incidentId,
-        dispatched,
-        failed: failed.length > 0 ? failed : undefined,
-        totalAssignedToIncident: inc.assignedResources.length,
-        remainingAvailableResources: availableCount,
-        capacityWarning:
-          availableCount <= 3
-            ? "WARNING: Resource capacity critically low. Consider mutual aid."
-            : undefined,
-      };
-    });
+    return {
+      incidentId: args.incidentId,
+      dispatched,
+      failed: failed.length > 0 ? failed : undefined,
+      totalAssignedToIncident: inc.assignedResources.length,
+      remainingAvailableResources: availableCount,
+      capacityWarning:
+        availableCount <= 3
+          ? "WARNING: Resource capacity critically low. Consider mutual aid."
+          : undefined,
+    };
   },
 });

package/dist/templates/dispatch-center/tools/resources_get_available.ts

@@ -1,8 +1,7 @@
-import { tool } from "@alexkroman1/aai";
 import { z } from "zod";
 import { dispatchSlot, RESOURCE_TYPES } from "../shared.ts";
 
-export const resourcesGetAvailable = tool({
+export default dispatchSlot.tool({
   description: "List available resources, optionally filtered by type.",
   inputSchema: z.object({
     type: z
@@ -10,8 +9,7 @@ export const resourcesGetAvailable = tool({
       .describe("Filter by resource type, or 'all'")
       .optional(),
   }),
-  async execute(args, ctx) {
-    const state = dispatchSlot.get(ctx);
+  execute(args, state) {
     let resources = state.resources;
     if (args.type && args.type !== "all") {
       resources = resources.filter((r) => r.type === args.type);

package/dist/templates/dispatch-center/tools/resources_update_status.ts

@@ -1,62 +1,59 @@
-import { tool } from "@alexkroman1/aai";
 import { z } from "zod";
 import { dispatchSlot, logEvent, RESOURCE_STATUSES } from "../shared.ts";
 
-export const resourcesUpdateStatus = tool({
+export default dispatchSlot.updateTool({
   description: "Update a resource unit's status when it radios in.",
   inputSchema: z.object({
     callsign: z.string().max(50).describe("The resource callsign"),
     status: z.enum(RESOURCE_STATUSES).describe("New status"),
     notes: z.string().max(1000).describe("Status notes").optional(),
   }),
-  async execute(args, ctx) {
-    return dispatchSlot.update(ctx, (state) => {
-      const resource = state.resources.find(
-        (r) => r.callsign.toLowerCase() === args.callsign.toLowerCase(),
-      );
-      if (!resource) {
-        return { error: `Resource ${args.callsign} not found` };
+  execute(args, state) {
+    const resource = state.resources.find(
+      (r) => r.callsign.toLowerCase() === args.callsign.toLowerCase(),
+    );
+    if (!resource) {
+      return { error: `Resource ${args.callsign} not found` };
+    }
+
+    const previousStatus = resource.status;
+
+    // Log to the incident timeline BEFORE unassigning, so the
+    // return-to-available transition is recorded too.
+    if (resource.assignedIncident) {
+      const inc = state.incidents[resource.assignedIncident];
+      if (inc) {
+        logEvent(
+          inc,
+          `${resource.callsign}: ${previousStatus} → ${args.status}${args.notes ? ` (${args.notes})` : ""}`,
+        );
       }
+    }
 
-      const previousStatus = resource.status;
+    resource.status = args.status;
 
-      // Log to the incident timeline BEFORE unassigning, so the
-      // return-to-available transition is recorded too.
+    if (args.status === "available") {
+      // Detach from the old incident on BOTH sides — leaving the id in
+      // assignedResources lets that incident later yank a unit that has
+      // been re-dispatched elsewhere.
       if (resource.assignedIncident) {
         const inc = state.incidents[resource.assignedIncident];
         if (inc) {
-          logEvent(
-            inc,
-            `${resource.callsign}: ${previousStatus} → ${args.status}${args.notes ? ` (${args.notes})` : ""}`,
-          );
+          inc.assignedResources = inc.assignedResources.filter((id) => id !== resource.id);
         }
       }
+      resource.assignedIncident = null;
+      resource.eta = null;
+    }
+    if (args.status === "on_scene") {
+      resource.eta = null;
+    }
 
-      resource.status = args.status;
-
-      if (args.status === "available") {
-        // Detach from the old incident on BOTH sides — leaving the id in
-        // assignedResources lets that incident later yank a unit that has
-        // been re-dispatched elsewhere.
-        if (resource.assignedIncident) {
-          const inc = state.incidents[resource.assignedIncident];
-          if (inc) {
-            inc.assignedResources = inc.assignedResources.filter((id) => id !== resource.id);
-          }
-        }
-        resource.assignedIncident = null;
-        resource.eta = null;
-      }
-      if (args.status === "on_scene") {
-        resource.eta = null;
-      }
-
-      return {
-        callsign: resource.callsign,
-        previousStatus,
-        newStatus: args.status,
-        assignedIncident: resource.assignedIncident,
-      };
-    });
+    return {
+      callsign: resource.callsign,
+      previousStatus,
+      newStatus: args.status,
+      assignedIncident: resource.assignedIncident,
+    };
   },
 });

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

@@ -0,0 +1,83 @@
+/// <reference types="vite/client" />
+
+import type { ToolContext } from "@alexkroman1/aai";
+import { createToolContext, runTool, withDiscoveredTools } 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 }),
+);
+
+const run = (name: string, args: Record<string, unknown>, ctx: ToolContext) =>
+  runTool(agentDef, name, args, ctx);
+
+describe("embedded-assets template", () => {
+  test("the JSON asset really is bundled, and the index is built from it", () => {
+    // The template's whole subject: an asset imported with an import attribute,
+    // resolved at build time rather than fetched. An empty knowledge base would
+    // make every search below trivially "not found".
+    expect(faqs.length).toBeGreaterThan(0);
+    expect(searchable).toHaveLength(faqs.length);
+    for (const entry of faqs) {
+      expect(entry.question).toBeTypeOf("string");
+      expect(entry.answer).toBeTypeOf("string");
+    }
+  });
+
+  test("both tools are discovered from tools/", () => {
+    // `agent()` takes no `tools` field: a file in `tools/` IS the tool, and
+    // nothing imports it. Discovery is what puts it in front of the model, so a
+    // template whose tools are never resolved ships a model with no tools.
+    expect(Object.keys(agentDef.tools ?? {}).sort()).toEqual(["list_topics", "search_knowledge"]);
+  });
+});
+
+describe("list_topics", () => {
+  test("answers with every question in the knowledge base", async () => {
+    const topics = await run("list_topics", {}, createToolContext());
+    expect(topics).toEqual(faqs.map((f) => f.question));
+  });
+});
+
+describe("search_knowledge", () => {
+  test("scores by word overlap rather than by substring", async () => {
+    // The reason the tool does not just `includes()` the query: a caller asks a
+    // natural question, which is never a substring of an FAQ entry.
+    const target = faqs[0];
+    if (!target) throw new Error("the knowledge base is empty");
+    const words = target.question
+      .toLowerCase()
+      .split(/\W+/)
+      .filter((w) => w.length > 2);
+    const result = await run(
+      "search_knowledge",
+      { query: `hey, could you tell me ${words.join(" ")}?` },
+      createToolContext(),
+    );
+    expect(result).toEqual(target);
+  });
+
+  test("a query with no words longer than two characters is refused early", async () => {
+    // The guard before the scan: with no scoreable words every entry ties at
+    // zero, and returning the first one would be an answer to nothing.
+    expect(await run("search_knowledge", { query: "is it a" }, createToolContext())).toEqual({
+      result: "No matching FAQ found.",
+    });
+  });
+
+  test("a query that overlaps nothing reports no match rather than guessing", async () => {
+    expect(
+      await run("search_knowledge", { query: "zzzqqq wibbleflange" }, createToolContext()),
+    ).toEqual({ result: "No matching FAQ found." });
+  });
+});

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

@@ -1,54 +1,7 @@
-import { agent, tool } from "@alexkroman1/aai";
-import { z } from "zod";
-import knowledge from "./knowledge.json" with { type: "json" };
-
-type FaqEntry = { question: string; answer: string };
-const faqs: FaqEntry[] = knowledge.faqs;
-
-// Search text is static, so it's normalized once at module load — per-call
-// work stays O(query) even when the knowledge base grows.
-const searchable = faqs.map((entry) => ({
-  entry,
-  text: `${entry.question} ${entry.answer}`.toLowerCase(),
-}));
+import { agent } from "@alexkroman1/aai";
 
 export default agent({
   name: "FAQ Bot",
-  systemPrompt:
-    "You are a friendly FAQ assistant. Answer questions using ONLY the information from your embedded knowledge base. If the user asks something not covered by your knowledge base, say you don't have that information and suggest they check the official documentation.\n\nRules:\n- Keep answers concise and conversational — this is a voice agent\n- Quote the knowledge base accurately, do not embellish\n- If a question is ambiguous, ask the user to clarify\n- Use 'search_knowledge' to find answers to specific questions\n- Use 'list_topics' to see all available FAQ topics\n- Always be helpful and polite",
   greeting:
     "Hi! I'm your FAQ assistant. Ask me anything about the AAI agent framework and I'll look it up in my knowledge base.",
-
-  tools: {
-    list_topics: tool({
-      description: "List all available topics in the embedded FAQ knowledge base.",
-      async execute() {
-        return faqs.map((f) => f.question);
-      },
-    }),
-
-    search_knowledge: tool({
-      description:
-        "Search the embedded FAQ knowledge base for an answer matching the user's question.",
-      inputSchema: z.object({
-        query: z.string().describe("The user's question to search for"),
-      }),
-      async execute(args) {
-        // Score by word overlap — natural questions rarely match an FAQ
-        // entry as an exact substring.
-        const words = args.query
-          .toLowerCase()
-          .split(/\W+/)
-          .filter((w) => w.length > 2);
-        if (words.length === 0) return { result: "No matching FAQ found." };
-
-        let best: { entry: FaqEntry; score: number } | null = null;
-        for (const { entry, text } of searchable) {
-          const score = words.filter((w) => text.includes(w)).length;
-          if (score > 0 && (!best || score > best.score)) best = { entry, score };
-        }
-        return best?.entry ?? { result: "No matching FAQ found." };
-      },
-    }),
-  },
 });

package/dist/templates/embedded-assets/shared.ts

@@ -0,0 +1,17 @@
+import knowledge from "./knowledge.json" with { type: "json" };
+
+export type FaqEntry = { question: string; answer: string };
+
+export const faqs: FaqEntry[] = knowledge.faqs;
+
+/**
+ * The searchable index, built once at module load.
+ *
+ * Search text is static, so normalizing it here keeps per-call work O(query)
+ * even when the knowledge base grows — and both tools import this module, so
+ * the index is built once for the process rather than once per tool.
+ */
+export const searchable = faqs.map((entry) => ({
+  entry,
+  text: `${entry.question} ${entry.answer}`.toLowerCase(),
+}));

package/dist/templates/embedded-assets/system-prompt.md

@@ -0,0 +1,13 @@
+You are a friendly FAQ assistant. Answer questions using ONLY the information
+from your embedded knowledge base. If the user asks something not covered by
+your knowledge base, say you don't have that information and suggest they check
+the official documentation.
+
+Rules:
+
+- Keep answers concise and conversational — this is a voice agent
+- Quote the knowledge base accurately, do not embellish
+- If a question is ambiguous, ask the user to clarify
+- Use 'search_knowledge' to find answers to specific questions
+- Use 'list_topics' to see all available FAQ topics
+- Always be helpful and polite

package/dist/templates/embedded-assets/tools/list_topics.ts

@@ -0,0 +1,9 @@
+import { tool } from "@alexkroman1/aai";
+import { faqs } from "../shared.ts";
+
+export default tool({
+  description: "List all available topics in the embedded FAQ knowledge base.",
+  async execute() {
+    return faqs.map((f) => f.question);
+  },
+});

package/dist/templates/embedded-assets/tools/search_knowledge.ts

@@ -0,0 +1,26 @@
+import { tool } from "@alexkroman1/aai";
+import { z } from "zod";
+import { type FaqEntry, searchable } from "../shared.ts";
+
+export default tool({
+  description: "Search the embedded FAQ knowledge base for an answer matching the user's question.",
+  inputSchema: z.object({
+    query: z.string().describe("The user's question to search for"),
+  }),
+  async execute(args) {
+    // Score by word overlap — natural questions rarely match an FAQ
+    // entry as an exact substring.
+    const words = args.query
+      .toLowerCase()
+      .split(/\W+/)
+      .filter((w) => w.length > 2);
+    if (words.length === 0) return { result: "No matching FAQ found." };
+
+    let best: { entry: FaqEntry; score: number } | null = null;
+    for (const { entry, text } of searchable) {
+      const score = words.filter((w) => text.includes(w)).length;
+      if (score > 0 && (!best || score > best.score)) best = { entry, score };
+    }
+    return best?.entry ?? { result: "No matching FAQ found." };
+  },
+});