@inflexa-ai/harness 0.17.0 → 0.18.0

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

@@ -0,0 +1,132 @@
+/**
+ * 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 mints 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";
+/** One reduced schema issue -- the dotted path and the message, without the rest. */
+export interface SchemaIssue {
+    readonly path: string;
+    readonly message: string;
+}
+/** 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,194 @@
+/**
+ * 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 mints 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 { z } from "zod";
+import { ReportDocumentSchema } from "../contracts/report-blocks.js";
+import { tryMutation, tryQuery } from "../lib/db-result.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";
+/**
+ * One pinned artifact of a stored snapshot. The value carries the content hash,
+ * an optional file type, and optional rows. The `z.ZodType<ReportSnapshot>`
+ * annotation below keeps this schema and the `ArtifactSnapshot` type of the
+ * reference model in step, thus a change to one shows as a compile error there.
+ */
+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 stored-snapshot schema. The annotation ties the parse output to the
+ * `ReportSnapshot` type of the reference model, thus the store and the structural
+ * validation never disagree about the snapshot shape. The mint never fills `rows`,
+ * but the schema admits what the type admits.
+ */
+const ReportSnapshotSchema = z.object({
+    artifacts: z.record(z.string(), ArtifactSnapshotSchema),
+    citations: z.array(z.string()).optional(),
+});
+function reduceIssues(error) {
+    return error.issues.map((issue) => ({
+        path: issue.path.map((segment) => String(segment)).join("."),
+        message: issue.message,
+    }));
+}
+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 = ReportSnapshotSchema.safeParse(row.snapshot);
+    if (!snapshot.success) {
+        return err({ type: "corrupt_version", op: "report-versions.read", versionId: row.version_id, part: "snapshot", issues: reduceIssues(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.data,
+        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 through a cast. The store
+        // stores the given value, thus the parse changes no value.
+        const parsedSnapshot = ReportSnapshotSchema.safeParse(input.snapshot);
+        if (!parsedSnapshot.success) {
+            return errAsync({ type: "malformed_snapshot", op: "report-versions.record", issues: reduceIssues(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/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/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 }));

package/dist/tools/bio/target-safety.d.ts

@@ -3,11 +3,9 @@
  * sources that carry it: the curated secondary-pharmacology panel that ships
  * with the harness, and Open Targets' curated liabilities.
  *
- * These were `check_safety_panel` and `opentargets({action:'safety'})`, and the
- * panel tool's own description instructed calling them together — a pairing
- * every caller had to remember, expressed in prose that had already gone stale
- * (it named two tools that no longer exist). Both are keyed on the same target
- * and answer the same question, so the pairing belongs in the tool.
+ * Both sources are keyed on the same target and answer the same question, so
+ * the pairing belongs in the tool rather than in prose a caller has to
+ * remember: one call consults both and merges what they carry.
  *
  * Identifier resolution is the tool's job, not the caller's: Open Targets
  * accepts ONLY an Ensembl gene id, and it is taken from the panel entry when
@@ -41,7 +39,7 @@ export declare const targetSafetyTool: import("../define-tool.js").Tool<{
     identifiers: string[];
     identifierType?: "auto" | "gene_symbol" | "uniprot" | "chembl_id" | "ensembl_id" | undefined;
     sources?: ("opentargets" | "panel")[] | undefined;
-    filterOrgan?: "hematologic" | "metabolic" | "immune" | "hepatic" | "cns" | "renal" | "respiratory" | "cardiac" | "gi" | undefined;
+    filterOrgan?: "hematologic" | "metabolic" | "immune" | "hepatic" | "musculoskeletal" | "cns" | "renal" | "reproductive" | "respiratory" | "cardiac" | "vascular" | "pns" | "gi" | "pancreas" | "endocrine_thyroid" | "dermatologic" | "ocular" | "oncology" | undefined;
     minSeverity?: "high" | "medium" | "low" | undefined;
     liabilityLimit?: number | undefined;
 }, {

package/dist/tools/bio/target-safety.js

@@ -3,11 +3,9 @@
  * sources that carry it: the curated secondary-pharmacology panel that ships
  * with the harness, and Open Targets' curated liabilities.
  *
- * These were `check_safety_panel` and `opentargets({action:'safety'})`, and the
- * panel tool's own description instructed calling them together — a pairing
- * every caller had to remember, expressed in prose that had already gone stale
- * (it named two tools that no longer exist). Both are keyed on the same target
- * and answer the same question, so the pairing belongs in the tool.
+ * Both sources are keyed on the same target and answer the same question, so
+ * the pairing belongs in the tool rather than in prose a caller has to
+ * remember: one call consults both and merges what they carry.
  *
  * Identifier resolution is the tool's job, not the caller's: Open Targets
  * accepts ONLY an Ensembl gene id, and it is taken from the panel entry when
@@ -15,7 +13,9 @@
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
-import { CHEMBL_RE, ORGAN_SYSTEMS, SEVERITIES, SafetyPanelFileSchema, UNIPROT_RE, } from "../../data/safety-panel-schema.js";
+import { ORGAN_SYSTEMS } from "../../contracts/organ-system.js";
+import { SEVERITIES } from "../../contracts/severity.js";
+import { CHEMBL_RE, SafetyPanelFileSchema, UNIPROT_RE } from "../../data/safety-panel-schema.js";
 import panelData from "../../data/safety-panel.json" with { type: "json" };
 import { defineTool } from "../define-tool.js";
 import { resolveSymbolToEnsemblId } from "../lib/ensembl-client.js";
@@ -100,6 +100,7 @@ export const targetSafetyTool = defineTool({
         "means no CURATED liability, not that none exists. Both are valid no-data — do not retry. Read `perSource` and each row's `opentargetsNote`: a " +
         "ChEMBL or UniProt identifier absent from the panel cannot be resolved to an Ensembl id, so its Open Targets half is skipped rather than empty.",
     inputSchema,
+    describeCall: "none",
     execute: async ({ identifiers, identifierType, sources, filterOrgan, minSeverity, liabilityLimit }) => {
         const selected = sources ?? [...SOURCES];
         const wantPanel = selected.includes("panel");

package/dist/tools/define-tool.d.ts

@@ -95,20 +95,28 @@ export interface ToolDefinition<Schema extends z.ZodType, Output> {
     readonly inputSchema: Schema;
     readonly executionMode?: ToolExecutionMode;
     /**
-     * One line naming what THIS call is doing — the call-time counterpart of
+     * One line that names what THIS call does — the call-time counterpart of
      * `description`. `description` self-describes the tool at attach time, so an
-     * agent knows what it holds; `describeCall` self-describes one invocation, so
+     * agent knows what it holds. `describeCall` self-describes one invocation, so
      * a surface can render four `update_working_memory` calls as four distinct
      * lines instead of four identical chips.
      *
-     * It lives here, beside `inputSchema`, because that is the one place the
-     * compiler checks the two against each other. A host-side formatter reading
-     * `input.path` by string key breaks silently the day the schema moves; this
-     * one fails to build. The tool author writes it because the tool author knows
-     * which field matters.
+     * The decision is REQUIRED. Give a hook, or give the literal `"none"`.
+     * `"none"` declares that the input of the tool cannot distinguish its calls,
+     * thus a hook can only restate the name of the tool. `defineTool` consumes
+     * the sentinel at construction, and the sentinel never reaches a packaged
+     * tool. Thus a reader of a `Tool` sees a function, or sees nothing. A hook
+     * that returns the string `"none"` is still a hook, because the discriminator
+     * is `typeof`, not equality.
      *
-     * Synchronous and pure — no I/O, no ambient state. Dispatch is what the user
-     * waits on, and a description must never be able to fail a call: the loop
+     * A hook lives here, beside `inputSchema`, because that is the one place
+     * where the compiler checks the two against each other. A host-side formatter
+     * that reads `input.path` by string key breaks silently the day the schema
+     * moves. This one fails to build. The tool author writes it, because the tool
+     * author knows which field matters.
+     *
+     * A hook is synchronous and pure — no I/O, no ambient state. Dispatch is what
+     * the user waits on, and a description must never fail a call: the loop
      * validates the input against `inputSchema` first, guards the call, and drops
      * the detail on any failure (see the tool-call-detail capability).
      *
@@ -116,10 +124,9 @@ export interface ToolDefinition<Schema extends z.ZodType, Output> {
      * removed, secrets redacted, length capped — happens once at the emit site,
      * never here.
      *
-     * OPTIONAL, and absence is a normal state: a tool without it is observable
-     * exactly as it is today. The hook never reaches the model.
+     * The hook never reaches the model.
      */
-    describeCall?(input: z.infer<Schema>): string;
+    describeCall: ((input: z.infer<Schema>) => string) | "none";
     execute(input: z.infer<Schema>, ctx: ToolContext): Promise<Result<Output, ToolError>>;
 }
 /**

package/dist/tools/define-tool.js

@@ -44,9 +44,11 @@ export function defineTool(def) {
         inputSchema: def.inputSchema,
         jsonSchema,
         executionMode,
-        // Spread rather than assigned: a tool that declares no hook carries no
+        // Spread rather than assigned: a tool that declines carries no
         // `describeCall` key at all, so "has a hook" is one property check.
-        ...(def.describeCall === undefined ? {} : { describeCall: def.describeCall }),
+        // `typeof` is the discriminator, not equality with the sentinel, so a
+        // hook that returns the string `"none"` still packages as a hook.
+        ...(typeof def.describeCall === "function" ? { describeCall: def.describeCall } : {}),
         execute: def.execute,
     };
 }

package/dist/tools/display/show-user.js

@@ -61,6 +61,7 @@ export const showUserTool = defineTool({
         "One card per call, rendered in call order; an identical repeat call resolves to the same card, so compose the " +
         "finished content before calling rather than re-rendering a draft.",
     inputSchema: ShowUserInputSchema,
+    describeCall: ({ kind, title }) => (title === undefined ? kind : `${kind}: ${title}`),
     execute: async (input, ctx) => {
         // `dataPath` is a reference the host resolves at render time; validate its
         // shape only (existence is a render-time host concern), and treat a