@inflexa-ai/harness 0.1.1

package/dist/tasks/refresh-regulatory-corpus.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Refresh the FDA/ICH regulatory corpus stored in `cortex_regulatory_chunks`.
+ *
+ * Pipeline: list documents → download → extract text → chunk → embed →
+ * upsert into `cortex_regulatory_chunks`. Idempotent at the (source, doc_id)
+ * grain — re-running replaces existing rows.
+ *
+ * Two callers:
+ *   - `scripts/index-regulatory-corpus.ts` — operator-run CLI
+ *   - `regulatory-corpus-boot-refresh.ts` — automatic 90-day-stale boot trigger
+ */
+import type { Pool } from "pg";
+export type RegulatoryCorpusSource = "FDA-CDER" | "FDA-CBER" | "ICH";
+export declare const REGULATORY_CORPUS_SOURCES: RegulatoryCorpusSource[];
+export interface RefreshResult {
+    ok: number;
+    fail: number;
+}
+export interface RefreshOptions {
+    pool: Pool;
+    sources?: RegulatoryCorpusSource[];
+    /**
+     * Embedder used to vectorise chunks. Required — callers must build one
+     * via `buildMaintenanceEmbedder(env)` (direct OpenAI, bypassing the billing gateway)
+     * or supply an injected stub for tests. There is no default: the corpus
+     * refresh is system-scoped maintenance work with no analysis to bill
+     * against, so we never silently fall through to the billing-gateway-routed
+     * `createEmbedder()` and emit unattributed calls.
+     */
+    embedder: (text: string) => Promise<number[]>;
+    /** Logger used for per-doc progress. Defaults to `console`. */
+    log?: Pick<Console, "log" | "error">;
+}
+/**
+ * Build an embedder that talks directly to api.openai.com using the given
+ * `apiKey`, bypassing the billing gateway.
+ *
+ * Returns `null` when `apiKey` is missing — callers MUST treat that as
+ * "auto-refresh disabled" rather than falling back to the workspace
+ * embedder (`workspace/search-config.ts`), which routes through the billing gateway
+ * via `OPENAI_BASE_URL` and would generate unbilled calls outside an ALS
+ * billing scope.
+ *
+ * The model id mirrors the workspace embedder default
+ * (`text-embedding-3-small`, 1536 dim) so chunks remain comparable to the
+ * default `cortex_regulatory_chunks.embedding` shape. Pass the existing
+ * `OPENAI_API_KEY` (a real OpenAI key, NOT a billing-gateway virtual key — direct
+ * calls to api.openai.com would 401 against a `sk-billing-*` value).
+ */
+export declare function buildMaintenanceEmbedder(opts: {
+    apiKey?: string;
+    embeddingModel?: string;
+}): ((text: string) => Promise<number[]>) | null;
+/**
+ * Refresh one or more regulatory corpus sources end-to-end. Returns
+ * aggregate ok/fail counts across all requested sources. Never throws —
+ * per-document failures are counted but do not abort the run.
+ */
+export declare function refreshRegulatoryCorpus(opts: RefreshOptions): Promise<RefreshResult>;

package/dist/tasks/refresh-regulatory-corpus.js

