@inflexa-ai/harness 0.29.0 → 0.30.0

package/dist/tools/bio/search-interactions.js

@@ -8,13 +8,17 @@ import { getEnrichment, getInteractionNetwork, getInteractionPartners } from "..
 const DEFAULT_LIMIT = 20;
 export const searchInteractionsTool = defineTool({
     id: "search_interactions",
-    description: "Query STRING DB for protein-protein interactions and gene-set functional enrichment. " +
+    description: "Query the STRING database — the protein-protein association network of EMBL, which folds experimental, database, co-expression and text-mined " +
+        "evidence into one confidence score — for interactions and gene-set functional enrichment. " +
         "'partners' — the one-hop interaction partners of the input proteins, score-sorted: 'what else does this protein work with?'. " +
         "'network' — the interactions AMONG the input proteins only, no new nodes: 'is my gene set actually connected?'. " +
         "'enrichment' — statistical over-representation of GO, KEGG, Reactome and Pfam terms in the input set, FDR-sorted: the enrichment TEST, as " +
         "opposed to lookup_annotation, which just reads a vocabulary. " +
+        "ACCEPTED IDENTIFIERS: STRING resolves each one itself, so a HUGO gene symbol ('TP53'), a UniProt accession ('P04637'), an Ensembl protein ID " +
+        "('ENSP00000269305') and a full protein name all work, mixed in one call. `species` takes an NCBI Taxonomy ID (9606 = human).\n" +
         "`limit` applies to all three actions and defaults small: a network over N proteins grows with N² edges. `totalEdges` / `totalTerms` give the " +
-        "pre-trim counts. An empty result is valid no-data (unconnected set, no enriched term, unresolvable identifiers) — do not retry.",
+        "pre-trim counts. An empty result is valid no-data (unconnected set, no enriched term, unresolvable identifiers) — report it and continue, do " +
+        "not retry.",
     inputSchema: z.object({
         identifiers: z.array(z.string()).min(1).max(100).describe("Protein/gene identifiers (e.g. ['TP53', 'BRCA1'])"),
         species: z.number().int().default(9606).describe("NCBI Taxonomy ID (9606 = human, 10090 = mouse)"),

package/dist/tools/bio/target-safety.d.ts

@@ -40,14 +40,14 @@ export declare const targetSafetyTool: import("../define-tool.js").Tool<{
     identifierType?: "auto" | "gene_symbol" | "uniprot" | "chembl_id" | "ensembl_id" | undefined;
     sources?: ("opentargets" | "panel")[] | undefined;
     filterOrgan?: "hematologic" | "metabolic" | "immune" | "hepatic" | "musculoskeletal" | "cns" | "renal" | "reproductive" | "respiratory" | "cardiac" | "vascular" | "pns" | "gi" | "pancreas" | "endocrine_thyroid" | "dermatologic" | "ocular" | "oncology" | undefined;
-    minSeverity?: "high" | "medium" | "low" | undefined;
+    minSeverity?: "low" | "medium" | "high" | undefined;
     liabilityLimit?: number | undefined;
 }, {
     perSource: SourceOutcome[];
     summary: {
         totalInput: number;
         panelMatched: number;
-        bySeverity: Record<"high" | "medium" | "low", number>;
+        bySeverity: Record<"low" | "medium" | "high", number>;
         byOrgan: Record<string, number>;
         openTargetsWithLiabilities: number;
     };

package/dist/tools/bio/target-safety.js

@@ -92,8 +92,9 @@ const inputSchema = z
 export const targetSafetyTool = defineTool({
     id: "target_safety",
     description: "TARGET-level, mechanism-based safety liability — the curated secondary-pharmacology panel and Open Targets' curated liabilities in one call. " +
-        "Judges what engaging a target is likely to do to an organ system, before any specific molecule exists. Identifiers may be gene symbols, ChEMBL " +
-        "target IDs, UniProt accessions or Ensembl gene IDs, mixed.\n" +
+        "Judges what engaging a target is likely to do to an organ system, before any specific molecule exists.\n" +
+        "ACCEPTED IDENTIFIERS, mixed freely in one call: a HUGO gene symbol ('HERG', 'KCNH2'), a ChEMBL target ID ('CHEMBL240'), a UniProt accession " +
+        "('Q12809') and an Ensembl gene ID ('ENSG00000055118').\n" +
         "This is the safety of the TARGET, not of a drug. For a marketed molecule's post-market adverse events use search_faers; for a chemical's " +
         "toxicology use comptox; for what removing the gene does in vivo use gene_preclinical_profile.\n" +
         "ABSENCE IS NOT SAFETY. The panel is finite and hand-curated, so no match means only 'not on the panel'; an empty Open Targets liability list " +

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

@@ -36,6 +36,8 @@ const RawCancerStudySchema = z.object({
     cancerType: z.object({ name: z.string().optional(), cancerTypeId: z.string().optional() }).optional(),
     name: z.string().optional(),
     description: z.string().optional(),
+    /** The denominator of a study. The sample-list SUMMARY projection carries no count. */
+    allSampleCount: z.number().optional(),
 });
 async function listStudies() {
     const url = `${CBIOPORTAL_BASE}/studies?projection=SUMMARY&pageSize=10000`;
@@ -44,6 +46,23 @@ async function listStudies() {
         throw new Error(describeApiError(res.error));
     return res.value ?? [];
 }
+/**
+ * The cancer-type vocabulary, keyed by its id. The study SUMMARY projection
+ * carries the id alone, thus a row would otherwise report `esca` where it must
+ * report `Esophageal Adenocarcinoma`.
+ */
+async function cancerTypeNames() {
+    const url = `${CBIOPORTAL_BASE}/cancer-types?pageSize=10000`;
+    const res = await apiFetchValidated(url, z.array(z.object({ cancerTypeId: z.string().optional(), name: z.string().optional() })), { headers: HEADERS });
+    const names = new Map();
+    if (res.isErr())
+        return names;
+    for (const row of res.value ?? []) {
+        if (row.cancerTypeId && row.name)
+            names.set(row.cancerTypeId, row.name);
+    }
+    return names;
+}
 async function listAllSampleLists() {
     const url = `${CBIOPORTAL_BASE}/sample-lists?projection=SUMMARY&pageSize=10000`;
     const res = await apiFetchValidated(url, z.array(RawSampleListSchema), { headers: HEADERS });
@@ -98,7 +117,7 @@ export async function getSomaticMutationFrequencies(geneSymbol, options = {}) {
     const entrezGeneId = await resolveEntrezId(geneSymbol);
     if (entrezGeneId == null)
         return { entrezGeneId: null, rows: [] };
-    const [studies, profiles, sampleLists] = await Promise.all([listStudies(), listMutationProfiles(), listAllSampleLists()]);
+    const [studies, profiles, sampleLists, typeNames] = await Promise.all([listStudies(), listMutationProfiles(), listAllSampleLists(), cancerTypeNames()]);
     const allSampleListByStudy = new Map();
     for (const sl of sampleLists) {
         if (sl.category === "all_cases_in_study") {
@@ -122,12 +141,12 @@ export async function getSomaticMutationFrequencies(geneSymbol, options = {}) {
     }
     const byCancerType = new Map();
     for (const studyId of studiesWithMutations) {
-        const sl = allSampleListByStudy.get(studyId);
-        if (!sl?.sampleCount)
-            continue;
         const study = studyById.get(studyId);
+        const sampleCount = study?.allSampleCount ?? 0;
+        if (sampleCount === 0)
+            continue;
         const cancerTypeId = study?.cancerType?.cancerTypeId ?? study?.cancerTypeId ?? "unknown";
-        const cancerTypeName = study?.cancerType?.name ?? cancerTypeId;
+        const cancerTypeName = study?.cancerType?.name ?? typeNames.get(cancerTypeId) ?? cancerTypeId;
         if (!byCancerType.has(cancerTypeId)) {
             byCancerType.set(cancerTypeId, {
                 name: cancerTypeName,
@@ -137,7 +156,7 @@ export async function getSomaticMutationFrequencies(geneSymbol, options = {}) {
             });
         }
         const bucket = byCancerType.get(cancerTypeId);
-        bucket.total += sl.sampleCount;
+        bucket.total += sampleCount;
         bucket.mutated += mutatedStudySamples.get(studyId)?.size ?? 0;
         bucket.studies.add(studyId);
     }

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

@@ -68,7 +68,9 @@ export interface ChemblPolypharmHit {
 /** Search ChEMBL for compounds by target, compound name, or SMILES. */
 export declare function searchCompounds(query: string, searchType: CompoundSearchType, limit?: number): Promise<ChemblCompound[]>;
 export declare function searchTargets(query: string, limit?: number): Promise<ChemblTarget[]>;
-export declare function getBioactivity(chemblId: string, type: "compound" | "target", options?: {
+/** Which column of the ChEMBL activity table the supplied id indexes. */
+export type BioactivityIdType = "compound" | "target" | "assay";
+export declare function getBioactivity(chemblId: string, type: BioactivityIdType, options?: {
     activityType?: string;
     limit?: number;
 }): Promise<ChemblActivity[]>;

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

@@ -241,9 +241,14 @@ export async function searchTargets(query, limit = 25) {
     }
     return (res.value.targets ?? []).map(mapTarget);
 }
+const ACTIVITY_ID_FIELD = {
+    compound: "molecule_chembl_id",
+    target: "target_chembl_id",
+    assay: "assay_chembl_id",
+};
 export async function getBioactivity(chemblId, type, options = {}) {
     const limit = options.limit ?? 500;
-    const idParam = type === "compound" ? `molecule_chembl_id=${encodeURIComponent(chemblId)}` : `target_chembl_id=${encodeURIComponent(chemblId)}`;
+    const idParam = `${ACTIVITY_ID_FIELD[type]}=${encodeURIComponent(chemblId)}`;
     let url = `${CHEMBL_BASE}/activity.json?${idParam}&limit=${limit}`;
     if (options.activityType) {
         url += `&standard_type=${encodeURIComponent(options.activityType)}`;

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

@@ -1,9 +1,10 @@
 /**
  * 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).
+ * Public, no key required. Four search paths: by gene (SNP-by-gene lookup then
+ * per-SNP associations), by trait (EFO trait search then its associations), by
+ * variant (direct rsID associations), and by study (the associations of one
+ * GCST study accession).
  */
 import { z } from "zod";
 export interface GwasAssociation {
@@ -21,7 +22,7 @@ export interface GwasAssociation {
     pubmedId: string;
     sampleSize: string;
 }
-export type GwasSearchType = "gene" | "trait" | "variant";
+export type GwasSearchType = "gene" | "trait" | "variant" | "study";
 declare const RawGwasAssociationSchema: z.ZodObject<{
     _snpRsId: z.ZodOptional<z.ZodString>;
     loci: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -42,10 +43,10 @@ declare const RawGwasAssociationSchema: z.ZodObject<{
     }, z.core.$strip>>;
     pvalueMantissa: z.ZodOptional<z.ZodNumber>;
     pvalueExponent: z.ZodOptional<z.ZodNumber>;
-    riskFrequency: z.ZodOptional<z.ZodString>;
+    riskFrequency: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     orPerCopyNum: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     betaNum: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-    range: z.ZodOptional<z.ZodString>;
+    range: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 type RawGwasAssociation = z.infer<typeof RawGwasAssociationSchema>;
 export declare function mapAssociation(a: RawGwasAssociation): GwasAssociation;

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

@@ -1,9 +1,10 @@
 /**
  * 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).
+ * Public, no key required. Four search paths: by gene (SNP-by-gene lookup then
+ * per-SNP associations), by trait (EFO trait search then its associations), by
+ * variant (direct rsID associations), and by study (the associations of one
+ * GCST study accession).
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError } from "./api-utils.js";
@@ -30,10 +31,10 @@ const RawGwasAssociationSchema = z.object({
     study: RawGwasStudySchema.optional(),
     pvalueMantissa: z.number().optional(),
     pvalueExponent: z.number().optional(),
-    riskFrequency: z.string().optional(),
+    riskFrequency: z.string().nullable().optional(),
     orPerCopyNum: z.number().nullable().optional(),
     betaNum: z.number().nullable().optional(),
-    range: z.string().optional(),
+    range: z.string().nullable().optional(),
 });
 const GwasEmbeddedSchema = z.object({
     _embedded: z.object({ associations: z.array(RawGwasAssociationSchema).optional() }).optional(),
@@ -115,6 +116,12 @@ export async function searchGwasCatalog(query, searchType, options = {}) {
         const rsId = query.startsWith("rs") ? query : `rs${query}`;
         associationsUrl = `${GWAS_BASE}/singleNucleotidePolymorphisms/${rsId}/associations?projection=associationBySnp`;
     }
+    else if (searchType === "study") {
+        // The study endpoint keys on the accession alone. The projection nests
+        // the study record on each association, thus `mapAssociation` reads the
+        // accession, the PubMed id and the sample size without a second request.
+        associationsUrl = `${GWAS_BASE}/studies/${encodeURIComponent(query)}/associations?projection=associationByStudy&size=${limit}`;
+    }
     else {
         const traitRes = await apiFetchValidated(`${GWAS_BASE}/efoTraits/search/findBySearchQuery?query=${encodeURIComponent(query)}`, GwasTraitSearchResponseSchema, {
             headers: GWAS_HEADERS,
@@ -127,8 +134,13 @@ export async function searchGwasCatalog(query, searchType, options = {}) {
         associationsUrl = `${GWAS_BASE}/efoTraits/${traitUri.split("/").pop()}/associations?size=${limit}`;
     }
     const res = await apiFetchValidated(associationsUrl, GwasEmbeddedSchema, { headers: GWAS_HEADERS });
-    if (res.isErr())
+    if (res.isErr()) {
+        // An accession or an rsID that the catalog does not hold is absence, not
+        // a failure, thus it returns an empty record set.
+        if (res.error.type === "http_status" && res.error.status === 404)
+            return { totalFound: 0, associations: [] };
         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);

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

@@ -43,11 +43,13 @@ export declare function getFaersByDrug(drugName: string, options?: {
  */
 export declare function getFaersSeriousness(drugName: string): Promise<SeriousnessProfile | null>;
 /**
- * Fetch FDA Structured Product Label entries by generic drug name. Returns
- * the most recent N labels (sorted by effective_time desc); each row carries
- * the boxed-warning text, the Section 5 warnings_and_cautions excerpt, and a
- * REMS indicator. Returns [] on 404 / no match.
+ * Fetch FDA Structured Product Label entries by drug name. The name matches
+ * the generic name or the brand name, thus a caller that holds only a brand
+ * name reads the generic name back off each row. Returns the most recent N
+ * labels (sorted by effective_time desc). Each row carries the boxed-warning
+ * text, the Section 5 warnings_and_cautions excerpt, and a REMS indicator.
+ * Returns [] on 404 / no match.
  */
-export declare function getDrugLabelActions(genericName: string, options?: {
+export declare function getDrugLabelActions(drugName: string, options?: {
     limit?: number;
 }): Promise<DrugLabelAction[]>;

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

@@ -42,11 +42,17 @@ const OpenFdaLabelSchema = z.object({
 function escapeQueryPhrase(value) {
     return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
 }
+/**
+ * A boolean operator is separated by a space, never by a literal `+`. The whole
+ * search string goes through `encodeURIComponent`, which turns a `+` into
+ * `%2B`. openFDA then reads that as a character of the term and matches
+ * nothing, but it reads `%20` as the separator that it is.
+ */
 function buildSearch(drugName, serious) {
     const escaped = escapeQueryPhrase(drugName);
     let search = `patient.drug.openfda.generic_name:"${escaped}"`;
     if (serious)
-        search += "+AND+serious:1";
+        search += " AND serious:1";
     return search;
 }
 /** Top adverse-reaction terms by count for a generic drug name. */
@@ -98,7 +104,7 @@ export async function getFaersSeriousness(drugName) {
         };
     }
     async function countWith(field) {
-        const q = `${search}+AND+${field}:1`;
+        const q = `${search} AND ${field}:1`;
         const url = `${OPENFDA_BASE}?search=${encodeURIComponent(q)}&limit=1`;
         const res = await apiFetchValidated(url, FaersMetaResponseSchema);
         if (res.isErr())
@@ -180,15 +186,17 @@ const OpenFdaLabelResponseSchema = z.object({
     results: z.array(OpenFdaLabelSchema.transform(mapLabel)).optional(),
 });
 /**
- * Fetch FDA Structured Product Label entries by generic drug name. Returns
- * the most recent N labels (sorted by effective_time desc); each row carries
- * the boxed-warning text, the Section 5 warnings_and_cautions excerpt, and a
- * REMS indicator. Returns [] on 404 / no match.
+ * Fetch FDA Structured Product Label entries by drug name. The name matches
+ * the generic name or the brand name, thus a caller that holds only a brand
+ * name reads the generic name back off each row. Returns the most recent N
+ * labels (sorted by effective_time desc). Each row carries the boxed-warning
+ * text, the Section 5 warnings_and_cautions excerpt, and a REMS indicator.
+ * Returns [] on 404 / no match.
  */
-export async function getDrugLabelActions(genericName, options = {}) {
+export async function getDrugLabelActions(drugName, options = {}) {
     const limit = options.limit ?? 5;
-    const escaped = escapeQueryPhrase(genericName);
-    const search = `openfda.generic_name:"${escaped}"`;
+    const escaped = escapeQueryPhrase(drugName);
+    const search = `(openfda.generic_name:"${escaped}" OR openfda.brand_name:"${escaped}")`;
     const url = `${OPENFDA_LABEL_BASE}?search=${encodeURIComponent(search)}` + `&sort=effective_time:desc&limit=${limit}`;
     const res = await apiFetchValidated(url, OpenFdaLabelResponseSchema);
     if (res.isErr()) {

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

@@ -35,6 +35,17 @@ export interface SafetyLiability {
     effects: string | null;
     source: string;
 }
+/**
+ * One disease or trait that Open Targets holds, as the free-text resolver
+ * returns it. The `id` is the identifier that `searchDiseaseAssociations`
+ * accepts. Open Targets keys a disease on the EFO ontology, which imports
+ * MONDO, Orphanet and HP, thus an id can read `EFO_…`, `MONDO_…` or `HP_…`.
+ */
+export interface DiseaseCandidate {
+    id: string;
+    name: string;
+    description: string | null;
+}
 export interface BaselineExpressionEntry {
     tissueId: string;
     tissueLabel: string;
@@ -51,6 +62,15 @@ export interface BaselineExpressionEntry {
 export declare function searchTargetAssociations(ensemblId: string, limit?: number): Promise<TargetInfo | null>;
 /** Fetch target associations for a disease (EFO id). */
 export declare function searchDiseaseAssociations(efoId: string, limit?: number): Promise<Association[]>;
+/**
+ * Resolve a free-text disease or trait name to the disease ids that
+ * `searchDiseaseAssociations` accepts. A name that matches nothing gives an
+ * empty candidate list, which is a normal outcome and not an error.
+ */
+export declare function searchDiseases(query: string, limit?: number): Promise<{
+    total: number;
+    candidates: DiseaseCandidate[];
+}>;
 /** Fetch known safety liabilities for a target. */
 export declare function getTargetSafetyLiabilities(ensemblId: string): Promise<{
     targetSymbol: string;

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

@@ -50,6 +50,18 @@ const DISEASE_QUERY = `
     }
   }
 `;
+const DISEASE_SEARCH_QUERY = `
+  query DiseaseSearch($queryString: String!, $size: Int!) {
+    search(queryString: $queryString, entityNames: ["disease"], page: { size: $size, index: 0 }) {
+      total
+      hits {
+        id
+        name
+        description
+      }
+    }
+  }
+`;
 const SAFETY_QUERY = `
   query TargetSafety($ensemblId: String!) {
     target(ensemblId: $ensemblId) {
@@ -147,6 +159,22 @@ const DiseaseAssociationsDataSchema = z.object({
         .nullable()
         .optional(),
 });
+const DiseaseSearchDataSchema = z.object({
+    search: z
+        .object({
+        total: z.number().nullable().optional(),
+        hits: z
+            .array(z.object({
+            id: z.string(),
+            name: z.string().nullable().optional(),
+            description: z.string().nullable().optional(),
+        }))
+            .nullable()
+            .optional(),
+    })
+        .nullable()
+        .optional(),
+});
 const TargetSafetyDataSchema = z.object({
     target: z
         .object({
@@ -253,6 +281,23 @@ export async function searchDiseaseAssociations(efoId, limit = 25) {
         literaturePmids: [],
     }));
 }
+/**
+ * Resolve a free-text disease or trait name to the disease ids that
+ * `searchDiseaseAssociations` accepts. A name that matches nothing gives an
+ * empty candidate list, which is a normal outcome and not an error.
+ */
+export async function searchDiseases(query, limit = 10) {
+    const data = await gqlFetch(DISEASE_SEARCH_QUERY, { queryString: query, size: limit }, DiseaseSearchDataSchema);
+    const hits = data.search?.hits ?? [];
+    return {
+        total: data.search?.total ?? hits.length,
+        candidates: hits.map((hit) => ({
+            id: hit.id,
+            name: hit.name ?? "",
+            description: hit.description ?? null,
+        })),
+    };
+}
 /** Fetch known safety liabilities for a target. */
 export async function getTargetSafetyLiabilities(ensemblId) {
     const data = await gqlFetch(SAFETY_QUERY, { ensemblId }, TargetSafetyDataSchema);

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

@@ -23,5 +23,12 @@ export interface PathwaySearchOptions {
 export declare function searchKegg(query: string, organism: string, maxResults: number, includeGenes: boolean): Promise<Pathway[]>;
 export declare function searchReactome(query: string, species: string, maxResults: number, includeGenes: boolean): Promise<Pathway[]>;
 export declare function searchPathways(query: string, options?: PathwaySearchOptions): Promise<Pathway[]>;
+/**
+ * Read one pathway by its own identifier. The prefix of the identifier picks
+ * the database, thus the caller passes the id back exactly as a search
+ * returned it. An identifier that neither database holds gives null, which is
+ * absence and not a failure.
+ */
+export declare function getPathwayById(id: string): Promise<Pathway | null>;
 /** Pathway memberships for a gene symbol — used directly by §3.7 collector. */
 export declare function getPathwayMemberships(geneSymbol: string): Promise<Pathway[]>;

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

@@ -6,7 +6,11 @@
 import { z } from "zod";
 import { apiFetch, apiFetchValidated, parseTSV } from "./api-utils.js";
 const KEGG_BASE = "https://rest.kegg.jp";
-const REACTOME_BASE = "https://reactome.org/ContentService";
+// The ContentService of the primary host answers 404 on each path. The release
+// host serves the same API, and a probe of `search/query`, `data/query/{stId}`
+// and `data/participants/{stId}` returned 200 on it. The web pages that a result
+// links to stay on the primary host, thus only the API base moves.
+const REACTOME_BASE = "https://release.reactome.org/ContentService";
 export function stripHtmlAndCollapseWs(s) {
     // Strip tags to a fixpoint: a single pass can leave a `<…>` behind when
     // removing an inner tag lets the surrounding angle brackets form a new one,
@@ -40,6 +44,12 @@ const ReactomeSearchResponseSchema = z.object({
 });
 /** Participant list — `searchReactome` reads `displayName` per participant. */
 const ReactomeParticipantsSchema = z.array(z.object({ displayName: z.string().optional() }));
+/** One Reactome event record, as `/data/query/{stId}` serves it. */
+const ReactomeEntrySchema = z.object({
+    stId: z.string().optional(),
+    displayName: z.string().optional(),
+    summation: z.array(z.object({ text: z.string().optional() })).optional(),
+});
 /** Participant list — `getPathwayMemberships` reads `refEntities` per participant. */
 const ReactomeParticipantEntitiesSchema = z.array(z.object({
     refEntities: z.array(z.object({ schemaClass: z.string().optional(), identifier: z.string().optional() })).optional(),
@@ -126,6 +136,63 @@ export async function searchPathways(query, options = {}) {
     const results = await Promise.all(tasks);
     return results.flat();
 }
+/** A Reactome stable identifier, for example `R-HSA-109581`. */
+const REACTOME_ID_RE = /^R-[A-Z]{3}-\d+(\.\d+)?$/;
+/** A KEGG pathway identifier, for example `hsa04010` or `map04010`. */
+const KEGG_ID_RE = /^[a-z]{3,4}\d{5}$/;
+/** Read one field out of a KEGG flat-file record. */
+function keggField(record, field) {
+    const match = new RegExp(`^${field}\\s+(.*)$`, "m").exec(record);
+    return match?.[1]?.trim() || null;
+}
+async function getKeggPathway(id) {
+    const res = await apiFetch(`${KEGG_BASE}/get/${encodeURIComponent(id)}`, { parseAs: "text" });
+    if (res.isErr())
+        return null;
+    const record = res.value;
+    const name = keggField(record, "NAME");
+    if (!name)
+        return null;
+    const description = keggField(record, "DESCRIPTION");
+    return {
+        id,
+        name,
+        source: "kegg",
+        ...(description ? { description } : {}),
+        url: `https://www.kegg.jp/pathway/${id}`,
+    };
+}
+async function getReactomePathway(id) {
+    const res = await apiFetchValidated(`${REACTOME_BASE}/data/query/${encodeURIComponent(id)}`, ReactomeEntrySchema, {
+        headers: { Accept: "application/json" },
+    });
+    if (res.isErr())
+        return null;
+    const entry = res.value;
+    const stId = entry.stId ?? id;
+    const description = entry.summation?.map((s) => s.text ?? "").find((text) => text.length > 0);
+    return {
+        id: stId,
+        name: stripHtmlAndCollapseWs(entry.displayName ?? ""),
+        source: "reactome",
+        ...(description ? { description: stripHtmlAndCollapseWs(description) } : {}),
+        url: `https://reactome.org/content/detail/${stId}`,
+    };
+}
+/**
+ * Read one pathway by its own identifier. The prefix of the identifier picks
+ * the database, thus the caller passes the id back exactly as a search
+ * returned it. An identifier that neither database holds gives null, which is
+ * absence and not a failure.
+ */
+export async function getPathwayById(id) {
+    const trimmed = id.trim();
+    if (REACTOME_ID_RE.test(trimmed))
+        return getReactomePathway(trimmed);
+    if (KEGG_ID_RE.test(trimmed))
+        return getKeggPathway(trimmed);
+    return null;
+}
 /** Pathway memberships for a gene symbol — used directly by §3.7 collector. */
 export async function getPathwayMemberships(geneSymbol) {
     const [kegg, reactome] = await Promise.all([searchKegg(geneSymbol, "hsa", 25, false), searchReactome(geneSymbol, "Homo sapiens", 25, false)]);

package/dist/tools/research/context7-docs.js

@@ -20,7 +20,7 @@ const Context7SearchResponseSchema = z.object({
 const Context7DocsResponseSchema = z.object({ content: z.string().optional() });
 export const resolveLibraryIdTool = defineTool({
     id: "resolve_library_id",
-    description: "Resolve a package name (e.g., 'scanpy', 'DESeq2', 'scikit-learn') to a Context7 library ID. Call this BEFORE queryDocs to get the library ID needed for documentation lookup. Returns matching libraries ranked by relevance.",
+    description: "Resolve a package name (e.g., 'scanpy', 'DESeq2', 'scikit-learn') to a Context7 library ID. Call this BEFORE `query_docs` to get the library ID needed for documentation lookup. Returns matching libraries ranked by relevance.",
     inputSchema: z.object({
         libraryName: z.string().describe("Package or library name to search for (e.g., 'scanpy', 'pysam', 'lifelines')."),
         query: z.string().describe("What you need help with — used to rank results by relevance (e.g., 'how to run differential expression')."),
@@ -44,9 +44,9 @@ export const resolveLibraryIdTool = defineTool({
 });
 export const queryDocsTool = defineTool({
     id: "query_docs",
-    description: "Query up-to-date documentation and code examples for a library. You must call resolve-library-id first to get the libraryId. Use this to verify function signatures, parameters, and usage patterns before writing code.",
+    description: "Query up-to-date documentation and code examples for a library. You must call `resolve_library_id` first to get the libraryId. Use this to verify function signatures, parameters, and usage patterns before writing code.",
     inputSchema: z.object({
-        libraryId: z.string().describe("Context7 library ID from resolve-library-id (e.g., '/scverse/scanpy')."),
+        libraryId: z.string().describe("Context7 library ID from `resolve_library_id` (for example '/scverse/scanpy')."),
         query: z.string().describe("Specific question about the library (e.g., 'rank_genes_groups function parameters and usage')."),
     }),
     describeCall: "none",

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

@@ -178,8 +178,8 @@ export function createGenerateAnalogyReportTool(deps) {
             "stuck', 'brainstorm ideas', 'are there precedents outside biology'. The " +
             "trigger is exploratory INTENT, not the words 'analogy' or 'cross-domain' " +
             "— users rarely name it, so infer it and reach for the tool proactively.\n" +
-            "NOT for: in-domain literature review (use `literature_reviewer` or " +
-            "`pubmed`), single-gene factual lookup (use `search_gene`), or " +
+            "NOT for: in-domain literature review (use `pubmed` and the other " +
+            "bio-lookup tools), single-gene factual lookup (use `search_gene`), or " +
             "execution-mode turns where the user just wants the next step done. It " +
             "drives a multi-step research sub-agent over live literature search, so " +
             "it is slow — never spend it on a fact you could look up.\n" +

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

@@ -28,6 +28,7 @@ import { type ChatProvider } from "../../providers/types.js";
 import type { UsageRecorder } from "../../billing/usage-recorder.js";
 import { type Tool } from "../define-tool.js";
 import type { EnvironmentStorePaths } from "../../config/environment-stores.js";
+import { type BioToolKeys } from "../bio/keys.js";
 import { type ResourcePolicy } from "../../config/resource-limits.js";
 import type { Logger } from "../../lib/logger.js";
 export interface GeneratePlanDeps extends EnvironmentStorePaths {
@@ -52,6 +53,8 @@ export interface GeneratePlanDeps extends EnvironmentStorePaths {
     readonly logger?: Logger;
     /** LLM usage-accounting seam for the planner loop; omitted falls back to the no-op recorder. */
     readonly usageRecorder?: UsageRecorder;
+    /** API keys for the search tools the planner uses to ground a plan. */
+    readonly bioKeys: BioToolKeys;
 }
 /** Build the `generate_plan` tool bound to its provider and pool. */
 export declare function createGeneratePlanTool(deps: GeneratePlanDeps): Tool;