@alexkroman1/aai-cli 5.14.0 → 6.1.0

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 ? "…" : ""}`;
+}

package/dist/templates/health-assistant/tools/check_drug_interaction.ts

@@ -0,0 +1,59 @@
+import { tool, toolFailure } from "@alexkroman1/aai";
+import { z } from "zod";
+import { excerptAround, fetchFdaLabel, toDrugInfo } from "../fda.ts";
+
+export default 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 toolFailure("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 toolFailure(
+        `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.",
+    };
+  },
+});

package/dist/templates/health-assistant/tools/medication_lookup.ts

@@ -0,0 +1,31 @@
+import { tool, toolFailure } from "@alexkroman1/aai";
+import { z } from "zod";
+import { fetchFdaLabel, first } from "../fda.ts";
+
+export default 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 toolFailure(`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",
+    };
+  },
+});