@@ -0,0 +1,146 @@
+/**
+ * Refresh the FDA/ICH regulatory corpus stored in `cortex_regulatory_chunks`.
+ *
+ * Pipeline: list documents → download → extract text → chunk → embed →
+ * upsert into `cortex_regulatory_chunks`. Idempotent at the (source, doc_id)
+ * grain — re-running replaces existing rows.
+ *
+ * Two callers:
+ *   - `scripts/index-regulatory-corpus.ts` — operator-run CLI
+ *   - `regulatory-corpus-boot-refresh.ts` — automatic 90-day-stale boot trigger
+ */
+import { unwrapOrThrow } from "../lib/result.js";
+import { fetchFdaGuidanceListing, fetchAndExtractFdaDoc } from "../lib/regulatory-corpus/fetch-fda-guidance.js";
+import { fetchIchListing, fetchAndExtractIchDoc } from "../lib/regulatory-corpus/fetch-ich.js";
+import { chunkText, upsertChunks } from "../lib/regulatory-corpus.js";
+export const REGULATORY_CORPUS_SOURCES = ["FDA-CDER", "FDA-CBER", "ICH"];
+// A large guidance doc can chunk into 200-500+ pieces. Firing them all at
+// once trips embedding-API rate limits and silently truncates the upserted
+// chunks, so we batch.
+const EMBED_CONCURRENCY = 20;
+/**
+ * Build an embedder that talks directly to api.openai.com using the given
+ * `apiKey`, bypassing the billing gateway.
+ *
+ * Returns `null` when `apiKey` is missing — callers MUST treat that as
+ * "auto-refresh disabled" rather than falling back to the workspace
+ * embedder (`workspace/search-config.ts`), which routes through the billing gateway
+ * via `OPENAI_BASE_URL` and would generate unbilled calls outside an ALS
+ * billing scope.
+ *
+ * The model id mirrors the workspace embedder default
+ * (`text-embedding-3-small`, 1536 dim) so chunks remain comparable to the
+ * default `cortex_regulatory_chunks.embedding` shape. Pass the existing
+ * `OPENAI_API_KEY` (a real OpenAI key, NOT a billing-gateway virtual key — direct
+ * calls to api.openai.com would 401 against a `sk-billing-*` value).
+ */
+export function buildMaintenanceEmbedder(opts) {
+    const { apiKey } = opts;
+    if (!apiKey)
+        return null;
+    // Strip the `openai/` provider prefix if present; we always talk to OpenAI here.
+    const id = opts.embeddingModel ?? "openai/text-embedding-3-small";
+    const modelId = id.startsWith("openai/") ? id.slice("openai/".length) : id;
+    // Direct call to api.openai.com (bypasses the billing gateway) — unbilled maintenance
+    // path. See doc comment above.
+    return async (text) => {
+        const res = await fetch("https://api.openai.com/v1/embeddings", {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({ model: modelId, input: text, encoding_format: "float" }),
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`buildMaintenanceEmbedder: openai /embeddings ${res.status}: ${body}`);
+        }
+        const data = (await res.json());
+        const embedding = data.data?.[0]?.embedding;
+        if (!embedding)
+            throw new Error("buildMaintenanceEmbedder: empty response");
+        return embedding;
+    };
+}
+async function listForSource(source) {
+    switch (source) {
+        case "FDA-CDER":
+            return (await fetchFdaGuidanceListing("CDER")).map((s) => ({
+                ...s,
+                center: "CDER",
+            }));
+        case "FDA-CBER":
+            return (await fetchFdaGuidanceListing("CBER")).map((s) => ({
+                ...s,
+                center: "CBER",
+            }));
+        case "ICH":
+            return await fetchIchListing();
+    }
+}
+async function fetchOne(source, stub) {
+    if (source === "ICH")
+        return await fetchAndExtractIchDoc(stub);
+    return await fetchAndExtractFdaDoc(stub);
+}
+async function indexSource(pool, source, embedder, log) {
+    log.log(`\n=== ${source} ===`);
+    const stubs = await listForSource(source);
+    log.log(`  ${stubs.length} document(s) listed`);
+    let ok = 0;
+    let fail = 0;
+    for (const stub of stubs) {
+        try {
+            const doc = await fetchOne(source, stub);
+            const rawChunks = chunkText(doc.text);
+            if (rawChunks.length === 0) {
+                log.error(`  SKIP ${doc.doc_id}: no chunks emitted`);
+                continue;
+            }
+            const embeddings = [];
+            for (let i = 0; i < rawChunks.length; i += EMBED_CONCURRENCY) {
+                const batch = rawChunks.slice(i, i + EMBED_CONCURRENCY);
+                const batchResults = await Promise.all(batch.map((c) => embedder(c.text)));
+                embeddings.push(...batchResults);
+            }
+            const chunks = rawChunks.map((c, i) => ({ ...c, embedding: embeddings[i] }));
+            const row = {
+                source,
+                doc_id: doc.doc_id,
+                doc_title: doc.doc_title,
+                doc_url: doc.doc_url,
+                chunks,
+                metadata: doc.metadata,
+            };
+            unwrapOrThrow(await upsertChunks(pool, row));
+            ok++;
+            log.log(`  ok ${doc.doc_id} (${chunks.length} chunks)`);
+        }
+        catch (err) {
+            fail++;
+            const msg = err instanceof Error ? err.message : String(err);
+            log.error(`  FAIL ${stub.doc_id}: ${msg}`);
+        }
+    }
+    return { ok, fail };
+}
+/**
+ * Refresh one or more regulatory corpus sources end-to-end. Returns
+ * aggregate ok/fail counts across all requested sources. Never throws —
+ * per-document failures are counted but do not abort the run.
+ */
+export async function refreshRegulatoryCorpus(opts) {
+    const sources = opts.sources ?? REGULATORY_CORPUS_SOURCES;
+    const { pool, embedder } = opts;
+    const log = opts.log ?? console;
+    let totalOk = 0;
+    let totalFail = 0;
+    for (const source of sources) {
+        const { ok, fail } = await indexSource(pool, source, embedder, log);
+        totalOk += ok;
+        totalFail += fail;
+    }
+    log.log(`\nDone. ok=${totalOk} fail=${totalFail}`);
+    return { ok: totalOk, fail: totalFail };
+}

