@alexkroman1/aai-cli 5.13.2 → 6.1.0

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." };
+  },
+});

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

@@ -0,0 +1,169 @@
+/// <reference types="vite/client" />
+
+import { isToolFailure, type ToolContext } from "@alexkroman1/aai";
+import { createToolContext, runTool, withDiscoveredTools } 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";
+
+/**
+ * Only the NETWORK half of `fda.ts` is faked.
+ *
+ * `fetchFdaLabel` is the one function in this template that leaves the process,
+ * so it is the one thing a unit test may not run — everything the tools are
+ * actually about (the cross-mention scan, the refuse-on-a-missing-drug rule,
+ * the field folding) is pure and stays real. `importActual` rather than a whole
+ * module stub for exactly that reason: a fully mocked `fda.ts` would leave
+ * `toDrugInfo` returning `undefined` and the tools passing over nothing.
+ */
+vi.mock("./fda.ts", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("./fda.ts")>()),
+  fetchFdaLabel: vi.fn(),
+}));
+
+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 }),
+);
+
+const run = (name: string, args: Record<string, unknown>, ctx: ToolContext = createToolContext()) =>
+  runTool(agentDef, name, args, ctx);
+
+const IBUPROFEN: FdaLabel = {
+  openfda: { generic_name: ["IBUPROFEN"], brand_name: ["Advil"], manufacturer_name: ["Acme"] },
+  purpose: ["Pain reliever"],
+  warnings: ["Stomach bleeding warning"],
+  dosage_and_administration: ["One tablet every 6 hours"],
+  adverse_reactions: ["Nausea"],
+  drug_interactions: ["Ask a doctor before use if taking WARFARIN, a blood thinner."],
+};
+
+const WARFARIN: FdaLabel = {
+  openfda: { generic_name: ["WARFARIN SODIUM"], brand_name: ["Coumadin"] },
+  purpose: ["Anticoagulant"],
+};
+
+beforeEach(() => {
+  // `restoreMocks` restores `vi.spyOn` mocks; it does not clear a `vi.fn()`'s
+  // history or its implementation, so an implementation set by one test would
+  // otherwise still be installed in the next.
+  label.mockReset();
+});
+
+describe("health-assistant template", () => {
+  test("both tools are discovered from tools/", () => {
+    // `agent()` takes no `tools` field: a file in `tools/` IS the tool. A
+    // template whose tools are never resolved ships a model with none.
+    expect(Object.keys(agentDef.tools ?? {}).sort()).toEqual([
+      "check_drug_interaction",
+      "medication_lookup",
+    ]);
+  });
+});
+
+describe("medication_lookup", () => {
+  test("folds the label's array fields into one flat answer", async () => {
+    label.mockResolvedValue(IBUPROFEN);
+    const result = await run("medication_lookup", { name: "advil" });
+    expect(result).toMatchObject({
+      name: "IBUPROFEN",
+      brand_names: ["Advil"],
+      purpose: "Pain reliever",
+      manufacturer: "Acme",
+    });
+  });
+
+  test("an unknown drug is a tool FAILURE, not an empty answer", async () => {
+    // The model has to be able to tell "no such drug" from "a drug with no
+    // warnings", which is why this is a failure rather than a record of "N/A".
+    label.mockResolvedValue(null);
+    const result = await run("medication_lookup", { name: "sparkleforin" });
+    expect(isToolFailure(result) && result.error).toContain("sparkleforin");
+  });
+
+  test("a missing section reads N/A rather than undefined", async () => {
+    label.mockResolvedValue(WARFARIN);
+    expect(await run("medication_lookup", { name: "warfarin" })).toMatchObject({
+      warnings: "N/A",
+      dosage: "N/A",
+      side_effects: "N/A",
+      manufacturer: "N/A",
+    });
+  });
+});
+
+describe("check_drug_interaction", () => {
+  test("reports a cross-mention with the excerpt that justifies it", async () => {
+    label.mockImplementation(async (name: string) =>
+      name.includes("ibuprofen") ? IBUPROFEN : WARFARIN,
+    );
+    const result = await run("check_drug_interaction", { drugs: ["ibuprofen", "warfarin"] });
+    expect(result).toMatchObject({ interactions_found: 1 });
+    const [first] = (result as { interactions: { drug: string; mentions: string }[] }).interactions;
+    expect(first).toMatchObject({ drug: "ibuprofen", mentions: "warfarin" });
+  });
+
+  test("matches on a BRAND alias, not only the name the caller used", async () => {
+    // `toDrugInfo` folds generic and brand names into one alias list precisely
+    // so a label naming "Coumadin" still matches a caller who said "warfarin".
+    const coumadinMention: FdaLabel = {
+      openfda: { generic_name: ["IBUPROFEN"] },
+      drug_interactions: ["Do not combine with COUMADIN."],
+    };
+    label.mockImplementation(async (name: string) =>
+      name.includes("ibuprofen") ? coumadinMention : WARFARIN,
+    );
+    const result = await run("check_drug_interaction", { drugs: ["ibuprofen", "warfarin"] });
+    expect(result).toMatchObject({ interactions_found: 1 });
+  });
+
+  test("a drug that cannot be resolved REFUSES the whole check", async () => {
+    // The rule that makes this tool safe to have: a partial answer would read
+    // as "no interaction" for the drug that was silently dropped.
+    label.mockImplementation(async (name: string) =>
+      name.includes("ibuprofen") ? IBUPROFEN : null,
+    );
+    const result = await run("check_drug_interaction", { drugs: ["ibuprofen", "sparkleforin"] });
+    expect(isToolFailure(result) && result.error).toContain("sparkleforin");
+  });
+
+  test("two drugs with no cross-mention are reported as such, with the caveat", async () => {
+    label.mockResolvedValue(WARFARIN);
+    const result = await run("check_drug_interaction", { drugs: ["warfarin", "aspirin"] });
+    expect(result).toMatchObject({ interactions_found: 0 });
+    expect((result as { note: string }).note).toContain("does not guarantee");
+  });
+
+  test("whitespace-only names are refused before any lookup happens", async () => {
+    // The schema's `min(2)` counts entries, not real names, so the body
+    // re-checks after trimming — and must do so BEFORE touching the network.
+    const result = await run("check_drug_interaction", { drugs: ["ibuprofen", "   "] });
+    expect(isToolFailure(result) && result.error).toContain("at least two");
+    expect(label).not.toHaveBeenCalled();
+  });
+});
+
+describe("fda.ts helpers", () => {
+  test("toDrugInfo lowercases every alias so cross-matching is case-blind", () => {
+    const info = toDrugInfo("advil", IBUPROFEN);
+    expect(info.aliases).toEqual(["advil", "ibuprofen"]);
+    expect(info.interactionsText).toContain("warfarin");
+  });
+
+  test("excerptAround ellipsizes only the ends it actually cut", () => {
+    const text = `${"a".repeat(300)}warfarin${"b".repeat(300)}`;
+    const excerpt = excerptAround(text, "warfarin");
+    expect(excerpt.startsWith("…")).toBe(true);
+    expect(excerpt.endsWith("…")).toBe(true);
+    expect(excerptAround("warfarin", "warfarin")).toBe("warfarin");
+  });
+});

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

