@inflexa-ai/harness 0.30.3 → 0.31.0

package/dist/tools/bio/pubchem.js

@@ -21,9 +21,11 @@ const inputSchema = z
         .describe("Which PubChem lookup to run. " +
         "'compound' — resolve `query` (in the namespace named by `searchBy`) to a compound. Returns results[]: identity (cid, canonicalSmiles, inchi, inchiKey, iupacName, " +
         "molecularFormula) and computed properties (molecularWeight, xlogp, tpsa, hbondDonorCount, hbondAcceptorCount, rotatableBondCount, complexity). " +
-        "'crossrefs' — external registry ids for a `cid`. Returns crossRefs[]: a flat list of { source, id } pairs across ChEMBL, DrugBank, KEGG, PDB and many other " +
-        "registries; filter by `source` for the one you want. This is the bridge out of PubChem. " +
-        "'assays' — bioassay screening summaries for a `cid`; answers 'has this compound ever been screened, and against what?'. Returns assays[]: aid, assayName, targetName, " +
+        "'crossrefs' — external registry ids for a `cid`. Returns crossRefs[]: a flat list of { source, id } entries. `source` names the registry that the id pattern " +
+        "identifies — ChEMBL, ChEBI, DrugBank, KEGG, HMDB, CAS, PDB or UNII — and it is null for an id of any other registry; filter by `source` for the one you want. " +
+        "This is the bridge out of PubChem. " +
+        "'assays' — bioassay screening summaries for a `cid`; answers 'has this compound ever been screened, and against what?'. Returns assays[]: aid, assayName, targetName " +
+        "(the target accession, for example a UniProt or PDB id), " +
         "activityOutcome (Active / Inactive / Inconclusive / Unspecified), activityValue. Broad HTS screening coverage, NOT curated potency — for numbers you intend to quote " +
         "(IC50/Ki), prefer chembl action='bioactivity'."),
     query: z

package/dist/tools/bio/search-clinical-trials.js