package/dist/tasks/regulatory-corpus-boot-refresh.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Boot-time regulatory corpus refresher.
+ *
+ * On every Cortex startup, check whether `cortex_regulatory_chunks` was
+ * last refreshed more than 90 days ago (or has never been populated). If
+ * stale, fire `refreshRegulatoryCorpus()` asynchronously so it does not
+ * block the server from coming up.
+ *
+ * Multi-replica safety: the refresh acquires a Postgres advisory lock on
+ * a dedicated `pg.Client` (advisory locks are session-scoped, so the lock
+ * only releases when the client connection closes — which we do explicitly
+ * after the refresh resolves or rejects). Replicas that lose the race
+ * skip silently. The 90-day check itself is racy against the lock holder
+ * but the cost of a redundant check is one round-trip; the actual scrape
+ * is what we serialize.
+ */
+import type { Pool } from "pg";
+import { refreshRegulatoryCorpus, type RefreshOptions } from "./refresh-regulatory-corpus.js";
+export declare const REFRESH_INTERVAL_DAYS = 90;
+export interface BootRefreshDeps {
+    /** Shared `pg.Pool`. */
+    pool: Pool;
+    /** Forwarded to `refreshRegulatoryCorpus()` when the refresh fires. */
+    refreshOptions?: Omit<RefreshOptions, "embedder">;
+    /**
+     * Embedder injected directly (used by tests). When omitted, the boot
+     * task derives one from `REGULATORY_CORPUS_OPENAI_API_KEY` — and skips
+     * the refresh when that env var is unset, to avoid generating
+     * unattributed billing-gateway calls outside any billing scope.
+     */
+    embedder?: (text: string) => Promise<number[]>;
+    /** Override the refresh function (used by tests). */
+    refresh?: typeof refreshRegulatoryCorpus;
+    /** Logger. Defaults to `console`. */
+    log?: Pick<Console, "log" | "warn" | "error">;
+    /** Override the staleness threshold (used by tests). */
+    intervalDays?: number;
+    /** Embedding model for the maintenance embedder (when `embedder` omitted). */
+    embeddingModel?: string;
+    /** Direct OpenAI key for the maintenance embedder (NOT a billing-gateway VK). */
+    openaiApiKey?: string;
+}
+/**
+ * Check the corpus freshness and, if stale, kick off an asynchronous
+ * refresh. Resolves quickly — does NOT wait for the refresh to finish.
+ *
+ * Returns:
+ *   - "skipped-fresh" when corpus age < intervalDays
+ *   - "skipped-unconfigured" when no maintenance embedder is available
+ *     (no `REGULATORY_CORPUS_OPENAI_API_KEY` and no injected embedder)
+ *   - "skipped-locked" when another replica holds the advisory lock
+ *   - "started" when this replica acquired the lock and dispatched the refresh
+ *   - "error" when the freshness check itself failed (refresh not attempted)
+ */
+export declare function maybeKickOffRegulatoryCorpusRefresh(deps: BootRefreshDeps): Promise<"skipped-fresh" | "skipped-unconfigured" | "skipped-locked" | "started" | "error">;

