@inflexa-ai/harness 0.15.1 → 0.17.0

package/dist/state/init.js

@@ -255,6 +255,9 @@ CREATE TABLE IF NOT EXISTS messages (
   role          TEXT,
   content_jsonb JSONB,
   message_envelope JSON,
+  -- Versioned AI SDK UIMessage projection for the whole turn. Present only
+  -- on the genuine-user-start row. Model-history reads never select it.
+  display_envelope JSONB,
   tokens        INTEGER NOT NULL,
   reported_usage JSONB,
   created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
@@ -272,12 +275,57 @@ CREATE TABLE IF NOT EXISTS cortex_analysis_threads (
   title       TEXT,
   created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
   updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-  deleted_at  TIMESTAMPTZ
+  deleted_at  TIMESTAMPTZ,
+  thread_type TEXT NOT NULL DEFAULT 'conversation',
+  -- The cascade on this self-reference is a BACKSTOP, never the deletion path.
+  -- messages carries no foreign key to this table, so a cascade firing on its
+  -- own drops a descendant's metadata row while leaving that descendant's
+  -- messages rows behind with nothing naming them, beyond the reach of any
+  -- later thread-scoped or analysis-scoped reclamation. purgeThread therefore
+  -- walks the subtree and deletes its messages rows explicitly, to the same
+  -- depth the cascade reaches.
+  parent_thread_id TEXT REFERENCES cortex_analysis_threads(thread_id) ON DELETE CASCADE,
+  parent_seq  BIGINT
 );
 
+-- These three sit here, and not in the additive block further down, because the
+-- index below reads one of them. CREATE TABLE IF NOT EXISTS adds no column to a
+-- table that already exists, so on every database but a brand new one the column
+-- arrives from an ALTER -- and the whole additive block runs after this text. An
+-- index declared here over a column added there fails with 42703 on exactly the
+-- databases a migration exists to serve. Additive with no backfill either way: an
+-- existing row reads back as a root conversation thread with no anchor, which is
+-- what it is.
+ALTER TABLE cortex_analysis_threads
+  ADD COLUMN IF NOT EXISTS thread_type TEXT NOT NULL DEFAULT 'conversation';
+
+ALTER TABLE cortex_analysis_threads
+  ADD COLUMN IF NOT EXISTS parent_thread_id TEXT REFERENCES cortex_analysis_threads(thread_id) ON DELETE CASCADE;
+
+ALTER TABLE cortex_analysis_threads
+  ADD COLUMN IF NOT EXISTS parent_seq BIGINT;
+
 CREATE INDEX IF NOT EXISTS idx_cortex_analysis_threads_analysis
   ON cortex_analysis_threads(analysis_id) WHERE deleted_at IS NULL;
 
+-- Not partial, unlike the analysis index above. Two of the three readers of
+-- parent_thread_id carry no deleted_at predicate and cannot: the recursive
+-- subtree walk in thread-store.ts must reach archived descendants, and the
+-- referential trigger behind ON DELETE CASCADE is the database's own query.
+-- Postgres uses a partial index only where it can prove the predicate holds, so
+-- a partial index here leaves both to a sequential scan of the whole table.
+-- Over 150k rows that measured 28 ms per walk and 20 ms per cascade, against
+-- 0.06 ms and 0.10 ms with this one. The third reader, a listing filtered by
+-- parent, keeps an index scan either way.
+--
+-- The old partial index goes by name: CREATE INDEX IF NOT EXISTS keeps whatever
+-- definition already holds the name, so a database that built the partial one
+-- would never see this.
+DROP INDEX IF EXISTS idx_cortex_analysis_threads_parent;
+
+CREATE INDEX IF NOT EXISTS idx_cortex_analysis_threads_parent_fk
+  ON cortex_analysis_threads(parent_thread_id);
+
 -- Working memory — the harness WorkingMemory module's table, one row per
 -- analysis. The data column holds a JSONB object with four sections (goal,
 -- constraints, hypotheses, findings). Section updates are a read-modify-write
@@ -475,6 +523,7 @@ export async function initCortexState(pool, injected) {
                     ALTER TABLE messages ALTER COLUMN message_envelope TYPE JSON USING message_envelope::text::json;
                   END IF;
                 END $$`,
+                "ALTER TABLE messages ADD COLUMN IF NOT EXISTS display_envelope JSONB",
                 // Grant key an 'always' records the standing grant under. Nullable
                 // and unbackfilled: every new row writes it (command when absent), and
                 // orphaned legacy pending rows are swept to 'expired' before any answer

package/dist/state/schema.d.ts

@@ -46,10 +46,10 @@ export declare const ArtifactRowSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type ArtifactRow = z.infer<typeof ArtifactRowSchema>;
 export declare const RunStatus: z.ZodEnum<{
+    partial: "partial";
     running: "running";
     completed: "completed";
     failed: "failed";
-    partial: "partial";
     canceled: "canceled";
     suspended_insufficient_funds: "suspended_insufficient_funds";
 }>;
@@ -77,10 +77,10 @@ export declare const CortexRunRowSchema: z.ZodObject<{
     threadId: z.ZodNullable<z.ZodString>;
     workflowName: z.ZodString;
     status: z.ZodEnum<{
+        partial: "partial";
         running: "running";
         completed: "completed";
         failed: "failed";
-        partial: "partial";
         canceled: "canceled";
         suspended_insufficient_funds: "suspended_insufficient_funds";
     }>;

package/dist/tools/bio/gene-preclinical-profile.d.ts

@@ -51,7 +51,7 @@ export declare const genePreclinicalProfileTool: import("../define-tool.js").Too
     geneSymbol: string;
     include?: ("expression" | "knockout")[] | undefined;
     species?: ("homo_sapiens" | "mus_musculus" | "rattus_norvegicus" | "canis_lupus_familiaris" | "macaca_mulatta")[] | undefined;
-    minRank?: "high" | "medium" | "low" | "absent" | undefined;
+    minRank?: "absent" | "high" | "medium" | "low" | undefined;
     tissueLimit?: number | undefined;
     phenotypeLimit?: number | undefined;
 }, PreclinicalOutput>;

package/dist/tools/bio/keys.d.ts

@@ -13,6 +13,7 @@ export interface BioToolKeys {
     readonly epaCcte: string;
     readonly ncbi?: string;
     readonly github?: string;
+    readonly semanticScholar?: string;
 }
 /**
  * The NCBI-backed literature tool, built from the shared key slice.

package/dist/tools/bio/pubmed.js

@@ -140,16 +140,16 @@ export function createPubMedTool(deps) {
                     return `fulltext ${input.pmcId ?? ""}`;
             }
         },
-        execute: async (input) => {
+        execute: async (input, context) => {
             switch (input.action) {
                 case "search":
                     return ok(await searchPubmed(deps.ncbiApiKey, input.query, {
                         maxResults: input.maxResults ?? DEFAULTS.searchResults,
                         ...(input.sort ? { sort: input.sort } : {}),
                         ...(input.dateRange ? { dateRange: input.dateRange } : {}),
-                    }));
+                    }, context.signal));
                 case "details": {
-                    const { articles, notFound } = await getArticleDetails(deps.ncbiApiKey, input.pmids);
+                    const { articles, notFound } = await getArticleDetails(deps.ncbiApiKey, input.pmids, context.signal);
                     return ok({
                         articles: boundArticleDetails(articles, {
                             maxAuthors: input.maxAuthors ?? DEFAULTS.maxAuthors,
@@ -162,7 +162,7 @@ export function createPubMedTool(deps) {
                     const parsed = await getArticleFullText(deps.ncbiApiKey, input.pmcId, {
                         ...(input.sections ? { sections: input.sections } : {}),
                         maxChars: input.maxChars ?? DEFAULTS.maxChars,
-                    });
+                    }, context.signal);
                     // "Not open-access" is an expected outcome — a data variant, not an error.
                     if (!parsed)
                         return ok({ pmcId: input.pmcId, available: false });

package/dist/tools/lib/ncbi-utils.d.ts

@@ -1,58 +1,3 @@
-/**
- * Shared NCBI E-utilities helpers for PubMed/PMC tools.
- *
- * Provides base URL constants, API key injection, and XML-to-article
- * mapping functions for PubMed and PMC DTD structures.
- */
-export declare const NCBI_BASE = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";
-export declare const NCBI_IDCONV = "https://www.ncbi.nlm.nih.gov/pmc/utils/idconv/v1.0";
-/**
- * Append `api_key` and optional extra params to a base URL.
- * Omits the key when `apiKey` is undefined.
- */
-export declare function ncbiUrl(apiKey: string | undefined, base: string, params: Record<string, string | number | undefined>): string;
-export interface PubMedSummary {
-    pmid: string;
-    title: string;
-    journal: string;
-    year: string;
-    authors: string;
-}
-/**
- * Parse esummary XML into PubMedSummary records.
- */
-export declare function parseEsummary(xml: string): PubMedSummary[];
-export interface ArticleDetail {
-    pmid: string;
-    title: string;
-    abstract: string;
-    authors: string[];
-    journal: string;
-    year: string;
-    doi: string;
-    meshTerms: string[];
-    pmcId: string | null;
-}
-/**
- * Parse efetch PubMed XML into ArticleDetail records.
- * `pmcId` is left null here — resolved separately via ID Converter.
- */
-export declare function parseEfetch(xml: string): ArticleDetail[];
-/**
- * Parse ID Converter JSON response into a PMID → PMC ID map.
- * Returns only entries that have a PMC ID.
- */
-export declare function parseIdConvResponse(data: unknown): Map<string, string>;
-export interface ArticleSection {
-    heading: string;
-    text: string;
-}
-export interface FullTextResult {
-    fullText: string;
-    sections: ArticleSection[];
-}
-/**
- * Parse PMC efetch XML into plain text with section structure.
- * Omits figures, tables, and supplementary material markup.
- */
-export declare function parsePmcFullText(xml: string): FullTextResult | null;
+/** @deprecated Import NCBI authority contracts from literature/sources/pubmed. */
+export { NCBI_BASE, NCBI_IDCONV, ncbiUrl, parseEfetch, parseEsummary, parseIdConvResponse, parsePmcFullText } from "../../literature/sources/pubmed.js";
+export type { ArticleDetail, ArticleSection, FullTextResult, PubMedSummary } from "../../literature/sources/pubmed.js";

package/dist/tools/lib/ncbi-utils.js

@@ -1,286 +1,2 @@
-/**
- * Shared NCBI E-utilities helpers for PubMed/PMC tools.
- *
- * Provides base URL constants, API key injection, and XML-to-article
- * mapping functions for PubMed and PMC DTD structures.
- */
-import { XMLParser } from "fast-xml-parser";
-// ── NCBI E-utilities base URLs ──────────────────────────────────────
-export const NCBI_BASE = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";
-export const NCBI_IDCONV = "https://www.ncbi.nlm.nih.gov/pmc/utils/idconv/v1.0";
-// ── API key injection ───────────────────────────────────────────────
-/**
- * Append `api_key` and optional extra params to a base URL.
- * Omits the key when `apiKey` is undefined.
- */
-export function ncbiUrl(apiKey, base, params) {
-    const url = new URL(base);
-    if (apiKey) {
-        url.searchParams.set("api_key", apiKey);
-    }
-    for (const [k, v] of Object.entries(params)) {
-        if (v !== undefined) {
-            url.searchParams.set(k, String(v));
-        }
-    }
-    return url.toString();
-}
-// ── XML parser (shared, configured once) ────────────────────────────
-const xmlParser = new XMLParser({
-    ignoreAttributes: false,
-    attributeNamePrefix: "@_",
-    isArray: (name) => ["PubmedArticle", "Author", "MeshHeading", "AbstractText", "sec", "p", "record"].includes(name),
-    textNodeName: "#text",
-});
-function getItemValue(items, name) {
-    if (!items)
-        return "";
-    const arr = Array.isArray(items) ? items : [items];
-    const item = arr.find((i) => i["@_Name"] === name);
-    return item?.["#text"] ?? "";
-}
-function getAuthorsFromDocSum(items) {
-    if (!items)
-        return "";
-    const arr = Array.isArray(items) ? items : [items];
-    const authorList = arr.find((i) => i["@_Name"] === "AuthorList");
-    if (!authorList?.Item)
-        return "";
-    const authors = Array.isArray(authorList.Item) ? authorList.Item : [authorList.Item];
-    const names = authors.map((a) => a["#text"] ?? "").filter(Boolean);
-    if (names.length === 0)
-        return "";
-    if (names.length <= 3)
-        return names.join(", ");
-    return `${names[0]} et al.`;
-}
-/**
- * Parse esummary XML into PubMedSummary records.
- */
-export function parseEsummary(xml) {
-    const parsed = xmlParser.parse(xml);
-    const result = parsed?.eSummaryResult ?? parsed;
-    const docSums = result?.DocSum;
-    if (!docSums)
-        return [];
-    const docs = Array.isArray(docSums) ? docSums : [docSums];
-    return docs.map((doc) => {
-        const items = doc.Item;
-        const pubDate = getItemValue(items, "PubDate");
-        return {
-            pmid: String(doc.Id ?? ""),
-            title: getItemValue(items, "Title"),
-            journal: getItemValue(items, "FullJournalName") || getItemValue(items, "Source"),
-            year: pubDate ? String(pubDate).slice(0, 4) : "",
-            authors: getAuthorsFromDocSum(items),
-        };
-    });
-}
-/**
- * Parse efetch PubMed XML into ArticleDetail records.
- * `pmcId` is left null here — resolved separately via ID Converter.
- */
-export function parseEfetch(xml) {
-    const parsed = xmlParser.parse(xml);
-    const articleSet = parsed?.PubmedArticleSet;
-    if (!articleSet)
-        return [];
-    const articles = Array.isArray(articleSet.PubmedArticle) ? articleSet.PubmedArticle : articleSet.PubmedArticle ? [articleSet.PubmedArticle] : [];
-    return articles.map((entry) => {
-        const article = entry;
-        const medlineCitation = article.MedlineCitation;
-        const articleData = medlineCitation?.Article;
-        // PMID
-        const pmidObj = medlineCitation?.PMID;
-        const pmid = typeof pmidObj === "object" && pmidObj !== null ? String(pmidObj["#text"] ?? "") : String(pmidObj ?? "");
-        // Title
-        const title = String(articleData?.ArticleTitle ?? "");
-        // Abstract
-        const abstractObj = articleData?.Abstract;
-        let abstract = "";
-        if (abstractObj?.AbstractText) {
-            const texts = Array.isArray(abstractObj.AbstractText) ? abstractObj.AbstractText : [abstractObj.AbstractText];
-            abstract = texts
-                .map((t) => {
-                if (typeof t === "string")
-                    return t;
-                if (typeof t === "object" && t !== null) {
-                    const label = t["@_Label"];
-                    const text = t["#text"] ?? "";
-                    return label ? `${label}: ${text}` : String(text);
-                }
-                return String(t);
-            })
-                .join("\n\n");
-        }
-        // Authors
-        const authorListObj = articleData?.AuthorList;
-        const rawAuthors = authorListObj?.Author;
-        const authorArr = Array.isArray(rawAuthors) ? rawAuthors : rawAuthors ? [rawAuthors] : [];
-        const authors = authorArr.map((a) => {
-            if (a.CollectiveName)
-                return a.CollectiveName;
-            return [a.ForeName ?? a.Initials, a.LastName].filter(Boolean).join(" ");
-        });
-        // Journal + year
-        const journalObj = articleData?.Journal;
-        const journal = String(journalObj?.Title ?? journalObj?.ISOAbbreviation ?? "");
-        const journalIssue = journalObj?.JournalIssue;
-        const pubDate = journalIssue?.PubDate;
-        const year = String(pubDate?.Year ?? "");
-        // DOI
-        let doi = "";
-        const articleIdList = article.PubmedData?.ArticleIdList;
-        if (articleIdList?.ArticleId) {
-            const ids = Array.isArray(articleIdList.ArticleId) ? articleIdList.ArticleId : [articleIdList.ArticleId];
-            for (const idObj of ids) {
-                if (typeof idObj === "object" && idObj !== null) {
-                    const typed = idObj;
-                    if (typed["@_IdType"] === "doi") {
-                        doi = String(typed["#text"] ?? "");
-                    }
-                }
-            }
-        }
-        // MeSH terms
-        const meshList = medlineCitation?.MeshHeadingList;
-        const meshHeadings = meshList?.MeshHeading
-            ? Array.isArray(meshList.MeshHeading)
-                ? meshList.MeshHeading
-                : [meshList.MeshHeading]
-            : [];
-        const meshTerms = meshHeadings
-            .map((h) => {
-            const desc = h.DescriptorName;
-            if (typeof desc === "string")
-                return desc;
-            if (typeof desc === "object" && desc !== null)
-                return desc["#text"] ?? "";
-            return "";
-        })
-            .filter(Boolean);
-        return {
-            pmid,
-            title,
-            abstract,
-            authors,
-            journal,
-            year,
-            doi,
-            meshTerms,
-            pmcId: null, // resolved separately via ID Converter
-        };
-    });
-}
-// ── NCBI ID Converter mapping ───────────────────────────────────────
-/**
- * Parse ID Converter JSON response into a PMID → PMC ID map.
- * Returns only entries that have a PMC ID.
- */
-export function parseIdConvResponse(data) {
-    const map = new Map();
-    const typed = data;
-    if (!typed?.records)
-        return map;
-    for (const rec of typed.records) {
-        if (rec.pmid && rec.pmcid) {
-            map.set(rec.pmid, rec.pmcid);
-        }
-    }
-    return map;
-}
-/**
- * Parse PMC efetch XML into plain text with section structure.
- * Omits figures, tables, and supplementary material markup.
- */
-export function parsePmcFullText(xml) {
-    const parsed = xmlParser.parse(xml);
-    const articleSet = parsed?.["pmc-articleset"];
-    const article = articleSet?.article;
-    if (!article)
-        return null;
-    const body = article.body;
-    if (!body)
-        return null;
-    const sections = [];
-    const rawSecs = body.sec ? (Array.isArray(body.sec) ? body.sec : [body.sec]) : [];
-    for (const sec of rawSecs) {
-        extractSection(sec, sections);
-    }
-    // If no sections found, try to extract body text directly
-    if (sections.length === 0) {
-        const bodyText = extractParagraphs(body);
-        if (bodyText) {
-            sections.push({ heading: "", text: bodyText });
-        }
-    }
-    const fullText = sections.map((s) => (s.heading ? `## ${s.heading}\n\n${s.text}` : s.text)).join("\n\n");
-    return { fullText, sections };
-}
-function extractSection(sec, out) {
-    if (!sec || typeof sec !== "object")
-        return;
-    const s = sec;
-    const heading = typeof s.title === "string" ? s.title : "";
-    const text = extractParagraphs(s);
-    if (text) {
-        out.push({ heading, text });
-    }
-    // Recurse into nested sections
-    if (s.sec) {
-        const nested = Array.isArray(s.sec) ? s.sec : [s.sec];
-        for (const sub of nested) {
-            extractSection(sub, out);
-        }
-    }
-}
-function extractParagraphs(container) {
-    const paragraphs = container.p;
-    if (!paragraphs)
-        return "";
-    const pArr = Array.isArray(paragraphs) ? paragraphs : [paragraphs];
-    return pArr
-        .map((p) => {
-        if (typeof p === "string")
-            return p;
-        if (typeof p === "object" && p !== null) {
-            return flattenTextContent(p);
-        }
-        return String(p);
-    })
-        .filter(Boolean)
-        .join("\n\n");
-}
-/**
- * Recursively extract text content from a parsed XML node,
- * ignoring markup like <fig>, <table-wrap>, <xref>, etc.
- */
-function flattenTextContent(node) {
-    if (typeof node === "string")
-        return node;
-    if (typeof node === "number")
-        return String(node);
-    if (!node || typeof node !== "object")
-        return "";
-    const obj = node;
-    const parts = [];
-    for (const [key, value] of Object.entries(obj)) {
-        // Skip attributes and figure/table elements
-        if (key.startsWith("@_"))
-            continue;
-        if (key === "fig" || key === "table-wrap" || key === "supplementary-material")
-            continue;
-        if (key === "#text") {
-            parts.push(String(value));
-        }
-        else if (Array.isArray(value)) {
-            for (const item of value) {
-                parts.push(flattenTextContent(item));
-            }
-        }
-        else {
-            parts.push(flattenTextContent(value));
-        }
-    }
-    return parts.filter(Boolean).join("");
-}
+/** @deprecated Import NCBI authority contracts from literature/sources/pubmed. */
+export { NCBI_BASE, NCBI_IDCONV, ncbiUrl, parseEfetch, parseEsummary, parseIdConvResponse, parsePmcFullText } from "../../literature/sources/pubmed.js";

package/dist/tools/lib/pubmed-client.d.ts

@@ -4,18 +4,11 @@
  * Used by §3.11 (Key Papers), §3.10.4 (Preclinical literature), and the
  * pubmed-index Phase-1 collector.
  */
-import { type ArticleDetail, type ArticleSection, type PubMedSummary, type FullTextResult } from "./ncbi-utils.js";
+import { type ArticleDetail, type ArticleSection, type FullTextResult, type PubmedSearchOptions, type PubMedSummary } from "../../literature/sources/pubmed.js";
 export type { PubMedSummary, ArticleDetail, ArticleSection, FullTextResult };
-export interface SearchOptions {
-    maxResults?: number;
-    sort?: "relevance" | "date";
-    dateRange?: {
-        from: string;
-        to: string;
-    };
-}
+export type SearchOptions = PubmedSearchOptions;
 /** PubMed search via esearch + esummary. */
-export declare function searchPubmed(ncbiApiKey: string | undefined, query: string, options?: SearchOptions): Promise<{
+export declare function searchPubmed(ncbiApiKey: string | undefined, query: string, options?: SearchOptions, signal?: AbortSignal): Promise<{
     totalFound: number;
     results: PubMedSummary[];
 }>;
@@ -36,7 +29,7 @@ export interface BoundedArticleDetail extends ArticleDetail {
     meshTermCount: number;
 }
 /** Fetch full PubMed article details (efetch + ID Converter for PMC). */
-export declare function getArticleDetails(ncbiApiKey: string | undefined, pmids: string[]): Promise<{
+export declare function getArticleDetails(ncbiApiKey: string | undefined, pmids: string[], signal?: AbortSignal): Promise<{
     articles: ArticleDetail[];
     notFound: string[];
 }>;
@@ -76,6 +69,6 @@ export interface BoundedFullText {
  * Methods is worse than none) and admitted in document order until the budget
  * would be exceeded.
  */
-export declare function getArticleFullText(ncbiApiKey: string | undefined, pmcId: string, options?: FullTextOptions): Promise<BoundedFullText | null>;
+export declare function getArticleFullText(ncbiApiKey: string | undefined, pmcId: string, options?: FullTextOptions, signal?: AbortSignal): Promise<BoundedFullText | null>;
 /** Apply the section filter and character budget to a parsed full text. */
 export declare function boundFullText(parsed: FullTextResult, options?: FullTextOptions): BoundedFullText;

package/dist/tools/lib/pubmed-client.js

@@ -4,76 +4,27 @@
  * Used by §3.11 (Key Papers), §3.10.4 (Preclinical literature), and the
  * pubmed-index Phase-1 collector.
  */
-import { z } from "zod";
-import { apiFetch, apiFetchValidated, describeApiError } from "./api-utils.js";
-import { NCBI_BASE, NCBI_IDCONV, ncbiUrl, parseEsummary, parseEfetch, parseIdConvResponse, parsePmcFullText, } from "./ncbi-utils.js";
-// NCBI E-utilities JSON payloads, validated at the fetch boundary. Every field
-// is optional because the API omits absent values.
-const EsearchResponseSchema = z.object({
-    esearchresult: z.object({ idlist: z.array(z.string()).optional(), count: z.string().optional() }).optional(),
-});
-const IdConvResponseSchema = z.object({
-    records: z.array(z.object({ pmid: z.string().optional(), pmcid: z.string().optional() })).optional(),
-});
-/** PubMed search via esearch + esummary. */
-export async function searchPubmed(ncbiApiKey, query, options = {}) {
-    const maxResults = options.maxResults ?? 10;
-    const sort = options.sort ?? "relevance";
-    const esearchParams = {
-        db: "pubmed",
-        term: query,
-        retmax: maxResults,
-        retmode: "json",
-        sort: sort === "date" ? "pub+date" : "relevance",
-    };
-    if (options.dateRange) {
-        esearchParams.mindate = options.dateRange.from;
-        esearchParams.maxdate = options.dateRange.to;
-        esearchParams.datetype = "pdat";
-    }
-    const searchUrl = ncbiUrl(ncbiApiKey, `${NCBI_BASE}/esearch.fcgi`, esearchParams);
-    const searchResult = await apiFetchValidated(searchUrl, EsearchResponseSchema);
-    if (searchResult.isErr())
-        throw new Error(describeApiError(searchResult.error));
-    const idList = searchResult.value.esearchresult?.idlist ?? [];
-    const totalFound = parseInt(searchResult.value.esearchresult?.count ?? "0", 10);
-    if (idList.length === 0)
-        return { totalFound, results: [] };
-    const summaryUrl = ncbiUrl(ncbiApiKey, `${NCBI_BASE}/esummary.fcgi`, {
-        db: "pubmed",
-        id: idList.join(","),
-        retmode: "xml",
+import { createPubmedSource, } from "../../literature/sources/pubmed.js";
+function pubmedSource(ncbiApiKey) {
+    return createPubmedSource({
+        ...(ncbiApiKey === undefined ? {} : { apiKey: ncbiApiKey }),
+        maxRetries: 3,
+        retryDelayMs: 1_000,
+        timeoutMs: 90_000,
     });
-    const summaryResult = await apiFetch(summaryUrl, { parseAs: "text" });
-    if (summaryResult.isErr())
-        throw new Error(describeApiError(summaryResult.error));
-    return { totalFound, results: parseEsummary(summaryResult.value) };
+}
+function unwrap(result) {
+    if (result.status !== "ok")
+        throw new Error(result.detail);
+    return result.value;
+}
+/** PubMed search via esearch + esummary. */
+export async function searchPubmed(ncbiApiKey, query, options = {}, signal) {
+    return unwrap(await pubmedSource(ncbiApiKey).search(query, options, signal));
 }
 /** Fetch full PubMed article details (efetch + ID Converter for PMC). */
-export async function getArticleDetails(ncbiApiKey, pmids) {
-    const idString = pmids.join(",");
-    const efetchAsync = apiFetch(ncbiUrl(ncbiApiKey, `${NCBI_BASE}/efetch.fcgi`, {
-        db: "pubmed",
-        id: idString,
-        rettype: "xml",
-        retmode: "xml",
-    }), { parseAs: "text" });
-    const idConvAsync = apiFetchValidated(ncbiUrl(ncbiApiKey, NCBI_IDCONV, { ids: idString, format: "json" }), IdConvResponseSchema);
-    // Both requests run concurrently; each Result is awaited and handled below.
-    const efetchResult = await efetchAsync;
-    const idConvResult = await idConvAsync;
-    if (efetchResult.isErr())
-        throw new Error(describeApiError(efetchResult.error));
-    const articles = parseEfetch(efetchResult.value);
-    if (idConvResult.isOk()) {
-        const pmcMap = parseIdConvResponse(idConvResult.value);
-        for (const article of articles) {
-            article.pmcId = pmcMap.get(article.pmid) ?? null;
-        }
-    }
-    const foundPmids = new Set(articles.map((a) => a.pmid));
-    const notFound = pmids.filter((id) => !foundPmids.has(id));
-    return { articles, notFound };
+export async function getArticleDetails(ncbiApiKey, pmids, signal) {
+    return unwrap(await pubmedSource(ncbiApiKey).articleDetails(pmids, signal));
 }
 /** Trim the two unbounded list fields on each article, recording their true sizes. */
 export function boundArticleDetails(articles, options = {}) {
@@ -97,18 +48,8 @@ export function boundArticleDetails(articles, options = {}) {
  * Methods is worse than none) and admitted in document order until the budget
  * would be exceeded.
  */
-export async function getArticleFullText(ncbiApiKey, pmcId, options = {}) {
-    const numericId = pmcId.replace(/^PMC/i, "");
-    const url = ncbiUrl(ncbiApiKey, `${NCBI_BASE}/efetch.fcgi`, {
-        db: "pmc",
-        id: numericId,
-        rettype: "xml",
-        retmode: "xml",
-    });
-    const result = await apiFetch(url, { parseAs: "text" });
-    if (result.isErr())
-        throw new Error(describeApiError(result.error));
-    const parsed = parsePmcFullText(result.value);
+export async function getArticleFullText(ncbiApiKey, pmcId, options = {}, signal) {
+    const parsed = unwrap(await pubmedSource(ncbiApiKey).fetchFullText(pmcId, signal));
     if (!parsed)
         return null;
     return boundFullText(parsed, options);

package/dist/tools/research/generate-analogy-report.js

@@ -23,7 +23,7 @@ import { finalText, runAgent } from "../../loop/run-agent.js";
 import { passthroughStep } from "../../loop/run-step.js";
 import { defineTool } from "../define-tool.js";
 // Cross-domain search tools the analogical-reasoner uses.
-import { searchSemanticScholarTool } from "./search-semantic-scholar.js";
+import { createSearchSemanticScholarTool } from "./search-semantic-scholar.js";
 import { searchArxivTool } from "./search-arxiv.js";
 import { createSearchGithubReposTool } from "./search-github-repos.js";
 // Biology literature — reused for analogies that land back in biology.
@@ -156,7 +156,7 @@ function buildConversionPrompt(rawOutput) {
 export function createGenerateAnalogyReportTool(deps) {
     const ncbi = createNcbiTools(deps.bioKeys);
     const reasonerTools = [
-        searchSemanticScholarTool,
+        createSearchSemanticScholarTool({ ...(deps.bioKeys.semanticScholar === undefined ? {} : { apiKey: deps.bioKeys.semanticScholar }) }),
         searchArxivTool,
         createSearchGithubReposTool({ githubToken: deps.bioKeys.github }),
         ncbi.pubmed,