@inflexa-ai/harness 0.13.0 → 0.14.0

package/dist/state/runs.js

@@ -139,6 +139,38 @@ export function queryActiveRun(pool, analysisId, planId) {
         return row ? mapRunRow(row) : null;
     });
 }
+/**
+ * Every NON-TERMINAL run of an analysis, newest-first and deliberately unbounded.
+ *
+ * The counterpart to {@link queryRunsByAnalysis}, which answers "the newest N runs" — a windowed
+ * question, and the wrong one for a host driving live surfaces. Ordering by `started_at DESC` and
+ * capping means the run most worth watching is the first to fall out: a long analysis still going
+ * while ten short ones start and finish after it leaves the window entirely, so a host reading only
+ * that window loses its progress AND never learns it terminated.
+ *
+ * Unbounded is safe here in a way it is not for the general listing: this result is capped by the
+ * analysis's live concurrency, not by its history, and a run leaves the set permanently when it
+ * finishes.
+ *
+ * The status set is the one {@link queryActiveRun} uses — non-terminal means still running, or
+ * suspended awaiting funds. Keep the two in step: a new non-terminal status added to one and not the
+ * other makes a live run invisible to exactly one of its readers.
+ */
+export function queryActiveRunsByAnalysis(pool, analysisId) {
+    return tryQuery("runs.queryActiveRunsByAnalysis", async () => {
+        const result = await pool.query({
+            text: `SELECT run_id, analysis_id, thread_id, workflow_name,
+                   status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
+                   mandate_jti, mandate_expires_at, plan_id -- oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
+            FROM cortex_runs
+            WHERE analysis_id = $1
+              AND status IN ('running','suspended_insufficient_funds')
+            ORDER BY started_at DESC`,
+            values: [analysisId],
+        });
+        return result.rows.map(mapRunRow);
+    });
+}
 export function updateRunStatus(pool, runId, status, error) {
     const now = new Date().toISOString();
     const isTerminal = status === "completed" || status === "partial" || status === "failed" || status === "canceled";
@@ -189,6 +221,77 @@ export function queryRunsByAnalysis(pool, analysisId, { limit = 50, offset = 0 }
         return result.rows.map(mapRunRow);
     });
 }