package/dist/tasks/regulatory-corpus-boot-refresh.js

@@ -0,0 +1,149 @@
+/**
+ * Boot-time regulatory corpus refresher.
+ *
+ * On every Cortex startup, check whether `cortex_regulatory_chunks` was
+ * last refreshed more than 90 days ago (or has never been populated). If
+ * stale, fire `refreshRegulatoryCorpus()` asynchronously so it does not
+ * block the server from coming up.
+ *
+ * Multi-replica safety: the refresh acquires a Postgres advisory lock on
+ * a dedicated `pg.Client` (advisory locks are session-scoped, so the lock
+ * only releases when the client connection closes — which we do explicitly
+ * after the refresh resolves or rejects). Replicas that lose the race
+ * skip silently. The 90-day check itself is racy against the lock holder
+ * but the cost of a redundant check is one round-trip; the actual scrape
+ * is what we serialize.
+ */
+import { buildMaintenanceEmbedder, refreshRegulatoryCorpus } from "./refresh-regulatory-corpus.js";
+export const REFRESH_INTERVAL_DAYS = 90;
+const ADVISORY_LOCK_KEY = "cortex_regulatory_corpus_refresh";
+async function checkFreshness(pool, intervalDays) {
+    const { rows } = await pool.query(`SELECT MAX(indexed_at) AS last_indexed_at,
+            EXTRACT(EPOCH FROM (NOW() - MAX(indexed_at))) / 86400 AS age_days
+     FROM cortex_regulatory_chunks`);
+    const row = rows[0];
+    const lastIndexedAt = row?.last_indexed_at ?? null;
+    const ageDays = row?.age_days != null ? Number(row.age_days) : null;
+    const stale = lastIndexedAt === null || (ageDays ?? Infinity) >= intervalDays;
+    return { stale, lastIndexedAt, ageDays };
+}
+/**
+ * Hash a string into a bigint suitable for `pg_try_advisory_lock(bigint)`.
+ * Uses Postgres's own `hashtext()`.
+ */
+async function tryAcquireLock(client) {
+    const { rows } = await client.query("SELECT pg_try_advisory_lock(hashtext($1)) AS acquired", [ADVISORY_LOCK_KEY]);
+    return rows[0]?.acquired === true;
+}
+async function releaseLock(client) {
+    try {
+        await client.query("SELECT pg_advisory_unlock(hashtext($1))", [ADVISORY_LOCK_KEY]);
+    }
+    catch {
+        // Connection may already be closed/poisoned — release-on-disconnect
+        // covers us. Swallow.
+    }
+}
+/**
+ * Check the corpus freshness and, if stale, kick off an asynchronous
+ * refresh. Resolves quickly — does NOT wait for the refresh to finish.
+ *
+ * Returns:
+ *   - "skipped-fresh" when corpus age < intervalDays
+ *   - "skipped-unconfigured" when no maintenance embedder is available
+ *     (no `REGULATORY_CORPUS_OPENAI_API_KEY` and no injected embedder)
+ *   - "skipped-locked" when another replica holds the advisory lock
+ *   - "started" when this replica acquired the lock and dispatched the refresh
+ *   - "error" when the freshness check itself failed (refresh not attempted)
+ */
+export async function maybeKickOffRegulatoryCorpusRefresh(deps) {
+    const pool = deps.pool;
+    const log = deps.log ?? console;
+    const intervalDays = deps.intervalDays ?? REFRESH_INTERVAL_DAYS;
+    const refresh = deps.refresh ?? refreshRegulatoryCorpus;
+    // Freshness first — cheap (single query) and has no env dependency. Pod
+    // restarts and scale-ups on a long-lived cluster hit this path constantly;
+    // logging "auto-refresh disabled because key is unset" on every one of
+    // them creates alert fatigue. Only complain about missing config when a
+    // refresh is actually needed.
+    let freshness;
+    try {
+        freshness = await checkFreshness(pool, intervalDays);
+    }
+    catch (err) {
+        log.warn("[boot] Regulatory corpus freshness check failed; skipping auto-refresh:", err instanceof Error ? err.message : err);
+        return "error";
+    }
+    if (!freshness.stale) {
+        log.log(`[boot] Regulatory corpus is fresh (age ${freshness.ageDays?.toFixed(1)}d < ${intervalDays}d); skipping refresh`);
+        return "skipped-fresh";
+    }
+    // Corpus is stale — resolve the maintenance embedder. System-scoped
+    // maintenance work has no analysis/target-assessment to bill against, so
+    // we route directly to api.openai.com on a dedicated key. Never the
+    // billing-gateway-routed workspace embedder, which would emit unattributed calls
+    // and flood the boot log via `billing-fetch-patch`.
+    let embedder = deps.embedder ?? null;
+    if (!embedder) {
+        try {
+            embedder = buildMaintenanceEmbedder({
+                apiKey: deps.openaiApiKey,
+                embeddingModel: deps.embeddingModel ?? "",
+            });
+        }
+        catch (err) {
+            log.warn("[boot] Could not load env for regulatory corpus refresh; skipping:", err instanceof Error ? err.message : err);
+            return "skipped-unconfigured";
+        }
+    }
+    if (!embedder) {
+        const ageStr = freshness.lastIndexedAt === null ? "empty" : `age ${freshness.ageDays?.toFixed(1)}d`;
+        log.warn(`[boot] Regulatory corpus is stale (${ageStr}) but ` +
+            "REGULATORY_CORPUS_OPENAI_API_KEY is unset; skipping auto-refresh. " +
+            "Set it (a real OpenAI key, NOT a billing-gateway virtual key — the " +
+            "maintenance embedder talks direct to api.openai.com) to enable, " +
+            "or run scripts/index-regulatory-corpus.ts manually.");
+        return "skipped-unconfigured";
+    }
+    // Acquire the advisory lock on a dedicated pool client. We hold this
+    // client (and the lock) for the whole refresh — releasing it only after
+    // the detached promise settles. Other replicas booting in the meantime
+    // hit `pg_try_advisory_lock` and skip.
+    const client = await pool.connect();
+    let acquired;
+    try {
+        acquired = await tryAcquireLock(client);
+    }
+    catch (err) {
+        client.release();
+        log.warn("[boot] Regulatory corpus advisory-lock attempt failed; skipping auto-refresh:", err instanceof Error ? err.message : err);
+        return "error";
+    }
+    if (!acquired) {
+        client.release();
+        log.log("[boot] Regulatory corpus refresh already in progress on another replica; skipping");
+        return "skipped-locked";
+    }
+    const ageStr = freshness.lastIndexedAt === null ? "empty" : `age ${freshness.ageDays?.toFixed(1)}d`;
+    log.log(`[boot] Regulatory corpus is stale (${ageStr}); starting async refresh in background`);
+    // Detached promise — startup must not wait for this to finish.
+    const dispatchEmbedder = embedder;
+    void (async () => {
+        try {
+            const result = await refresh({
+                ...(deps.refreshOptions ?? {}),
+                pool,
+                embedder: dispatchEmbedder,
+            });
+            log.log(`[boot] Regulatory corpus refresh complete: ok=${result.ok} fail=${result.fail}`);
+        }
+        catch (err) {
+            log.error("[boot] Regulatory corpus refresh threw:", err instanceof Error ? err.message : err);
+        }
+        finally {
+            await releaseLock(client);
+            client.release();
+        }
+    })();
+    return "started";
+}