@@ -1,173 +1,8 @@
-import { agent, tool } from "@alexkroman1/aai";
-import { z } from "zod";
-import systemPrompt from "./system-prompt.md?raw";
-
-function first(arr: string[] | undefined): string | undefined {
-  return arr?.[0];
-}
-
-type FdaLabel = Record<string, unknown> & { openfda?: Record<string, string[]> };
-
-/**
- * Fetch a drug's FDA label (generic OR brand name match) from openFDA.
- * Returns null when the drug can't be found or the API is unreachable.
- *
- * Memoized per drug name: a voice session naturally asks several questions
- * about the same drugs, and labels are static, so repeats skip the network
- * round-trip. A null result (not found, or a transient network failure) is
- * NOT cached, so the next call retries instead of pinning the failure.
- */
-const labelCache = new Map<string, Promise<FdaLabel | null>>();
-
-function fetchFdaLabel(name: string): Promise<FdaLabel | null> {
-  const key = name.toLowerCase();
-  let p = labelCache.get(key);
-  if (!p) {
-    p = fetchFdaLabelUncached(key).then((label) => {
-      if (label === null) labelCache.delete(key);
-      return label;
-    });
-    labelCache.set(key, p);
-  }
-  return p;
-}
-
-async function fetchFdaLabelUncached(name: string): Promise<FdaLabel | null> {
-  const q = encodeURIComponent(name);
-  try {
-    const resp = await fetch(
-      `https://api.fda.gov/drug/label.json?search=openfda.generic_name:"${q}"+openfda.brand_name:"${q}"&limit=1`,
-    );
-    if (!resp.ok) return null;
-    const raw = (await resp.json()) as { results?: FdaLabel[] };
-    return raw.results?.[0] ?? null;
-  } catch {
-    return null;
-  }
-}
-
-type DrugInfo = {
-  /** The name the user asked about. */
-  name: string;
-  /** All known names, lowercased — generic + brands — used for cross-matching. */
-  aliases: string[];
-  /** The label's "Drug Interactions" section, lowercased. */
-  interactionsText: string;
-};
-
-function toDrugInfo(name: string, label: FdaLabel): DrugInfo {
-  const openfda = label.openfda ?? {};
-  const generic = openfda.generic_name ?? [];
-  const brands = openfda.brand_name ?? [];
-  const aliases = [...new Set([name, ...generic, ...brands].map((n) => n.toLowerCase()))];
-  const interactionsText = ((label.drug_interactions as string[] | undefined) ?? [])
-    .join(" ")
-    .toLowerCase();
-  return { name, aliases, interactionsText };
-}
-
-/** Pull a short excerpt around the first mention of `alias` in `text`. */
-function excerptAround(text: string, alias: string): string {
-  const idx = text.indexOf(alias);
-  const start = Math.max(0, idx - 100);
-  const end = Math.min(text.length, idx + alias.length + 200);
-  return `${start > 0 ? "…" : ""}${text.slice(start, end)}${end < text.length ? "…" : ""}`;
-}
+import { agent } from "@alexkroman1/aai";
 
 export default agent({
   name: "Dr. Sage",
-  systemPrompt,
   greeting:
     "Hey, I'm Dr. Sage. Try asking me something like, what are the side effects of ibuprofen, can I take aspirin and warfarin together, or calculate my BMI. Just remember, I'm not a real doctor, so always check with your healthcare provider.",
   builtinTools: ["web_search", "run_code"],
-
-  tools: {
-    check_drug_interaction: tool({
-      description:
-        "Check for interactions between two or more medications using FDA drug label data. Looks up each drug's official label and reports where one drug's Drug Interactions section mentions another. Absence of a mention does not guarantee safety.",
-      inputSchema: z.object({
-        drugs: z
-          .array(z.string().min(1))
-          .min(2)
-          .describe("Medication names to check, e.g. ['ibuprofen', 'warfarin']"),
-      }),
-      async execute(args) {
-        const names = args.drugs.map((d) => d.trim().toLowerCase()).filter((d) => d.length > 0);
-        if (names.length < 2) {
-          return { error: "Provide at least two medication names to check." };
-        }
-
-        const labels = await Promise.all(names.map((n) => fetchFdaLabel(n)));
-        const unresolved = names.filter((_, i) => labels[i] === null);
-        if (unresolved.length > 0) {
-          // Never silently drop a drug from an interaction check — a partial
-          // answer would read as "no interaction" for the missing one.
-          return {
-            error: `Could not find FDA label data for: ${unresolved.join(", ")}. Check the spelling, or try the generic name.`,
-          };
-        }
-
-        // The unresolved check above guarantees every label resolved.
-        const drugs = names.map((name, i) => toDrugInfo(name, labels[i]!));
-
-        const interactions: Array<{ drug: string; mentions: string; excerpt: string }> = [];
-        for (const a of drugs) {
-          if (!a.interactionsText) continue;
-          for (const b of drugs) {
-            if (a === b) continue;
-            const hit = b.aliases.find((alias) => a.interactionsText.includes(alias));
-            if (hit) {
-              interactions.push({
-                drug: a.name,
-                mentions: b.name,
-                excerpt: excerptAround(a.interactionsText, hit).slice(0, 400),
-              });
-            }
-          }
-        }
-
-        return {
-          drugs: names,
-          interactions_found: interactions.length,
-          interactions: interactions.slice(0, 5),
-          note:
-            interactions.length === 0
-              ? "No cross-mentions found in the FDA label Drug Interactions sections. This does not guarantee the combination is safe — confirm with a pharmacist or doctor."
-              : "Based on FDA label Drug Interactions sections. Confirm with a pharmacist or doctor.",
-        };
-      },
-    }),
-
-    medication_lookup: tool({
-      description:
-        "Look up detailed information about a single medication, including purpose, warnings, dosage, side effects, and manufacturer. Works with both generic and brand names.",
-      inputSchema: z.object({
-        name: z
-          .string()
-          .describe("Medication name (generic or brand, e.g. 'ibuprofen' or 'Advil')"),
-      }),
-      async execute(args) {
-        const drug = await fetchFdaLabel(args.name);
-        if (!drug) {
-          return { error: `No FDA data found for: ${args.name}` };
-        }
-
-        const openfda = drug.openfda ?? {};
-        return {
-          name: openfda.generic_name?.[0] ?? args.name,
-          brand_names: openfda.brand_name ?? [],
-          purpose:
-            first(drug.purpose as string[] | undefined) ??
-            first(drug.indications_and_usage as string[] | undefined) ??
-            "N/A",
-          warnings: first(drug.warnings as string[] | undefined)?.slice(0, 500) ?? "N/A",
-          dosage:
-            first(drug.dosage_and_administration as string[] | undefined)?.slice(0, 500) ?? "N/A",
-          side_effects:
-            first(drug.adverse_reactions as string[] | undefined)?.slice(0, 500) ?? "N/A",
-          manufacturer: openfda.manufacturer_name?.[0] ?? "N/A",
-        };
-      },
-    }),
-  },
 });

