@inflexa-ai/harness 0.17.0 → 0.19.0

package/dist/state/report-versions.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The report version store -- the append-only record of report versions.
+ *
+ * A version is one immutable row. It holds the block document, the pinned
+ * snapshot, and the anchor. The store records a version and reads a version. It
+ * never updates a recorded row, thus a correction is a new version.
+ *
+ * A thread holds at most one version, and a named unique constraint on the thread
+ * id enforces it. The record reads nothing before the insert. A second record for
+ * one thread trips the constraint, and the store maps that trip to the typed
+ * refusal thread_already_holds_version.
+ *
+ * The store keeps the snapshot and the anchor as given, and it never pins a
+ * snapshot. A read parses the stored document and the stored snapshot with the
+ * current schemas. A row that fails a parse reads as a typed error, and it does
+ * not crash. An absent row reads as a normal absence.
+ *
+ * A version outlives its thread. The anchor columns sit on the row, thus a
+ * deleted thread leaves a recorded version in place. Only a purge of the analysis
+ * removes the version, through the analysis-id cascade.
+ */
+import { type ResultAsync } from "neverthrow";
+import type { Pool } from "pg";
+import { type ReportDocument } from "../contracts/report-blocks.js";
+import { type DbError } from "../lib/db-result.js";
+import type { Logger } from "../lib/logger.js";
+import type { ReportSnapshot } from "../report-model/reference-resolver.js";
+import { type SchemaIssue } from "./snapshot-parse.js";
+export type { SchemaIssue };
+/** The anchor and the payload of a version to record. */
+export interface RecordVersionInput {
+    /** The block document. It rides as `unknown`, and the record parses it. */
+    readonly document: unknown;
+    /** The pinned snapshot, stored as given. */
+    readonly snapshot: ReportSnapshot;
+    readonly analysisId: string;
+    readonly threadId: string;
+    /** The parent conversation thread of the anchor, or `null` when a root has none. */
+    readonly parentThreadId: string | null;
+    /** The parent transcript position of the anchor, or `null` beside a null parent thread. */
+    readonly parentSeq: number | null;
+    /** The earlier version that this one reuses. The parent must belong to the same analysis. */
+    readonly parentVersionId?: string;
+}
+/** The stable reference of a freshly recorded version. */
+export interface RecordedVersionRef {
+    readonly versionId: string;
+}
+/**
+ * A record the store refuses as data, before or in place of a row. Distinct from
+ * `DbError`: the request describes a version that the store will not write.
+ *
+ * The store parses the document and the snapshot before any row. The store
+ * refuses a malformed document or a malformed snapshot here as typed data, and
+ * no row lands.
+ *
+ * A second record for one thread is `thread_already_holds_version`. The unique
+ * constraint on the thread id trips, and the record maps that one constraint by
+ * its name. Every other constraint trip stays a `DbError`.
+ *
+ * A `parentVersionId` naming no row is not one of these -- the self foreign key
+ * refuses an unknown parent id, and `tryMutation` classifies that refusal as the
+ * `constraint_violation` variant of `DbError`.
+ */
+export type RecordVersionError = {
+    readonly type: "malformed_document";
+    readonly op: string;
+    readonly issues: readonly SchemaIssue[];
+} | {
+    readonly type: "malformed_snapshot";
+    readonly op: string;
+    readonly issues: readonly SchemaIssue[];
+} | {
+    readonly type: "parent_analysis_mismatch";
+    readonly op: string;
+    readonly analysisId: string;
+    readonly parentVersionId: string;
+    readonly parentAnalysisId: string;
+} | {
+    readonly type: "thread_already_holds_version";
+    readonly op: string;
+    readonly threadId: string;
+} | DbError;
+/**
+ * A stored row that a read cannot parse with the current schemas. It names the
+ * version id and the part that failed, and it carries the reduced issues.
+ */
+export type VersionReadError = {
+    readonly type: "corrupt_version";
+    readonly op: string;
+    readonly versionId: string;
+    readonly part: "document" | "snapshot";
+    readonly issues: readonly SchemaIssue[];
+};
+/** One recorded version, as the store gives it back. */
+export interface RecordedVersion {
+    readonly versionId: string;
+    readonly analysisId: string;
+    readonly threadId: string;
+    readonly parentThreadId: string | null;
+    readonly parentSeq: number | null;
+    /** The earlier version that this one reuses, or `null` when it has none. */
+    readonly parentVersionId: string | null;
+    readonly document: ReportDocument;
+    readonly snapshot: ReportSnapshot;
+    readonly createdAt: Date;
+}
+export interface ReportVersionStore {
+    /**
+     * Record a version. The record parses the document, refuses a malformed value
+     * as data with no row, and refuses a parent from a different analysis. It reads
+     * nothing before the insert. A second record for one thread refuses with
+     * thread_already_holds_version. The snapshot and the anchor store as given.
+     */
+    record(input: RecordVersionInput): ResultAsync<RecordedVersionRef, RecordVersionError>;
+    /** One version by its id, or `null` when no row holds it. */
+    getVersion(versionId: string): ResultAsync<RecordedVersion | null, DbError | VersionReadError>;
+    /** The one version of a thread, or `null` for a thread with no version. */
+    getThreadVersion(threadId: string): ResultAsync<RecordedVersion | null, DbError | VersionReadError>;
+}
+export interface ReportVersionStoreDeps {
+    readonly pool: Pool;
+    readonly logger?: Logger;
+}
+/**
+ * Create a `ReportVersionStore` bound to a Postgres pool. The
+ * `cortex_report_versions` table is provisioned by the state-init DDL.
+ */
+export declare function createReportVersionStore({ pool }: ReportVersionStoreDeps): ReportVersionStore;