package/dist/tools/__fixtures__/tool-context.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Test-only `ToolContext` builder. Not a `*.test.ts` file, so the test
+ * runner ignores it; imported by the tool unit tests.
+ */
+import type { ToolContext } from "../define-tool.js";
+/** A `ToolContext` plus the list of events its `emit` recorded. */
+export interface TestToolContext {
+    readonly ctx: ToolContext;
+    /** Every event passed to `ctx.emit`, in call order. */
+    readonly emitted: unknown[];
+}
+/** Build a `ToolContext` for tests; `emit` records into `emitted`. */
+export declare function makeToolContext(signal?: AbortSignal): TestToolContext;

package/dist/tools/__fixtures__/tool-context.js

@@ -0,0 +1,18 @@
+/**
+ * Test-only `ToolContext` builder. Not a `*.test.ts` file, so the test
+ * runner ignores it; imported by the tool unit tests.
+ */
+import { makeSession } from "../../providers/__fixtures__/session.js";
+/** Build a `ToolContext` for tests; `emit` records into `emitted`. */
+export function makeToolContext(signal) {
+    const emitted = [];
+    const ctx = {
+        session: makeSession(),
+        signal: signal ?? new AbortController().signal,
+        emit: (event) => {
+            emitted.push(event);
+        },
+        runStep: (_name, fn) => fn(),
+    };
+    return { ctx, emitted };
+}

