@inflexa-ai/harness 0.13.0 → 0.14.0

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

@@ -0,0 +1,83 @@
+/**
+ * Pure async client functions for DrugBank.
+ *
+ * Requires a DrugBank API key; `getDrugbankHeaders` throws when it is absent.
+ */
+import { z } from "zod";
+declare const DrugResultSchema: z.ZodPipe<z.ZodObject<{
+    drugbank_id: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    type: z.ZodOptional<z.ZodString>;
+    groups: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    categories: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        category: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    indication: z.ZodOptional<z.ZodString>;
+    pharmacodynamics: z.ZodOptional<z.ZodString>;
+    mechanism_of_action: z.ZodOptional<z.ZodString>;
+    toxicity: z.ZodOptional<z.ZodString>;
+    half_life: z.ZodOptional<z.ZodString>;
+    targets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        gene_name: z.ZodOptional<z.ZodString>;
+        actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        known_action: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    drug_interactions: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        drugbank_id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodTransform<{
+    drugbankId: string;
+    name: string;
+    description: string;
+    type: string;
+    groups: string[];
+    categories: string[];
+    indication: string;
+    pharmacodynamics: string;
+    mechanismOfAction: string;
+    toxicity: string;
+    halfLife: string;
+    targets: {
+        name: string;
+        geneSymbol: string;
+        actions: string[];
+        knownAction: string;
+    }[];
+    interactions: {
+        drugbankId: string;
+        name: string;
+        description: string;
+    }[];
+}, {
+    drugbank_id?: string | undefined;
+    name?: string | undefined;
+    description?: string | undefined;
+    type?: string | undefined;
+    groups?: string[] | undefined;
+    categories?: {
+        category?: string | undefined;
+    }[] | undefined;
+    indication?: string | undefined;
+    pharmacodynamics?: string | undefined;
+    mechanism_of_action?: string | undefined;
+    toxicity?: string | undefined;
+    half_life?: string | undefined;
+    targets?: {
+        name?: string | undefined;
+        gene_name?: string | undefined;
+        actions?: string[] | undefined;
+        known_action?: string | undefined;
+    }[] | undefined;
+    drug_interactions?: {
+        drugbank_id?: string | undefined;
+        name?: string | undefined;
+        description?: string | undefined;
+    }[] | undefined;
+}>>;
+export type DrugResult = z.infer<typeof DrugResultSchema>;
+export declare function searchDrugbank(apiKey: string, query: string, searchType: "drug" | "target", limit?: number): Promise<DrugResult[]>;
+export {};

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

@@ -0,0 +1,95 @@
+/**
+ * Pure async client functions for DrugBank.
+ *
+ * Requires a DrugBank API key; `getDrugbankHeaders` throws when it is absent.
+ */
+import { z } from "zod";
+import { apiFetchValidated, describeApiError } from "./api-utils.js";
+import { DRUGBANK_BASE, getDrugbankHeaders } from "./drugbank-config.js";
+/** Hard ceiling on each prose field at the parse boundary; callers trim further. */
+const PROSE_CEILING = 500;
+// A single schema that both validates and normalizes one DrugBank record.
+// The `.object(...)` half is the snake_case wire shape (every field optional —
+// the API omits absent values); the `.transform(...)` half maps it into the
+// camelCase result we return. Parsing IS the validation: `apiFetchValidated`
+// runs this schema over the JSON, so a payload whose field TYPES drift (an
+// object where the API used to send an array, a number for a string) is
+// rejected as `invalid_response` instead of being silently mis-mapped. Because
+// the schema carries the transform, `z.infer` below is the OUTPUT (camelCase)
+// type callers receive — there is no separate raw interface or mapper to keep
+// in sync.
+const DrugResultSchema = z
+    .object({
+    drugbank_id: z.string().optional(),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    type: z.string().optional(),
+    groups: z.array(z.string()).optional(),
+    categories: z.array(z.object({ category: z.string().optional() })).optional(),
+    indication: z.string().optional(),
+    pharmacodynamics: z.string().optional(),
+    mechanism_of_action: z.string().optional(),
+    toxicity: z.string().optional(),
+    half_life: z.string().optional(),
+    targets: z
+        .array(z.object({
+        name: z.string().optional(),
+        gene_name: z.string().optional(),
+        actions: z.array(z.string()).optional(),
+        known_action: z.string().optional(),
+    }))
+        .optional(),
+    drug_interactions: z
+        .array(z.object({
+        drugbank_id: z.string().optional(),
+        name: z.string().optional(),
+        description: z.string().optional(),
+    }))
+        .optional(),
+})
+    .transform((raw) => ({
+    drugbankId: raw.drugbank_id ?? "",
+    name: raw.name ?? "",
+    description: (raw.description ?? "").slice(0, PROSE_CEILING),
+    type: raw.type ?? "",
+    groups: raw.groups ?? [],
+    categories: (raw.categories ?? []).map((c) => c.category ?? "").filter(Boolean),
+    indication: (raw.indication ?? "").slice(0, PROSE_CEILING),
+    pharmacodynamics: (raw.pharmacodynamics ?? "").slice(0, PROSE_CEILING),
+    mechanismOfAction: (raw.mechanism_of_action ?? "").slice(0, PROSE_CEILING),
+    toxicity: (raw.toxicity ?? "").slice(0, PROSE_CEILING),
+    halfLife: raw.half_life ?? "",
+    targets: (raw.targets ?? []).map((t) => ({
+        name: t.name ?? "",
+        geneSymbol: t.gene_name ?? "",
+        actions: t.actions ?? [],
+        knownAction: t.known_action ?? "",
+    })),
+    interactions: (raw.drug_interactions ?? []).map((i) => ({
+        drugbankId: i.drugbank_id ?? "",
+        name: i.name ?? "",
+        description: (i.description ?? "").slice(0, 200),
+    })),
+}));
+// The /drugs endpoint returns a single object (by-id lookup) or an array
+// (query/target lookups); accept either, transforming each element.
+const DrugResponseSchema = z.union([DrugResultSchema, z.array(DrugResultSchema)]);
+export async function searchDrugbank(apiKey, query, searchType, limit = 10) {
+    const headers = getDrugbankHeaders(apiKey);
+    let url;
+    if (searchType === "target") {
+        url = `${DRUGBANK_BASE}/drugs?target=${encodeURIComponent(query)}&limit=${limit}`;
+    }
+    else if (query.startsWith("DB")) {
+        url = `${DRUGBANK_BASE}/drugs/${query}`;
+    }
+    else {
+        url = `${DRUGBANK_BASE}/drugs?q=${encodeURIComponent(query)}&limit=${limit}`;
+    }
+    const res = await apiFetchValidated(url, DrugResponseSchema, { headers });
+    if (res.isErr())
+        throw new Error(describeApiError(res.error));
+    // Already validated + normalized by DrugResultSchema's transform.
+    const drugs = Array.isArray(res.value) ? res.value : [res.value];
+    return drugs.slice(0, limit);
+}

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

@@ -17,8 +17,11 @@ export interface GeneInfo {
 }
 export interface LookupOptions {
     species?: string;
-    expand?: boolean;
 }
+/**
+ * Look up genes by symbol. Gene-level only: `RawGeneSchema`/`mapGene` model the
+ * gene record itself, so there is no transcript or exon detail to ask for.
+ */
 export declare function lookupGenes(symbols: string[], options?: LookupOptions): Promise<{
     genes: GeneInfo[];
     notFound: string[];

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

@@ -38,12 +38,14 @@ function mapGene(symbol, raw) {
         seqRegionName: raw.seq_region_name ?? "",
     };
 }
+/**
+ * Look up genes by symbol. Gene-level only: `RawGeneSchema`/`mapGene` model the
+ * gene record itself, so there is no transcript or exon detail to ask for.
+ */
 export async function lookupGenes(symbols, options = {}) {
     const species = options.species ?? "homo_sapiens";
-    const expand = options.expand ?? false;
     if (symbols.length === 1) {
-        const expandParam = expand ? "?expand=1" : "";
-        const result = await apiFetchValidated(`${ENSEMBL_BASE}/lookup/symbol/${species}/${symbols[0]}${expandParam}`, RawGeneSchema, { headers: HEADERS });
+        const result = await apiFetchValidated(`${ENSEMBL_BASE}/lookup/symbol/${species}/${symbols[0]}`, RawGeneSchema, { headers: HEADERS });
         if (result.isErr()) {
             if (result.error.type === "http_status" && result.error.status === 400) {
                 return { genes: [], notFound: [symbols[0]] };

package/dist/tools/lib/gwas-catalog-client.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure async client functions for the NHGRI-EBI GWAS Catalog REST API.
+ *
+ * Public, no key required. Three search paths: by gene (SNP-by-gene lookup then
+ * per-SNP associations), by trait (EFO trait search then its associations), and
+ * by variant (direct rsID associations).
+ */
+import { z } from "zod";
+export interface GwasAssociation {
+    rsId: string;
+    pValue: number;
+    pValueMantissa: number;
+    pValueExponent: number;
+    riskAllele: string;
+    riskFrequency: string;
+    orBeta: number | null;
+    ci: string;
+    trait: string;
+    mappedGenes: string[];
+    studyAccession: string;
+    pubmedId: string;
+    sampleSize: string;
+}
+export type GwasSearchType = "gene" | "trait" | "variant";
+declare const RawGwasAssociationSchema: z.ZodObject<{
+    _snpRsId: z.ZodOptional<z.ZodString>;
+    loci: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        strongestRiskAlleles: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            riskAlleleName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>;
+        authorReportedGenes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            geneName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+    efoTraits: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        trait: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+    study: z.ZodOptional<z.ZodObject<{
+        accessionId: z.ZodOptional<z.ZodString>;
+        pubmedId: z.ZodOptional<z.ZodString>;
+        initialSampleSize: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    pvalueMantissa: z.ZodOptional<z.ZodNumber>;
+    pvalueExponent: z.ZodOptional<z.ZodNumber>;
+    riskFrequency: z.ZodOptional<z.ZodString>;
+    orPerCopyNum: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    betaNum: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    range: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type RawGwasAssociation = z.infer<typeof RawGwasAssociationSchema>;
+export declare function mapAssociation(a: RawGwasAssociation): GwasAssociation;
+export interface GwasSearchOptions {
+    pValueThreshold?: number;
+    limit?: number;
+}
+export declare function searchGwasCatalog(query: string, searchType: GwasSearchType, options?: GwasSearchOptions): Promise<{
+    totalFound: number;
+    associations: GwasAssociation[];
+}>;
+export {};

package/dist/tools/lib/gwas-catalog-client.js

@@ -0,0 +1,136 @@
+/**
+ * Pure async client functions for the NHGRI-EBI GWAS Catalog REST API.
+ *
+ * Public, no key required. Three search paths: by gene (SNP-by-gene lookup then
+ * per-SNP associations), by trait (EFO trait search then its associations), and
+ * by variant (direct rsID associations).
+ */
+import { z } from "zod";
+import { apiFetchValidated, describeApiError } from "./api-utils.js";
+import { GWAS_BASE, GWAS_HEADERS } from "./gwas-catalog-config.js";
+// GWAS Catalog raw wire shapes (HAL+JSON), validated at the fetch boundary.
+// Every field is optional because the API omits absent values; leaf strings
+// that the API can return as an explicit `null` are `.nullable()`.
+const RawGwasStudySchema = z.object({
+    accessionId: z.string().optional(),
+    pubmedId: z.string().optional(),
+    initialSampleSize: z.string().optional(),
+});
+// `_snpRsId` is not on the wire — the 'gene' search path assigns it after
+// parsing (`a._snpRsId = snp.rsId`), so it stays a writable optional field.
+const RawGwasAssociationSchema = z.object({
+    _snpRsId: z.string().optional(),
+    loci: z
+        .array(z.object({
+        strongestRiskAlleles: z.array(z.object({ riskAlleleName: z.string().nullable().optional() })).optional(),
+        authorReportedGenes: z.array(z.object({ geneName: z.string().nullable().optional() })).optional(),
+    }))
+        .optional(),
+    efoTraits: z.array(z.object({ trait: z.string().nullable().optional() })).optional(),
+    study: RawGwasStudySchema.optional(),
+    pvalueMantissa: z.number().optional(),
+    pvalueExponent: z.number().optional(),
+    riskFrequency: z.string().optional(),
+    orPerCopyNum: z.number().nullable().optional(),
+    betaNum: z.number().nullable().optional(),
+    range: z.string().optional(),
+});
+const GwasEmbeddedSchema = z.object({
+    _embedded: z.object({ associations: z.array(RawGwasAssociationSchema).optional() }).optional(),
+    page: z.object({ totalElements: z.number().optional() }).optional(),
+});
+const GwasTraitSearchResponseSchema = z.object({
+    _embedded: z
+        .object({
+        efoTraits: z.array(z.object({ _links: z.object({ self: z.object({ href: z.string().optional() }).optional() }).optional() })).optional(),
+    })
+        .optional(),
+});
+const GwasSnpSearchResponseSchema = z.object({
+    _embedded: z
+        .object({
+        singleNucleotidePolymorphisms: z
+            .array(z.object({
+            rsId: z.string().optional(),
+            _links: z.object({ associations: z.object({ href: z.string().optional() }).optional() }).optional(),
+        }))
+            .optional(),
+    })
+        .optional(),
+});
+export function mapAssociation(a) {
+    const loci = a.loci ?? [];
+    const riskAlleles = loci.flatMap((l) => l.strongestRiskAlleles?.map((ra) => String(ra.riskAlleleName ?? "")) ?? []);
+    const genes = loci.flatMap((l) => l.authorReportedGenes?.map((g) => String(g.geneName ?? "")) ?? []);
+    const traits = (a.efoTraits ?? []).map((t) => String(t.trait ?? ""));
+    const study = a.study ?? {};
+    const pMantissa = a.pvalueMantissa ?? 0;
+    const pExponent = a.pvalueExponent ?? 0;
+    return {
+        rsId: String(a._snpRsId ?? riskAlleles[0]?.split("-")[0] ?? ""),
+        pValue: pMantissa * Math.pow(10, pExponent),
+        pValueMantissa: pMantissa,
+        pValueExponent: pExponent,
+        riskAllele: riskAlleles.join(", "),
+        riskFrequency: String(a.riskFrequency ?? ""),
+        orBeta: (a.orPerCopyNum ?? a.betaNum ?? null),
+        ci: String(a.range ?? ""),
+        trait: traits.join("; "),
+        mappedGenes: [...new Set(genes)],
+        studyAccession: String(study.accessionId ?? ""),
+        pubmedId: String(study.pubmedId ?? ""),
+        sampleSize: String(study.initialSampleSize ?? ""),
+    };
+}
+/** Max SNPs whose associations the 'gene' path walks; each is one request. */
+const GENE_PATH_MAX_SNPS = 10;
+export async function searchGwasCatalog(query, searchType, options = {}) {
+    const pValueThreshold = options.pValueThreshold ?? 5e-8;
+    const limit = options.limit ?? 25;
+    if (searchType === "gene") {
+        const url = `${GWAS_BASE}/singleNucleotidePolymorphisms/search/findByGene?geneName=${encodeURIComponent(query)}&projection=snpByGene`;
+        const snpRes = await apiFetchValidated(url, GwasSnpSearchResponseSchema, { headers: GWAS_HEADERS });
+        if (snpRes.isErr())
+            throw new Error(describeApiError(snpRes.error));
+        const snps = snpRes.value?._embedded?.singleNucleotidePolymorphisms ?? [];
+        const allAssocs = [];
+        for (const snp of snps.slice(0, Math.min(limit, GENE_PATH_MAX_SNPS))) {
+            const assocLink = snp?._links?.associations?.href;
+            if (!assocLink)
+                continue;
+            const aRes = await apiFetchValidated(assocLink, GwasEmbeddedSchema, { headers: GWAS_HEADERS });
+            if (aRes.isOk()) {
+                for (const a of aRes.value?._embedded?.associations ?? []) {
+                    a._snpRsId = snp.rsId;
+                    allAssocs.push(a);
+                }
+            }
+            if (allAssocs.length >= limit)
+                break;
+        }
+        return { totalFound: allAssocs.length, associations: allAssocs.slice(0, limit).map(mapAssociation) };
+    }
+    let associationsUrl;
+    if (searchType === "variant") {
+        const rsId = query.startsWith("rs") ? query : `rs${query}`;
+        associationsUrl = `${GWAS_BASE}/singleNucleotidePolymorphisms/${rsId}/associations?projection=associationBySnp`;
+    }
+    else {
+        const traitRes = await apiFetchValidated(`${GWAS_BASE}/efoTraits/search/findBySearchQuery?query=${encodeURIComponent(query)}`, GwasTraitSearchResponseSchema, {
+            headers: GWAS_HEADERS,
+        });
+        if (traitRes.isErr())
+            throw new Error(describeApiError(traitRes.error));
+        const traitUri = (traitRes.value?._embedded?.efoTraits ?? [])[0]?._links?.self?.href;
+        if (!traitUri)
+            return { totalFound: 0, associations: [] };
+        associationsUrl = `${GWAS_BASE}/efoTraits/${traitUri.split("/").pop()}/associations?size=${limit}`;
+    }
+    const res = await apiFetchValidated(associationsUrl, GwasEmbeddedSchema, { headers: GWAS_HEADERS });
+    if (res.isErr())
+        throw new Error(describeApiError(res.error));
+    const rawAssocs = res.value?._embedded?.associations ?? [];
+    const totalFound = res.value?.page?.totalElements ?? rawAssocs.length;
+    const filtered = rawAssocs.filter((a) => (a.pvalueMantissa ?? 1) * Math.pow(10, a.pvalueExponent ?? 0) <= pValueThreshold).slice(0, limit);
+    return { totalFound, associations: filtered.map(mapAssociation) };
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Pure async client functions for PharmGKB clinical annotations.
+ *
+ * Public API, no key required. Matching is an exact field filter, not a search:
+ * `location.genes.symbol` for a gene, `relatedChemicals.name` for a drug.
+ */
+/**
+ * One PharmGKB clinical annotation.
+ *
+ * `levelOfEvidence` is the only strength signal this endpoint carries — the
+ * phenotype, guideline source and summary live on other PharmGKB resources, so
+ * they are absent here rather than present-and-null.
+ */
+export interface PharmgkbAnnotation {
+    gene: string;
+    drug: string;
+    levelOfEvidence: string;
+}
+export declare function searchPharmgkb(query: string, searchType: "gene" | "drug", limit?: number): Promise<{
+    annotations: PharmgkbAnnotation[];
+    totalFound: number;
+}>;

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

@@ -0,0 +1,32 @@
+/**
+ * Pure async client functions for PharmGKB clinical annotations.
+ *
+ * Public API, no key required. Matching is an exact field filter, not a search:
+ * `location.genes.symbol` for a gene, `relatedChemicals.name` for a drug.
+ */
+import { z } from "zod";
+import { apiFetchValidated, describeApiError } from "./api-utils.js";
+import { PHARMGKB_BASE, PHARMGKB_HEADERS } from "./pharmgkb-config.js";
+// Raw PharmGKB clinicalAnnotation wire shape, validated at the fetch boundary.
+// Every field is optional because the API omits absent values.
+const PharmgkbAnnotationSchema = z.object({
+    location: z.object({ genes: z.array(z.object({ symbol: z.string().optional() })).optional() }).optional(),
+    relatedChemicals: z.array(z.object({ name: z.string().optional() })).optional(),
+    levelOfEvidence: z.object({ term: z.string().optional() }).optional(),
+});
+const PharmgkbResponseSchema = z.object({
+    data: z.array(PharmgkbAnnotationSchema).optional(),
+});
+export async function searchPharmgkb(query, searchType, limit = 20) {
+    const filter = searchType === "gene" ? `location.genes.symbol=${encodeURIComponent(query)}` : `relatedChemicals.name=${encodeURIComponent(query)}`;
+    const res = await apiFetchValidated(`${PHARMGKB_BASE}/clinicalAnnotation?${filter}`, PharmgkbResponseSchema, { headers: PHARMGKB_HEADERS });
+    if (res.isErr())
+        throw new Error(describeApiError(res.error));
+    const data = res.value?.data ?? [];
+    const annotations = data.slice(0, limit).map((ann) => ({
+        gene: ann.location?.genes?.map((g) => g.symbol).join(", ") ?? query,
+        drug: ann.relatedChemicals?.map((c) => c.name).join(", ") ?? "",
+        levelOfEvidence: ann.levelOfEvidence?.term ?? "Unknown",
+    }));
+    return { annotations, totalFound: data.length };
+}

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

@@ -4,8 +4,8 @@
  * Used by §3.11 (Key Papers), §3.10.4 (Preclinical literature), and the
  * pubmed-index Phase-1 collector.
  */
-import { type ArticleDetail, type PubMedSummary, type FullTextResult } from "./ncbi-utils.js";
-export type { PubMedSummary, ArticleDetail, FullTextResult };
+import { type ArticleDetail, type ArticleSection, type PubMedSummary, type FullTextResult } from "./ncbi-utils.js";
+export type { PubMedSummary, ArticleDetail, ArticleSection, FullTextResult };
 export interface SearchOptions {
     maxResults?: number;
     sort?: "relevance" | "date";
@@ -19,10 +19,63 @@ export declare function searchPubmed(ncbiApiKey: string | undefined, query: stri
     totalFound: number;
     results: PubMedSummary[];
 }>;
+export interface DetailOptions {
+    /** Authors kept per article before collapsing the rest into `authorCount`. */
+    maxAuthors?: number;
+    /** MeSH terms kept per article; 0 drops the list entirely. */
+    maxMeshTerms?: number;
+}
+/**
+ * One article as the tool returns it: `ArticleDetail` with the two unbounded
+ * list fields trimmed. A consortium paper can carry hundreds of authors and
+ * dozens of MeSH headings — neither is worth the context, so the counts travel
+ * instead of the tails.
+ */
+export interface BoundedArticleDetail extends ArticleDetail {
+    authorCount: number;
+    meshTermCount: number;
+}
 /** Fetch full PubMed article details (efetch + ID Converter for PMC). */
 export declare function getArticleDetails(ncbiApiKey: string | undefined, pmids: string[]): Promise<{
     articles: ArticleDetail[];
     notFound: string[];
 }>;
-/** Fetch open-access full text from PMC. Returns null when unavailable. */
-export declare function getArticleFullText(ncbiApiKey: string | undefined, pmcId: string): Promise<FullTextResult | null>;
+/** Trim the two unbounded list fields on each article, recording their true sizes. */
+export declare function boundArticleDetails(articles: ArticleDetail[], options?: DetailOptions): BoundedArticleDetail[];
+export interface FullTextOptions {
+    /** Case-insensitive substring match against section headings. */
+    sections?: string[];
+    /** Character budget across the returned section bodies. */
+    maxChars?: number;
+}
+/**
+ * A full text trimmed to a character budget. `outline` always lists EVERY
+ * section in the article with its size and whether the body came back, so one
+ * call is enough to decide which sections a follow-up should request — the
+ * alternative is the agent guessing headings it has not seen.
+ */
+export interface BoundedFullText {
+    fullText: string;
+    sections: ArticleSection[];
+    outline: {
+        heading: string;
+        chars: number;
+        included: boolean;
+    }[];
+    totalChars: number;
+    returnedChars: number;
+    truncated: boolean;
+}
+/**
+ * Fetch open-access full text from PMC, trimmed to a section filter and a
+ * character budget. Returns null when the article is not open-access.
+ *
+ * A research article routinely parses to 40–80k characters, so returning the
+ * whole body by default would spend more context on one paper than the entire
+ * tool surface costs to attach. Sections are kept whole (a half-sentence of
+ * 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>;
+/** 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

@@ -75,8 +75,29 @@ export async function getArticleDetails(ncbiApiKey, pmids) {
     const notFound = pmids.filter((id) => !foundPmids.has(id));
     return { articles, notFound };
 }
-/** Fetch open-access full text from PMC. Returns null when unavailable. */
-export async function getArticleFullText(ncbiApiKey, pmcId) {
+/** Trim the two unbounded list fields on each article, recording their true sizes. */
+export function boundArticleDetails(articles, options = {}) {
+    const maxAuthors = options.maxAuthors ?? 5;
+    const maxMeshTerms = options.maxMeshTerms ?? 10;
+    return articles.map((a) => ({
+        ...a,
+        authors: a.authors.slice(0, maxAuthors),
+        authorCount: a.authors.length,
+        meshTerms: a.meshTerms.slice(0, maxMeshTerms),
+        meshTermCount: a.meshTerms.length,
+    }));
+}
+/**
+ * Fetch open-access full text from PMC, trimmed to a section filter and a
+ * character budget. Returns null when the article is not open-access.
+ *
+ * A research article routinely parses to 40–80k characters, so returning the
+ * whole body by default would spend more context on one paper than the entire
+ * tool surface costs to attach. Sections are kept whole (a half-sentence of
+ * 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",
@@ -87,5 +108,38 @@ export async function getArticleFullText(ncbiApiKey, pmcId) {
     const result = await apiFetch(url, { parseAs: "text" });
     if (result.isErr())
         throw new Error(describeApiError(result.error));
-    return parsePmcFullText(result.value);
+    const parsed = parsePmcFullText(result.value);
+    if (!parsed)
+        return null;
+    return boundFullText(parsed, options);
+}
+/** Apply the section filter and character budget to a parsed full text. */
+export function boundFullText(parsed, options = {}) {
+    const maxChars = options.maxChars ?? 12_000;
+    const needles = (options.sections ?? []).map((s) => s.toLowerCase()).filter(Boolean);
+    const totalChars = parsed.sections.reduce((n, s) => n + s.text.length, 0);
+    const outline = [];
+    const kept = [];
+    let returnedChars = 0;
+    for (const section of parsed.sections) {
+        const matchesFilter = needles.length === 0 || needles.some((n) => section.heading.toLowerCase().includes(n));
+        // A section is admitted whole or not at all. The first section is always
+        // admitted even if it alone busts the budget — a single-section article
+        // would otherwise come back empty with no way to ask for less.
+        const fits = returnedChars + section.text.length <= maxChars || kept.length === 0;
+        const included = matchesFilter && fits;
+        if (included) {
+            kept.push(section);
+            returnedChars += section.text.length;
+        }
+        outline.push({ heading: section.heading, chars: section.text.length, included });
+    }
+    return {
+        fullText: kept.map((s) => (s.heading ? `## ${s.heading}\n\n${s.text}` : s.text)).join("\n\n"),
+        sections: kept,
+        outline,
+        totalChars,
+        returnedChars,
+        truncated: returnedChars < totalChars,
+    };
 }

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

@@ -27,7 +27,28 @@ export interface InteractionOptions {
 }
 /** Fetch interaction partners (one-hop) for the given identifiers. */
 export declare function getInteractionPartners(identifiers: string[], options?: InteractionOptions): Promise<StringInteraction[]>;
-/** Fetch the network among the given identifiers. */
-export declare function getInteractionNetwork(identifiers: string[], options?: InteractionOptions): Promise<StringInteraction[]>;
-/** Functional enrichment for a gene set. */
-export declare function getEnrichment(identifiers: string[], species?: number): Promise<StringEnrichment[]>;
+/**
+ * Fetch the network among the given identifiers.
+ *
+ * STRING has no server-side row cap on `/network` — edge count grows with the
+ * square of the input set, so `limit` truncates the score-sorted rows here.
+ * `totalEdges` reports the true count so a caller can tell a trimmed network
+ * from a sparse one.
+ */
+export declare function getInteractionNetwork(identifiers: string[], options?: InteractionOptions): Promise<{
+    interactions: StringInteraction[];
+    totalEdges: number;
+}>;
+/**
+ * Functional enrichment for a gene set.
+ *
+ * STRING returns every enriched term across all categories (GO, KEGG,
+ * Reactome, Pfam, …) with the full member-gene list per term, so `limit`
+ * truncates the FDR-sorted rows and `totalTerms` reports what was there.
+ */
+export declare function getEnrichment(identifiers: string[], species?: number, options?: {
+    limit?: number;
+}): Promise<{
+    enrichment: StringEnrichment[];
+    totalTerms: number;
+}>;