package/dist/templates/health-assistant/fda.ts

@@ -0,0 +1,100 @@
+/**
+ * openFDA drug labels, and the one cache both tools read.
+ *
+ * This module exists because the memoization below has to be shared: with a
+ * cache per tool file, a session that looks a drug up and then checks it for
+ * interactions pays the network round-trip twice and the "labels are static"
+ * argument stops being true.
+ */
+
+import { isToolFailure } from "@alexkroman1/aai";
+import { fetchJson } from "@alexkroman1/aai/tools";
+
+export type FdaLabel = Record<string, unknown> & { openfda?: Record<string, string[]> };
+
+export function first(arr: string[] | undefined): string | undefined {
+  return arr?.[0];
+}
+
+/**
+ * Memoized per drug name: a voice session naturally asks several questions
+ * about the same drugs, and labels are static, so repeats skip the network
+ * round-trip. A null result (not found, or a transient network failure) is
+ * NOT cached, so the next call retries instead of pinning the failure.
+ */
+const labelCache = new Map<string, Promise<FdaLabel | null>>();
+
+/**
+ * Fetch a drug's FDA label (generic OR brand name match) from openFDA.
+ * Returns null when the drug can't be found or the API is unreachable.
+ */
+export function fetchFdaLabel(name: string): Promise<FdaLabel | null> {
+  const key = name.toLowerCase();
+  let p = labelCache.get(key);
+  if (!p) {
+    p = fetchFdaLabelUncached(key).then((label) => {
+      if (label === null) labelCache.delete(key);
+      return label;
+    });
+    labelCache.set(key, p);
+  }
+  return p;
+}
+
+/**
+ * One openFDA lookup, through the SDK's own REST call rather than a bare
+ * `fetch`.
+ *
+ * `fetchJson` (`@alexkroman1/aai/tools`) is the same implementation behind the
+ * model-facing `fetch_json` builtin, so this inherits the three things a bare
+ * `fetch` here had none of: a request DEADLINE (`check_drug_interaction` fires
+ * a `Promise.all` over one of these per drug the caller named, and a stalled
+ * one held the whole tool call open for as long as the far side wanted), a
+ * bounded read so an unexpected body cannot be buffered whole, and URL
+ * screening on a developer's own machine under `aai dev`.
+ *
+ * It ANSWERS with `{ error }` rather than throwing for an HTTP failure, which
+ * is the builtin contract — narrowed with `isToolFailure` and folded into the
+ * same `null` this has always returned. The `catch` still earns its keep: a
+ * connection failure, a timeout or a refused URL is a throw.
+ */
+async function fetchFdaLabelUncached(name: string): Promise<FdaLabel | null> {
+  const q = encodeURIComponent(name);
+  try {
+    const raw = await fetchJson<{ results?: FdaLabel[] }>(
+      `https://api.fda.gov/drug/label.json?search=openfda.generic_name:"${q}"+openfda.brand_name:"${q}"&limit=1`,
+    );
+    if (isToolFailure(raw)) return null;
+    return raw.results?.[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+export type DrugInfo = {
+  /** The name the user asked about. */
+  name: string;
+  /** All known names, lowercased — generic + brands — used for cross-matching. */
+  aliases: string[];
+  /** The label's "Drug Interactions" section, lowercased. */
+  interactionsText: string;
+};
+
+export function toDrugInfo(name: string, label: FdaLabel): DrugInfo {
+  const openfda = label.openfda ?? {};
+  const generic = openfda.generic_name ?? [];
+  const brands = openfda.brand_name ?? [];
+  const aliases = [...new Set([name, ...generic, ...brands].map((n) => n.toLowerCase()))];
+  const interactionsText = ((label.drug_interactions as string[] | undefined) ?? [])
+    .join(" ")
+    .toLowerCase();
+  return { name, aliases, interactionsText };
+}
+
+/** Pull a short excerpt around the first mention of `alias` in `text`. */
+export function excerptAround(text: string, alias: string): string {
+  const idx = text.indexOf(alias);
+  const start = Math.max(0, idx - 100);
+  const end = Math.min(text.length, idx + alias.length + 200);
+  return `${start > 0 ? "…" : ""}${text.slice(start, end)}${end < text.length ? "…" : ""}`;
+}