package/dist/tools/bio/check-safety-panel.d.ts

@@ -0,0 +1,35 @@
+/**
+ * checkSafetyPanel — look up identifiers against the curated
+ * secondary-pharmacology safety target panel.
+ */
+export declare const checkSafetyPanelTool: import("../define-tool.js").Tool<{
+    identifiers: string[];
+    identifier_type: "auto" | "gene_symbol" | "uniprot" | "chembl_id";
+    filter_organ?: "hematologic" | "metabolic" | "immune" | "hepatic" | "cns" | "renal" | "respiratory" | "cardiac" | "gi" | undefined;
+}, {
+    matches: {
+        input: string;
+        matched_entry: {
+            chembl_id: string;
+            gene_symbol: string;
+            uniprot: string;
+            name: string;
+            organ_system: "hematologic" | "metabolic" | "immune" | "hepatic" | "cns" | "renal" | "respiratory" | "cardiac" | "gi";
+            clinical_consequence: string;
+            severity: "high" | "medium" | "low";
+            references: string[];
+            ensembl_gene_id?: string | undefined;
+        } | null;
+    }[];
+    summary: {
+        total_input: number;
+        matched: number;
+        by_severity: {
+            high: number;
+            medium: number;
+            low: number;
+        };
+        by_organ: Record<string, number>;
+    };
+    panel_version: string;
+}>;

package/dist/tools/bio/check-safety-panel.js

