@inflexa-ai/harness 0.45.1 → 0.46.0

package/dist/tools/knowledge/template.js

@@ -26,12 +26,16 @@
  * nothing again.
  */
 import { ok } from "neverthrow";
+import { presentGet } from "../../lib/present.js";
 import { z } from "zod";
 import { defineTool, withToolCallRecord } from "../define-tool.js";
 import { decisionRecordPath, scriptSha256 } from "../workspace/decision-record.js";
 import { installedPackages } from "./environment.js";
 import { bindLocalSlots, localParameters, validateLocalSlot } from "./local-slots.js";
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the template reference grammar: the tpl- prefix, an id, and an optional @version tail.
 const TEMPLATE_REF = /^tpl-[a-z0-9-]+(@\d+\.\d+\.\d+)?$/;
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- a script file name is one segment of the safe file-name charset; the shape is the path-safety rule.
+const SCRIPT_NAME_RE = /^[A-Za-z0-9_.-]+$/;
 /** A model value equals a bound value when the scalars are identical, or when two lists hold the same strings in order. */
 function sameValue(bound, value) {
     if (Array.isArray(bound)) {
@@ -83,6 +87,27 @@ function splitSlots(slots, names) {
         (names.has(name) ? local : remote)[name] = value;
     return { local, remote };
 }
+const KnowledgeTemplateInputSchema = z.object({
+    template: z
+        .string()
+        .regex(TEMPLATE_REF, "a template id, optionally with @version")
+        .describe("The template id from the Grounding of the step, with its version, for example `tpl-deseq2-two-group@1.0.0`."),
+    slots: z
+        .record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.array(z.string())]))
+        .describe("The slot values, by slot name. Only the adaptable slots of the template; a pinned slot is refused. Strings, numbers, booleans, and lists of strings."),
+    overrides: z
+        .array(z.object({
+        slot: z.string().min(1).describe("The name of the bound slot whose value you change."),
+        reason: z.string().min(1).describe("Why the plan value does not hold for this step, in one sentence."),
+    }))
+        .optional()
+        .describe("One entry per bound slot whose value you change from the plan value. Absent when you send every bound value as it is."),
+    script_name: z
+        .string()
+        .regex(SCRIPT_NAME_RE)
+        .optional()
+        .describe("The file name under `scripts/`. Defaults to `<template id>.R` or `<template id>.py` by the language of the template."),
+});
 export function createKnowledgeTemplateTool(deps) {
     return defineTool({
         id: "knowledge_template",
@@ -94,30 +119,11 @@ export function createKnowledgeTemplateTool(deps) {
             "A bound value rides into the script as it is; send it unchanged, or omit it. To change a bound value, send the new value and add an `overrides` entry with the slot and the reason. A changed value without an override is refused before the service call. " +
             "Prefer the template over a script of your own: it is tested, and it carries the settings of the plan. When the template does not fit the step (a design it does not cover, or an input it cannot read), write the script yourself with `write_file`, and state the reason in your summary. " +
             "The tool writes `scripts/<template>.R` or `scripts/<template>.py` and `output/decision_record_<script>.json`, one record per rendered script (the step, its claims, the template, the snapshot, each slot with its source, the bound slots, the overrides, the environment match, the citations, and the digest of the script as written), then you run the script with `execute_command` using the command in `run_with`. " +
-            "A slot value the template refuses comes back as `match: rejected` with the slot and the permitted values; correct it and call again. " +
+            "A slot value of the right type that the template refuses comes back as `match: rejected` with the slot and the permitted values; correct it and call again. " +
+            "A slot value of a different type (a string for a number, for example) fails the input check of the tool before the template sees it; send the type that the slot states. " +
             "A change the slots do not cover: use `edit_file` on a line marked `# [adaptable: ...]` in the rendered script, and keep the edit small; the record lists each such edit. " +
             "`match: unavailable` means the service did not answer, and `match: snapshot_mismatch` means the service moved to another release than the plan pinned; in both cases write the script yourself as you would without this tool, and state it in your summary.",
-        inputSchema: z.object({
-            template: z
-                .string()
-                .regex(TEMPLATE_REF, "a template id, optionally with @version")
-                .describe("The template id from the Grounding of the step, with its version, for example `tpl-deseq2-two-group@1.0.0`."),
-            slots: z
-                .record(z.string(), z.unknown())
-                .describe("The slot values, by slot name. Only the adaptable slots of the template; a pinned slot is refused. Strings, numbers, booleans, and lists of strings."),
-            overrides: z
-                .array(z.object({
-                slot: z.string().min(1).describe("The name of the bound slot whose value you change."),
-                reason: z.string().min(1).describe("Why the plan value does not hold for this step, in one sentence."),
-            }))
-                .optional()
-                .describe("One entry per bound slot whose value you change from the plan value. Absent when you send every bound value as it is."),
-            script_name: z
-                .string()
-                .regex(/^[A-Za-z0-9_.-]+$/)
-                .optional()
-                .describe("The file name under `scripts/`. Defaults to `<template id>.R` or `<template id>.py` by the language of the template."),
-        }),
+        inputSchema: KnowledgeTemplateInputSchema,
         describeCall: ({ template }) => template,
         describeResult: (_input, result) => "status" in result ? (result.status === "ok" ? `${result.script_path} (${result.environment_match})` : result.status) : result.match,
         execute: async ({ template, slots, overrides, script_name }, ctx) => {
@@ -161,7 +167,7 @@ export function createKnowledgeTemplateTool(deps) {
             const localByName = new Map(locals.map((parameter) => [parameter.name, parameter]));
             // A local value the contract refuses is refused before the service call, thus a bad path costs no render.
             const localIssues = Object.entries(localValues).flatMap(([name, value]) => {
-                const issue = validateLocalSlot(localByName.get(name), value);
+                const issue = validateLocalSlot(presentGet(localByName, name, "the template parameter of the local value"), value);
                 return issue ? [issue] : [];
             });
             if (localIssues.length > 0) {
@@ -169,13 +175,13 @@ export function createKnowledgeTemplateTool(deps) {
             }
             const farmLockFile = typeof deps.farmLockFile === "function" ? deps.farmLockFile(ctx.session.scope.analysisId) : deps.farmLockFile;
             const installed = installedPackages({
-                ...(farmLockFile ? { farmLockFile } : {}),
-                ...(deps.imagePackagesFile ? { imagePackagesFile: deps.imagePackagesFile } : {}),
+                farmLockFile,
+                imagePackagesFile: deps.imagePackagesFile,
             });
             const answer = await deps.client.render(template, merged, installed.packages, {
-                ...(binding?.step ? { step: binding.step } : {}),
-                ...(binding?.claims ? { claims: binding.claims } : {}),
-                ...(binding?.snapshot ? { expectedSnapshot: binding.snapshot } : {}),
+                step: binding?.step,
+                claims: binding?.claims,
+                expectedSnapshot: binding?.snapshot,
             });
             // A rendered answer carries `ok: true`; the refusals carry `match` and no `ok`.
             if (!("ok" in answer))
@@ -205,7 +211,7 @@ export function createKnowledgeTemplateTool(deps) {
                 return ok({ status: "write_refused", path: scriptWrite.path, reason: scriptWrite.status });
             const boundSlots = Object.entries(binding?.slots ?? {}).map(([slot, value]) => ({
                 slot,
-                value: value,
+                value,
                 source: binding ? sourceOf(binding, slot) : "plan",
             }));
             const settingsOverrides = boundSlots.flatMap(({ slot, value }) => {
@@ -245,9 +251,9 @@ export function createKnowledgeTemplateTool(deps) {
                     version: answer.template.version,
                     label: answer.template.label,
                     method: { id: answer.template.method.id, label: answer.template.method.label },
-                    ...(answer.template.substitute_for
-                        ? { substitute_for: { id: answer.template.substitute_for.id, label: answer.template.substitute_for.label } }
-                        : {}),
+                    substitute_for: answer.template.substitute_for === undefined
+                        ? undefined
+                        : { id: answer.template.substitute_for.id, label: answer.template.substitute_for.label },
                 },
                 snapshot: answer.snapshot,
                 slots: reportedSlots,

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

@@ -19,6 +19,7 @@
  * `found: false` tells the agent to report the absence and not to retry.
  */
 import { z } from "zod";
+import { presentFirst } from "../../lib/present.js";
 import { apiFetchValidated, describeApiError } from "./api-utils.js";
 const ALPHAFOLD_BASE = "https://alphafold.ebi.ac.uk/api/prediction";
 /**
@@ -70,7 +71,7 @@ export async function fetchAlphaFoldPrediction(uniprotAccession) {
     if (entries.length === 0)
         return null;
     const exact = entries.find((entry) => entry.uniprotAccession.toUpperCase() === accession.toUpperCase());
-    return exact ?? entries[0];
+    return exact ?? presentFirst(entries, "the fallback entry");
 }
 function isAbsence(e) {
     return e.type === "http_status" && (e.status === 400 || e.status === 404);

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

@@ -349,24 +349,24 @@ export declare const RegulatorySectionResponseSchema: z.ZodObject<{
 }, z.core.$strip>;
 type RegulatoryBase = z.infer<typeof RegulatoryBaseSchema>;
 /** The sections of one source document. The document fields appear once, not on every section. */
-export interface SectionGroup<S> {
+export type SectionGroup<S> = {
     readonly docType: string;
     readonly sourceUrl: string | null;
     readonly sourceDate: string | null;
     readonly sections: S[];
-}
+};
 /** One entry of a table of contents. */
-export interface SectionEntry {
+export type SectionEntry = {
     readonly documentSectionId: string;
     readonly path: string | null;
     readonly title: string | null;
-}
+};
 /** One matched section of a search, with the excerpt that drove the match. */
-export interface MatchedSectionEntry extends SectionEntry {
+export type MatchedSectionEntry = SectionEntry & {
     readonly matchedText: string | null;
-}
+};
 /** The fields of an authorization that both the search and the details answer carry. */
-export interface AuthorizationSummary {
+export type AuthorizationSummary = {
     readonly amassId: string;
     readonly agency: string;
     readonly name: string | null;
@@ -382,22 +382,22 @@ export interface AuthorizationSummary {
     readonly designations: RegulatoryBase["designations"];
     readonly otherAuthorizations: RegulatoryBase["authorizationsByAgency"];
     readonly sourceUrl: string | null;
-}
+};
 /** The matched sections that a search row keeps. The count still reports all of them. */
 export declare const MAX_MATCHED_SECTIONS = 5;
-export interface AuthorizationSearchRow extends AuthorizationSummary {
+export type AuthorizationSearchRow = AuthorizationSummary & {
     readonly matchedSectionCount: number;
     readonly matchedDocuments: SectionGroup<MatchedSectionEntry>[];
-}
+};
 export declare function mapRegulatorySearchRow(record: z.infer<typeof RegulatorySearchResponseSchema>["data"][number]): AuthorizationSearchRow;
-export interface AuthorizationRecord extends AuthorizationSummary {
+export type AuthorizationRecord = AuthorizationSummary & {
     readonly fdaDetails: z.infer<typeof FdaDetailsSchema> | null;
     readonly emaDetails: z.infer<typeof EmaDetailsSchema> | null;
     readonly sectionCount: number;
     readonly documents: SectionGroup<SectionEntry>[];
-}
+};
 export declare function mapRegulatoryRecord(record: z.infer<typeof RegulatoryRecordResponseSchema>["data"]): AuthorizationRecord;
-export interface RegulatorySection {
+export type RegulatorySection = {
     readonly amassId: string;
     readonly documentSectionId: string;
     readonly docType: string;
@@ -406,8 +406,8 @@ export interface RegulatorySection {
     readonly sourceUrl: string | null;
     readonly sourceDate: string | null;
     readonly content: string | null;
-}
-export interface RegulatorySearchParams {
+};
+export type RegulatorySearchParams = {
     readonly query: string;
     readonly limit: number;
     readonly agency?: readonly string[];
@@ -418,19 +418,19 @@ export interface RegulatorySearchParams {
     readonly minAuthorizationDate?: string;
     readonly maxAuthorizationDate?: string;
     readonly amassId?: string;
-}
+};
 export declare function searchRegulatoryRecords(params: RegulatorySearchParams, headers: Record<string, string>): ResultAsync<AuthorizationSearchRow[], AmassError>;
 /** One authorization with its table of contents, or `null` when Amass holds no such ID. */
 export declare function getRegulatoryRecord(amassId: string, headers: Record<string, string>): ResultAsync<AuthorizationRecord | null, AmassError>;
 /** The full text of one document section, or `null` when Amass holds no such section. */
 export declare function getRegulatorySection(amassId: string, documentSectionId: string, headers: Record<string, string>): ResultAsync<RegulatorySection | null, AmassError>;
 /** The identifiers that the RegulatoryCore lookup accepts. Exactly one is set. */
-export interface RegulatoryIdentifier {
+export type RegulatoryIdentifier = {
     readonly fdaApplicationNumber?: string;
     readonly emaProductNumber?: string;
     readonly ndc?: string;
     readonly splSetId?: string;
-}
+};
 export declare function regulatoryLookupItems(id: RegulatoryIdentifier): LookupItem[];
 export declare function lookupRegulatoryIds(id: RegulatoryIdentifier, headers: Record<string, string>): ResultAsync<string[], AmassError>;
 declare const PatentBaseSchema: z.ZodObject<{
@@ -523,7 +523,7 @@ export declare const PatentRecordResponseSchema: z.ZodObject<{
 }, z.core.$strip>;
 type PatentBase = z.infer<typeof PatentBaseSchema>;
 /** A patent with its citation counts. The citation lists stay out: a cited patent can carry thousands. */
-export interface PatentSummary {
+export type PatentSummary = {
     readonly amassId: string;
     readonly publicationNumber: string | null;
     readonly applicationNumber: string | null;
@@ -546,17 +546,17 @@ export interface PatentSummary {
     readonly hasClaims: boolean | null;
     readonly hasDescription: boolean | null;
     readonly url: string | null;
-}
+};
 export declare function mapPatentSummary(record: PatentBase): PatentSummary;
-export interface PatentRecord extends PatentSummary {
+export type PatentRecord = PatentSummary & {
     readonly familyMembers: string[];
     readonly language: string | null;
     readonly nonEnglishFallback: boolean | null;
-    readonly claims?: string | null;
-    readonly description?: string | null;
-}
+    claims?: string | null;
+    description?: string | null;
+};
 export declare function mapPatentRecord(record: PatentBase): PatentRecord;
-export interface PatentSearchParams {
+export type PatentSearchParams = {
     readonly query: string;
     readonly limit: number;
     readonly assignee?: readonly string[];
@@ -571,16 +571,16 @@ export interface PatentSearchParams {
     readonly maxPriorityDate?: string;
     readonly minGrantDate?: string;
     readonly maxGrantDate?: string;
-}
+};
 export declare function searchPatentRecords(params: PatentSearchParams, headers: Record<string, string>): ResultAsync<PatentSummary[], AmassError>;
 export declare function getPatentRecord(amassId: string, include: {
     readonly claims: boolean;
     readonly description: boolean;
 }, headers: Record<string, string>): ResultAsync<PatentRecord | null, AmassError>;
 /** The identifiers that the PatentCore lookup accepts. Exactly one is set. */
-export interface PatentIdentifier {
+export type PatentIdentifier = {
     readonly publicationNumber?: string;
     readonly applicationNumber?: string;
-}
+};
 export declare function lookupPatentIds(id: PatentIdentifier, headers: Record<string, string>): ResultAsync<string[], AmassError>;
 export {};

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

@@ -31,6 +31,8 @@
 import { err, ok } from "neverthrow";
 import { z } from "zod";
 import { apiFetchValidated, describeApiError } from "./api-utils.js";
+import { safeParseJsonAs } from "../../lib/parse-json.js";
+import { hasWhitespace, isAllDigits } from "../../lib/text.js";
 import { AMASS_BASE } from "./amass-config.js";
 /** Render an `AmassError` as a one-line message for the model or for a throw. */
 export function describeAmassError(e) {
@@ -60,14 +62,13 @@ export const AmassErrorEnvelopeSchema = z.object({
 });
 /** Read the message of an Amass error body, with the per-field reasons of a 400. */
 function envelopeOf(body) {
-    let parsed;
+    let envelope;
     try {
-        parsed = JSON.parse(body);
+        envelope = safeParseJsonAs(body, AmassErrorEnvelopeSchema);
     }
     catch {
         return { code: null, message: body || "no message" };
     }
-    const envelope = AmassErrorEnvelopeSchema.safeParse(parsed);
     if (!envelope.success)
         return { code: null, message: body || "no message" };
     const { code, message, fields } = envelope.data.error;
@@ -105,7 +106,8 @@ function urlOf(path, params) {
         if (value === undefined)
             continue;
         if (Array.isArray(value)) {
-            for (const item of value)
+            const items = value;
+            for (const item of items)
                 url.searchParams.append(key, item);
         }
         else {
@@ -154,8 +156,11 @@ const FDA_APPLICATION_PREFIXES = ["NDA", "BLA", "ANDA"];
  * thus goes as all three prefixes, in one request at the price of one.
  */
 export function fdaApplicationForms(input) {
-    const compact = input.replace(/[\s-]/g, "").toUpperCase();
-    if (/^\d+$/.test(compact))
+    const compact = Array.from(input)
+        .filter((char) => char !== "-" && !hasWhitespace(char))
+        .join("")
+        .toUpperCase();
+    if (compact !== "" && isAllDigits(compact))
         return FDA_APPLICATION_PREFIXES.map((prefix) => `${prefix}${compact}`);
     return [compact];
 }
@@ -166,7 +171,9 @@ export function fdaApplicationForms(input) {
 export function productNdcOf(input) {
     const trimmed = input.trim();
     const segments = trimmed.split("-");
-    return segments.length === 3 && segments.every((segment) => /^\d+$/.test(segment)) ? `${segments[0]}-${segments[1]}` : trimmed;
+    return segments.length === 3 && segments.every((segment) => segment.length > 0 && isAllDigits(segment))
+        ? `${String(segments[0])}-${String(segments[1])}`
+        : trimmed;
 }
 // ---------------------------------------------------------------------------
 // RegulatoryCore
@@ -455,14 +462,17 @@ export function mapPatentSummary(record) {
     };
 }
 export function mapPatentRecord(record) {
-    return {
+    const patent = {
         ...mapPatentSummary(record),
         familyMembers: record.familyMembers,
         language: record.language,
         nonEnglishFallback: record.nonEnglishFallback,
-        ...(record.claims === undefined ? {} : { claims: record.claims }),
-        ...(record.description === undefined ? {} : { description: record.description }),
     };
+    if (record.claims !== undefined)
+        patent.claims = record.claims;
+    if (record.description !== undefined)
+        patent.description = record.description;
+    return patent;
 }
 /** PatentCore reads a list filter as one comma-separated value, not as a repeated parameter. */
 function commaList(values) {

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

@@ -10,7 +10,7 @@
  */
 import { ResultAsync } from "neverthrow";
 import { z } from "zod";
-export interface ApiFetchOptions {
+export type ApiFetchOptions = {
     method?: "GET" | "POST";
     headers?: Record<string, string>;
     body?: string;
@@ -31,7 +31,7 @@ export interface ApiFetchOptions {
     sleep?: (ms: number) => Promise<void>;
     timeoutMs?: number;
     parseAs?: "json" | "text";
-}
+};
 /** The error channel of `apiFetch`. A `DomainError` (string `type` discriminant). */
 export type ApiError = {
     readonly type: "http_status";
@@ -64,8 +64,18 @@ export declare const HARNESS_USER_AGENT = "inflexa-harness (+https://inflexa.ai)
  * and every wait stays at or below `maxRetryDelayMs`.
  *
  * Each request sends `HARNESS_USER_AGENT`, unless `headers` sets a User-Agent.
+ *
+ * The success value is `unknown`: the caller either walks it with guards, or
+ * validates it with `apiFetchValidated`, or reads text with `apiFetchText`.
+ */
+export declare function apiFetch(url: string, options?: ApiFetchOptions): ResultAsync<unknown, ApiError>;
+/**
+ * `apiFetch` for a `parseAs: "text"` response. The body reader is what makes the
+ * value a string, so the wrapper states that shape instead of casting the
+ * `unknown` read; the check never refuses a body, because `res.text()` always
+ * resolves to one.
  */
-export declare function apiFetch<T = unknown>(url: string, options?: ApiFetchOptions): ResultAsync<T, ApiError>;
+export declare function apiFetchText(url: string, options?: ApiFetchOptions): ResultAsync<string, ApiError>;
 /**
  * `apiFetch` that validates the JSON response against a Zod `schema` before
  * returning it. The success value is the schema's parsed output, so callers

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

@@ -8,6 +8,8 @@
  * `ResultAsync<T, ApiError>` rather than throwing — callers branch on
  * `isErr()` and read `value` / `error` (see `result.ts` for the house rules).
  */
+import { errorMessageOf } from "../../lib/thrown.js";
+import { textOf } from "../../lib/unknown-text.js";
 import { ResultAsync, err, ok } from "neverthrow";
 import { z } from "zod";
 import { sleep } from "../../lib/async-utils.js";
@@ -33,10 +35,22 @@ export const HARNESS_USER_AGENT = "inflexa-harness (+https://inflexa.ai)";
  * and every wait stays at or below `maxRetryDelayMs`.
  *
  * Each request sends `HARNESS_USER_AGENT`, unless `headers` sets a User-Agent.
+ *
+ * The success value is `unknown`: the caller either walks it with guards, or
+ * validates it with `apiFetchValidated`, or reads text with `apiFetchText`.
  */
 export function apiFetch(url, options = {}) {
     return new ResultAsync(runFetch(url, options));
 }
+/**
+ * `apiFetch` for a `parseAs: "text"` response. The body reader is what makes the
+ * value a string, so the wrapper states that shape instead of casting the
+ * `unknown` read; the check never refuses a body, because `res.text()` always
+ * resolves to one.
+ */
+export function apiFetchText(url, options = {}) {
+    return apiFetch(url, { ...options, parseAs: "text" }).andThen((data) => typeof data === "string" ? ok(data) : err({ type: "invalid_response", issues: "expected a text body" }));
+}
 /**
  * `apiFetch` that validates the JSON response against a Zod `schema` before
  * returning it. The success value is the schema's parsed output, so callers
@@ -125,14 +139,14 @@ async function runFetch(url, options) {
                 const text = await res.text().catch(() => "");
                 return err({ type: "http_status", status: res.status, body: text.trim() });
             }
-            const data = parseAs === "text" ? (await res.text()) : (await res.json());
-            return ok(data);
+            const readBody = parseAs === "text" ? (res) => res.text() : (res) => res.json();
+            return ok(await readBody(res));
         }
         catch (e) {
             if (e instanceof DOMException && e.name === "TimeoutError") {
                 return err({ type: "timeout", timeoutMs });
             }
-            lastError = e instanceof Error ? e.message : String(e);
+            lastError = errorMessageOf(e) ?? textOf(e);
             if (attempt < maxRetries) {
                 await wait(Math.min(maxRetryDelayMs, retryDelayMs * 2 ** attempt));
                 continue;

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

@@ -15,26 +15,26 @@ export declare const SUPPORTED_SPECIES: readonly ["homo_sapiens", "mus_musculus"
 export type SupportedSpecies = (typeof SUPPORTED_SPECIES)[number];
 export declare const SPECIES_TAXON: Record<SupportedSpecies, number>;
 export type ExpressionRank = "absent" | "low" | "medium" | "high";
-export interface TissueRow {
+export type TissueRow = {
     tissue: string;
     cellType: string | null;
     expressionScore: number | null;
     confidence: "gold" | "silver" | null;
     expressionState: "expressed" | "not expressed";
     rank: ExpressionRank;
-}
-export interface SpeciesEntry {
+};
+export type SpeciesEntry = {
     species: SupportedSpecies;
     taxonId: number;
     ensemblId: string;
     tissues: TissueRow[];
-}
-export interface MultiSpeciesExpression {
+};
+export type MultiSpeciesExpression = {
     geneSymbol: string;
     humanEnsemblId: string | null;
     bySpecies: SpeciesEntry[];
     notFound: string[];
-}
+};
 export declare function bucketRank(expressionState: string, score: number | null): ExpressionRank;
 export declare const EnsemblLookupSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodString>;

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

@@ -11,6 +11,8 @@
  * field carries `.optional()`, not `.nullable()`.
  */
 import { z } from "zod";
+import { isUnknownArray } from "../../lib/unknown-array.js";
+import { parseUnknownRecord } from "../../lib/unknown-containers.js";
 import { apiFetchValidated, describeApiError, isUnexpectedApiError } from "./api-utils.js";
 const ENSEMBL_BASE = "https://rest.ensembl.org";
 const BGEE_BASE = "https://www.bgee.org/api";
@@ -60,28 +62,32 @@ 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) {
-    // `raw` is the untyped Bgee API payload; `.data.calls` is reached defensively and
-    // the `Array.isArray` guard below means a shape mismatch degrades to an empty list.
-    const calls = raw?.data?.calls;
-    if (!Array.isArray(calls))
+    const calls = parseUnknownRecord(parseUnknownRecord(raw)?.data)?.calls;
+    if (!isUnknownArray(calls))
         return [];
     const out = [];
-    for (const call of calls) {
-        const anatName = call?.condition?.anatEntity?.name ?? "";
+    for (const entry of calls) {
+        const call = parseUnknownRecord(entry);
+        if (!call)
+            continue;
+        const condition = parseUnknownRecord(call.condition);
+        const anatEntity = parseUnknownRecord(condition?.anatEntity);
+        const anatName = typeof anatEntity?.name === "string" ? anatEntity.name : "";
         const tissue = anatName.trim().toLowerCase();
         if (!tissue)
             continue;
-        const cellTypeName = call?.condition?.cellType?.name;
+        const cellTypeRecord = parseUnknownRecord(condition?.cellType);
+        const cellTypeName = cellTypeRecord?.name;
         const cellType = typeof cellTypeName === "string" && cellTypeName.trim() !== "" ? cellTypeName.trim().toLowerCase() : null;
-        const rawScore = call?.expressionScore?.expressionScore;
+        const rawScore = parseUnknownRecord(call.expressionScore)?.expressionScore;
         let expressionScore = null;
         if (typeof rawScore === "string" || typeof rawScore === "number") {
             const n = typeof rawScore === "number" ? rawScore : parseFloat(rawScore);
             expressionScore = Number.isFinite(n) ? n : null;
         }
-        const quality = call?.expressionQuality;
+        const quality = call.expressionQuality;
         const confidence = quality === "gold" || quality === "silver" ? quality : null;
-        const stateRaw = call?.expressionState;
+        const stateRaw = call.expressionState;
         const expressionState = stateRaw === "not expressed" ? "not expressed" : "expressed";
         out.push({
             tissue,

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

@@ -11,19 +11,19 @@
  * not `.nullable()`.
  */
 import { z } from "zod";
-export interface CancerStudy {
+export type CancerStudy = {
     studyId: string;
     cancerType: string;
     cancerTypeName: string;
-}
-export interface MutationFrequency {
+};
+export type MutationFrequency = {
     cancerTypeId: string;
     cancerTypeName: string;
     totalSamples: number;
     mutatedSamples: number;
     frequency: number;
     studies: string[];
-}
+};
 export declare const RawMutationRowSchema: z.ZodObject<{
     studyId: z.ZodString;
     sampleId: z.ZodString;

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

@@ -12,6 +12,7 @@
  */
 import { z } from "zod";
 import { apiFetchValidated, describeApiError } from "./api-utils.js";
+import { presentGet } from "../../lib/present.js";
 const CBIOPORTAL_BASE = "https://www.cbioportal.org/api";
 const HEADERS = { Accept: "application/json" };
 // Raw cBioPortal wire shapes, validated at the fetch boundary. Fields the code
@@ -52,7 +53,7 @@ async function listStudies() {
     const res = await apiFetchValidated(url, z.array(RawCancerStudySchema), { headers: HEADERS });
     if (res.isErr())
         throw new Error(describeApiError(res.error));
-    return res.value ?? [];
+    return res.value;
 }
 /**
  * The cancer-type vocabulary, keyed by its id. The study SUMMARY projection
@@ -65,7 +66,7 @@ async function cancerTypeNames() {
     const names = new Map();
     if (res.isErr())
         return names;
-    for (const row of res.value ?? []) {
+    for (const row of res.value) {
         if (row.cancerTypeId && row.name)
             names.set(row.cancerTypeId, row.name);
     }
@@ -76,14 +77,14 @@ async function listAllSampleLists() {
     const res = await apiFetchValidated(url, z.array(RawSampleListSchema), { headers: HEADERS });
     if (res.isErr())
         throw new Error(describeApiError(res.error));
-    return res.value ?? [];
+    return res.value;
 }
 async function listMutationProfiles() {
     const url = `${CBIOPORTAL_BASE}/molecular-profiles?projection=SUMMARY&pageSize=10000`;
     const res = await apiFetchValidated(url, z.array(RawMolecularProfileSchema), { headers: HEADERS });
     if (res.isErr())
         throw new Error(describeApiError(res.error));
-    return (res.value ?? []).filter((p) => p.molecularAlterationType === "MUTATION_EXTENDED");
+    return res.value.filter((p) => p.molecularAlterationType === "MUTATION_EXTENDED");
 }
 async function fetchMutationRowsForGene(entrezGeneId, profileIds) {
     if (profileIds.length === 0)
@@ -99,7 +100,7 @@ async function fetchMutationRowsForGene(entrezGeneId, profileIds) {
     });
     if (res.isErr())
         throw new Error(describeApiError(res.error));
-    return res.value ?? [];
+    return res.value;
 }
 /**
  * Resolve a gene symbol to its NCBI Entrez Gene ID via cBioPortal's gene
@@ -111,7 +112,7 @@ async function resolveEntrezId(symbol) {
     const res = await apiFetchValidated(url, z.object({ entrezGeneId: z.number().optional() }), { headers: HEADERS });
     if (res.isErr())
         return null;
-    return res.value?.entrezGeneId ?? null;
+    return res.value.entrezGeneId ?? null;
 }
 /**
  * Compute somatic mutation frequencies for a target across all curated
@@ -145,7 +146,7 @@ export async function getSomaticMutationFrequencies(geneSymbol, options = {}) {
     for (const m of mutations) {
         if (!mutatedStudySamples.has(m.studyId))
             mutatedStudySamples.set(m.studyId, new Set());
-        mutatedStudySamples.get(m.studyId).add(m.sampleId);
+        presentGet(mutatedStudySamples, m.studyId, "the sample set of the study").add(m.sampleId);
     }
     const byCancerType = new Map();
     for (const studyId of studiesWithMutations) {
@@ -163,7 +164,7 @@ export async function getSomaticMutationFrequencies(geneSymbol, options = {}) {
                 studies: new Set(),
             });
         }
-        const bucket = byCancerType.get(cancerTypeId);
+        const bucket = presentGet(byCancerType, cancerTypeId, "the aggregate bucket");
         bucket.total += sampleCount;
         bucket.mutated += mutatedStudySamples.get(studyId)?.size ?? 0;
         bucket.studies.add(studyId);