@@ -26,8 +26,8 @@ export const searchClinicalTrialsTool = defineTool({
         "read a result, as opposed to finding a trial.\n" +
         "ACCEPTED IDENTIFIERS: `query` is free text matched across the whole study record, so a gene symbol ('KRAS'), a drug or brand name ('imatinib', " +
         "'Gleevec'), a condition ('melanoma') or an NCT ID ('NCT00000102') all work. `nctId` takes one NCT ID and nothing else.\n" +
-        "`phase` and `status` are optional server-side filters — omit them to see the full landscape; totalFound reports the true match count even when it " +
-        "exceeds the page returned.\n" +
+        "`status` is an optional server-side filter and `phase` narrows the returned page. Omit both to see the full landscape. totalFound reports the true " +
+        "match count of `query` plus `status`, thus it can exceed the trials that a phase-narrowed answer carries.\n" +
         "ABSENCE IS NORMAL. An empty trials array is a valid 'nothing matched' (often an over-narrow filter) and a null trial from 'details' means the " +
         "registry holds no such NCT ID — report it and move on, do not retry the identical call. A trial with no posted results carries empty outcomes " +
         "and adverse events, which means unreported, never zero.",
@@ -45,8 +45,9 @@ export const searchClinicalTrialsTool = defineTool({
         phase: z
             .enum(["EARLY_PHASE1", "PHASE1", "PHASE2", "PHASE3", "PHASE4"])
             .optional()
-            .describe("'search' only. Optional exact phase filter. Omit for all phases (observational and expanded-access studies carry no phase and are " +
-            "excluded when this is set)."),
+            .describe("'search' only. Optional exact phase filter, applied to the returned page rather than to the whole query. Omit for all phases " +
+            "(observational and expanded-access studies carry no phase and are excluded when this is set). A narrow phase over a broad query " +
+            "can give fewer trials than `limit` asks for, even when the registry holds more."),
         status: z
             .enum(["RECRUITING", "ACTIVE_NOT_RECRUITING", "COMPLETED", "NOT_YET_RECRUITING", "TERMINATED", "WITHDRAWN", "SUSPENDED"])
             .optional()

package/dist/tools/bio/search-geo-datasets.d.ts

@@ -1,6 +1,44 @@
 /**
  * searchGeoDatasets — search NCBI GEO for public gene expression datasets.
  */
+import { z } from "zod";
+export declare const GeoEsearchResponseSchema: z.ZodObject<{
+    esearchresult: z.ZodOptional<z.ZodObject<{
+        idlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        count: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** One dataset row, as the tool returns it. */
+export interface GeoDataset {
+    accession: string;
+    title: string;
+    summary: string;
+    platform: string | null;
+    sampleCount: number | null;
+    organism: string | null;
+    pubmedIds: (string | number)[];
+}
+export declare const GeoEsummaryResponseSchema: z.ZodObject<{
+    result: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        accession: z.ZodOptional<z.ZodString>;
+        gse: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+        gpl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        n_samples: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        taxon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        pubmedids: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>>>;
+}, z.core.$strip>;
+/**
+ * Map one esummary answer onto the dataset rows.
+ *
+ * `ids` is the id list of the search, and it names the order of the rows. The
+ * function is pure, thus the golden-fixture table exercises it against a stored
+ * payload.
+ */
+export declare function mapGeoDatasets(ids: string[], summary: z.infer<typeof GeoEsummaryResponseSchema>): GeoDataset[];
 export declare const searchGeoDatasetsTool: import("../define-tool.js").Tool<{
     query: string;
     datasetType: "gse" | "gds";
@@ -8,13 +46,5 @@ export declare const searchGeoDatasetsTool: import("../define-tool.js").Tool<{
     organism?: string | undefined;
 }, {
     totalFound: number;
-    datasets: {
-        accession: string;
-        title: string;
-        summary: string;
-        platform: string | null;
-        sampleCount: number | null;
-        organism: string | null;
-        pubmedIds: (string | number)[];
-    }[];
+    datasets: GeoDataset[];
 }>;

package/dist/tools/bio/search-geo-datasets.js

@@ -10,7 +10,7 @@ const ESEARCH_BASE = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";
 // optional because the API omits absent values; the mapping in `execute` keys
 // off the esearch `idlist` (request context) and reshapes each summary, so the
 // schemas model only the raw wire.
-const GeoEsearchResponseSchema = z.object({
+export const GeoEsearchResponseSchema = z.object({
     esearchresult: z
         .object({
         idlist: z.array(z.string()).optional(),
@@ -18,24 +18,58 @@ const GeoEsearchResponseSchema = z.object({
     })
         .optional(),
 });
+// `gpl` is the platform accession, as a bare number string ("20301"). esummary
+// serves no `platform` key at any level. `error` marks the 200-with-error form:
+// esummary answers HTTP 200 for an unknown uid and puts `{"uid": …, "error": …}`
+// under that key, which carries no dataset.
 const GeoDatasetSummarySchema = z.object({
     accession: z.string().optional(),
     gse: z.string().optional(),
     title: z.string().optional(),
     summary: z.string().optional(),
     gpl: z.string().nullable().optional(),
-    platform: z.string().nullable().optional(),
     n_samples: z.union([z.string(), z.number()]).optional(),
     taxon: z.string().nullable().optional(),
     pubmedids: z.array(z.union([z.string(), z.number()])).optional(),
+    error: z.string().optional(),
 });
 // The esummary `result` object mixes a `uids` string array in with the
 // numeric-keyed dataset summaries; `.catch(undefined)` on the record value lets
 // that `uids` entry (and any drifted summary) fall through as undefined rather
 // than rejecting the whole response — the mapping reads only the numeric ids.
-const GeoEsummaryResponseSchema = z.object({
+export const GeoEsummaryResponseSchema = z.object({
     result: z.record(z.string(), GeoDatasetSummarySchema.optional().catch(undefined)).optional(),
 });
+/**
+ * Map one esummary answer onto the dataset rows.
+ *
+ * `ids` is the id list of the search, and it names the order of the rows. The
+ * function is pure, thus the golden-fixture table exercises it against a stored
+ * payload.
+ */
+export function mapGeoDatasets(ids, summary) {
+    const result = summary?.result ?? {};
+    const datasets = [];
+    for (const id of ids) {
+        const r = result[id];
+        if (!r)
+            continue;
+        // An error record carries no dataset. Without this guard it becomes a
+        // row of empty strings with a fabricated accession.
+        if (r.error !== undefined)
+            continue;
+        datasets.push({
+            accession: r.accession ?? r.gse ?? `GDS${id}`,
+            title: r.title ?? "",
+            summary: (r.summary ?? "").slice(0, 300),
+            platform: r.gpl ?? null,
+            sampleCount: r.n_samples ? Number(r.n_samples) : null,
+            organism: r.taxon ?? null,
+            pubmedIds: r.pubmedids ?? [],
+        });
+    }
+    return datasets;
+}
 export const searchGeoDatasetsTool = defineTool({
     id: "search_geo_datasets",
     description: "Search the NCBI Gene Expression Omnibus (GEO) — the public functional-genomics repository of the U.S. National Library of Medicine — for " +
@@ -88,23 +122,7 @@ export const searchGeoDatasetsTool = defineTool({
         const summaryRes = await apiFetchValidated(summaryUrl, GeoEsummaryResponseSchema);
         if (summaryRes.isErr())
             throw new Error(describeApiError(summaryRes.error));
-        const result = summaryRes.value?.result ?? {};
-        const datasets = ids
-            .map((id) => {
-            const r = result[id];
-            if (!r)
-                return null;
-            return {
-                accession: r.accession ?? r.gse ?? `GDS${id}`,
-                title: r.title ?? "",
-                summary: (r.summary ?? "").slice(0, 300),
-                platform: r.gpl ?? r.platform ?? null,
-                sampleCount: r.n_samples ? Number(r.n_samples) : null,
-                organism: r.taxon ?? null,
-                pubmedIds: r.pubmedids ?? [],
-            };
-        })
-            .filter((d) => d !== null);
+        const datasets = mapGeoDatasets(ids, summaryRes.value);
         const totalFound = Number(searchRes.value?.esearchresult?.count) || datasets.length;
         return ok({ totalFound, datasets });
     },

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

@@ -1,7 +1,8 @@
 /**
  * Shared HTTP fetch helper for bioinformatics API tools.
  *
- * Provides retry-with-backoff for rate-limited APIs (429/503), request
+ * Provides retry-with-backoff for a rate-limited or a transiently-broken API
+ * (429/502/503/504), request
  * timeouts, and tab-delimited text parsing. `apiFetch` is the external-call
  * boundary, so it is where a throw becomes a `Result`: it returns a
  * `ResultAsync<T, ApiError>` rather than throwing — callers branch on
@@ -35,7 +36,7 @@ export type ApiError = {
     readonly issues: string;
 };
 /**
- * Fetch a URL with retry on 429/503, exponential backoff, and timeout.
+ * Fetch a URL with retry on 429/502/503/504, exponential backoff, and timeout.
  * `err` carries the structured failure; a non-ok HTTP status is reported as
  * `http_status` so callers can branch on a concrete code (a 404 is usually an
  * expected "not found" → a data variant; see `isUnexpectedApiError`).
@@ -73,6 +74,30 @@ export declare function describeApiError(e: ApiError): string;
  * throwing (or returning `err`).
  */
 export declare function isUnexpectedApiError(e: ApiError): boolean;
+/**
+ * Read a number that a provider serializes as a JSON string.
+ *
+ * A Tastypie `decimal` field (ChEMBL `max_phase`, `standard_value`,
+ * `pchembl_value`) and the eutils `esearch` counts arrive as strings, and the
+ * same value arrives as a number from a different serializer of the same
+ * provider. One helper answers for both encodings, thus no call site invents its
+ * own rule.
+ *
+ * A value that is not a finite number gives `null`. As a result a caller never
+ * sees `NaN`, which compares false against itself and poisons every downstream
+ * threshold.
+ */
+export declare function parseWireNumber(value: string | number | null | undefined): number | null;
+/**
+ * The schema form of `parseWireNumber`, for a field that a provider serializes
+ * as a string or as a number.
+ *
+ * The helper accepts neither `null` nor an omission, because absence is a
+ * per-provider policy and no field is widened without evidence. A caller
+ * composes `.nullable()`, `.optional()`, or both, per the policy of its
+ * provider.
+ */
+export declare const zWireNumber: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>;
 /**
  * Parse tab-separated text into rows of columns (e.g., KEGG responses).
  * Filters out empty lines.

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

@@ -1,17 +1,22 @@
 /**
  * Shared HTTP fetch helper for bioinformatics API tools.
  *
- * Provides retry-with-backoff for rate-limited APIs (429/503), request
+ * Provides retry-with-backoff for a rate-limited or a transiently-broken API
+ * (429/502/503/504), request
  * timeouts, and tab-delimited text parsing. `apiFetch` is the external-call
  * boundary, so it is where a throw becomes a `Result`: it returns a
  * `ResultAsync<T, ApiError>` rather than throwing — callers branch on
  * `isErr()` and read `value` / `error` (see `result.ts` for the house rules).
  */
 import { ResultAsync, err, ok } from "neverthrow";
+import { z } from "zod";
 import { sleep } from "../../lib/async-utils.js";
-const RETRYABLE_STATUSES = new Set([429, 503]);
+// 502 and 504 sit here next to 429 and 503 because a gateway in front of a bio
+// provider answers with one of them while the origin restarts, and it sends an
+// HTML body. That answer is transient, thus a retry gets the real payload.
+const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
 /**
- * Fetch a URL with retry on 429/503, exponential backoff, and timeout.
+ * Fetch a URL with retry on 429/502/503/504, exponential backoff, and timeout.
  * `err` carries the structured failure; a non-ok HTTP status is reported as
  * `http_status` so callers can branch on a concrete code (a 404 is usually an
  * expected "not found" → a data variant; see `isUnexpectedApiError`).
@@ -116,6 +121,41 @@ export function describeApiError(e) {
 export function isUnexpectedApiError(e) {
     return !(e.type === "http_status" && e.status >= 400 && e.status < 500);
 }
+/**
+ * Read a number that a provider serializes as a JSON string.
+ *
+ * A Tastypie `decimal` field (ChEMBL `max_phase`, `standard_value`,
+ * `pchembl_value`) and the eutils `esearch` counts arrive as strings, and the
+ * same value arrives as a number from a different serializer of the same
+ * provider. One helper answers for both encodings, thus no call site invents its
+ * own rule.
+ *
+ * A value that is not a finite number gives `null`. As a result a caller never
+ * sees `NaN`, which compares false against itself and poisons every downstream
+ * threshold.
+ */
+export function parseWireNumber(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "number")
+        return Number.isFinite(value) ? value : null;
+    const trimmed = value.trim();
+    // `Number("")` and `Number(" ")` give 0, thus an empty string must not reach it.
+    if (trimmed === "")
+        return null;
+    const parsed = Number(trimmed);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+/**
+ * The schema form of `parseWireNumber`, for a field that a provider serializes
+ * as a string or as a number.
+ *
+ * The helper accepts neither `null` nor an omission, because absence is a
+ * per-provider policy and no field is widened without evidence. A caller
+ * composes `.nullable()`, `.optional()`, or both, per the policy of its
+ * provider.
+ */
+export const zWireNumber = z.union([z.string(), z.number()]).transform((value) => parseWireNumber(value));
 /**
  * Parse tab-separated text into rows of columns (e.g., KEGG responses).
  * Filters out empty lines.

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

@@ -5,7 +5,12 @@
  * lookups for the configured non-human species (Ensembl REST), then
  * queries Bgee per (species, ortholog ENSG) for tissue-level expression
  * calls. Returns a per-species table of tissue × expression-rank.
+ *
+ * Absence policy: Bgee and the Ensembl calls in this file omit the key of an
+ * absent value, and neither one sends an explicit `null`. Thus a maybe-absent
+ * field carries `.optional()`, not `.nullable()`.
  */
+import { z } from "zod";
 export declare const SUPPORTED_SPECIES: readonly ["homo_sapiens", "mus_musculus", "rattus_norvegicus", "canis_lupus_familiaris", "macaca_mulatta"];
 export type SupportedSpecies = (typeof SUPPORTED_SPECIES)[number];
 export declare const SPECIES_TAXON: Record<SupportedSpecies, number>;
@@ -31,6 +36,17 @@ export interface MultiSpeciesExpression {
     notFound: string[];
 }
 export declare function bucketRank(expressionState: string, score: number | null): ExpressionRank;
+export declare const EnsemblLookupSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const EnsemblHomologyResponseSchema: z.ZodObject<{
+    data: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        homologies: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            type: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
 export declare function parseExpressionResponse(raw: unknown): TissueRow[];
 /** Fetch multi-species expression for a human gene symbol. */
 export declare function getMultiSpeciesExpression(geneSymbol: string, species?: SupportedSpecies[]): Promise<MultiSpeciesExpression>;

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

@@ -5,6 +5,10 @@
  * lookups for the configured non-human species (Ensembl REST), then
  * queries Bgee per (species, ortholog ENSG) for tissue-level expression
  * calls. Returns a per-species table of tissue × expression-rank.
+ *
+ * Absence policy: Bgee and the Ensembl calls in this file omit the key of an
+ * absent value, and neither one sends an explicit `null`. Thus a maybe-absent
+ * field carries `.optional()`, not `.nullable()`.
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError, isUnexpectedApiError } from "./api-utils.js";
@@ -51,8 +55,8 @@ const BgeeExpressionResponseSchema = z.object({
     data: z.object({ calls: z.array(BgeeCallSchema).optional() }).optional(),
 });
 // Ensembl REST response shapes consumed by the ortholog-resolution path.
-const EnsemblLookupSchema = z.object({ id: z.string().optional() });
-const EnsemblHomologyResponseSchema = z.object({
+export const EnsemblLookupSchema = z.object({ id: z.string().optional() });
+export const EnsemblHomologyResponseSchema = z.object({
     data: z.array(z.object({ homologies: z.array(z.object({ id: z.string().optional(), type: z.string().optional() })).optional() })).optional(),
 });
 export function parseExpressionResponse(raw) {
@@ -102,8 +106,15 @@ async function resolveHumanEnsembl(symbol) {
         return null;
     return res.value.id;
 }
-async function resolveOrtholog(symbol, targetSpecies) {
-    const url = `${ENSEMBL_BASE}/homology/symbol/homo_sapiens/${encodeURIComponent(symbol)}` + `?type=orthologues;target_species=${targetSpecies};format=condensed`;
+/**
+ * Resolve the ortholog of one human gene in one other species.
+ *
+ * The route keys on the Ensembl gene id, and never on the symbol. The symbol
+ * route serves the identical envelope, but it answers HTTP 503 under load while
+ * the id route answers. Thus the caller resolves the id first.
+ */
+async function resolveOrtholog(humanEnsemblId, targetSpecies) {
+    const url = `${ENSEMBL_BASE}/homology/id/homo_sapiens/${encodeURIComponent(humanEnsemblId)}` + `?type=orthologues;target_species=${targetSpecies};format=condensed`;
     const res = await apiFetchValidated(url, EnsemblHomologyResponseSchema, { headers: ENSEMBL_HEADERS });
     if (res.isErr()) {
         if (isUnexpectedApiError(res.error))
@@ -133,7 +144,7 @@ export async function getMultiSpeciesExpression(geneSymbol, species = [...SUPPOR
     const idEntries = await Promise.all(species.map(async (sp) => {
         if (sp === "homo_sapiens")
             return { sp, id: humanEnsemblId };
-        const id = await resolveOrtholog(geneSymbol, sp);
+        const id = await resolveOrtholog(humanEnsemblId, sp);
         return { sp, id };
     }));
     const bySpecies = [];

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

@@ -5,7 +5,12 @@
  * the public cBioPortal REST API for mutation occurrence across all curated
  * cancer studies, then aggregates by cancer type to produce the spec's
  * "where is the target broken in human disease, and how often" view.
+ *
+ * Absence policy: cBioPortal omits the key of an absent value, and it never
+ * sends an explicit `null`. Thus a maybe-absent field carries `.optional()`,
+ * not `.nullable()`.
  */
+import { z } from "zod";
 export interface CancerStudy {
     studyId: string;
     cancerType: string;
@@ -19,6 +24,21 @@ export interface MutationFrequency {
     frequency: number;
     studies: string[];
 }
+export declare const RawMutationRowSchema: z.ZodObject<{
+    studyId: z.ZodString;
+    sampleId: z.ZodString;
+}, z.core.$strip>;
+export declare const RawCancerStudySchema: z.ZodObject<{
+    studyId: z.ZodString;
+    cancerTypeId: z.ZodOptional<z.ZodString>;
+    cancerType: z.ZodOptional<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    allSampleCount: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 /**
  * Compute somatic mutation frequencies for a target across all curated
  * cancer studies in cBioPortal, grouped by cancer type. Returns one row

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

@@ -5,6 +5,10 @@
  * the public cBioPortal REST API for mutation occurrence across all curated
  * cancer studies, then aggregates by cancer type to produce the spec's
  * "where is the target broken in human disease, and how often" view.
+ *
+ * Absence policy: cBioPortal omits the key of an absent value, and it never
+ * sends an explicit `null`. Thus a maybe-absent field carries `.optional()`,
+ * not `.nullable()`.
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError } from "./api-utils.js";
@@ -19,10 +23,11 @@ const RawMolecularProfileSchema = z.object({
     studyId: z.string(),
     molecularAlterationType: z.string().optional(),
 });
-const RawMutationCountSchema = z.object({
+// One mutation row of `mutations/fetch`. The aggregation counts the distinct
+// samples of a study, thus it reads only the two key fields of the row.
+export const RawMutationRowSchema = z.object({
     studyId: z.string(),
     sampleId: z.string(),
-    mutationCount: z.number().optional(),
 });
 const RawSampleListSchema = z.object({
     sampleListId: z.string().optional(),
@@ -30,10 +35,13 @@ const RawSampleListSchema = z.object({
     category: z.string().optional(),
     sampleCount: z.number().optional(),
 });
-const RawCancerStudySchema = z.object({
+export const RawCancerStudySchema = z.object({
     studyId: z.string(),
     cancerTypeId: z.string().optional(),
-    cancerType: z.object({ name: z.string().optional(), cancerTypeId: z.string().optional() }).optional(),
+    // The nested block keys its identifier as `id`. The `projection=DETAILED`
+    // answer carries the block, and `projection=SUMMARY` omits it, thus the
+    // top-level `cancerTypeId` stays the fallback.
+    cancerType: z.object({ id: z.string().optional(), name: 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. */
@@ -77,11 +85,11 @@ async function listMutationProfiles() {
         throw new Error(describeApiError(res.error));
     return (res.value ?? []).filter((p) => p.molecularAlterationType === "MUTATION_EXTENDED");
 }
-async function fetchMutationCountsForGene(entrezGeneId, profileIds) {
+async function fetchMutationRowsForGene(entrezGeneId, profileIds) {
     if (profileIds.length === 0)
         return [];
     const url = `${CBIOPORTAL_BASE}/mutations/fetch?projection=SUMMARY`;
-    const res = await apiFetchValidated(url, z.array(RawMutationCountSchema), {
+    const res = await apiFetchValidated(url, z.array(RawMutationRowSchema), {
         method: "POST",
         headers: { ...HEADERS, "Content-Type": "application/json" },
         body: JSON.stringify({
@@ -132,7 +140,7 @@ export async function getSomaticMutationFrequencies(geneSymbol, options = {}) {
     const studyById = new Map();
     for (const s of studies)
         studyById.set(s.studyId, s);
-    const mutations = await fetchMutationCountsForGene(entrezGeneId, profileIds);
+    const mutations = await fetchMutationRowsForGene(entrezGeneId, profileIds);
     const mutatedStudySamples = new Map();
     for (const m of mutations) {
         if (!mutatedStudySamples.has(m.studyId))
@@ -145,7 +153,7 @@ export async function getSomaticMutationFrequencies(geneSymbol, options = {}) {
         const sampleCount = study?.allSampleCount ?? 0;
         if (sampleCount === 0)
             continue;
-        const cancerTypeId = study?.cancerType?.cancerTypeId ?? study?.cancerTypeId ?? "unknown";
+        const cancerTypeId = study?.cancerType?.id ?? study?.cancerTypeId ?? "unknown";
         const cancerTypeName = study?.cancerType?.name ?? typeNames.get(cancerTypeId) ?? cancerTypeId;
         if (!byCancerType.has(cancerTypeId)) {
             byCancerType.set(cancerTypeId, {

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

@@ -2,7 +2,13 @@
  * Pure async client functions for the ChEMBL REST API.
  *
  * Used directly by target-assessment workflow steps and by tool wrappers.
+ *
+ * Absence policy: ChEMBL sends an explicit `null` for an absent value, and it
+ * never omits the key. Thus a maybe-absent field carries `.nullable()`, not
+ * `.optional()`.
  */
+import { z } from "zod";
+import type { Logger } from "../../lib/logger.js";
 export interface ChemblCompound {
     chemblId: string;
     preferredCompoundName: string | null;
@@ -65,6 +71,92 @@ export interface ChemblPolypharmHit {
     standardUnits: string | null;
     pchemblValue: number | null;
 }
+export declare const TargetSearchResponseSchema: z.ZodObject<{
+    targets: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        target_chembl_id: z.ZodOptional<z.ZodString>;
+        pref_name: z.ZodOptional<z.ZodString>;
+        target_type: z.ZodOptional<z.ZodString>;
+        organism: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        target_components: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            accession: z.ZodOptional<z.ZodString>;
+            target_component_synonyms: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                syn_type: z.ZodOptional<z.ZodString>;
+                component_synonym: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const ActivitiesResponseSchema: z.ZodObject<{
+    activities: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        activity_id: z.ZodOptional<z.ZodNumber>;
+        molecule_chembl_id: z.ZodOptional<z.ZodString>;
+        target_chembl_id: z.ZodOptional<z.ZodString>;
+        standard_type: z.ZodOptional<z.ZodString>;
+        standard_value: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>>>;
+        standard_units: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        assay_chembl_id: z.ZodOptional<z.ZodString>;
+        assay_type: z.ZodOptional<z.ZodString>;
+        pchembl_value: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const MechanismsResponseSchema: z.ZodObject<{
+    mechanisms: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        mechanism_of_action: z.ZodOptional<z.ZodString>;
+        action_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        target_chembl_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        molecule_chembl_id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const DrugIndicationsResponseSchema: z.ZodObject<{
+    drug_indications: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        molecule_chembl_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        mesh_heading: z.ZodOptional<z.ZodString>;
+        efo_term: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        max_phase_for_ind: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const MoleculeSearchResponseSchema: z.ZodObject<{
+    molecules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        molecule_chembl_id: z.ZodOptional<z.ZodString>;
+        pref_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        max_phase: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>>>;
+        molecule_type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        first_approval: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        molecule_hierarchy: z.ZodOptional<z.ZodObject<{
+            parent_chembl_id: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const MoleculeStructuresResponseSchema: z.ZodObject<{
+    molecule_structures: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        standard_inchi_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export declare const CompoundsResponseSchema: z.ZodObject<{
+    molecules: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodObject<{
+        molecule_chembl_id: z.ZodOptional<z.ZodString>;
+        pref_name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        molecule_structures: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            canonical_smiles: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>;
+        molecule_properties: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            full_mwt: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>>>;
+            alogp: z.ZodOptional<z.ZodNullable<z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>>>;
+            full_molformula: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>, z.ZodTransform<ChemblCompound, {
+        molecule_chembl_id?: string | undefined;
+        pref_name?: string | null | undefined;
+        molecule_structures?: {
+            canonical_smiles?: string | null | undefined;
+        } | null | undefined;
+        molecule_properties?: {
+            full_mwt?: number | null | undefined;
+            alogp?: number | null | undefined;
+            full_molformula?: string | null | undefined;
+        } | null | undefined;
+    }>>>>;
+}, z.core.$strip>;
 /** 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[]>;
@@ -75,6 +167,16 @@ export declare function getBioactivity(chemblId: string, type: BioactivityIdType
     limit?: number;
 }): Promise<ChemblActivity[]>;
 export declare function getMechanism(chemblId: string): Promise<ChemblMechanism[]>;
+/**
+ * Approved drugs by name or by disease term.
+ *
+ * The `drug` resource of ChEMBL has no search endpoint, and it carries neither a
+ * name nor an indication. The molecule name search runs first, because an
+ * `icontains` read of `drug_indication` captures a drug name that is a substring
+ * of a disease term ("insulin" matches "insulin resistance"). A query that
+ * names no molecule falls through to the indication read, which answers
+ * highest-phase first and can carry a clinical-stage molecule below approval.
+ */
 export declare function getDrugInfo(query: string, limit?: number): Promise<ChemblDrug[]>;
 /**
  * Fetch all clinical-stage modulators (max_phase ≥ 2 by default) for a target.
@@ -83,7 +185,7 @@ export declare function getDrugInfo(query: string, limit?: number): Promise<Chem
 export declare function getTargetModulators(targetChemblId: string, options?: {
     minPhase?: number;
     limit?: number;
-}): Promise<ChemblModulator[]>;
+}, logger?: Logger): Promise<ChemblModulator[]>;
 /**
  * Fetch off-target binding hits for a modulator: every target the molecule
  * has been measured against (excluding the primary target), with potency.
@@ -102,7 +204,7 @@ export declare function getModulatorPolypharmacology(moleculeChemblId: string, o
  * Used by the polypharm fanout step so the assembler's computeSelectivity
  * can produce real fold values instead of selectivity_unknown.
  */
-export declare function getModulatorOnTargetPchembl(modulatorChemblId: string, targetChemblId: string): Promise<number | null>;
+export declare function getModulatorOnTargetPchembl(modulatorChemblId: string, targetChemblId: string, logger?: Logger): Promise<number | null>;
 /**
  * Secondary path: fetch clinical-stage small molecules via the activity table.
  *
@@ -121,7 +223,7 @@ export declare function getModulatorsViaActivity(args: {
     max_phase_min?: number;
     molecule_type?: string;
     limit?: number;
-}): Promise<ChemblModulator[]>;
+}, logger?: Logger): Promise<ChemblModulator[]>;
 /**
  * Fetch the canonical InChI key for a ChEMBL molecule. Returns null when
  * ChEMBL has no recorded structure (typical for peptide/protein entries