package/dist/state/report-versions.js

@@ -0,0 +1,167 @@
+/**
+ * The report version store -- the append-only record of report versions.
+ *
+ * A version is one immutable row. It holds the block document, the pinned
+ * snapshot, and the anchor. The store records a version and reads a version. It
+ * never updates a recorded row, thus a correction is a new version.
+ *
+ * A thread holds at most one version, and a named unique constraint on the thread
+ * id enforces it. The record reads nothing before the insert. A second record for
+ * one thread trips the constraint, and the store maps that trip to the typed
+ * refusal thread_already_holds_version.
+ *
+ * The store keeps the snapshot and the anchor as given, and it never pins a
+ * snapshot. A read parses the stored document and the stored snapshot with the
+ * current schemas. A row that fails a parse reads as a typed error, and it does
+ * not crash. An absent row reads as a normal absence.
+ *
+ * A version outlives its thread. The anchor columns sit on the row, thus a
+ * deleted thread leaves a recorded version in place. Only a purge of the analysis
+ * removes the version, through the analysis-id cascade.
+ */
+import { randomUUID } from "node:crypto";
+import { err, errAsync, ok } from "neverthrow";
+import { ReportDocumentSchema } from "../contracts/report-blocks.js";
+import { tryMutation, tryQuery } from "../lib/db-result.js";
+import { parseSnapshot, reduceIssues } from "./snapshot-parse.js";
+/**
+ * The name of the unique constraint on thread_id. Postgres reports it on a
+ * duplicate-thread refusal, and the record matches it to map the trip to the
+ * thread_already_holds_version refusal.
+ */
+const THREAD_UNIQUE_CONSTRAINT = "cortex_report_versions_one_per_thread";
+const _assertRecordError = true;
+const _assertReadError = true;
+/**
+ * The full row projection every read shares. `parent_seq` is a bigint, thus the
+ * driver hands it back as text, and `rowToVersion` is the single place that turns
+ * it into a number.
+ */
+const VERSION_COLUMNS = "version_id, analysis_id, thread_id, parent_thread_id, parent_seq::text AS parent_seq, parent_version_id, document, snapshot, created_at";
+/**
+ * The insert. The row carries no ordinal, thus the statement writes the given
+ * columns directly. `created_at` takes the column default.
+ */
+const INSERT_SQL = `INSERT INTO cortex_report_versions
+    (version_id, analysis_id, thread_id, parent_thread_id, parent_seq,
+     parent_version_id, document, snapshot)
+  VALUES ($1, $2, $3, $4, $5::bigint, $6, $7::jsonb, $8::jsonb)`;
+function rowToVersion(row) {
+    const document = ReportDocumentSchema.safeParse(row.document);
+    if (!document.success) {
+        return err({ type: "corrupt_version", op: "report-versions.read", versionId: row.version_id, part: "document", issues: reduceIssues(document.error) });
+    }
+    const snapshot = parseSnapshot(row.snapshot);
+    if (snapshot.isErr()) {
+        return err({ type: "corrupt_version", op: "report-versions.read", versionId: row.version_id, part: "snapshot", issues: snapshot.error });
+    }
+    return ok({
+        versionId: row.version_id,
+        analysisId: row.analysis_id,
+        threadId: row.thread_id,
+        parentThreadId: row.parent_thread_id,
+        parentSeq: row.parent_seq === null ? null : Number(row.parent_seq),
+        parentVersionId: row.parent_version_id,
+        document: document.data,
+        snapshot: snapshot.value,
+        createdAt: row.created_at,
+    });
+}
+/**
+ * Map an insert failure to a record refusal. A trip of the thread constraint is
+ * thread_already_holds_version. Every other DbError stays unchanged.
+ */
+function mapInsertError(error, threadId) {
+    if (error.type === "constraint_violation" && error.constraint === THREAD_UNIQUE_CONSTRAINT) {
+        return { type: "thread_already_holds_version", op: "report-versions.record", threadId };
+    }
+    return error;
+}
+/**
+ * Create a `ReportVersionStore` bound to a Postgres pool. The
+ * `cortex_report_versions` table is provisioned by the state-init DDL.
+ */
+export function createReportVersionStore({ pool }) {
+    /**
+     * The analysis scope of a parent version, or `null` when no such row exists.
+     * Absence is not a verdict here: an unknown parent id falls through to the
+     * insert, where the self foreign key refuses it as a `DbError`.
+     */
+    function parentAnalysis(parentVersionId) {
+        return tryQuery("report-versions.record.parentScope", () => pool.query({
+            text: "SELECT analysis_id FROM cortex_report_versions WHERE version_id = $1",
+            values: [parentVersionId],
+        })).map(({ rows }) => rows[0]?.analysis_id ?? null);
+    }
+    function record(input) {
+        const parsed = ReportDocumentSchema.safeParse(input.document);
+        if (!parsed.success) {
+            return errAsync({ type: "malformed_document", op: "report-versions.record", issues: reduceIssues(parsed.error) });
+        }
+        const document = parsed.data;
+        // The parse guards the row against a caller bug. The store stores the given
+        // value, thus the parse changes no value.
+        const parsedSnapshot = parseSnapshot(input.snapshot);
+        if (parsedSnapshot.isErr()) {
+            return errAsync({ type: "malformed_snapshot", op: "report-versions.record", issues: parsedSnapshot.error });
+        }
+        const insert = () => {
+            const versionId = randomUUID();
+            return tryMutation("report-versions.record.insert", async () => {
+                await pool.query({
+                    text: INSERT_SQL,
+                    values: [
+                        versionId,
+                        input.analysisId,
+                        input.threadId,
+                        input.parentThreadId,
+                        input.parentSeq,
+                        input.parentVersionId ?? null,
+                        JSON.stringify(document),
+                        JSON.stringify(input.snapshot),
+                    ],
+                });
+                return { versionId };
+            }).mapErr((error) => mapInsertError(error, input.threadId));
+        };
+        if (input.parentVersionId === undefined) {
+            return insert();
+        }
+        const parentVersionId = input.parentVersionId;
+        return parentAnalysis(parentVersionId).andThen((parentAnalysisId) => {
+            if (parentAnalysisId !== null && parentAnalysisId !== input.analysisId) {
+                return errAsync({
+                    type: "parent_analysis_mismatch",
+                    op: "report-versions.record",
+                    analysisId: input.analysisId,
+                    parentVersionId,
+                    parentAnalysisId,
+                });
+            }
+            return insert();
+        });
+    }
+    function getVersion(versionId) {
+        return tryQuery("report-versions.getVersion", () => pool.query({
+            text: `SELECT ${VERSION_COLUMNS} FROM cortex_report_versions WHERE version_id = $1`,
+            values: [versionId],
+        })).andThen(({ rows }) => {
+            const row = rows[0];
+            if (!row)
+                return ok(null);
+            return rowToVersion(row);
+        });
+    }
+    function getThreadVersion(threadId) {
+        return tryQuery("report-versions.getThreadVersion", () => pool.query({
+            text: `SELECT ${VERSION_COLUMNS} FROM cortex_report_versions WHERE thread_id = $1`,
+            values: [threadId],
+        })).andThen(({ rows }) => {
+            const row = rows[0];
+            if (!row)
+                return ok(null);
+            return rowToVersion(row);
+        });
+    }
+    return { record, getVersion, getThreadVersion };
+}

