@inflexa-ai/harness 0.12.0 → 0.14.0

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/__fixtures__/tool-context.js

@@ -9,6 +9,7 @@ export function makeToolContext(signal) {
     const emitted = [];
     const deny = new UnavailableAsk();
     const ctx = {
+        invocationId: "test-tool-call",
         session: makeSession(),
         signal: signal ?? new AbortController().signal,
         emit: (event) => {

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

@@ -0,0 +1,31 @@
+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";
+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";
+export interface AdHocRoute {
+    readonly agentId: string;
+    readonly resources: ResourceSpec;
+    readonly rationale: string;
+    readonly fallbackClass?: "timeout" | "provider_error" | "malformed" | "no_match" | "invalid_agent" | "invalid_resources";
+}
+export interface AdHocRouterDeps {
+    readonly provider: ChatProvider;
+    readonly model: string;
+    readonly pool: Pool;
+    readonly resourcePolicy?: ResourcePolicy;
+    readonly logger?: Logger;
+    /** Test seam; production always uses {@link AD_HOC_ROUTER_TIMEOUT_MS}. */
+    readonly timeoutMs?: number;
+}
+export declare function defaultAdHocResources(policy?: ResourcePolicy): ResourceSpec;
+export declare function validAdHocResources(value: unknown, policy?: ResourcePolicy): ResourceSpec | null;
+export declare function routeAdHocRequest(deps: AdHocRouterDeps, input: {
+    analysisId: string;
+    request: string;
+    session: AgentSession;
+    signal: AbortSignal;
+}): Promise<AdHocRoute>;

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

@@ -0,0 +1,132 @@
+import { jsonSchema, tool as aiTool } from "ai";
+import { z } from "zod";
+import { PLANNABLE_AGENT_CATALOG } from "../agents/sandbox-catalog.js";
+import { forSubAgent } from "../auth/types.js";
+import { DATA_PROFILE_ORIENTATION_MAX_CHARS, buildDataProfileOrientation } from "../app/data-profile-orientation.js";
+import { createNoopLogger } from "../lib/console-logger.js";
+import { unwrapOrThrow } from "../lib/result.js";
+import { resourceEstimationSection } from "../prompts/planner.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;
+export const AD_HOC_FALLBACK_AGENT_ID = "scientific-executor";
+const resourcesSchema = z.object({
+    cpu: z.number().positive(),
+    memoryGb: z.number().positive(),
+    gpu: z.object({ count: z.number().int().positive() }).optional(),
+});
+const routeSchema = z.object({
+    agentId: z.string().optional(),
+    resources: resourcesSchema.optional(),
+    rationale: z.string().optional(),
+});
+export function defaultAdHocResources(policy) {
+    return policy ? { cpu: Math.min(4, policy.perStep.maxCpu), memoryGb: Math.min(8, policy.perStep.maxMemoryGb) } : { cpu: 4, memoryGb: 8 };
+}
+export function validAdHocResources(value, policy) {
+    const parsed = resourcesSchema.safeParse(value);
+    if (!parsed.success)
+        return null;
+    const r = parsed.data;
+    const maxCpu = policy?.perStep.maxCpu ?? 4;
+    const maxMemoryGb = policy?.perStep.maxMemoryGb ?? 8;
+    const maxGpuCount = policy?.perStep.maxGpuCount ?? 0;
+    if (r.cpu > maxCpu || r.memoryGb > maxMemoryGb || (r.gpu?.count ?? 0) > maxGpuCount)
+        return null;
+    return r;
+}
+function resourceBounds(policy) {
+    const defaults = defaultAdHocResources(policy);
+    if (!policy) {
+        return `CPU range 1..${defaults.cpu}; default ${defaults.cpu}. Memory range 1..${defaults.memoryGb} GB; default ${defaults.memoryGb}. GPU range 0..0.`;
+    }
+    const { perStep } = policy;
+    return [
+        `CPU range ${Math.min(1, perStep.maxCpu)}..${perStep.maxCpu}; default ${defaults.cpu}.`,
+        `Memory range ${Math.min(1, perStep.maxMemoryGb)}..${perStep.maxMemoryGb} GB; default ${defaults.memoryGb}.`,
+        `GPU range 0..${perStep.maxGpuCount}; omit gpu unless required.`,
+    ].join(" ");
+}
+async function profileOrientation(pool, analysisId, logger) {
+    try {
+        const status = unwrapOrThrow(await loadDataProfileStatus(pool, analysisId));
+        if (!status?.result)
+            return "No persisted data-profile facts are available.";
+        return buildDataProfileOrientation(status.result, DATA_PROFILE_ORIENTATION_MAX_CHARS);
+    }
+    catch (error) {
+        logger.warn("could not load data profile for ad hoc routing", { error: error instanceof Error ? error.message : String(error) });
+        return "The persisted data profile could not be loaded; route from the request alone.";
+    }
+}
+function routeTool() {
+    return {
+        submit_route: aiTool({
+            description: "Submit the single specialist and resource recommendation. This is the only valid response.",
+            inputSchema: jsonSchema(z.toJSONSchema(routeSchema)),
+        }),
+    };
+}
+export async function routeAdHocRequest(deps, input) {
+    const logger = (deps.logger ?? createNoopLogger()).named("adhoc-router").with({ analysisId: input.analysisId, model: deps.model });
+    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 signal = AbortSignal.any([input.signal, controller.signal]);
+    let raw;
+    let failure;
+    try {
+        const response = unwrapOrThrow(await deps.provider.chat({
+            system: [
+                "Select exactly one specialist for a targeted one-step analysis and estimate its sandbox resources.",
+                "Choose only from the supplied catalog. Do not create a plan, reject the request, or select scientific-executor.",
+                resourceEstimationSection(deps.resourcePolicy),
+                resourceBounds(deps.resourcePolicy),
+                "Respond only by calling submit_route.",
+            ].join("\n\n"),
+            messages: [
+                {
+                    role: "user",
+                    content: `Request:\n${input.request}\n\nPersisted data-profile orientation:\n${orientation}\n\nEligible specialists:\n${catalog}`,
+                },
+            ],
+            tools: routeTool(),
+            toolChoice: { type: "tool", toolName: "submit_route" },
+        }, forSubAgent(input.session, AD_HOC_ROUTER_AGENT_ID), signal));
+        const call = Array.isArray(response.message.content)
+            ? response.message.content.find((part) => part.type === "tool-call" && part.toolName === "submit_route")
+            : undefined;
+        raw = call?.input;
+        if (!call)
+            failure = "malformed";
+    }
+    catch (error) {
+        if (input.signal.aborted)
+            throw error;
+        failure = controller.signal.aborted && !input.signal.aborted ? "timeout" : "provider_error";
+        logger.warn("ad hoc route fell back", { failure, error: error instanceof Error ? error.message : String(error) });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const candidate = raw !== null && typeof raw === "object" ? raw : {};
+    const requestedAgent = typeof candidate.agentId === "string" ? candidate.agentId : undefined;
+    const validAgent = requestedAgent !== undefined && PLANNABLE_AGENT_CATALOG.some((agent) => agent.id === requestedAgent);
+    const agentId = validAgent ? requestedAgent : AD_HOC_FALLBACK_AGENT_ID;
+    if (!failure && !requestedAgent)
+        failure = "no_match";
+    if (!failure && !validAgent)
+        failure = "invalid_agent";
+    const validResources = validAdHocResources(candidate.resources, deps.resourcePolicy);
+    const resources = validResources ?? defaultAdHocResources(deps.resourcePolicy);
+    if (!validResources && candidate.resources !== undefined && !failure)
+        failure = "invalid_resources";
+    const rationale = typeof candidate.rationale === "string" && candidate.rationale.trim()
+        ? candidate.rationale.trim()
+        : failure
+            ? `Deterministic fallback: ${failure}`
+            : `Selected ${agentId}`;
+    logger.info("ad hoc route selected", { agentId, resources, rationale, failure });
+    return { agentId, resources, rationale, ...(failure ? { fallbackClass: failure } : {}) };
+}

package/dist/tools/analysis-invocation.d.ts

@@ -0,0 +1,4 @@
+/** Deterministic internal plan id in the existing persistence shape. */
+export declare function adHocPlanId(analysisId: string, invocationId: string): string;
+/** Deterministic RFC-4122 UUID used as both cortex run id and DBOS workflow id. */
+export declare function adHocRunId(analysisId: string, invocationId: string): string;

package/dist/tools/analysis-invocation.js

@@ -0,0 +1,17 @@
+import { createHash } from "node:crypto";
+const TOOL_ID = "execute_analysis";
+function digest(analysisId, invocationId) {
+    return createHash("sha256").update(`${TOOL_ID}\0${analysisId}\0${invocationId}`, "utf8").digest();
+}
+/** Deterministic internal plan id in the existing persistence shape. */
+export function adHocPlanId(analysisId, invocationId) {
+    return `pln-${digest(analysisId, invocationId).toString("hex", 0, 4)}`;
+}
+/** Deterministic RFC-4122 UUID used as both cortex run id and DBOS workflow id. */
+export function adHocRunId(analysisId, invocationId) {
+    const bytes = Buffer.from(digest(analysisId, invocationId).subarray(4, 20));
+    bytes[6] = (bytes[6] & 0x0f) | 0x50;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = bytes.toString("hex");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

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) });
         }
     },
 });