@inflexa-ai/harness 0.35.4 → 0.35.6

package/dist/tools/execute-analysis.js

@@ -17,6 +17,7 @@ import { RunDedupCollisionError, insertRun, loadPlan, queryActiveRun, reserveRun
 import { routeAdHocRequest } from "./ad-hoc-router.js";
 import { adHocPlanId, adHocRunId } from "./analysis-invocation.js";
 import { defineTool } from "./define-tool.js";
+import { queryPackages, readInventorySections } from "./sandbox/list-available-packages.js";
 const planIdSchema = z.string().regex(/^pln-[a-f0-9]{8}$/, "planId must be a pln-<8hex> value");
 const inputSchema = z
     .object({
@@ -86,10 +87,15 @@ export class PlanPackagesMissingError extends Error {
  * run reserves anything. The linked set is the union of the queries of each
  * step. A pool miss and a collision refuse the launch with the spellings.
  * Without a bound seam, the pass returns at once.
+ *
+ * @returns How many queries reached the seam. Zero says that nothing was
+ * checked — an unbound seam, or a plan whose steps declare no package — which
+ * is what the launch record must carry to tell a checked launch from an
+ * unchecked one.
  */
 async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
     if (!extendAnalysisFarm)
-        return;
+        return 0;
     // The union dedupes EQUAL queries only: two entries are one ask when their
     // spelling, their track, and their version are equal. A bare entry beside a
     // qualified entry of one spelling stays two asks, because the bare one
@@ -112,7 +118,7 @@ async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
     }
     const queries = [...union.values()];
     if (queries.length === 0)
-        return;
+        return 0;
     let outcomes;
     try {
         outcomes = await extendAnalysisFarm(analysisId, queries);
@@ -154,6 +160,7 @@ async function linkPlanPackages(extendAnalysisFarm, analysisId, plan) {
     if (missing.length > 0 || collisions.length > 0) {
         throw new PlanPackagesMissingError(missing, collisions);
     }
+    return queries.length;
 }
 function planSummary(plan) {
     return plan.title?.trim() || plan.analytical_narrative.trim().slice(0, 280);
@@ -192,8 +199,32 @@ function adHocTitle(request) {
     const compact = request.trim().replace(/\s+/g, " ");
     return compact.length <= 80 ? compact : `${compact.slice(0, 77)}…`;
 }
+/** How a dropped entry reads to the step agent, in the terms of its own reason. */
+const DROP_REASON_TEXT = {
+    unparsable: "does not parse",
+    absent: "the pool does not hold it",
+};
+/**
+ * What the step agent must know about the packages that it did not choose.
+ * The routing guessed them, and no person reviewed that guess, thus a drop and
+ * an empty list are facts the agent needs before its first import.
+ */
+function adHocCaveats(route) {
+    const caveats = [];
+    if (route.fallbackClass)
+        caveats.push(`Automatic routing fallback: ${route.fallbackClass}`);
+    if (route.droppedPackages.length > 0) {
+        const drops = route.droppedPackages.map((drop) => `\`${drop.entry}\` (${DROP_REASON_TEXT[drop.reason]})`).join(", ");
+        caveats.push(`The routing dropped these package entries: ${drops}.`);
+    }
+    if (route.packages.length === 0) {
+        caveats.push("This step declares no packages, thus the pre-launch link pass linked nothing. Confirm that each library you intend to use imports before you rely on it.");
+    }
+    return caveats;
+}
 export function buildAdHocPlan(request, route, createdAt = new Date().toISOString()) {
     const meta = SANDBOX_AGENT_META[route.agentId];
+    const caveats = adHocCaveats(route);
     const plan = {
         title: adHocTitle(request),
         analytical_narrative: `Execute one targeted analysis step for the explicit request: ${request}`,
@@ -215,7 +246,8 @@ export function buildAdHocPlan(request, route, createdAt = new Date().toISOStrin
                     "Persist machine-readable result file(s), even when the answer is a single scalar.",
                     "Provide a direct result summary grounded in the persisted outputs.",
                 ],
-                caveats: route.fallbackClass ? [`Automatic routing fallback: ${route.fallbackClass}`] : undefined,
+                caveats: caveats.length > 0 ? caveats : undefined,
+                packages: [...route.packages],
                 depends_on: [],
                 status: "pending",
                 resources: route.resources,
@@ -226,16 +258,45 @@ export function buildAdHocPlan(request, route, createdAt = new Date().toISOStrin
     };
     return AnalysisPlanSchema.parse(plan);
 }
+/**
+ * The targeted presence check that the router runs over the names it emits,
+ * against the same inventory that `list_available_packages` reads.
+ *
+ * It binds only when the embedder gives an inventory source. The unbound
+ * defaults name a container mountpoint, and a host that mounts nothing there
+ * would pay a file read on every ad hoc launch to learn nothing — while the
+ * router, with no resolution, already keeps every entry that parses.
+ */
+function adHocPackageResolver(deps) {
+    if (!deps.farmLockFile && !deps.imagePackagesFile && !deps.readPoolInventory)
+        return undefined;
+    const inventory = {
+        ...(deps.farmLockFile === undefined ? {} : { farmLockFile: deps.farmLockFile }),
+        ...(deps.imagePackagesFile === undefined ? {} : { imagePackagesFile: deps.imagePackagesFile }),
+        ...(deps.readPoolInventory === undefined ? {} : { readPoolInventory: deps.readPoolInventory }),
+    };
+    return async (names) => {
+        const read = await readInventorySections(inventory);
+        // An inventory that cannot answer must not drop a name: the router
+        // keeps every parsed entry, and the link pass judges at launch.
+        if (read.kind === "unavailable")
+            return null;
+        const answer = queryPackages(read.sections, { names });
+        return "checked" in answer ? answer.checked : null;
+    };
+}
 async function persistedAdHocPlan(deps, args) {
     const existing = unwrapOrThrow(await loadPlan(deps.pool, args.planId, { analysisId: args.analysisId }));
     if (existing)
         return validateStoredPlan(existing, args.planId);
+    const resolvePackages = adHocPackageResolver(deps);
     const route = await routeAdHocRequest({
         provider: deps.utilityProvider,
         model: deps.utilityModel,
         pool: deps.pool,
         resourcePolicy: deps.resourcePolicy,
         logger: deps.logger,
+        ...(resolvePackages ? { resolvePackages } : {}),
     }, { analysisId: args.analysisId, request: args.request, session: args.ctx.session, signal: args.ctx.signal });
     const candidate = buildAdHocPlan(args.request, route);
     unwrapOrThrow(await upsertPlan(deps.pool, { planId: args.planId, analysisId: args.analysisId, plan: candidate }));
@@ -286,7 +347,7 @@ export function createExecuteAnalysisTool(deps) {
             }
             // The link pass comes before the run reserves anything, thus a pool
             // miss leaves no run row and no revoked authorization behind.
-            await linkPlanPackages(deps.extendAnalysisFarm, analysisId, plan);
+            const packageQueries = await linkPlanPackages(deps.extendAnalysisFarm, analysisId, plan);
             const runId = input.mode === "plan" ? randomUUID() : adHocRunId(analysisId, ctx.invocationId);
             if (input.mode === "plan") {
                 try {
@@ -351,7 +412,7 @@ export function createExecuteAnalysisTool(deps) {
                 await updateRunStatus(deps.pool, runId, "failed", "workflow start failed").match(() => { }, () => { });
                 throw error;
             }
-            logger.info("analysis launched", { analysisId, runId, planId, mode: input.mode });
+            logger.info("analysis launched", { analysisId, runId, planId, mode: input.mode, packageQueries });
             await emitRunCard(runId);
             return ok({ runId, status: "in_progress" });
         },

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

@@ -0,0 +1,55 @@
+/**
+ * Pure async client functions for the AlphaFold Protein Structure Database
+ * (AlphaFold DB) prediction API. Keyless and public: one unauthenticated GET,
+ * keyed by a UniProt accession.
+ *
+ * Absence policy: AlphaFold DB omits the key of an absent value — the
+ * AlphaMissense annotation URLs (`amAnnotationsUrl` and its two genome-build
+ * siblings) ride on the AlphaMissense proteome-wide predictions, which cover
+ * the human proteome only. A canonical accession of a different organism
+ * carries no such URL, and neither does an isoform entry of any organism —
+ * thus a maybe-absent field carries `.optional()`, not `.nullable()`.
+ *
+ * Not-found semantics: AlphaFold splits absence over two status codes. An
+ * identifier that does not parse as a UniProt accession or an AlphaFold DB id
+ * gives 400 with an `Invalid identifier format` body. A well-formed accession
+ * that AlphaFold holds no model for gives 404 with an empty object. Both are
+ * the same outcome for a caller, and `isUnexpectedApiError` classifies each
+ * `http_status` in the 4xx range as expected, thus one branch answers both.
+ */
+import { z } from "zod";
+/**
+ * One entry of the AlphaFold DB prediction array. A query by a canonical
+ * accession can answer with more than one entry — one per UniProt isoform —
+ * thus the schema is `z.array(...)` and the client selects the entry that
+ * matches the queried accession.
+ */
+export declare const AlphaFoldPredictionSchema: z.ZodObject<{
+    uniprotAccession: z.ZodString;
+    uniprotDescription: z.ZodString;
+    latestVersion: z.ZodNumber;
+    modelCreatedDate: z.ZodString;
+    globalMetricValue: z.ZodNumber;
+    fractionPlddtVeryLow: z.ZodNumber;
+    fractionPlddtLow: z.ZodNumber;
+    fractionPlddtConfident: z.ZodNumber;
+    fractionPlddtVeryHigh: z.ZodNumber;
+    pdbUrl: z.ZodURL;
+    cifUrl: z.ZodURL;
+    paeImageUrl: z.ZodURL;
+    plddtDocUrl: z.ZodURL;
+    paeDocUrl: z.ZodURL;
+    amAnnotationsUrl: z.ZodOptional<z.ZodURL>;
+}, z.core.$strip>;
+export type AlphaFoldPrediction = z.infer<typeof AlphaFoldPredictionSchema>;
+/**
+ * Fetch the AlphaFold structure prediction for one UniProt accession.
+ *
+ * Gives `null` when AlphaFold holds no model for the accession, and `null` for
+ * an identifier it cannot parse. When the array holds more than one entry —
+ * the isoforms of one canonical accession — the entry whose own
+ * `uniprotAccession` matches the queried accession wins. A query that names no
+ * exact isoform falls back to the first entry, which AlphaFold orders
+ * canonical-first.
+ */
+export declare function fetchAlphaFoldPrediction(uniprotAccession: string): Promise<AlphaFoldPrediction | null>;

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

@@ -0,0 +1,72 @@
+/**
+ * Pure async client functions for the AlphaFold Protein Structure Database
+ * (AlphaFold DB) prediction API. Keyless and public: one unauthenticated GET,
+ * keyed by a UniProt accession.
+ *
+ * Absence policy: AlphaFold DB omits the key of an absent value — the
+ * AlphaMissense annotation URLs (`amAnnotationsUrl` and its two genome-build
+ * siblings) ride on the AlphaMissense proteome-wide predictions, which cover
+ * the human proteome only. A canonical accession of a different organism
+ * carries no such URL, and neither does an isoform entry of any organism —
+ * thus a maybe-absent field carries `.optional()`, not `.nullable()`.
+ *
+ * Not-found semantics: AlphaFold splits absence over two status codes. An
+ * identifier that does not parse as a UniProt accession or an AlphaFold DB id
+ * gives 400 with an `Invalid identifier format` body. A well-formed accession
+ * that AlphaFold holds no model for gives 404 with an empty object. Both are
+ * the same outcome for a caller, and `isUnexpectedApiError` classifies each
+ * `http_status` in the 4xx range as expected, thus one branch answers both.
+ */
+import { z } from "zod";
+import { apiFetchValidated, describeApiError, isUnexpectedApiError } from "./api-utils.js";
+const ALPHAFOLD_BASE = "https://alphafold.ebi.ac.uk/api/prediction";
+/**
+ * One entry of the AlphaFold DB prediction array. A query by a canonical
+ * accession can answer with more than one entry — one per UniProt isoform —
+ * thus the schema is `z.array(...)` and the client selects the entry that
+ * matches the queried accession.
+ */
+export const AlphaFoldPredictionSchema = z.object({
+    uniprotAccession: z.string(),
+    uniprotDescription: z.string(),
+    latestVersion: z.number(),
+    modelCreatedDate: z.string(),
+    globalMetricValue: z.number(),
+    fractionPlddtVeryLow: z.number(),
+    fractionPlddtLow: z.number(),
+    fractionPlddtConfident: z.number(),
+    fractionPlddtVeryHigh: z.number(),
+    pdbUrl: z.url(),
+    cifUrl: z.url(),
+    paeImageUrl: z.url(),
+    // The per-residue confidence document. `globalMetricValue` and the
+    // `fractionPlddt*` fractions describe the whole chain, thus this URL is the
+    // only field that tells a caller *which* residues are disordered.
+    plddtDocUrl: z.url(),
+    paeDocUrl: z.url(),
+    amAnnotationsUrl: z.url().optional(),
+});
+/**
+ * Fetch the AlphaFold structure prediction for one UniProt accession.
+ *
+ * Gives `null` when AlphaFold holds no model for the accession, and `null` for
+ * an identifier it cannot parse. When the array holds more than one entry —
+ * the isoforms of one canonical accession — the entry whose own
+ * `uniprotAccession` matches the queried accession wins. A query that names no
+ * exact isoform falls back to the first entry, which AlphaFold orders
+ * canonical-first.
+ */
+export async function fetchAlphaFoldPrediction(uniprotAccession) {
+    const accession = uniprotAccession.trim();
+    const res = await apiFetchValidated(`${ALPHAFOLD_BASE}/${encodeURIComponent(accession)}`, z.array(AlphaFoldPredictionSchema));
+    if (res.isErr()) {
+        if (isUnexpectedApiError(res.error))
+            throw new Error(describeApiError(res.error));
+        return null;
+    }
+    const entries = res.value;
+    if (entries.length === 0)
+        return null;
+    const exact = entries.find((entry) => entry.uniprotAccession.toUpperCase() === accession.toUpperCase());
+    return exact ?? entries[0];
+}

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

@@ -16,6 +16,19 @@ export interface ApiFetchOptions {
     body?: string;
     maxRetries?: number;
     retryDelayMs?: number;
+    /**
+     * Ceiling on any single retry wait, the value a server asks for through
+     * `Retry-After` included. The default is finite because this wait is not
+     * cancelable and these calls run inside a DBOS step, thus an unbounded
+     * `Retry-After: 3600` would park that step for an hour.
+     */
+    maxRetryDelayMs?: number;
+    /**
+     * Seam for the wait between two attempts. A test binds a function that
+     * records the wait and returns at once, thus it asserts the computed delay
+     * without real time.
+     */
+    sleep?: (ms: number) => Promise<void>;
     timeoutMs?: number;
     parseAs?: "json" | "text";
 }
@@ -40,6 +53,14 @@ export type ApiError = {
  * `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`).
+ *
+ * A retryable status that outlives the retries is the exception: it resolves to
+ * `exhausted`, whose `lastError` is `HTTP <status>`. A throttled or a restarting
+ * upstream is not the answer "the resource is not there", thus it must not reach
+ * a caller as a 4xx that `isUnexpectedApiError` reads as an expected absence.
+ *
+ * Between two attempts the wait obeys `Retry-After` when the response carries it,
+ * and every wait stays at or below `maxRetryDelayMs`.
  */
 export declare function apiFetch<T = unknown>(url: string, options?: ApiFetchOptions): ResultAsync<T, ApiError>;
 /**
@@ -72,6 +93,10 @@ export declare function describeApiError(e: ApiError): string;
  * timeout, retry exhaustion, a transport failure, or a schema mismatch
  * (`invalid_response`) — is unexpected and the caller should surface it by
  * throwing (or returning `err`).
+ *
+ * A retryable status that outlived the retries never arrives as `http_status`.
+ * `apiFetch` gives it as `exhausted`, thus a spent 429 reads as unexpected here
+ * and no call site turns a throttle into an absence.
  */
 export declare function isUnexpectedApiError(e: ApiError): boolean;
 /**

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

@@ -20,6 +20,14 @@ const RETRYABLE_STATUSES = new Set([429, 502, 503, 504]);
  * `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`).
+ *
+ * A retryable status that outlives the retries is the exception: it resolves to
+ * `exhausted`, whose `lastError` is `HTTP <status>`. A throttled or a restarting
+ * upstream is not the answer "the resource is not there", thus it must not reach
+ * a caller as a 4xx that `isUnexpectedApiError` reads as an expected absence.
+ *
+ * Between two attempts the wait obeys `Retry-After` when the response carries it,
+ * and every wait stays at or below `maxRetryDelayMs`.
  */
 export function apiFetch(url, options = {}) {
     return new ResultAsync(runFetch(url, options));
@@ -59,8 +67,31 @@ function summarizeZodIssues(error) {
     const remaining = error.issues.length - issues.length;
     return remaining > 0 ? `${issues.join("; ")} (+${remaining} more)` : issues.join("; ");
 }
+/**
+ * The wait that a server asks for through `Retry-After`, in milliseconds.
+ *
+ * The header carries a count of seconds or an HTTP date, and a date that already
+ * passed clamps to zero. Any other value — a negative count, text that is neither
+ * form — counts as absent, thus the backoff governs. The literature HTTP layer
+ * parses the same header (`literature/sources/http.ts`), and the two copies stay
+ * separate because that module carries its own schedule, signal, and result type.
+ */
+function retryAfterMilliseconds(res) {
+    const value = res.headers.get("retry-after")?.trim();
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    // A numeric value settles the header, and a negative count is absent rather
+    // than a date. `Date.parse` is lenient enough to read "-5" as a calendar date
+    // in the past, which would clamp to a wait of zero and retry at once against
+    // an upstream that is already throttling.
+    if (Number.isFinite(seconds))
+        return seconds >= 0 ? seconds * 1000 : undefined;
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : undefined;
+}
 async function runFetch(url, options) {
-    const { method = "GET", headers = {}, body, maxRetries = 3, retryDelayMs = 1000, timeoutMs = 90_000, parseAs = "json" } = options;
+    const { method = "GET", headers = {}, body, maxRetries = 3, retryDelayMs = 1000, maxRetryDelayMs = 30_000, sleep: wait = sleep, timeoutMs = 90_000, parseAs = "json", } = options;
     let lastError = "";
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         try {
@@ -71,10 +102,17 @@ async function runFetch(url, options) {
                 signal: AbortSignal.timeout(timeoutMs),
             });
             if (RETRYABLE_STATUSES.has(res.status) && attempt < maxRetries) {
-                await sleep(retryDelayMs * 2 ** attempt);
                 lastError = `HTTP ${res.status}`;
+                await wait(Math.min(maxRetryDelayMs, retryAfterMilliseconds(res) ?? retryDelayMs * 2 ** attempt));
                 continue;
             }
+            // The branch above consumed every attempt that still has a retry, thus a
+            // retryable status here has spent them all. The status comes from this
+            // response and not from `lastError`, because an earlier attempt that failed
+            // with a connection error would otherwise name that instead of the throttle.
+            if (RETRYABLE_STATUSES.has(res.status)) {
+                return err({ type: "exhausted", attempts: attempt + 1, lastError: `HTTP ${res.status}` });
+            }
             if (!res.ok) {
                 const text = await res.text().catch(() => "");
                 return err({ type: "http_status", status: res.status, body: text.trim() });
@@ -88,7 +126,7 @@ async function runFetch(url, options) {
             }
             lastError = e instanceof Error ? e.message : String(e);
             if (attempt < maxRetries) {
-                await sleep(retryDelayMs * 2 ** attempt);
+                await wait(Math.min(maxRetryDelayMs, retryDelayMs * 2 ** attempt));
                 continue;
             }
         }
@@ -117,6 +155,10 @@ export function describeApiError(e) {
  * timeout, retry exhaustion, a transport failure, or a schema mismatch
  * (`invalid_response`) — is unexpected and the caller should surface it by
  * throwing (or returning `err`).
+ *
+ * A retryable status that outlived the retries never arrives as `http_status`.
+ * `apiFetch` gives it as `exhausted`, thus a spent 429 reads as unexpected here
+ * and no call site turns a throttle into an absence.
  */
 export function isUnexpectedApiError(e) {
     return !(e.type === "http_status" && e.status >= 400 && e.status < 500);

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

@@ -13,6 +13,7 @@
  * and the API omits the key of an absent value. Thus a maybe-absent field
  * carries `.optional()`, not `.nullable()`.
  */
+import { z } from "zod";
 export interface UniProtRecord {
     primaryAccession: string;
     uniProtkbId: string | null;
@@ -30,3 +31,133 @@ export declare function getUniProtRecord(accession: string): Promise<UniProtReco
 export declare function getChemblIdsByUniProt(accession: string): Promise<string[]>;
 /** All Reactome pathway ids cross-referenced from a UniProt accession. */
 export declare function getReactomePathwaysByUniProt(accession: string): Promise<string[]>;
+/** One protein of a UniProtKB search. */
+export interface UniProtProtein {
+    accession: string;
+    /** The UniProtKB ID, for example `BRCA1_HUMAN`. */
+    uniProtkbId: string | null;
+    proteinName: string | null;
+    geneNames: string[];
+    sequenceLength: number | null;
+    /** The curated FUNCTION comment, trimmed to a readable length. */
+    function: string | null;
+    /** The distinct curated subcellular locations, in the order UniProt lists them. */
+    subcellularLocations: string[];
+    /** True for a Swiss-Prot entry, false for a TrEMBL entry. */
+    reviewed: boolean;
+}
+/**
+ * One result row of `uniprotkb/search`, with the same all-optional discipline as
+ * `UniProtRecordSchema`: UniProt omits the key of an absent value, thus every
+ * field carries `.optional()` and none carries `.nullable()`.
+ *
+ * A TrEMBL row can carry `submissionNames` in place of `recommendedName`
+ * (`X5D778` is one), thus the name reader falls back rather than reporting the
+ * protein as unnamed.
+ */
+export declare const UniProtSearchResultSchema: z.ZodObject<{
+    primaryAccession: z.ZodOptional<z.ZodString>;
+    uniProtkbId: z.ZodOptional<z.ZodString>;
+    entryType: z.ZodOptional<z.ZodString>;
+    proteinDescription: z.ZodOptional<z.ZodObject<{
+        recommendedName: z.ZodOptional<z.ZodObject<{
+            fullName: z.ZodOptional<z.ZodObject<{
+                value: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        submissionNames: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            fullName: z.ZodOptional<z.ZodObject<{
+                value: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    genes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        geneName: z.ZodOptional<z.ZodObject<{
+            value: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>>;
+    sequence: z.ZodOptional<z.ZodObject<{
+        length: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    comments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        commentType: z.ZodOptional<z.ZodString>;
+        texts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            value: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        subcellularLocations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            location: z.ZodOptional<z.ZodObject<{
+                value: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/** The search envelope. It is exported so that the golden-fixture table drives it. */
+export declare const UniProtSearchResponseSchema: z.ZodObject<{
+    results: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        primaryAccession: z.ZodOptional<z.ZodString>;
+        uniProtkbId: z.ZodOptional<z.ZodString>;
+        entryType: z.ZodOptional<z.ZodString>;
+        proteinDescription: z.ZodOptional<z.ZodObject<{
+            recommendedName: z.ZodOptional<z.ZodObject<{
+                fullName: z.ZodOptional<z.ZodObject<{
+                    value: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            submissionNames: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                fullName: z.ZodOptional<z.ZodObject<{
+                    value: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>;
+        genes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            geneName: z.ZodOptional<z.ZodObject<{
+                value: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+        sequence: z.ZodOptional<z.ZodObject<{
+            length: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        comments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            commentType: z.ZodOptional<z.ZodString>;
+            texts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                value: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            subcellularLocations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                location: z.ZodOptional<z.ZodObject<{
+                    value: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+/**
+ * Can the query ride in an `accession:` clause?
+ *
+ * UniProt validates the value of that clause, and it answers HTTP 400 for a
+ * value that is not accession-shaped. Thus a plain symbol such as `BRCA1` must
+ * never reach one, because the 400 fails the whole request.
+ */
+export declare function isUniProtAccession(query: string): boolean;
+export interface SearchProteinsOptions {
+    /** NCBI taxonomy id; omit to search every organism. */
+    organismId?: number;
+    /** Swiss-Prot only when true (the default), Swiss-Prot and TrEMBL when false. */
+    reviewedOnly?: boolean;
+    /** Max rows returned. */
+    limit?: number;
+}
+export interface SearchProteinsResult {
+    proteins: UniProtProtein[];
+    /** True when UniProt held at least one row beyond `limit`. */
+    hasMore: boolean;
+}
+/**
+ * Search UniProtKB for a protein by gene symbol or by accession.
+ *
+ * An unknown query is HTTP 200 with `{"results":[]}`, never a 404, thus the
+ * empty result is an ordinary answer and never an error. The request asks for
+ * one row beyond `limit`, because UniProt reports its match count in the
+ * `x-total-results` header and `apiFetch` exposes no header. The extra row is
+ * what separates a trimmed answer from a complete one.
+ */
+export declare function searchProteins(query: string, opts?: SearchProteinsOptions): Promise<SearchProteinsResult>;