@@ -0,0 +1,76 @@
+/**
+ * checkSafetyPanel — look up identifiers against the curated
+ * secondary-pharmacology safety target panel.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { CHEMBL_RE, ORGAN_SYSTEMS, SafetyPanelFileSchema, UNIPROT_RE } from "../../data/safety-panel-schema.js";
+import panelData from "../../data/safety-panel.json" with { type: "json" };
+import { defineTool } from "../define-tool.js";
+const PANEL = SafetyPanelFileSchema.parse(panelData);
+const BY_CHEMBL = new Map(PANEL.targets.map((t) => [t.chembl_id, t]));
+const BY_GENE = new Map(PANEL.targets.map((t) => [t.gene_symbol, t]));
+const BY_UNIPROT = new Map(PANEL.targets.map((t) => [t.uniprot, t]));
+function detectType(id) {
+    if (CHEMBL_RE.test(id))
+        return "chembl_id";
+    if (UNIPROT_RE.test(id))
+        return "uniprot";
+    return "gene_symbol";
+}
+function lookup(id, type) {
+    switch (type) {
+        case "chembl_id":
+            return BY_CHEMBL.get(id) ?? null;
+        case "gene_symbol":
+            return BY_GENE.get(id.toUpperCase()) ?? null;
+        case "uniprot":
+            return BY_UNIPROT.get(id) ?? null;
+    }
+}
+export const checkSafetyPanelTool = defineTool({
+    id: "check_safety_panel",
+    description: "Look up identifiers (ChEMBL ID, gene symbol, or UniProt accession) against the curated " +
+        "secondary-pharmacology safety target panel. Returns organ system, severity, and clinical " +
+        "consequence for each matched target. Use as a fast first-pass off-target liability check; " +
+        "for comprehensive assessment also call get-target-safety and search-toxcast.",
+    inputSchema: z.object({
+        identifiers: z.array(z.string().min(1)).min(0).max(200).describe("0-200 identifiers (ChEMBL IDs, gene symbols, or UniProt accessions)."),
+        identifier_type: z
+            .enum(["chembl_id", "gene_symbol", "uniprot", "auto"])
+            .default("auto")
+            .describe("Identifier interpretation. 'auto' detects per-input."),
+        filter_organ: z.enum(ORGAN_SYSTEMS).optional().describe("Restrict matches to this organ system."),
+    }),
+    execute: async ({ identifiers, identifier_type = "auto", filter_organ }) => {
+        const matches = identifiers.map((input) => {
+            const type = identifier_type === "auto" ? detectType(input) : identifier_type;
+            let entry = lookup(input, type);
+            if (entry && filter_organ && entry.organ_system !== filter_organ) {
+                entry = null;
+            }
+            return { input, matched_entry: entry };
+        });
+        const bySeverity = { high: 0, medium: 0, low: 0 };
+        const byOrgan = {};
+        let matched = 0;
+        for (const m of matches) {
+            if (!m.matched_entry)
+                continue;
+            matched++;
+            bySeverity[m.matched_entry.severity]++;
+            const o = m.matched_entry.organ_system;
+            byOrgan[o] = (byOrgan[o] ?? 0) + 1;
+        }
+        return ok({
+            matches,
+            summary: {
+                total_input: identifiers.length,
+                matched,
+                by_severity: bySeverity,
+                by_organ: byOrgan,
+            },
+            panel_version: PANEL.panel_version,
+        });
+    },
+});

package/dist/tools/bio/find-approval-precedent.d.ts

@@ -0,0 +1,32 @@
+/**
+ * findApprovalPrecedent — query openFDA / Drugs@FDA for prior approvals in a
+ * given indication.
+ */
+import { z } from "zod";
+export declare const findApprovalPrecedentInputSchema: z.ZodObject<{
+    indication: z.ZodString;
+    modality: z.ZodOptional<z.ZodEnum<{
+        small_molecule: "small_molecule";
+        biologic: "biologic";
+        gene_therapy: "gene_therapy";
+        cell_therapy: "cell_therapy";
+    }>>;
+    mechanism: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+interface Precedent {
+    application_number: string;
+    brand_name?: string;
+    generic_name?: string;
+    approval_date?: string;
+    label_section_excerpts?: Record<string, string>;
+}
+export declare const findApprovalPrecedent: import("../define-tool.js").Tool<{
+    indication: string;
+    modality?: "small_molecule" | "biologic" | "gene_therapy" | "cell_therapy" | undefined;
+    mechanism?: string | undefined;
+}, {
+    precedents: Precedent[];
+}>;
+/** Test-only — clears the in-memory cache to avoid cross-test bleed. */
+export declare function __resetApprovalPrecedentCacheForTest(): void;
+export {};

package/dist/tools/bio/find-approval-precedent.js

@@ -0,0 +1,72 @@
+/**
+ * findApprovalPrecedent — query openFDA / Drugs@FDA for prior approvals in a
+ * given indication.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+export const findApprovalPrecedentInputSchema = z.object({
+    indication: z.string().min(1).describe("Indication / disease name — searched against openFDA label.indications_and_usage"),
+    modality: z
+        .enum(["small_molecule", "biologic", "gene_therapy", "cell_therapy"])
+        .optional()
+        .describe("Optional modality hint (advisory; not used for filtering today)"),
+    mechanism: z.string().optional().describe("Optional MoA / mechanism hint (advisory; not used for filtering today)"),
+});
+const cache = new Map();
+const TTL_MS = 60 * 60 * 1000;
+export const findApprovalPrecedent = defineTool({
+    id: "find_approval_precedent",
+    description: "Query openFDA / Drugs@FDA for prior approvals in a given indication. Returns NDA/BLA application numbers, generic and brand names, approval dates (effective time of the label), and label-section excerpts (boxed warning, warnings and precautions, contraindications). Use to ground class-precedent claims and disposition framing in the executive recommendation.",
+    inputSchema: findApprovalPrecedentInputSchema,
+    execute: async ({ indication, modality, mechanism }) => {
+        const key = JSON.stringify({
+            indication: indication.toLowerCase(),
+            modality,
+            mechanism,
+        });
+        const cached = cache.get(key);
+        if (cached && Date.now() - cached.ts < TTL_MS)
+            return ok(cached.value);
+        const term = indication.replace(/"/g, "");
+        const url = new URL("https://api.fda.gov/drug/label.json");
+        url.searchParams.set("search", `indications_and_usage:"${term}"`);
+        url.searchParams.set("limit", "10");
+        const res = await fetch(url);
+        // openFDA answers a zero-match search with 404 — an expected "no
+        // precedents" outcome, not a failure. It is returned uncached so a
+        // later, more specific query is not masked. Any other non-ok status
+        // (5xx, 429) is an unexpected failure and throws.
+        if (res.status === 404)
+            return ok({ precedents: [] });
+        if (!res.ok) {
+            throw new Error(`openFDA label query failed: HTTP ${res.status}`);
+        }
+        const json = (await res.json());
+        const precedents = (json.results ?? []).slice(0, 10).map((r) => {
+            const excerpts = {};
+            if (r.boxed_warning?.[0])
+                excerpts.boxed_warning = r.boxed_warning[0].slice(0, 1000);
+            if (r.warnings_and_precautions?.[0])
+                excerpts.warnings_and_precautions = r.warnings_and_precautions[0].slice(0, 1000);
+            else if (r.warnings?.[0])
+                excerpts.warnings = r.warnings[0].slice(0, 1000);
+            if (r.contraindications?.[0])
+                excerpts.contraindications = r.contraindications[0].slice(0, 1000);
+            return {
+                application_number: r.openfda?.application_number?.[0] ?? "(unknown)",
+                brand_name: r.openfda?.brand_name?.[0],
+                generic_name: r.openfda?.generic_name?.[0],
+                approval_date: r.effective_time,
+                label_section_excerpts: Object.keys(excerpts).length > 0 ? excerpts : undefined,
+            };
+        });
+        const value = { precedents };
+        cache.set(key, { ts: Date.now(), value });
+        return ok(value);
+    },
+});
+/** Test-only — clears the in-memory cache to avoid cross-test bleed. */
+export function __resetApprovalPrecedentCacheForTest() {
+    cache.clear();
+}

package/dist/tools/bio/get-article-details.d.ts

@@ -0,0 +1,11 @@
+/**
+ * getArticleDetails — fetch detailed metadata for PubMed articles.
+ */
+export declare function createGetArticleDetailsTool(deps: {
+    ncbiApiKey?: string;
+}): import("../define-tool.js").Tool<{
+    pmids: string[];
+}, {
+    articles: import("../lib/ncbi-utils.js").ArticleDetail[];
+    notFound: string[];
+}>;