@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/tools/knowledge/template.js

@@ -0,0 +1,273 @@
+/**
+ * `knowledge_template` — the model emits slot values, and the tool writes the
+ * rendered script and the decision record into the step workspace through
+ * the same `WorkspaceMutator` as `write_file`. The script is never output tokens.
+ *
+ * The installed versions ride from the tool, not from the model: the tool
+ * reads the `inflexa.lock` of the farm and the `image-packages.json` of the
+ * store when the host names them (`installedPackages`), and the service
+ * answers with the environment match, which the decision record keeps.
+ *
+ * The plan settings ride from the host, not from the model: the step input
+ * carries a `TemplateBinding` when the plan step grounds on a template, and
+ * the tool merges the bound slots under the model values. A model value that
+ * differs from a bound value is refused before the service call unless an
+ * `overrides` entry names the slot with a reason, and the decision record
+ * keeps the bound slots and the overrides beside the script path.
+ *
+ * The facts of the machine never ride at all: a local slot of the template
+ * (a path, a column name, a level label, a design formula) is split off the
+ * request, the service renders it as its marker, and the tool binds the
+ * value on the machine before it writes the file. The request carries the
+ * step, its claims, and the release digest the plan pinned, thus the record
+ * binds the cited decision to the bytes, and a service on another release
+ * refuses the render instead of moving the plan in silence. The call runs as
+ * one durable step, thus a replay returns the cached result and renders
+ * 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)) {
+        return Array.isArray(value) && value.length === bound.length && bound.every((item, index) => item === value[index]);
+    }
+    return bound === value;
+}
+/** The source of a bound slot as the issue names it. A binding without a source for the slot reads as the plan. */
+function sourceOf(binding, slot) {
+    return binding.sources[slot] ?? "plan";
+}
+/**
+ * The refusal of a render request against the binding, or `undefined` when
+ * the request obeys it. A different template reference is one issue on the
+ * field `template`. Each bound slot whose model value differs without an
+ * override is one issue that names the slot, the bound value, and its source.
+ */
+function refusedByBinding(binding, template, slots, overridden) {
+    if (template !== binding.template) {
+        const message = `the plan binds the template ${binding.template}; this step renders that reference only`;
+        return { match: "rejected", message, issues: [{ field: "template", message, permitted: [binding.template] }] };
+    }
+    const issues = [];
+    for (const [slot, bound] of Object.entries(binding.slots)) {
+        const value = slots[slot];
+        if (value === undefined || sameValue(bound, value) || overridden.has(slot))
+            continue;
+        const shown = JSON.stringify(bound);
+        issues.push({
+            slot,
+            reason: "bound by the plan",
+            message: `the plan binds ${slot} = ${shown} (${sourceOf(binding, slot)}); send that value, or name the slot in overrides with the reason for the change`,
+            permitted: [shown],
+        });
+    }
+    if (issues.length === 0)
+        return undefined;
+    return { match: "rejected", message: "one or more slot values differ from the plan settings without an override", issues };
+}
+/** A contract answer that is a refusal. The contract itself is a loose object, thus `in` alone cannot tell the two apart. */
+function isContractRefusal(answer) {
+    return "match" in answer && (answer.match === "unavailable" || answer.match === "rejected");
+}
+/** The slots of `slots` whose names are in `names`, and the rest, as two records. */
+function splitSlots(slots, names) {
+    const local = {};
+    const remote = {};
+    for (const [name, value] of Object.entries(slots))
+        (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",
+        description: "Render a tested analysis script from a knowledge template and write it into your working directory. " +
+            "Use it for a step whose briefing names a template in its Grounding (for example `tpl-deseq2-two-group@1.0.0`). " +
+            "The briefing lists the slots of the template and the values the plan binds. " +
+            "Send the template id and the slot values only: the file paths of your inputs (absolute `/<analysisId>/...` paths), the column names, the levels of the contrast, and the design. " +
+            "A slot the briefing marks local (a path, a column name, a level, a formula) is bound on this machine and never sent to the service; send it as any other slot. " +
+            "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 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: 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) => {
+            const binding = deps.binding;
+            const reasons = new Map((overrides ?? []).map((entry) => [entry.slot, entry.reason]));
+            if (binding) {
+                const refused = refusedByBinding(binding, template, slots, new Set(reasons.keys()));
+                if (refused)
+                    return ok(refused);
+            }
+            // The local slots and the adaptable names come from the binding the host composed at dispatch, else from
+            // the contract itself. Without them no free-text value can be told from a fact of the machine, and an
+            // unknown name could carry one, thus no render happens without them.
+            let locals;
+            let adaptable;
+            if (binding?.local && binding.adaptable) {
+                locals = binding.local;
+                adaptable = binding.adaptable;
+            }
+            else {
+                const contract = await deps.client.contract(template);
+                if (isContractRefusal(contract))
+                    return ok(contract);
+                locals = localParameters(contract.parameters);
+                adaptable = contract.parameters.filter((parameter) => parameter.adaptable).map((parameter) => parameter.name);
+            }
+            const unknown = Object.keys(slots).filter((name) => !adaptable.includes(name));
+            if (unknown.length > 0) {
+                return ok({
+                    match: "rejected",
+                    message: "one or more slot names are not adaptable slots of this template",
+                    issues: unknown.map((slot) => ({ slot, reason: "the template has no such adaptable slot", permitted: [...adaptable] })),
+                });
+            }
+            const localNames = new Set(locals.map((parameter) => parameter.name));
+            const split = splitSlots(slots, localNames);
+            const boundSplit = splitSlots(binding?.slots ?? {}, localNames);
+            const merged = { ...boundSplit.remote, ...split.remote };
+            // A bound local slot is bound on the machine like a model value, under the model value.
+            const localValues = { ...boundSplit.local, ...split.local };
+            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(presentGet(localByName, name, "the template parameter of the local value"), value);
+                return issue ? [issue] : [];
+            });
+            if (localIssues.length > 0) {
+                return ok({ match: "rejected", message: "one or more local slot values are not valid for this template", issues: localIssues });
+            }
+            const farmLockFile = typeof deps.farmLockFile === "function" ? deps.farmLockFile(ctx.session.scope.analysisId) : deps.farmLockFile;
+            const installed = installedPackages({
+                farmLockFile,
+                imagePackagesFile: deps.imagePackagesFile,
+            });
+            const answer = await deps.client.render(template, merged, installed.packages, {
+                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))
+                return ok(answer);
+            const bound = bindLocalSlots({ language: answer.template.language, parameters: locals }, answer.script, localValues, answer.slots);
+            if (!bound.ok) {
+                return ok({ match: "rejected", message: "one or more local slot values are not valid for this template", issues: bound.issues });
+            }
+            const scriptFile = script_name ?? `${answer.template.id}.${answer.template.language === "R" ? "R" : "py"}`;
+            const scriptPath = `scripts/${scriptFile}`;
+            // Each landed write rides the call record, also when a later write is refused.
+            const records = [];
+            const write = async (path, content) => {
+                const outcome = await deps.mutator.writeFile({
+                    path,
+                    content,
+                    toolName: "knowledge_template",
+                    invocationId: ctx.invocationId,
+                    session: ctx.session,
+                });
+                if (outcome.status === "ok")
+                    records.push(outcome.record);
+                return outcome;
+            };
+            const scriptWrite = await write(scriptPath, bound.script);
+            if (scriptWrite.status !== "ok")
+                return ok({ status: "write_refused", path: scriptWrite.path, reason: scriptWrite.status });
+            const boundSlots = Object.entries(binding?.slots ?? {}).map(([slot, value]) => ({
+                slot,
+                value,
+                source: binding ? sourceOf(binding, slot) : "plan",
+            }));
+            const settingsOverrides = boundSlots.flatMap(({ slot, value }) => {
+                const reason = reasons.get(slot);
+                const sent = slots[slot];
+                if (reason === undefined || sent === undefined || sameValue(value, sent))
+                    return [];
+                return [{ slot, plan_value: value, new_value: sent, reason }];
+            });
+            // The slot report of the record: the service entries, with each local marker entry replaced by the slot as
+            // bound here. An optional local slot with no value has no entry, as in a full render.
+            const boundByName = new Map(bound.slots.map((slot) => [slot.name, slot]));
+            const reportedSlots = answer.slots.flatMap((slot) => {
+                if (slot.source !== "local")
+                    return [slot];
+                const local = boundByName.get(slot.name);
+                return local ? [local] : [];
+            });
+            const record = {
+                ...answer.decision_record,
+                slots: reportedSlots,
+                script_path: scriptWrite.path,
+                written_sha256: scriptSha256(bound.script),
+                bound_slots: boundSlots,
+                settings_overrides: settingsOverrides,
+            };
+            const recordWrite = await write(decisionRecordPath(scriptFile), `${JSON.stringify(record, null, 2)}\n`);
+            if (recordWrite.status !== "ok") {
+                return ok(withToolCallRecord({ status: "write_refused", path: recordWrite.path, reason: recordWrite.status }, records));
+            }
+            return ok(withToolCallRecord({
+                status: "ok",
+                script_path: scriptWrite.path,
+                decision_record_path: recordWrite.path,
+                template: {
+                    id: answer.template.id,
+                    version: answer.template.version,
+                    label: answer.template.label,
+                    method: { id: answer.template.method.id, label: answer.template.method.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,
+                local_slots: bound.slots.map((slot) => slot.name),
+                written_sha256: record.written_sha256,
+                environment_match: answer.environment.match,
+                syntax: answer.syntax.status,
+                expected_outputs: answer.outputs,
+                run_with: `${answer.template.language === "R" ? "Rscript" : "python3"} ${scriptPath}`,
+            }, records));
+        },
+        foldCallRecord: (records) => {
+            for (const record of records)
+                deps.mutator.recordWrite(record);
+        },
+    });
+}

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