@inflexa-ai/harness 0.12.0 → 0.14.0

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;
+}>;

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

@@ -73,7 +73,14 @@ export async function getInteractionPartners(identifiers, options = {}) {
         throw new Error(describeApiError(res.error));
     return res.value.sort((a, b) => b.score - a.score);
 }
-/** Fetch the network among the given identifiers. */
+/**
+ * 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 async function getInteractionNetwork(identifiers, options = {}) {
     const params = buildParams(identifiers, options.species ?? 9606, {
         required_score: options.minScore ?? 400,
@@ -81,13 +88,23 @@ export async function getInteractionNetwork(identifiers, options = {}) {
     const res = await apiFetchValidated(`${STRING_BASE}/network?${params}`, z.array(StringInteractionSchema));
     if (res.isErr())
         throw new Error(describeApiError(res.error));
-    return res.value.sort((a, b) => b.score - a.score);
+    const sorted = res.value.sort((a, b) => b.score - a.score);
+    const limit = options.limit ?? sorted.length;
+    return { interactions: sorted.slice(0, limit), totalEdges: sorted.length };
 }
-/** Functional enrichment for a gene set. */
-export async function getEnrichment(identifiers, species = 9606) {
+/**
+ * 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 async function getEnrichment(identifiers, species = 9606, options = {}) {
     const params = buildParams(identifiers, species);
     const res = await apiFetchValidated(`${STRING_BASE}/enrichment?${params}`, z.array(StringEnrichmentSchema));
     if (res.isErr())
         throw new Error(describeApiError(res.error));
-    return res.value.sort((a, b) => a.fdr - b.fdr);
+    const sorted = res.value.sort((a, b) => a.fdr - b.fdr);
+    const limit = options.limit ?? sorted.length;
+    return { enrichment: sorted.slice(0, limit), totalTerms: sorted.length };
 }

package/dist/tools/research/generate-plan.d.ts

@@ -11,11 +11,10 @@
  * database already holds, and it would lose fidelity at every hop.
  *
  * The tool drives an internal "planner" agent that communicates outcomes
- * EXCLUSIVELY via four terminal tool calls:
+ * EXCLUSIVELY via three terminal tool calls:
  *
- *   - validate_plan(plan)       → non-terminal dry-run: an any-shape candidate
- *                                 in, {valid, issues} out (schema + semantic)
- *   - submit_plan(plan)         → terminal success: re-validates + persists
+ *   - submit_plan(plan)         → terminal success: re-validates + persists;
+ *                                 rejected candidates return structured issues
  *   - request_clarification(…)  → terminal: planner needs more context
  *   - report_blocker(reason)    → terminal: no viable plan
  *
@@ -29,19 +28,27 @@ import { type ChatProvider } from "../../providers/types.js";
 import { type Tool } from "../define-tool.js";
 import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
 import { type ResourcePolicy } from "../../config/resource-limits.js";
+import type { Logger } from "../../lib/logger.js";
 export interface GeneratePlanDeps extends EnvironmentStorePaths {
-    /** The LLM seam the planner loop runs on. */
-    readonly provider: ChatProvider;
+    /**
+     * The conversation-role backend the planner is pinned to. Keeping the
+     * provider and its model label in one value prevents composition roots from
+     * accidentally pairing the planner with the sandbox or utility role.
+     */
+    readonly conversation: {
+        readonly provider: ChatProvider;
+        readonly model: string;
+    };
     /** Database pool — plan persistence and prior-plan loading. */
     readonly pool: Pool;
-    /** Model id — provenance / metric label; the provider owns the wire model. */
-    readonly model: string;
     /**
      * Host resource policy — stated to the planner as concrete per-step
-     * ceilings and enforced by `validate_plan`. Absent, the prompt keeps its
+     * ceilings and enforced by `submit_plan`. Absent, the prompt keeps its
      * default guidance and validation skips the ceiling check.
      */
     readonly resourcePolicy?: ResourcePolicy;
+    /** Diagnostic sink. Absent, the tool runs silently — see `RunAgentOptions.logger`. */
+    readonly logger?: Logger;
 }
 /** Build the `generate_plan` tool bound to its provider and pool. */
 export declare function createGeneratePlanTool(deps: GeneratePlanDeps): Tool;