package/dist/state/snapshot-parse.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The one parse of a stored report snapshot, shared by the two stores.
+ *
+ * The session-state store and the version store each hold a snapshot column, and
+ * each reads it back the same way. A path such as `__proto__` is an ordinary
+ * artifact key of the ledger, and the pin keeps it as an own member of a
+ * null-prototype map (`report-model/pin-snapshot.ts`). Each object-shaped schema
+ * of zod drops such a key, thus a store that parsed the map through one would
+ * resolve a reference to that artifact before a reload and refuse it as absent
+ * after one. The walk reads the own keys of the stored map, and it parses each
+ * value on its own, thus the two stores agree on the key set.
+ */
+import { type Result } from "neverthrow";
+import { z } from "zod";
+import type { ReportSnapshot } from "../report-model/reference-resolver.js";
+/** One reduced schema issue -- the dotted path and the message, without the rest. */
+export interface SchemaIssue {
+    readonly path: string;
+    readonly message: string;
+}
+/** Reduce a zod error to the dotted path and the message of each issue. */
+export declare function reduceIssues(error: z.ZodError): SchemaIssue[];
+/**
+ * Parse a stored snapshot.
+ *
+ * The artifacts map never goes through a zod object schema, for the reason that
+ * the module header gives: a zod object drops a `__proto__` key and the pin keeps
+ * it. The walk reads the own keys of the stored map, and it parses each value on
+ * its own.
+ *
+ * The `ReportSnapshot` return type ties this parse to the type of the reference
+ * model, thus a change to one shows as a compile error here.
+ */
+export declare function parseSnapshot(stored: unknown): Result<ReportSnapshot, SchemaIssue[]>;

