@inflexa-ai/harness 0.48.4 → 0.48.5

package/dist/agents/conversation-agent.js

@@ -29,7 +29,7 @@ import { createEditIntentStore } from "../state/edit-intents.js";
 import { conversationPrompt } from "../prompts/conversation.js";
 import { composeSystemPrompt } from "./system-prompt.js";
 // Bio-lookup leaf tools (pure — no dependencies).
-import { searchGeneTool, searchProteinTool, lookupAnnotationTool, searchInteractionsTool, alphafoldPredictionTool, chemblTool, pubchemTool, openTargetsTool, searchFaersTool, searchClinicalTrialsTool, searchGeoDatasetsTool, genePreclinicalProfileTool, targetSafetyTool, } from "../tools/bio/index.js";
+import { searchGeneTool, searchProteinTool, resolveGeneIdsTool, lookupAnnotationTool, searchInteractionsTool, humanbaseTool, alphafoldPredictionTool, chemblTool, pubchemTool, openTargetsTool, searchFaersTool, searchClinicalTrialsTool, searchGeoDatasetsTool, genePreclinicalProfileTool, targetSafetyTool, } from "../tools/bio/index.js";
 import { createAmassTools, createNcbiTools, createChemDbTools } from "../tools/bio/keys.js";
 // Dependency-bearing tool factories.
 import { createGeneratePlanTool, createInspectRunTool, createInspectDataProfileTool, createGenerateAnalogyReportTool, createSearchSemanticScholarTool, searchArxivTool, } from "../tools/research/index.js";