+/**
+ * Read the analysis's non-terminal run activity without coupling it to a
+ * conversation thread. The total is counted before the detail limit so a
+ * bounded prompt projection can disclose omitted rows.
+ */
+export function queryNonTerminalRunsByAnalysis(pool, analysisId, limit = 20) {
+    return tryQuery("runs.queryNonTerminalRunsByAnalysis", async () => {
+        const countResult = await pool.query({
+            text: `SELECT COUNT(*)::int AS total
+            FROM cortex_runs
+            WHERE analysis_id = $1
+              AND status IN ('running','suspended_insufficient_funds')`,
+            values: [analysisId],
+        });
+        const rowsResult = await pool.query({
+            text: `SELECT run_id, analysis_id, thread_id, workflow_name,
+                   status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
+                   mandate_jti, mandate_expires_at, plan_id
+            FROM cortex_runs
+            WHERE analysis_id = $1
+              AND status IN ('running','suspended_insufficient_funds')
+            ORDER BY CASE status
+                         WHEN 'running' THEN 0
+                         WHEN 'suspended_insufficient_funds' THEN 1
+                         ELSE 2
+                     END,
+                     started_at DESC,
+                     run_id DESC
+            LIMIT $2`,
+            values: [analysisId, limit],
+        });
+        return {
+            runs: rowsResult.rows.map(mapRunRow),
+            total: Number(countResult.rows[0]?.total ?? 0),
+        };
+    });
+}
+/**
+ * Read one stable inspection page: running first, then suspended, then
+ * terminal history. This is deliberately separate from
+ * {@link queryRunsByAnalysis}, whose chronological order is an embedder/UI
+ * contract.
+ */
+export function queryRunsForInspection(pool, analysisId, { limit = 50, offset = 0 } = {}) {
+    return tryQuery("runs.queryRunsForInspection", async () => {
+        const countResult = await pool.query({
+            text: "SELECT COUNT(*)::int AS total FROM cortex_runs WHERE analysis_id = $1",
+            values: [analysisId],
+        });
+        const rowsResult = await pool.query({
+            text: `SELECT run_id, analysis_id, thread_id, workflow_name,
+                   status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
+                   mandate_jti, mandate_expires_at, plan_id
+            FROM cortex_runs
+            WHERE analysis_id = $1
+            ORDER BY CASE status
+                         WHEN 'running' THEN 0
+                         WHEN 'suspended_insufficient_funds' THEN 1
+                         ELSE 2
+                     END,
+                     started_at DESC,
+                     run_id DESC
+            LIMIT $2 OFFSET $3`,
+            values: [analysisId, limit, offset],
+        });
+        return {
+            runs: rowsResult.rows.map(mapRunRow),
+            total: Number(countResult.rows[0]?.total ?? 0),
+        };
+    });
+}
 export function queryRunsByThread(pool, analysisId, threadId, { limit = 50, offset = 0 } = {}) {
     return tryQuery("runs.queryRunsByThread", async () => {
         const result = await pool.query({

package/dist/tasks/data-profile-activity.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The data-profile workflow's activity emissions, as a pure factory over a raw
+ * stream write.
+ *
+ * Extracted from the workflow body for the same reason `createLineageCollector`
+ * and `buildDriftSignature` are: a DBOS workflow body is not reachable from a
+ * unit test — it needs a launched engine, a sandbox, a scripted model, and an
+ * embedder — so the decidable part is lifted out and tested on its own. What is
+ * decidable here is the whole observable contract of this capability: which
+ * phase each moment of a profile reports, and in what words. Those phrases are
+ * what a user reads, so they are the one part of the work that must not be left
+ * to drift.
+ *
+ * What stays in the body is only control flow — where each call sits relative to
+ * the ledger writes. That is not extractable, and the ordering property it
+ * carries (exactly one terminal emission) is guaranteed structurally instead:
+ * there is exactly one `complete` call site and it is the last statement of the
+ * success path, after the terminal ledger write and the authorization revoke, so
+ * anything that throws on the way there reaches the failure path having emitted
+ * no terminal at all.
+ */
+import type { Logger } from "../lib/logger.js";
+/**
+ * Writes one part to the run-event stream. Injected rather than imported so this
+ * module stays free of the durability engine and so a test can record what a
+ * profile would have reported without launching one.
+ */
+export type ActivityWrite = (part: unknown) => Promise<void>;
+/**
+ * The profile's activity channel. One method per moment the body reports, rather
+ * than a generic `emit(phase, text)`: the phrases are normative, and a call site
+ * that passes its own string is a call site that can drift from the spec.
+ *
+ * Every method resolves even when the underlying write fails — see
+ * {@link createProfileActivityEmitter}.
+ *
+ * Five of the contract's phases have no method here, and their absence is a
+ * decision rather than an oversight: `generating-metadata` and
+ * `generating-summary` describe the sandbox-step's post-agent pipeline, which a
+ * profile does not run (its agent delivers everything through `submit_profile`);
+ * `persisting` is defined as step bytes uploading to an artifact store, and a
+ * profile's durable products are the vector index and the ledger row, so it would
+ * describe nothing; `retrying` needs a retry loop, and a profile failure is
+ * terminal with recovery being a fresh attempt; `warning` needs a non-fatal
+ * user-facing warning channel, and the body's two soft conditions (an empty
+ * manifest, a fallback file description) are logged because neither warrants
+ * interrupting the activity line.
+ */
+export interface ProfileActivityEmitter {
+    /** Reported before the sandbox is created — the longest wait in a profile, and the one that precedes the agent entirely. */
+    sandboxInit(): Promise<void>;
+    /** Reported once the sandbox is ready, covering the gap before the agent's first tool call. */
+    agentStarting(): Promise<void>;
+    /** Reported per tool call the profiler agent makes, phrased by the shared translator. */
+    forTool(name: string, input: unknown): Promise<void>;
+    /** Reported for the vector-store pass that indexes per-file descriptions. */
+    indexing(): Promise<void>;
+    /** The success terminal. Emitted only after the terminal ledger write has landed. */
+    complete(): Promise<void>;
+    /** The failure terminal, carrying the same user-safe reason the ledger receives. */
+    failed(reason: string): Promise<void>;
+}
+/** Identity the emitted parts carry — the workflow's synthetic frame, not a real run. */
+export interface ProfileActivityFrame {
+    /**
+     * The constant literal the data-profile workflow uses as its run id. It is the
+     * same string for every analysis, so it identifies nothing; consumers are
+     * required not to key on it (see the data-profile-observation spec). It is
+     * carried because the part contract requires the field and because this is the
+     * frame the workflow already uses for its sandbox identity and scratch path.
+     */
+    readonly runId: string;
+    /** The constant literal step id of the profile's single synthetic step. */
+    readonly stepId: string;
+}
+/**
+ * Build the profile's activity channel over `write`.
+ *
+ * Every emission is awaited by its caller in body order, because `DBOS.writeStream`
+ * allocates a function id and an unawaited write would race the next real operation
+ * for the counter, desynchronising the recorded sequence on replay.
+ *
+ * A failing write is swallowed and logged, never propagated: observation is a
+ * diagnostic channel, and a dropped frame must not fail a profile that is otherwise
+ * succeeding. This mirrors the sandbox-step producer's stance on the same write.
+ */
+export declare function createProfileActivityEmitter(write: ActivityWrite, frame: ProfileActivityFrame, logger: Logger): ProfileActivityEmitter;

package/dist/tasks/data-profile-activity.js

@@ -0,0 +1,56 @@
+/**
+ * The data-profile workflow's activity emissions, as a pure factory over a raw
+ * stream write.
+ *
+ * Extracted from the workflow body for the same reason `createLineageCollector`
+ * and `buildDriftSignature` are: a DBOS workflow body is not reachable from a
+ * unit test — it needs a launched engine, a sandbox, a scripted model, and an
+ * embedder — so the decidable part is lifted out and tested on its own. What is
+ * decidable here is the whole observable contract of this capability: which
+ * phase each moment of a profile reports, and in what words. Those phrases are
+ * what a user reads, so they are the one part of the work that must not be left
+ * to drift.
+ *
+ * What stays in the body is only control flow — where each call sits relative to
+ * the ledger writes. That is not extractable, and the ordering property it
+ * carries (exactly one terminal emission) is guaranteed structurally instead:
+ * there is exactly one `complete` call site and it is the last statement of the
+ * success path, after the terminal ledger write and the authorization revoke, so
+ * anything that throws on the way there reaches the failure path having emitted
+ * no terminal at all.
+ */
+import { activityForTool, stepPartId } from "../sandbox/sandbox-step-translate.js";
+/**
+ * Build the profile's activity channel over `write`.
+ *
+ * Every emission is awaited by its caller in body order, because `DBOS.writeStream`
+ * allocates a function id and an unawaited write would race the next real operation
+ * for the counter, desynchronising the recorded sequence on replay.
+ *
+ * A failing write is swallowed and logged, never propagated: observation is a
+ * diagnostic channel, and a dropped frame must not fail a profile that is otherwise
+ * succeeding. This mirrors the sandbox-step producer's stance on the same write.
+ */
+export function createProfileActivityEmitter(write, frame, logger) {
+    // One reconciling id for the profile's single step, so the run-stream fold
+    // collapses every phase transition latest-wins onto one frame rather than
+    // accumulating them. Minted through the shared construction because that
+    // sameness across producers is what makes the fold correct.
+    const id = stepPartId("step-activity", frame.runId, frame.stepId);
+    const emit = async (phase, activity) => {
+        try {
+            await write({ type: "data-step-activity", id, runId: frame.runId, stepId: frame.stepId, phase, activity });
+        }
+        catch (err) {
+            logger.warn("run-event write failed (non-fatal)", { phase, ...logger.errorFields(err) });
+        }
+    };
+    return {
+        sandboxInit: () => emit("sandbox-init", "Starting sandbox"),
+        agentStarting: () => emit("executing", "Running data-profiler"),
+        forTool: (name, input) => emit("executing", activityForTool(name, input)),
+        indexing: () => emit("indexing", "Indexing input descriptions for search"),
+        complete: () => emit("complete", "Profile complete"),
+        failed: (reason) => emit("failed", reason),
+    };
+}

package/dist/tasks/data-profile.js

@@ -33,7 +33,8 @@ import { generateExecutionId } from "../sandbox/execution-id.js";
 import { mintSandboxIdentity } from "../sandbox/identity.js";
 import { createVectorStore } from "../state/vector-store.js";
 import { ProfilerOutputSchema } from "../schemas/data-profile-schemas.js";
-import { completeDataProfile, failDataProfile, loadDataProfileStatus, loadSeedInputFileIds, tryRerunDataProfile, tryStartDataProfile, upsertArtifacts, } from "../state/index.js";
+import { completeDataProfile, failDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, tryRerunDataProfile, tryStartDataProfile, upsertArtifacts, } from "../state/index.js";
+import { createProfileActivityEmitter } from "./data-profile-activity.js";
 import { ensureSearchIndex, searchIndexName } from "../workspace/search-config.js";
 /** Synthetic run/step literal for the data-profile workflow. */
 const DATA_PROFILE_RUN_LITERAL = "data-profile";
@@ -135,7 +136,29 @@ export async function runDataProfileBody(input, deps) {
     // Cortex-owned and must be revoked here.
     const { analysisId, runSession, ownsMandate = true, stagedInputs } = input; // oss-core-managed-ok
     const authorization = { runSession, ownsMandate }; // oss-core-managed-ok
+    // The profile's activity channel. `DBOS.writeStream` is body-only, so the write is bound here
+    // while every phase and phrase lives in the emitter — the phrases are the observable contract of
+    // this capability, and a body that composed its own strings is a body they can drift from.
+    // The frame is the workflow's synthetic one: both values are constants shared by every analysis,
+    // so they identify nothing and consumers are required not to key on them.
+    const activity = createProfileActivityEmitter((part) => DBOS.writeStream("events", part), { runId: DATA_PROFILE_RUN_LITERAL, stepId: DATA_PROFILE_STEP_LITERAL }, logger);
     try {
+        // Record which workflow owns this profile before anything else, so a consumer that resolves
+        // the id from the ledger can subscribe from the earliest possible moment. Guarded on a real
+        // ambient id: this body is also driven directly (outside a workflow), where the synthetic
+        // fallback used further down names no workflow at all and must never reach the ledger.
+        const ownWorkflowId = DBOS.workflowID;
+        if (ownWorkflowId !== undefined) {
+            await DBOS.runStep(async () => {
+                // A refused CAS is a normal in-band outcome, not a failure: the row left
+                // `running` underneath us (cleared, or stale-expired and re-claimed), which is
+                // the ledger correctly moving on. There is nothing to repair, and the profile's
+                // own work is unaffected — only its observability is.
+                if (!unwrapOrThrow(await recordDataProfileWorkflowId(deps.pool, analysisId, ownWorkflowId))) {
+                    logger.warn("workflow-id record skipped: ledger row not running (cleared or re-claimed concurrently)");
+                }
+            }, { name: "record-workflow-id" });
+        }
         // 1. Input files are already staged under data/inputs/ (see the data-profile-init spec); the
         // embedder populated the tree and handed us this manifest in the workflow
         // input. The body never downloads.
@@ -144,6 +167,9 @@ export async function runDataProfileBody(input, deps) {
             if (!unwrapOrThrow(await completeDataProfile(deps.pool, analysisId)))
                 logTerminalNoop(logger, analysisId, "completion");
             await deps.runAuthorizer.revoke(authorization, "data-profile-completed");
+            // This is a terminal completion like any other, so it reports one — a consumer watching
+            // an empty-manifest profile sees it settle rather than seeing the stream simply stop.
+            await activity.complete();
             return;
         }
         // 2. Register staged files in cortex_artifacts
@@ -193,6 +219,11 @@ export async function runDataProfileBody(input, deps) {
             `All file paths in your response must be relative to the analysis root and must EXACTLY match the paths listed above.`,
         ].join("\n");
         logger.info("starting sandbox", { executionId });
+        // Reported BEFORE the container exists, deliberately: provisioning is the longest single
+        // operation in a profile and it precedes the agent entirely, so a body that reported only
+        // from the agent loop would leave the longest wait of all unreported — the same defect the
+        // run panel's activity readout was built to remove.
+        await activity.sandboxInit();
         const sandbox = await deps.sandboxClient.createSandbox({
             runId: DATA_PROFILE_RUN_LITERAL,
             stepId: DATA_PROFILE_STEP_LITERAL,
@@ -247,13 +278,27 @@ export async function runDataProfileBody(input, deps) {
             const baseAgent = createDataProfilerAgent(sandboxAgentDeps);
             const agentDef = { ...baseAgent, tools: [...baseAgent.tools, submitProfileTool] };
             const signal = new AbortController().signal;
+            // Covers the gap between a ready sandbox and the agent's first tool call, which would
+            // otherwise still read as `Starting sandbox` long after the container was up. The run
+            // path's `Running ${agentId}` serves the same purpose at the same point.
+            await activity.agentStarting();
             await runToTerminal(agentDef, [{ role: "user", content: prompt }], childSession, {
                 provider: deps.provider,
                 signal,
-                emit: () => { },
+                // Every tool call the profiler makes becomes live activity. Only `tool-started`
+                // is forwarded: the loop's other events (iteration boundaries, model deltas,
+                // tool completions) describe machinery rather than work, and the panel this
+                // feeds carries a single line whose value is that it always names what is
+                // happening now. Awaited in body order, because `DBOS.writeStream` allocates a
+                // function id and an unawaited write would race the next operation for the
+                // counter and desynchronise the recorded sequence on replay.
+                emit: async (event) => {
+                    if (event.type === "tool-started")
+                        await activity.forTool(event.name, event.input);
+                },
                 runStep: durableStep,
-            }, {
                 resolved: () => capturedProfile !== null,
+            }, {
                 tools: [submitProfileTool],
                 nudge: "You stopped without calling submit_profile, so no profile was " +
                     "recorded. Call submit_profile now with structured metadata for " +
@@ -264,6 +309,11 @@ export async function runDataProfileBody(input, deps) {
             }
             const profilerData = capturedProfile;
             // 4. Index into vector store — real files only, consistent type metadata
+            //
+            // Reported as `indexing`, not `persisting`: the contract defines `persisting` as step
+            // bytes uploading to an artifact store, and a profile uploads nothing — its durable
+            // products are this vector index and the ledger row.
+            await activity.indexing();
             const profilerByPath = new Map(profilerData.files.map((f) => [f.path, f]));
             const normPath = (p) => p
                 .replace(/\/+/g, "/")
@@ -326,6 +376,13 @@ export async function runDataProfileBody(input, deps) {
                 logTerminalNoop(logger, analysisId, "completion");
             }
             await deps.runAuthorizer.revoke(authorization, "data-profile-completed");
+            // LAST statement of the success path, and that placement is the guarantee that exactly
+            // one terminal activity is ever emitted. Everything that could still throw — the ledger
+            // write above, the revoke — is already behind us, so any failure on the way here reaches
+            // the catch having emitted no terminal at all and reports `failed` alone. Emitted any
+            // earlier, a failing write would produce BOTH terminals and leave the fold's winner
+            // decided by arrival order. The sandbox teardown below emits nothing for the same reason.
+            await activity.complete();
         }
         finally {
             try {
@@ -338,9 +395,14 @@ export async function runDataProfileBody(input, deps) {
     }
     catch (err) {
         logger.error("profile failed", logger.errorFields(err));
-        if (!unwrapOrThrow(await failDataProfile(deps.pool, analysisId, profileFailureReason(err))))
+        const reason = profileFailureReason(err);
+        if (!unwrapOrThrow(await failDataProfile(deps.pool, analysisId, reason)))
             logTerminalNoop(logger, analysisId, "failure");
         await deps.runAuthorizer.revoke(authorization, "data-profile-failed");
+        // The same bounded, user-safe line the ledger receives — never the raw error, whose paths and
+        // stack frames stay in the log record above. This is the only other terminal emission, so
+        // reaching it means the success path did not emit one.
+        await activity.failed(reason);
     }
 }
 /**

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

@@ -28,7 +28,7 @@ export type ChemblOutput = {
     readonly targets: ChemblTarget[];
 };
 export declare const chemblTool: import("../define-tool.js").Tool<{
-    action: "targets" | "drug" | "compounds" | "mechanism" | "bioactivity";
+    action: "drug" | "targets" | "compounds" | "mechanism" | "bioactivity";
     query?: string | undefined;
     searchType?: "target" | "smiles" | "compound" | undefined;
     chemblId?: string | undefined;

package/dist/tools/bio/chembl.js

@@ -18,74 +18,74 @@ import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { getBioactivity, getDrugInfo, getMechanism, searchCompounds, searchTargets } from "../lib/chembl-client.js";
-/** Per-action record caps, preserved from the five tools this one replaces. */
+/**
+ * Per-action record caps. The ceilings are what the endpoints will serve; the
+ * defaults are deliberately far below them — 500 activity rows is ~125k
+ * characters, which answers no question that the top 25 by potency does not.
+ */
 const LIMITS = {
     /** `compounds` / `bioactivity` — activity-scale reads. */
-    wide: 500,
+    wideMax: 500,
+    wideDefault: 25,
     /** `drug` / `targets` — resolution reads, where a long list is noise. */
-    narrow: 25,
+    narrowMax: 25,
+    narrowDefault: 10,
 };
 const inputSchema = z
     .object({
     action: z
         .enum(["compounds", "drug", "mechanism", "bioactivity", "targets"])
-        .describe("Which ChEMBL lookup to run — each names the params it needs and the fields it returns.\n" +
-        "'compounds' (query + searchType) — molecules by target, name, or SMILES; resolves a named compound to its ChEMBL ID " +
-        "and structure, or lists the compounds assayed against a target. Returns chemblId, preferredCompoundName, " +
-        "canonicalSmiles, molecularWeight, alogp, molecularFormula.\n" +
-        "'drug' (query) — the drug registry by drug name or disease indication: 'what drugs treat X?', 'is Y approved, and " +
-        "since when?'. Returns moleculeChemblId, preferredName, maxPhase (4 = approved), moleculeType (small molecule, " +
-        "antibody, …), firstApproval year, indication. When the drug endpoint is empty it falls back to a molecule search " +
-        "filtered to max_phase >= 4; rows from that fallback carry indication: null.\n" +
-        "'mechanism' (chemblId) — the curated mechanism of action of ONE molecule: 'how does drug X work?'. Returns " +
-        "mechanismOfAction (prose), actionType (INHIBITOR, AGONIST, ANTAGONIST, …), targetChemblId + the resolved targetName, " +
-        "moleculeChemblId. ChEMBL curates mechanisms mainly for clinical/approved molecules, so tool compounds often have none.\n" +
-        "'bioactivity' (chemblId + idType) — measured activity rows (IC50, EC50, Ki, Kd, …): the curated, quotable potency " +
-        "data for a compound or a target. Returns standardType, standardValue + standardUnits, pchemblValue (normalized " +
-        "-log10 potency), assayChemblId, assayType, compoundChemblId, targetChemblId.\n" +
-        "'targets' (query) — resolve a gene symbol or protein name to a ChEMBL target: the step that produces the target ID " +
-        "used by bioactivity (idType='target') and compounds (searchType='target'). Returns targetChemblId, preferredName, " +
-        "targetType (SINGLE PROTEIN, PROTEIN COMPLEX, …), organism, geneNames. Results span organisms — check `organism` " +
-        "before using an ID, since the top hit for a human gene symbol may be a non-human ortholog."),
+        .describe("Which ChEMBL lookup to run; each names its params and return fields.\n" +
+        "'compounds' (query + searchType) — molecules by target, name or SMILES: resolve a named compound to its ID and structure, or list " +
+        "what was assayed against a target. → chemblId, preferredCompoundName, canonicalSmiles, molecularWeight, alogp, molecularFormula.\n" +
+        "'drug' (query) — the drug registry by drug name or indication: 'what treats X?', 'is Y approved, since when?'. → moleculeChemblId, " +
+        "preferredName, maxPhase (4 = approved), moleculeType, firstApproval, indication. If the drug endpoint is empty it falls back to a " +
+        "max_phase >= 4 molecule search, whose rows carry indication: null.\n" +
+        "'mechanism' (chemblId, molecule only) — curated mechanism of ONE molecule: 'how does X work?'. → mechanismOfAction, actionType " +
+        "(INHIBITOR, AGONIST, …), targetChemblId + targetName, moleculeChemblId. Curated mainly for clinical/approved molecules, so tool " +
+        "compounds often have none.\n" +
+        "'bioactivity' (chemblId + idType) — measured activity rows: the curated, QUOTABLE potency. → standardType, standardValue + " +
+        "standardUnits, pchemblValue (normalized -log10), assayChemblId, assayType, compoundChemblId, targetChemblId.\n" +
+        "'targets' (query) — resolve a gene symbol or protein name to a ChEMBL target, producing the ID that bioactivity (idType='target') " +
+        "and compounds (searchType='target') need. → targetChemblId, preferredName, targetType, organism, geneNames. Check `organism`: the " +
+        "top hit for a human symbol may be a non-human ortholog."),
     query: z
         .string()
         .min(1)
         .optional()
-        .describe("Required for 'compounds', 'drug', 'targets'. compounds: must match searchType — a target name/gene symbol or target " +
-        "ChEMBL ID, a compound name, or a SMILES string. drug: a drug name (e.g. 'imatinib') or a disease indication " +
-        "(e.g. 'melanoma'). targets: a gene symbol (e.g. 'EGFR', 'ABL1'), a protein name, or a ChEMBL target ID."),
+        .describe("Required for 'compounds', 'drug', 'targets'. compounds: must match searchType — a target name/gene symbol or target ChEMBL ID, a " +
+        "compound name, or a SMILES. drug: a drug name ('imatinib') or an indication ('melanoma'). targets: a gene symbol ('EGFR'), a " +
+        "protein name, or a ChEMBL target ID."),
     searchType: z
         .enum(["target", "compound", "smiles"])
         .optional()
-        .describe("Required for 'compounds' — how to read `query`. 'target': resolve it to a ChEMBL target, then return the compounds " +
-        "assayed against that target. 'compound': free-text search over molecule names. 'smiles': flexible (flexmatch) " +
-        "structure search on canonical SMILES."),
+        .describe("Required for 'compounds' — how to read `query`. 'target': resolve to a ChEMBL target, then return what was assayed against it. " +
+        "'compound': free-text over molecule names. 'smiles': flexmatch structure search."),
     chemblId: z
         .string()
         .min(1)
         .optional()
-        .describe("Required for 'mechanism' and 'bioactivity'. A ChEMBL molecule ID (e.g. 'CHEMBL25' = aspirin) or — for bioactivity " +
-        "with idType='target' — a target ID (e.g. 'CHEMBL203' = EGFR). 'mechanism' takes a molecule ID only, never a target ID."),
+        .describe("Required for 'mechanism' and 'bioactivity'. A molecule ID ('CHEMBL25' = aspirin), or — for bioactivity with idType='target' — a target " +
+        "ID ('CHEMBL203' = EGFR). 'mechanism' takes a molecule ID only."),
     idType: z
         .enum(["compound", "target"])
         .optional()
-        .describe("Required for 'bioactivity' — which side of the activity table `chemblId` indexes. 'compound': chemblId is a molecule " +
-        "ID; returns everything that molecule was assayed against. 'target': chemblId is a target ID; returns every compound " +
-        "assayed against that target."),
+        .describe("Required for 'bioactivity' — which side of the activity table `chemblId` indexes. 'compound': everything that molecule was assayed " +
+        "against. 'target': every compound assayed against that target."),
     activityType: z
         .string()
         .optional()
-        .describe("'bioactivity' only. Exact ChEMBL standard_type filter, e.g. 'IC50', 'EC50', 'Ki', 'Kd'. Matched exactly " +
-        "(case-sensitive); omit to get all activity types."),
+        .describe("'bioactivity' only. Exact, case-sensitive standard_type filter — 'IC50', 'EC50', 'Ki', 'Kd'. Omit for all types."),
     limit: z
         .number()
         .int()
         .min(1)
-        .max(LIMITS.wide)
+        .max(LIMITS.wideMax)
         .optional()
-        .describe(`Max records. 'compounds'/'bioactivity': 1–${LIMITS.wide} (default ${LIMITS.wide}). 'drug'/'targets': 1–${LIMITS.narrow} ` +
-        `(default ${LIMITS.narrow}). Ignored by 'mechanism'. With searchType='target' it caps the activity rows scanned, so ` +
-        `fewer unique compounds usually come back.`),
+        .describe(`Max records. 'compounds'/'bioactivity': 1–${LIMITS.wideMax} (default ${LIMITS.wideDefault}). 'drug'/'targets': 1–${LIMITS.narrowMax} ` +
+        `(default ${LIMITS.narrowDefault}). Ignored by 'mechanism'. Rows are UNSORTED, so raising this is the only way to widen the window — ` +
+        `do it to survey an SAR series or a full assay panel, not to browse. With searchType='target' it caps the activity rows scanned, so ` +
+        `fewer unique compounds come back.`),
 })
     .refine((d) => !(d.action === "compounds" || d.action === "drug" || d.action === "targets") || (d.query !== undefined && d.query.length > 0), {
     message: "query is required when action is 'compounds', 'drug', or 'targets'",
@@ -104,35 +104,32 @@ const inputSchema = z
     message: "idType is required when action is 'bioactivity' — 'compound' if chemblId is a molecule ID, 'target' if it is a target ID",
     path: ["idType"],
 })
-    .refine((d) => !(d.action === "drug" || d.action === "targets") || d.limit === undefined || d.limit <= LIMITS.narrow, {
-    message: `limit is capped at ${LIMITS.narrow} for action 'drug' and 'targets' (only 'compounds' and 'bioactivity' reach ${LIMITS.wide})`,
+    .refine((d) => !(d.action === "drug" || d.action === "targets") || d.limit === undefined || d.limit <= LIMITS.narrowMax, {
+    message: `limit is capped at ${LIMITS.narrowMax} for action 'drug' and 'targets' (only 'compounds' and 'bioactivity' reach ${LIMITS.wideMax})`,
     path: ["limit"],
 });
 export const chemblTool = defineTool({
     id: "chembl",
-    description: "ChEMBL — the manually curated database of drug-like bioactives (~2.4M compounds), the targets they were measured " +
-        "against, their mechanisms, and their approval status. One tool, five lookups; pick with `action` (its description gives " +
-        "each action's params and return fields).\n" +
-        "IDs are resolved, never guessed: a `chemblId` comes from a prior action='compounds'/'drug' (molecule IDs) or action='targets' " +
-        "(target IDs) call, or from pubchem action='crossrefs' — a compound or gene name is not a ChEMBL ID.\n" +
-        "ChEMBL is curated, so prefer it over PubChem for anything you will quote or build on: use action='bioactivity' rather than " +
-        "pubchem action='assays' whenever you will quote a number (PubChem assay summaries are broader HTS screening outcomes), and resolve " +
-        "compounds here first. If ChEMBL does not find the compound, resolve it in PubChem with pubchem action='compound' and bridge back " +
-        "to a ChEMBL ID via pubchem action='crossrefs'.\n" +
-        "An empty array is a valid 'no match' / no-data answer, not an error — do not retry the same call.",
+    description: "ChEMBL — the manually curated database of drug-like bioactives (~2.4M compounds), the targets they were measured against, their mechanisms and " +
+        "their approval status. Five lookups; pick with `action`, which gives each one's params and return fields.\n" +
+        "IDs are resolved, never guessed: a `chemblId` comes from a prior action='compounds'/'drug' (molecules) or action='targets' (targets), or from " +
+        "pubchem action='crossrefs'. A compound or gene name is not a ChEMBL ID.\n" +
+        "Being curated, ChEMBL is what you quote from: prefer action='bioactivity' over pubchem action='assays' for any number you will cite, and resolve " +
+        "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,
     execute: async ({ action, query, searchType, chemblId, idType, activityType, limit }) => {
         switch (action) {
             case "compounds":
-                return ok({ compounds: await searchCompounds(query, searchType, limit ?? LIMITS.wide) });
+                return ok({ compounds: await searchCompounds(query, searchType, limit ?? LIMITS.wideDefault) });
             case "drug":
-                return ok({ drugs: await getDrugInfo(query, limit ?? LIMITS.narrow) });
+                return ok({ drugs: await getDrugInfo(query, limit ?? LIMITS.narrowDefault) });
             case "mechanism":
                 return ok({ mechanisms: await getMechanism(chemblId) });
             case "bioactivity":
-                return ok({ activities: await getBioactivity(chemblId, idType, { activityType, limit: limit ?? LIMITS.wide }) });
+                return ok({ activities: await getBioactivity(chemblId, idType, { activityType, limit: limit ?? LIMITS.wideDefault }) });
             case "targets":
-                return ok({ targets: await searchTargets(query, limit ?? LIMITS.narrow) });
+                return ok({ targets: await searchTargets(query, limit ?? LIMITS.narrowDefault) });
         }
     },
 });