package/dist/state/snapshot-parse.js

@@ -0,0 +1,82 @@
+/**
+ * The one parse of a stored report snapshot, shared by the two stores.
+ *
+ * The session-state store and the version store each hold a snapshot column, and
+ * each reads it back the same way. A path such as `__proto__` is an ordinary
+ * artifact key of the ledger, and the pin keeps it as an own member of a
+ * null-prototype map (`report-model/pin-snapshot.ts`). Each object-shaped schema
+ * of zod drops such a key, thus a store that parsed the map through one would
+ * resolve a reference to that artifact before a reload and refuse it as absent
+ * after one. The walk reads the own keys of the stored map, and it parses each
+ * value on its own, thus the two stores agree on the key set.
+ */
+import { err, ok } from "neverthrow";
+import { z } from "zod";
+/**
+ * One pinned artifact of a stored snapshot. The value carries the content hash, an
+ * optional file type, and optional rows.
+ */
+const ArtifactSnapshotSchema = z.object({
+    hash: z.string(),
+    fileType: z.string().nullable().optional(),
+    rows: z.array(z.record(z.string(), z.union([z.string(), z.number()]))).optional(),
+});
+/** The citation list of a stored snapshot. A snapshot with no list reads as an absent field. */
+const CitationsSchema = z.array(z.string()).optional();
+/** Reduce a zod error to the dotted path and the message of each issue. */
+export function reduceIssues(error) {
+    return error.issues.map((issue) => ({
+        path: issue.path.map((segment) => String(segment)).join("."),
+        message: issue.message,
+    }));
+}
+/** Put a prefix before the path of each issue, thus a nested parse names the key that failed. */
+function prefixIssues(prefix, issues) {
+    return issues.map((issue) => ({
+        path: issue.path === "" ? prefix : `${prefix}.${issue.path}`,
+        message: issue.message,
+    }));
+}
+/** A stored map is a plain object. An array and a null carry no own key that a map read can use. */
+function isPlainRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Parse a stored snapshot.
+ *
+ * The artifacts map never goes through a zod object schema, for the reason that
+ * the module header gives: a zod object drops a `__proto__` key and the pin keeps
+ * it. The walk reads the own keys of the stored map, and it parses each value on
+ * its own.
+ *
+ * The `ReportSnapshot` return type ties this parse to the type of the reference
+ * model, thus a change to one shows as a compile error here.
+ */
+export function parseSnapshot(stored) {
+    if (!isPlainRecord(stored)) {
+        return err([{ path: "", message: "the stored snapshot is not an object" }]);
+    }
+    if (!isPlainRecord(stored.artifacts)) {
+        return err([{ path: "artifacts", message: "the artifacts map is not an object" }]);
+    }
+    const citations = CitationsSchema.safeParse(stored.citations);
+    if (!citations.success) {
+        return err(prefixIssues("citations", reduceIssues(citations.error)));
+    }
+    // The map takes a null prototype, the same as the pin, thus a path such as
+    // `__proto__` stays an ordinary entry and never reaches a prototype slot.
+    const artifacts = Object.create(null);
+    const issues = [];
+    for (const [path, value] of Object.entries(stored.artifacts)) {
+        const parsed = ArtifactSnapshotSchema.safeParse(value);
+        if (!parsed.success) {
+            issues.push(...prefixIssues(`artifacts.${path}`, reduceIssues(parsed.error)));
+            continue;
+        }
+        artifacts[path] = parsed.data;
+    }
+    if (issues.length > 0) {
+        return err(issues);
+    }
+    return citations.data === undefined ? ok({ artifacts }) : ok({ artifacts, citations: citations.data });
+}