@@ -86,10 +86,14 @@ export function createConversationAgent(deps) {
         // UniProt accession that the structure tools take.
         searchGeneTool,
         searchProteinTool,
+        // The mapping across the symbol, Entrez, Ensembl and UniProt spaces — the Entrez ID that humanbase takes.
+        resolveGeneIdsTool,
         // Functional annotation (GO / KEGG / Reactome behind one vocabulary) and
         // STRING networks + gene-set enrichment.
         lookupAnnotationTool,
         searchInteractionsTool,
+        // GIANT tissue- and process-specific functional networks (network / relevant / contexts behind one action).
+        humanbaseTool,
         // Structural biology — the whole-chain confidence of a predicted 3-D
         // model, and the URLs of its coordinate and per-residue files.
         alphafoldPredictionTool,

package/dist/agents/sandbox/network-agent.js

@@ -8,7 +8,7 @@ export const meta = {
     capabilities: ["network analysis", "co-expression networks", "regulatory analysis", "module detection", "TF activity inference"],
     suitableFor: ["expression-matrices", "correlation-matrices", "general-omics"],
     skills: ["network-regulatory", "shared/omics-general"],
-    tools: [...BASE_SANDBOX_TOOLS, "pubmed", "searchGene", "lookupAnnotation", "searchInteractions"],
+    tools: [...BASE_SANDBOX_TOOLS, "pubmed", "searchGene", "lookupAnnotation", "searchInteractions", "humanbase", "resolveGeneIds"],
 };
 export function createNetworkAgent(deps) {
     return createSandboxAgent(deps, meta, networkAgentPrompt);

package/dist/agents/sandbox/shared.js

@@ -27,7 +27,7 @@ import { queryDocsTool, resolveLibraryIdTool } from "../../tools/research/contex
 // Data-profile retrieval (dependency-bearing) — always-on, see `createSandboxAgent`.
 import { createInspectDataProfileTool } from "../../tools/research/inspect-data-profile.js";
 // Bio leaf tools.
-import { chemblTool, genePreclinicalProfileTool, lookupAnnotationTool, openTargetsTool, pubchemTool, searchClinicalTrialsTool, searchFaersTool, searchGeneTool, searchGeoDatasetsTool, searchInteractionsTool, targetSafetyTool, } from "../../tools/bio/index.js";
+import { chemblTool, genePreclinicalProfileTool, humanbaseTool, lookupAnnotationTool, openTargetsTool, pubchemTool, resolveGeneIdsTool, searchClinicalTrialsTool, searchFaersTool, searchGeneTool, searchGeoDatasetsTool, searchInteractionsTool, targetSafetyTool, } from "../../tools/bio/index.js";
 import { createAmassTools, createNcbiTools, createChemDbTools } from "../../tools/bio/keys.js";
 // Workspace read surface.
 import { createFileStatTool, createGrepTool, createListFilesTool, createReadFileTool, createWorkspaceSearchTool } from "../../tools/workspace/index.js";
@@ -101,8 +101,10 @@ function resolveSandboxTools(deps, tools, mutator) {
         pubmed: ncbi.pubmed,
         resolve_citation: deps.citationResolver === undefined ? undefined : createResolveCitationTool(deps.citationResolver),
         searchGene: searchGeneTool,
+        resolveGeneIds: resolveGeneIdsTool,
         lookupAnnotation: lookupAnnotationTool,
         searchInteractions: searchInteractionsTool,
+        humanbase: humanbaseTool,
         chembl: chemblTool,
         pubchem: pubchemTool,
         opentargets: openTargetsTool,

package/dist/agents/sandbox/types.d.ts

@@ -12,7 +12,7 @@
  * in the tool's `perSource` report; the rest of the call still answers.
  */
 /** Closed allowlist of tools any sandbox agent may declare. */
-export type SandboxToolName = "listAvailablePackages" | "listAvailableRefs" | "scanInputs" | "resolveLibraryId" | "queryDocs" | "pubmed" | "resolve_citation" | "searchGene" | "lookupAnnotation" | "searchInteractions" | "chembl" | "pubchem" | "opentargets" | "geneDiseaseEvidence" | "drugGeneInteractions" | "genePreclinicalProfile" | "searchFaers" | "searchClinicalTrials" | "searchGeoDatasets" | "searchRegulatoryApprovals" | "targetSafety" | "comptox" | "knowledgeTemplate";
+export type SandboxToolName = "listAvailablePackages" | "listAvailableRefs" | "scanInputs" | "resolveLibraryId" | "queryDocs" | "pubmed" | "resolve_citation" | "searchGene" | "resolveGeneIds" | "lookupAnnotation" | "searchInteractions" | "humanbase" | "chembl" | "pubchem" | "opentargets" | "geneDiseaseEvidence" | "drugGeneInteractions" | "genePreclinicalProfile" | "searchFaers" | "searchClinicalTrials" | "searchGeoDatasets" | "searchRegulatoryApprovals" | "targetSafety" | "comptox" | "knowledgeTemplate";
 /**
  * The reference datasets that one capability of one agent cannot run without.
  *

package/dist/execution/run-event-stream.d.ts

@@ -31,10 +31,10 @@
  * writer it observes.
  */
 import type { ResultAsync } from "neverthrow";
-import type { Pool } from "pg";
 import type { ChatPart } from "../contracts/chat-parts.js";
 import { type DbError } from "../lib/db-result.js";
 import type { Logger } from "../lib/logger.js";
+import type { Querier } from "../state/db.js";
 import type { RunStatus } from "../state/schema.js";
 /** The part of a run row that the terminal part is made from. */
 export type RunEventRunRead = {
@@ -48,7 +48,7 @@ export type RunEventRunRead = {
  * having console forced on it.
  */
 export type RunEventStreamDeps = {
-    readonly pool: Pool;
+    readonly pool: Querier;
     readonly logger?: Logger;
     /** Reads the status and the error of the run row, `null` when no row exists. Defaults to `queryRun` on `pool`. */
     readonly readRun?: (runId: string) => ResultAsync<RunEventRunRead | null, DbError>;

package/dist/loop/chat-stream.d.ts

@@ -16,7 +16,10 @@ import type { EmitFn } from "./types.js";
 export declare const CHAT_STREAM_KEY = "chat";
 /** The data part that names the child workflow of a sub-agent call in the stream of its caller. */
 export declare const SUB_AGENT_STREAM_PART = "data-subagent-stream";
-/** The chunk that carries one frame of the harness in the stream of a turn. A transient chunk is live only. */
+/**
+ * The chunk that carries one frame of the harness in the stream of a turn. A transient chunk is in the stream, and
+ * a reader gets it. A replay of the step does not write it again, and the stored transcript does not hold it.
+ */
 export declare function chunkOfFrame(frame: ChatFrame, transient?: boolean): UIMessageChunk;
 /** What the body of a turn workflow writes to its stream, and what each of its tool steps writes. */
 export type TurnStreamWriter = {

package/dist/loop/chat-stream.js

@@ -28,13 +28,16 @@ const HarnessFrameChunkSchema = z.object({
     type: z.literal(HARNESS_FRAME_CHUNK),
     data: z.looseObject({ type: z.string() }),
 });
-/** The chunk that carries one frame of the harness in the stream of a turn. A transient chunk is live only. */
+/**
+ * The chunk that carries one frame of the harness in the stream of a turn. A transient chunk is in the stream, and
+ * a reader gets it. A replay of the step does not write it again, and the stored transcript does not hold it.
+ */
 export function chunkOfFrame(frame, transient = false) {
     return transient ? { type: HARNESS_FRAME_CHUNK, data: frame, transient: true } : { type: HARNESS_FRAME_CHUNK, data: frame };
 }
 /**
- * Whether a frame from a tool step shows progress only. The library gives such a frame live, and a replay of the
- * step does not give it again. Each other frame of a tool step is checkpointed with the step, and the display of a
+ * Whether a frame from a step shows progress only. Such a frame goes to the stream at once, and a replay of the step
+ * does not write it again. Each other frame of a tool step is checkpointed with the step, and the display of a
  * round that a recovery stores keeps it: the end of each call, and each part of the root agent.
  */
 function isProgressFrame(frame) {
@@ -43,18 +46,27 @@ function isProgressFrame(frame) {
     return isKnownPartType(frame.type) && PART_REGISTRY[frame.type].transient;
 }
 /**
- * Run each body write of one workflow after the body write before it ends.
+ * Run each body write of one workflow after the body write before it ends, and each step write after the step write
+ * before it ends.
  *
  * DBOS gives a stream write its offset inside the insert, thus two writes in flight take the same offset, and the
  * write that loses sleeps 100 ms before it tries again. A body write must still take its function id at the call,
  * because a replay finds each checkpoint by the order of the calls. Thus the call reserves its id now, and the
- * chained write takes the reserved id from the context of the workflow when it starts.
+ * chained write takes the reserved id from the context of the workflow when it starts. A step write takes no
+ * function id, thus its chain reserves none.
  */
-function chainBodyWrites() {
-    let tail = Promise.resolve();
+function chainWrites() {
+    let bodyTail = Promise.resolve();
+    let stepTail = Promise.resolve();
+    const ended = (write) => write.then(() => undefined, () => undefined);
     return (start) => {
+        if (DBOS.isInStep()) {
+            const write = stepTail.then(start, start);
+            stepTail = ended(write);
+            return write;
+        }
         const ctx = getCurrentContextStore();
-        if (ctx === undefined || !DBOS.isInWorkflow() || DBOS.isInStep())
+        if (ctx === undefined || !DBOS.isInWorkflow())
             return start();
         const reserved = functionIDGetIncrement();
         const run = () => {
@@ -71,8 +83,8 @@ function chainBodyWrites() {
                 ctx.curWFFunctionId = next;
             }
         };
-        const write = tail.then(run, run);
-        tail = write.then(() => undefined, () => undefined);
+        const write = bodyTail.then(run, run);
+        bodyTail = ended(write);
         return write;
     };
 }
@@ -85,7 +97,7 @@ function chainBodyWrites() {
  */
 export function createTurnStreamWriter(rootSource, observe) {
     const pending = [];
-    const chained = chainBodyWrites();
+    const chained = chainWrites();
     const track = (write) => {
         // Observed now, thus a failure before the settle is not an unhandled rejection. The settle still sees it.
         write.catch(() => undefined);
@@ -114,10 +126,15 @@ export function createTurnStreamWriter(rootSource, observe) {
         const frame = toChatFrame(event, rootSource);
         if (frame === null)
             return;
-        // A tool step gives its frames to the library, which checkpoints each one that is not progress.
         if (DBOS.isInStep()) {
             const liveOnly = "transient" in event && event.transient === true;
-            toolWriter().write(chunkOfFrame(frame, liveOnly || isProgressFrame(frame)));
+            const transient = liveOnly || isProgressFrame(frame);
+            // A model step has no library writer, and a transient chunk is not checkpointed with its step. Thus the
+            // chunk goes straight to the stream. The library checkpoints each other frame with its tool step.
+            if (transient)
+                writer.write(chunkOfFrame(frame, true));
+            else
+                toolWriter().write(chunkOfFrame(frame));
             return;
         }
         await write(frame);

package/dist/prompts/sandbox/network-agent.d.ts

@@ -1 +1 @@
-export declare const networkAgentPrompt = "# Network & Regulatory Analysis Agent\n\nYou are a modality-agnostic network and regulatory analysis specialist.\nYou construct co-expression networks, detect functional modules, infer\ntranscription-factor activity, and analyze protein-protein interaction\nnetworks. You consume expression matrices, score matrices, and gene lists\nproduced by upstream modality agents.\n\n## Skills\n\nYour skills: `network-regulatory`, `shared/omics-general`.\n\nAPI references in `network-regulatory`: PyWGCNA, decoupler, networkx,\nigraph.\n\n## Method Selection (Summary)\n\n- **Co-expression (bulk/microarray)** \u2014 PyWGCNA. Needs variance-stabilized\n  or log-transformed expression. `pickSoftThreshold()` targeting\n  scale-free topology fit > 0.8.\n- **Co-expression (single-cell)** \u2014 aggregate to pseudobulk FIRST, then\n  PyWGCNA. Never on raw single-cell count matrices.\n- **TF activity (per-cell)** \u2014 decoupler with CollecTRI through\n  `dc.mt.ulm()` or `dc.mt.mlm()`. This is the regulatory route here. No\n  tool discovers a regulon from the data alone, thus say so when a\n  request asks for one.\n- **PPI network** \u2014 scripts cannot reach the STRING or OmniPath web\n  APIs. For a gene set of up to 100 proteins, `search_interactions`\n  returns the STRING network from the host. For a larger network,\n  resolve an interaction file from the reference inventory. If neither\n  covers the request, say so, and scope the analysis to what is. Build\n  with networkx or igraph. Filter by confidence as needed.\n- **Community detection** \u2014 Leiden via igraph or leidenalg.\n- **Hub genes** \u2014 combine betweenness centrality, degree centrality, and\n  module membership (kME). Validate against known biology.\n- **Module-trait correlation** \u2014 PyWGCNA `module_trait_relationships()`\n  or Pearson/Spearman with FDR correction.\n\n## Domain Standards\n\n- Filter to top 3000-5000 variable genes before correlation matrices.\n  At 5000 genes the matrix is ~200 MB; at 10000 it is ~800 MB.\n- Use float32 where possible.\n- For large networks (>10k nodes), use sparse representations or\n  adjacency-list format.\n- Log-transform expression before correlations. Pearson on raw counts\n  is dominated by high-count genes.\n- decoupler: use CollecTRI (not DoRothEA) for TF regulons, PROGENy for\n  pathways. Resolve the network file from the reference inventory \u2014\n  never assume a staged path.\n- Save processed networks and module assignments as AnnData when\n  meaningful.\n\n## Figures\n\nSelect from this list the figures that show the findings of the step.\n\n- **Network graph** \u2014 spring/Fruchterman-Reingold layout for key\n  modules. Top 50 genes by kME, colored by module.\n- **Module eigengene heatmap** \u2014 modules \u00D7 samples, colored by\n  eigengene, annotated with phenotype.\n- **Hub gene network** \u2014 subnetwork of top hubs per module with\n  centrality-scaled node sizes.\n- **Module-trait correlation heatmap** \u2014 modules \u00D7 traits, color =\n  correlation, annotated with FDR-corrected p-values.\n- **TF activity heatmap** \u2014 top TFs \u00D7 samples or cell groups when\n  decoupler is used.\n\n## Domain Anti-Patterns\n\n- WGCNA on >5000 genes without filtering \u2014 memory explosion, signal\n  drowned in noise.\n- Correlations on raw or unnormalized counts \u2014 log-transform first.\n- Ignoring batch effects in co-expression \u2014 batch-driven correlations\n  create spurious modules.\n- WGCNA on single-cell count matrices \u2014 aggregate to pseudobulk first.\n- PyWGCNA `geneExp=` kwarg \u2014 use positional or `geneExpPath=`. Call\n  `.to_df()` before pandas operations on internal AnnData.\n- DoRothEA for TF analysis \u2014 superseded by CollecTRI (better coverage\n  and curation).\n\n## Required Output Files\n\n- `output/module_assignments.csv` \u2014 `gene`, `module_id`,\n  `module_color`, `kME`.\n- `output/network_edges.csv` \u2014 `source`, `target`, `weight`, `type`\n  (co-expression/PPI/regulatory).\n- `output/hub_genes.csv` \u2014 `gene`, `module`, `degree_centrality`,\n  `betweenness_centrality`, `kME`, `rank`.\n- `output/module_trait_correlations.csv` \u2014 `module`, `trait`,\n  `correlation`, `p_value`, `fdr`.\n- `output/tf_activity.h5ad` \u2014 per-sample or per-cell TF activity\n  scores (when decoupler is used).\n- `output/network.graphml` \u2014 graph export for external visualization.\n";
+export declare const networkAgentPrompt = "# Network & Regulatory Analysis Agent\n\nYou are a modality-agnostic network and regulatory analysis specialist.\nYou construct co-expression networks, detect functional modules, infer\ntranscription-factor activity, and analyze protein-protein interaction\nnetworks. You consume expression matrices, score matrices, and gene lists\nproduced by upstream modality agents.\n\n## Skills\n\nYour skills: `network-regulatory`, `shared/omics-general`.\n\nAPI references in `network-regulatory`: PyWGCNA, decoupler, networkx,\nigraph.\n\n## Method Selection (Summary)\n\n- **Co-expression (bulk/microarray)** \u2014 PyWGCNA. Needs variance-stabilized\n  or log-transformed expression. `pickSoftThreshold()` targeting\n  scale-free topology fit > 0.8.\n- **Co-expression (single-cell)** \u2014 aggregate to pseudobulk FIRST, then\n  PyWGCNA. Never on raw single-cell count matrices.\n- **TF activity (per-cell)** \u2014 decoupler with CollecTRI through\n  `dc.mt.ulm()` or `dc.mt.mlm()`. This is the regulatory route here. No\n  tool discovers a regulon from the data alone, thus say so when a\n  request asks for one.\n- **PPI network** \u2014 scripts cannot reach the STRING or OmniPath web\n  APIs. For a gene set of up to 100 proteins, `search_interactions`\n  returns the STRING network from the host. For a larger network,\n  resolve an interaction file from the reference inventory. If neither\n  covers the request, say so, and scope the analysis to what is. Build\n  with networkx or igraph. Filter by confidence as needed.\n- **Tissue-specific network** \u2014 a STRING edge carries no tissue. For\n  the network of hub genes in one tissue or cell type, or for the\n  tissues that a module points to, `humanbase` answers from the host.\n  Send the hub genes or the module genes, not the whole matrix.\n- **Community detection** \u2014 Leiden via igraph or leidenalg.\n- **Hub genes** \u2014 combine betweenness centrality, degree centrality, and\n  module membership (kME). Validate against known biology.\n- **Module-trait correlation** \u2014 PyWGCNA `module_trait_relationships()`\n  or Pearson/Spearman with FDR correction.\n\n## Domain Standards\n\n- Filter to top 3000-5000 variable genes before correlation matrices.\n  At 5000 genes the matrix is ~200 MB; at 10000 it is ~800 MB.\n- Use float32 where possible.\n- For large networks (>10k nodes), use sparse representations or\n  adjacency-list format.\n- Log-transform expression before correlations. Pearson on raw counts\n  is dominated by high-count genes.\n- decoupler: use CollecTRI (not DoRothEA) for TF regulons, PROGENy for\n  pathways. Resolve the network file from the reference inventory \u2014\n  never assume a staged path.\n- Save processed networks and module assignments as AnnData when\n  meaningful.\n\n## Figures\n\nSelect from this list the figures that show the findings of the step.\n\n- **Network graph** \u2014 spring/Fruchterman-Reingold layout for key\n  modules. Top 50 genes by kME, colored by module.\n- **Module eigengene heatmap** \u2014 modules \u00D7 samples, colored by\n  eigengene, annotated with phenotype.\n- **Hub gene network** \u2014 subnetwork of top hubs per module with\n  centrality-scaled node sizes.\n- **Module-trait correlation heatmap** \u2014 modules \u00D7 traits, color =\n  correlation, annotated with FDR-corrected p-values.\n- **TF activity heatmap** \u2014 top TFs \u00D7 samples or cell groups when\n  decoupler is used.\n\n## Domain Anti-Patterns\n\n- WGCNA on >5000 genes without filtering \u2014 memory explosion, signal\n  drowned in noise.\n- Correlations on raw or unnormalized counts \u2014 log-transform first.\n- Ignoring batch effects in co-expression \u2014 batch-driven correlations\n  create spurious modules.\n- WGCNA on single-cell count matrices \u2014 aggregate to pseudobulk first.\n- PyWGCNA `geneExp=` kwarg \u2014 use positional or `geneExpPath=`. Call\n  `.to_df()` before pandas operations on internal AnnData.\n- DoRothEA for TF analysis \u2014 superseded by CollecTRI (better coverage\n  and curation).\n\n## Required Output Files\n\n- `output/module_assignments.csv` \u2014 `gene`, `module_id`,\n  `module_color`, `kME`.\n- `output/network_edges.csv` \u2014 `source`, `target`, `weight`, `type`\n  (co-expression/PPI/regulatory).\n- `output/hub_genes.csv` \u2014 `gene`, `module`, `degree_centrality`,\n  `betweenness_centrality`, `kME`, `rank`.\n- `output/module_trait_correlations.csv` \u2014 `module`, `trait`,\n  `correlation`, `p_value`, `fdr`.\n- `output/tf_activity.h5ad` \u2014 per-sample or per-cell TF activity\n  scores (when decoupler is used).\n- `output/network.graphml` \u2014 graph export for external visualization.\n";

package/dist/prompts/sandbox/network-agent.js

@@ -30,6 +30,10 @@ igraph.
   resolve an interaction file from the reference inventory. If neither
   covers the request, say so, and scope the analysis to what is. Build
   with networkx or igraph. Filter by confidence as needed.
+- **Tissue-specific network** — a STRING edge carries no tissue. For
+  the network of hub genes in one tissue or cell type, or for the
+  tissues that a module points to, \`humanbase\` answers from the host.
+  Send the hub genes or the module genes, not the whole matrix.
 - **Community detection** — Leiden via igraph or leidenalg.
 - **Hub genes** — combine betweenness centrality, degree centrality, and
   module membership (kME). Validate against known biology.

package/dist/providers/errors.js

@@ -192,9 +192,10 @@ function excerptResponseBody(body) {
 }
 /** Max links walked on the `cause` chain looking for a structured status. */
 const MAX_CAUSE_HOPS = 5;
-/** Node/undici error codes that mean "the connection itself failed". */
+/** Node/undici and Bun error codes that mean "the connection itself failed". Bun names a refused connection `ConnectionRefused`. */
 const CONNECTION_ERROR_CODES = new Set([
     "ECONNREFUSED",
+    "ConnectionRefused",
     "ECONNRESET",
     "ENOTFOUND",
     "ETIMEDOUT",

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

@@ -0,0 +1,32 @@
+/**
+ * humanbase — the GIANT tissue-specific functional networks of HumanBase.
+ *
+ * One database, three questions, thus one tool with an `action` (the barrel
+ * rule in `index.ts`). The input is a flat object with an `action` enum, not a
+ * `z.discriminatedUnion`, because model tool calling needs a top-level
+ * `"type":"object"`. The argument of each action is optional in the schema, and
+ * a `.refine` makes it required for its action.
+ *
+ * The GIANT version is not an input: the client derives it from the slug.
+ */
+import { type HumanBaseContext, type HumanBaseNetwork, type HumanBaseScoredContext } from "../lib/humanbase-client.js";
+export type HumanBaseOutput = ({
+    found: true;
+} & HumanBaseNetwork) | {
+    found: false;
+    context: string;
+} | {
+    contexts: HumanBaseScoredContext[];
+    totalFound: number;
+} | {
+    contexts: HumanBaseContext[];
+    totalFound: number;
+};
+export declare const humanbaseTool: import("../define-tool.js").Tool<{
+    action: "contexts" | "network" | "relevant";
+    entrez?: number[] | undefined;
+    context?: string | undefined;
+    nodeSize?: number | undefined;
+    query?: string | undefined;
+    limit?: number | undefined;
+}, HumanBaseOutput>;

package/dist/tools/bio/humanbase.js

@@ -0,0 +1,180 @@
+/**
+ * humanbase — the GIANT tissue-specific functional networks of HumanBase.
+ *
+ * One database, three questions, thus one tool with an `action` (the barrel
+ * rule in `index.ts`). The input is a flat object with an `action` enum, not a
+ * `z.discriminatedUnion`, because model tool calling needs a top-level
+ * `"type":"object"`. The argument of each action is optional in the schema, and
+ * a `.refine` makes it required for its action.
+ *
+ * The GIANT version is not an input: the client derives it from the slug.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { getNetwork, getRelevantContexts, HUMANBASE_MAX_NETWORK_GENES, listContexts, } from "../lib/humanbase-client.js";
+const DEFAULTS = { nodeSize: 10, networkEdges: 50, relevantContexts: 10, contexts: 20 };
+const MAX_NODE_SIZE = 50;
+const MAX_RELEVANT_GENES = 200;
+const MAX_LIMIT = 1000;
+/** How many Entrez IDs a call detail names before it switches to a count plus a sample. */
+const IDS_LISTED_IN_FULL = 8;
+const ContextOutputSchema = z.object({
+    slug: z.string(),
+    title: z.string(),
+    giantVersion: z.enum(["v1", "v3"]),
+    term: z.object({ id: z.string(), ontology: z.string() }).nullable(),
+});
+/** The ok value of each action. A script reads it as data, thus the catalog of `run_script` shows this type. */
+const outputSchema = z.union([
+    z
+        .object({
+        found: z.literal(true),
+        context: z.string(),
+        giantVersion: z.enum(["v1", "v3"]),
+        mincut: z.number().nullable(),
+        genes: z.array(z.object({
+            entrez: z.number(),
+            symbol: z.string(),
+            description: z.string(),
+            ensembl: z.string().nullable(),
+            hgnc: z.string().nullable(),
+            query: z.boolean(),
+        })),
+        edges: z.array(z.object({ geneA: z.string(), geneB: z.string(), weight: z.number() })),
+        totalEdges: z.number(),
+        notFound: z.array(z.number()),
+    })
+        .describe("action 'network'"),
+    z.object({ found: z.literal(false), context: z.string() }).describe("action 'network', no network for the request"),
+    z.object({ contexts: z.array(ContextOutputSchema.extend({ score: z.number() })), totalFound: z.number() }).describe("action 'relevant'"),
+    z.object({ contexts: z.array(ContextOutputSchema), totalFound: z.number() }).describe("action 'contexts'"),
+]);
+function listIds(ids) {
+    if (ids === undefined)
+        return "";
+    if (ids.length <= IDS_LISTED_IN_FULL)
+        return ids.join(", ");
+    return `${ids.length} genes: ${ids.slice(0, IDS_LISTED_IN_FULL).join(", ")}, …`;
+}
+const inputSchema = z
+    .object({
+    action: z
+        .enum(["network", "relevant", "contexts"])
+        .describe("'network' (needs entrez, max 30, and context) — the functional subnetwork of the genes in ONE context, plus nodeSize neighbor genes. " +
+        "'relevant' (needs entrez) — the contexts ranked by how relevant each is to the gene set, best first. " +
+        "'contexts' — the context slugs that HumanBase serves, filtered by query."),
+    entrez: z
+        .array(z.number().int().positive())
+        .min(1)
+        .max(MAX_RELEVANT_GENES)
+        .optional()
+        .describe(`Required for 'network' (max ${HUMANBASE_MAX_NETWORK_GENES}) and 'relevant' (max ${MAX_RELEVANT_GENES}). NCBI Entrez Gene IDs as ` +
+        "numbers (672 = BRCA1, 3553 = IL1B) — not symbols, not Ensembl IDs."),
+    context: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Required for 'network'. A context slug, copied from a 'contexts' or a 'relevant' result ('blood', 'liver-v3')."),
+    nodeSize: z
+        .number()
+        .int()
+        .min(0)
+        .max(MAX_NODE_SIZE)
+        .optional()
+        .describe(`'network' only: the neighbor genes that HumanBase adds to the query genes (default ${DEFAULTS.nodeSize}, max ${MAX_NODE_SIZE}).`),
+    query: z
+        .string()
+        .optional()
+        .describe("'contexts' only: a case-insensitive substring of the slug or the title ('liver', 'neuron', '-v3'). Omit it to list every context."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_LIMIT)
+        .optional()
+        .describe(`Max rows returned — the edges of 'network' (default ${DEFAULTS.networkEdges}, highest weight first), the contexts of 'relevant' ` +
+        `(default ${DEFAULTS.relevantContexts}, best first), or the contexts of 'contexts' (default ${DEFAULTS.contexts}).`),
+})
+    .refine((d) => d.action === "contexts" || d.entrez !== undefined, {
+    message: "entrez is required when action is 'network' or 'relevant' — pass NCBI Entrez Gene IDs as numbers",
+    path: ["entrez"],
+})
+    .refine((d) => d.action !== "network" || d.context !== undefined, {
+    message: "context is required when action is 'network' — copy a slug from a 'contexts' or a 'relevant' result",
+    path: ["context"],
+})
+    .refine((d) => d.action !== "network" || (d.entrez?.length ?? 0) <= HUMANBASE_MAX_NETWORK_GENES, {
+    message: `action 'network' takes at most ${HUMANBASE_MAX_NETWORK_GENES} entrez IDs — rank a larger set with 'relevant'`,
+    path: ["entrez"],
+})
+    .refine((d) => d.action !== "contexts" || d.entrez === undefined, {
+    message: "entrez does not apply to action 'contexts'",
+    path: ["entrez"],
+})
+    .refine((d) => d.action === "network" || (d.context === undefined && d.nodeSize === undefined), {
+    message: "context and nodeSize apply to action 'network' only",
+    path: ["action"],
+})
+    .refine((d) => d.action === "contexts" || d.query === undefined, {
+    message: "query applies to action 'contexts' only",
+    path: ["action"],
+});
+export const humanbaseTool = defineTool({
+    id: "humanbase",
+    description: "HumanBase — the GIANT functional networks of the Flatiron Institute (Greene et al., Nature Genetics 2015): for each tissue, cell type, or " +
+        "biological process, a genome-wide network whose edge weight is the posterior probability that two genes work together IN THAT CONTEXT, " +
+        "integrated from the expression, interaction and other data of about 14,000 publications. It answers 'which genes act with my genes in the liver?' and " +
+        "'which tissues does my gene set point to?' — questions that the context-free STRING network of search_interactions cannot.\n" +
+        "'network' — the subnetwork of the query genes in one context, plus nodeSize neighbor genes. Each gene carries its Entrez ID, symbol, full name, " +
+        "Ensembl ID, HGNC ID, and `query` (false for an added neighbor). Each edge is { geneA, geneB, weight }, highest weight first; " +
+        "`totalEdges` gives the count before limit (one edge per gene pair, thus it grows with the square of the gene count). `notFound` lists " +
+        "the query IDs that the network does not hold. found: false means HumanBase holds no network for the request: an unknown context slug, " +
+        "or no query gene in the network.\n" +
+        "'relevant' — the contexts ranked by relevance to the gene set, each with a score from 0 to 1. It ranks the v1 contexts only.\n" +
+        "'contexts' — the slugs. Each context has a GIANT version: a slug that ends in '-v3' is a v3 (GIANT 3) network of a tissue or a cell type; " +
+        "every other slug is v1, which holds the tissue contexts (with a BRENDA Tissue Ontology term) and the biological-process contexts " +
+        "(with a GO term). 'global' and 'global-v3' are the networks with no context. The tool sets the version from the slug.\n" +
+        "IDENTIFIERS: NCBI Entrez Gene IDs only, as numbers (672 = BRCA1). Map a symbol or an Ensembl ID with resolve_gene_ids first: the `entrez` " +
+        "field of each of its hits is the input here. " +
+        "HUMAN genes only.\n" +
+        "An empty result (no ranked context, no matched context, found: false) is valid no-data — report it and continue, do not retry.",
+    inputSchema,
+    outputSchema,
+    view: "none",
+    // One tool, three jobs: each action names its own subject — the context and
+    // the genes, the genes, or the filter of the list.
+    describeCall: (input) => {
+        switch (input.action) {
+            case "network":
+                return `network ${input.context ?? ""}: ${listIds(input.entrez)}`;
+            case "relevant":
+                return `relevant: ${listIds(input.entrez)}`;
+            case "contexts":
+                return input.query === undefined ? "contexts" : `contexts ${input.query}`;
+        }
+    },
+    execute: async (input) => {
+        switch (input.action) {
+            case "network": {
+                if (input.entrez === undefined || input.context === undefined)
+                    throw new Error("network requires entrez and context");
+                const network = await getNetwork(input.context, input.entrez, {
+                    nodeSize: input.nodeSize ?? DEFAULTS.nodeSize,
+                    limit: input.limit ?? DEFAULTS.networkEdges,
+                });
+                if (network === null)
+                    return ok({ found: false, context: input.context });
+                return ok({ found: true, ...network });
+            }
+            case "relevant": {
+                if (input.entrez === undefined)
+                    throw new Error("relevant requires entrez");
+                return ok(await getRelevantContexts(input.entrez, { limit: input.limit ?? DEFAULTS.relevantContexts }));
+            }
+            case "contexts":
+                return ok(await listContexts({ query: input.query, limit: input.limit ?? DEFAULTS.contexts }));
+        }
+    },
+});

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

@@ -11,7 +11,7 @@
  * (`gene_disease_evidence`, `drug_gene_interactions`, `target_safety`,
  * `lookup_annotation`, `gene_preclinical_profile`); where one database answers
  * several questions, the endpoint is an `action` parameter (`chembl`,
- * `pubchem`, `pubmed`, `comptox`, `opentargets`, `search_interactions`).
+ * `pubchem`, `pubmed`, `comptox`, `opentargets`, `search_interactions`, `humanbase`).
  *
  * Every tool returns a BOUNDED result by default. A default call is sized to be
  * read, not to be complete: limits are small, verbose fields are opt-in, and
@@ -21,8 +21,10 @@
  */
 export * from "./search-gene.js";
 export * from "./search-protein.js";
+export * from "./resolve-gene-ids.js";
 export * from "./lookup-annotation.js";
 export * from "./search-interactions.js";
+export * from "./humanbase.js";
 export * from "./alphafold-prediction.js";
 export * from "./pubmed.js";
 export * from "./chembl.js";

package/dist/tools/bio/index.js

@@ -11,7 +11,7 @@
  * (`gene_disease_evidence`, `drug_gene_interactions`, `target_safety`,
  * `lookup_annotation`, `gene_preclinical_profile`); where one database answers
  * several questions, the endpoint is an `action` parameter (`chembl`,
- * `pubchem`, `pubmed`, `comptox`, `opentargets`, `search_interactions`).
+ * `pubchem`, `pubmed`, `comptox`, `opentargets`, `search_interactions`, `humanbase`).
  *
  * Every tool returns a BOUNDED result by default. A default call is sized to be
  * read, not to be complete: limits are small, verbose fields are opt-in, and
@@ -22,9 +22,11 @@
 // Identifier resolution
 export * from "./search-gene.js";
 export * from "./search-protein.js";
+export * from "./resolve-gene-ids.js";
 // Functional annotation / networks
 export * from "./lookup-annotation.js";
 export * from "./search-interactions.js";
+export * from "./humanbase.js";
 // Structural biology
 export * from "./alphafold-prediction.js";
 // Literature

package/dist/tools/bio/resolve-gene-ids.d.ts

@@ -0,0 +1,13 @@
+/**
+ * resolveGeneIds — map gene identifiers across the HGNC symbol, the Entrez Gene
+ * ID, the Ensembl gene ID, and the UniProt accession, through MyGene.info.
+ *
+ * `search_gene` answers with Ensembl records only. A source keyed on Entrez IDs
+ * (`humanbase`) needs the mapping step that this tool gives, and in a script the
+ * `entrez` field of a hit goes straight into the `entrez` argument of such a tool.
+ */
+import { type GeneIdResolution } from "../lib/mygene-client.js";
+export declare const resolveGeneIdsTool: import("../define-tool.js").Tool<{
+    identifiers: string[];
+    species: string;
+}, GeneIdResolution>;

package/dist/tools/bio/resolve-gene-ids.js

@@ -0,0 +1,67 @@
+/**
+ * resolveGeneIds — map gene identifiers across the HGNC symbol, the Entrez Gene
+ * ID, the Ensembl gene ID, and the UniProt accession, through MyGene.info.
+ *
+ * `search_gene` answers with Ensembl records only. A source keyed on Entrez IDs
+ * (`humanbase`) needs the mapping step that this tool gives, and in a script the
+ * `entrez` field of a hit goes straight into the `entrez` argument of such a tool.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { MYGENE_HITS_PER_ID, resolveGeneIds } from "../lib/mygene-client.js";
+const MAX_IDENTIFIERS = 200;
+/**
+ * How many identifiers a detail names before it switches to a count plus a
+ * sample. Eight identifiers of typical length stay well inside the emit-site
+ * cap, so the listed form is never the thing that trips it.
+ */
+const IDENTIFIERS_LISTED_IN_FULL = 8;
+/** The ok value. A script reads it as data, thus the catalog of `run_script` shows this type. */
+const outputSchema = z.object({
+    genes: z.array(z.object({
+        query: z.string(),
+        symbol: z.string().nullable(),
+        name: z.string().nullable(),
+        entrez: z.number().nullable(),
+        ensembl: z.array(z.string()),
+        uniprot: z.array(z.string()),
+    })),
+    notFound: z.array(z.string()),
+    ambiguous: z.array(z.string()),
+    truncated: z.array(z.string()),
+});
+export const resolveGeneIdsTool = defineTool({
+    id: "resolve_gene_ids",
+    description: "Map gene identifiers across the HGNC symbol, the NCBI Entrez Gene ID, the Ensembl gene ID and the reviewed UniProt accession, through " +
+        "MyGene.info — the ID step for a tool keyed on an ID that search_gene does not give, such as the Entrez IDs of humanbase.\n" +
+        "ACCEPTED IDENTIFIERS, mixed freely in one call of up to 200: a current symbol ('BRCA1', any case), an Entrez ID ('672'), an Ensembl gene " +
+        "ID ('ENSG00000012048'), or a UniProt accession ('P38398'). An old or informal symbol does not resolve, because an alias can name several " +
+        "current genes: resolve it to its current HGNC symbol first.\n" +
+        "Each hit carries the `query` that it answers, `symbol`, `name` (the full gene name), `entrez` (a number, or null for a gene with no " +
+        "Entrez record), `ensembl` and `uniprot` (arrays: several Ensembl IDs mean copies on alternate haplotypes or strains, and their order " +
+        "carries no rank). `notFound` lists each identifier with no gene. `ambiguous` lists each identifier with more than one gene, and each of " +
+        "those genes is in `genes` — a UniProt accession shared by a family of genes gives every member. An identifier gives at most " +
+        `${MYGENE_HITS_PER_ID} genes, and \`truncated\` lists each identifier that had more.\n` +
+        "`species` takes a common name ('human', the default, 'mouse', 'rat', 'zebrafish') or an NCBI Taxonomy ID as a string ('9606').\n" +
+        "notFound is valid no-data — report it and continue, do not retry unchanged.",
+    inputSchema: z.object({
+        identifiers: z
+            .array(z.string())
+            .min(1)
+            .max(MAX_IDENTIFIERS)
+            .describe(`Gene identifiers to map, mixed freely, max ${MAX_IDENTIFIERS} (e.g. ['BRCA1', '7157', 'ENSG00000146648', 'P38398']).`),
+        species: z.string().trim().min(1).default("human").describe("A common name ('human', 'mouse') or an NCBI Taxonomy ID as a string ('9606')."),
+    }),
+    outputSchema,
+    view: "none",
+    // The identifiers are the call. A large batch is summarized here rather than
+    // left to the emit-site cap: that cap cuts at a character, so a 200-symbol
+    // join arrives ending in `TP5` — a fragment that reads as a real symbol and
+    // says nothing about how many were dropped. The count leads, so a batch is
+    // legible as a batch even when the sample after it is itself trimmed.
+    describeCall: ({ identifiers }) => identifiers.length <= IDENTIFIERS_LISTED_IN_FULL
+        ? identifiers.join(", ")
+        : `${identifiers.length} genes: ${identifiers.slice(0, IDENTIFIERS_LISTED_IN_FULL).join(", ")}, …`,
+    execute: async ({ identifiers, species }) => ok(await resolveGeneIds(identifiers, species)),
+});