package/dist/tasks/data-profile.js

@@ -272,6 +272,7 @@ export async function runDataProfileBody(input, deps) {
                 id: "submit_profile",
                 description: "Submit the profiling results. Call this tool once after completing " + "all profiling work — it validates and records your findings.",
                 inputSchema: ProfilerOutputSchema,
+                describeCall: "none",
                 execute: async (input) => {
                     capturedProfile = input;
                     return ok({ status: "accepted" });

package/dist/tools/ad-hoc-router.d.ts

@@ -2,7 +2,7 @@ import type { Pool } from "pg";
 import { type AgentSession } from "../auth/types.js";
 import type { ResourcePolicy, ResourceSpec } from "../config/resource-limits.js";
 import type { Logger } from "../lib/logger.js";
-import type { ChatProvider } from "../providers/types.js";
+import { type ChatProvider } from "../providers/types.js";
 export declare const AD_HOC_ROUTER_AGENT_ID = "adhoc-router";
 export declare const AD_HOC_ROUTER_TIMEOUT_MS = 10000;
 export declare const AD_HOC_FALLBACK_AGENT_ID = "scientific-executor";
@@ -18,7 +18,12 @@ export interface AdHocRouterDeps {
     readonly pool: Pool;
     readonly resourcePolicy?: ResourcePolicy;
     readonly logger?: Logger;
-    /** Test seam; production always uses {@link AD_HOC_ROUTER_TIMEOUT_MS}. */
+    /**
+     * Test seam that sets an explicit deadline. An explicit value overrides the
+     * derived deadline. The derived deadline is the maximum of
+     * {@link AD_HOC_ROUTER_TIMEOUT_MS} and the request-timeout limit that the
+     * provider advertises.
+     */
     readonly timeoutMs?: number;
 }
 export declare function defaultAdHocResources(policy?: ResourcePolicy): ResourceSpec;

package/dist/tools/ad-hoc-router.js

@@ -6,6 +6,7 @@ import { DATA_PROFILE_ORIENTATION_MAX_CHARS, buildDataProfileOrientation } from
 import { createNoopLogger } from "../lib/console-logger.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { resourceEstimationSection } from "../prompts/planner.js";
+import { effectiveDeadlineMs } from "../providers/types.js";
 import { loadDataProfileStatus } from "../state/index.js";
 export const AD_HOC_ROUTER_AGENT_ID = "adhoc-router";
 export const AD_HOC_ROUTER_TIMEOUT_MS = 10_000;
@@ -72,7 +73,7 @@ export async function routeAdHocRequest(deps, input) {
     const catalog = PLANNABLE_AGENT_CATALOG.map((agent) => `- ${agent.id}: capabilities [${agent.capabilities.join(", ")}]; suitable for [${agent.suitableFor.join(", ")}]`).join("\n");
     const orientation = await profileOrientation(deps.pool, input.analysisId, logger);
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(new Error("ad hoc routing timed out")), deps.timeoutMs ?? AD_HOC_ROUTER_TIMEOUT_MS);
+    const timer = setTimeout(() => controller.abort(new Error("ad hoc routing timed out")), effectiveDeadlineMs(deps.provider, AD_HOC_ROUTER_TIMEOUT_MS, deps.timeoutMs));
     const signal = AbortSignal.any([input.signal, controller.signal]);
     let raw;
     let failure;

package/dist/tools/bio/chembl.js

@@ -118,6 +118,7 @@ export const chemblTool = defineTool({
         "compounds here first. If ChEMBL misses the compound, resolve it via pubchem action='compound' and bridge back with pubchem action='crossrefs'.\n" +
         "An empty array is valid no-data, not an error — do not retry the same call.",
     inputSchema,
+    describeCall: "none",
     execute: async ({ action, query, searchType, chemblId, idType, activityType, limit }) => {
         switch (action) {
             case "compounds":

package/dist/tools/bio/comptox.js

@@ -106,6 +106,7 @@ export function createComptoxTool(deps) {
             "This is environmental/industrial-chemical data: for drug-like compounds prefer PubChem or ChEMBL — dataset 'chemical' returns " +
             "`detail.pubchemCid` to bridge back.",
         inputSchema,
+        describeCall: "none",
         execute: async (input) => {
             const headers = getEpaCcteHeaders(deps.apiKey);
             const resolved = await resolveDtxsid(input.query, headers);

package/dist/tools/bio/drug-gene-interactions.js

@@ -119,6 +119,7 @@ export function createDrugGeneInteractionsTool(deps) {
             "not be reached (a missing DRUGBANK_API_KEY lands here — tell the user and proceed with DGIdb). A `found: false` entry means the identifier " +
             "is not in DGIdb at all, usually a non-HUGO symbol or a brand name. Neither is worth retrying unchanged.",
         inputSchema,
+        describeCall: "none",
         execute: async (input) => {
             const inputs = typeof input.query === "string" ? [input.query] : input.query;
             const selected = input.sources ?? ["dgidb"];

package/dist/tools/bio/gene-disease-evidence.js

@@ -118,6 +118,7 @@ export function createGeneDiseaseEvidenceTool(deps) {
             "could not be reached (a missing DISGENET_API_KEY lands here — tell the user and proceed with the other two); 'not_applicable' means that " +
             "corpus has no lookup for this queryType. Only 'no_data' is evidence of absence, and none is worth retrying unchanged.",
         inputSchema,
+        describeCall: "none",
         execute: async (input) => {
             const applicable = applicableSources(input.queryType);
             const requested = input.sources ?? applicable;

package/dist/tools/bio/gene-preclinical-profile.js

@@ -105,6 +105,7 @@ export const genePreclinicalProfileTool = defineTool({
         "SPARSE OUTPUT IS VALID NO-DATA, not an error — do not retry. A null humanEnsemblId means the symbol did not resolve; a null mouseMarkerSymbol " +
         "with no phenotype terms means the gene has not been IMPC-phenotyped, which is common.",
     inputSchema,
+    describeCall: "none",
     execute: async ({ geneSymbol, include, species, minRank, tissueLimit, phenotypeLimit }) => {
         const halves = include ?? ["expression", "knockout"];
         const wantExpression = halves.includes("expression");

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

@@ -19,8 +19,9 @@ export interface BioToolKeys {
  * The NCBI-backed literature tool, built from the shared key slice.
  *
  * `pubmed` is the consolidated literature tool (search / details / fulltext
- * behind one `action`). ClinVar is no longer its own tool — it is one of the
- * corpora behind `gene_disease_evidence`, which also needs the NCBI key.
+ * behind one `action`). ClinVar reaches a caller through
+ * `gene_disease_evidence`, as one of the corpora behind it, and it needs the
+ * same NCBI key.
  */
 export declare function createNcbiTools(keys: BioToolKeys): {
     pubmed: Tool;

package/dist/tools/bio/keys.js

@@ -6,8 +6,9 @@ import { createPubMedTool } from "./pubmed.js";
  * The NCBI-backed literature tool, built from the shared key slice.
  *
  * `pubmed` is the consolidated literature tool (search / details / fulltext
- * behind one `action`). ClinVar is no longer its own tool — it is one of the
- * corpora behind `gene_disease_evidence`, which also needs the NCBI key.
+ * behind one `action`). ClinVar reaches a caller through
+ * `gene_disease_evidence`, as one of the corpora behind it, and it needs the
+ * same NCBI key.
  */
 export function createNcbiTools(keys) {
     return {

package/dist/tools/bio/lookup-annotation.js

@@ -122,6 +122,7 @@ export const lookupAnnotationTool = defineTool({
         "search_interactions({action:'enrichment'}), which does the statistics.\n" +
         "An empty terms / annotations / pathways array is valid no-data — do not retry the same input.",
     inputSchema,
+    describeCall: "none",
     execute: async ({ vocabulary, query, goId, geneProductId, taxonId, organism, includeGenes, limit }) => {
         const cap = limit ?? DEFAULT_LIMIT;
         if (vocabulary !== "go") {

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

@@ -2,9 +2,9 @@
  * opentargets — one tool over the Open Targets Platform: target-disease
  * association evidence, read from a gene or from a disease.
  *
- * The curated safety liabilities this tool used to serve now belong to
- * `target_safety`, which pairs them with the local secondary-pharmacology panel
- * and resolves the Ensembl id they need.
+ * Curated safety liabilities are not served here: `target_safety` owns them,
+ * because it pairs them with the local secondary-pharmacology panel and
+ * resolves the Ensembl id they need.
  *
  * The input is a flat object with an `action` discriminator — not a
  * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs

package/dist/tools/bio/opentargets.js

@@ -2,9 +2,9 @@
  * opentargets — one tool over the Open Targets Platform: target-disease
  * association evidence, read from a gene or from a disease.
  *
- * The curated safety liabilities this tool used to serve now belong to
- * `target_safety`, which pairs them with the local secondary-pharmacology panel
- * and resolves the Ensembl id they need.
+ * Curated safety liabilities are not served here: `target_safety` owns them,
+ * because it pairs them with the local secondary-pharmacology panel and
+ * resolves the Ensembl id they need.
  *
  * The input is a flat object with an `action` discriminator — not a
  * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs
@@ -62,6 +62,7 @@ export const openTargetsTool = defineTool({
         "disease name silently returns an EMPTY result rather than an error — resolve a symbol to its ENSG id with search_gene first.\n" +
         "NO-DATA IS FINAL — do not retry the same id. Empty associations mean no evidence, or an unresolvable id.",
     inputSchema,
+    describeCall: "none",
     execute: async (input) => {
         const limit = input.limit ?? DEFAULT_LIMIT;
         switch (input.action) {

package/dist/tools/bio/pubchem.js

@@ -76,6 +76,7 @@ export const pubchemTool = defineTool({
         "then chembl action='mechanism' / 'bioactivity' there for curated activity data. " +
         "An empty results / crossRefs / assays array is valid no-data (no match; the CID is in no external registry; the compound was never screened) — do not retry.",
     inputSchema,
+    describeCall: "none",
     execute: async (input) => {
         switch (input.action) {
             case "compound":

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

@@ -39,6 +39,7 @@ export const searchClinicalTrialsTool = defineTool({
             "landscape. Set true for the full protocol prose, and narrow `limit` when you do: a full summary runs to several thousand characters " +
             "per trial."),
     }),
+    describeCall: "none",
     execute: async ({ query, phase, status, limit = 10, includeSummaries = false }) => {
         const result = await searchTrials(query, { phase, status, limit });
         const trials = includeSummaries

package/dist/tools/bio/search-faers.js

@@ -23,6 +23,7 @@ export const searchFaersTool = defineTool({
             .describe("Max distinct adverse-reaction terms to return, most-reported first (default 15, max 100). totalReports covers the whole drug regardless."),
         serious: z.boolean().default(false).describe("When true, count only reports flagged serious (death, hospitalization, life-threatening, disabling)."),
     }),
+    describeCall: "none",
     execute: async ({ drugName, limit = 15, serious = false }) => {
         const result = await getFaersByDrug(drugName, { limit, serious });
         return ok({

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

@@ -63,6 +63,7 @@ export const searchGeoDatasetsTool = defineTool({
             .default(10)
             .describe("Max datasets to return (default 10, max 50). totalFound reports the true match count regardless."),
     }),
+    describeCall: "none",
     execute: async ({ query, organism, datasetType = "gse", limit = 10 }) => {
         let searchQuery = query;
         // Escape backslashes first, then quotes, so a `\` in the organism value

package/dist/tools/bio/search-interactions.js

@@ -35,6 +35,7 @@ export const searchInteractionsTool = defineTool({
             .describe(`Max records returned — partners, network edges, or enriched terms depending on action (default ${DEFAULT_LIMIT}, max 500). ` +
             "Rows are ordered best-first (score descending for interactions, FDR ascending for enrichment), so the default keeps the strongest."),
     }),
+    describeCall: "none",
     execute: async ({ identifiers, species, action, minScore, limit }) => {
         if (action === "enrichment") {
             return ok(await getEnrichment(identifiers, species, { limit }));