@inflexa-ai/harness 0.1.1 → 0.3.0

package/dist/state/index.js

@@ -8,7 +8,7 @@
  */
 export { initCortexState } from "./init.js";
 export { upsertAnalysis, resolveAnalysisBilling, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.js";
-export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
+export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
 export { insertRun, RunDedupCollisionError, updateRunStatus, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
 queryRun, queryActiveRun, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";

package/dist/state/init.d.ts

@@ -7,8 +7,9 @@
  * simultaneous startups don't race on DDL.
  */
 import type { Pool } from "pg";
+import type { Logger } from "../lib/logger.js";
 /**
  * Initialize Cortex state tables. Safe to call on every startup and across
  * concurrent replicas (advisory lock serializes the init flow).
  */
-export declare function initCortexState(pool: Pool): Promise<void>;
+export declare function initCortexState(pool: Pool, injected?: Logger): Promise<void>;

package/dist/state/init.js

@@ -7,6 +7,7 @@
  * simultaneous startups don't race on DDL.
  */
 import { backfillAiSdkMessageEnvelopes } from "../memory/message-backfill.js";
+import { createNoopLogger } from "../lib/console-logger.js";
 const DDL = `
 -- Analysis-level state (status, context, data-profile tracking, billing identity).
 --
@@ -245,7 +246,8 @@ CREATE TABLE IF NOT EXISTS cortex_working_memory (
  * Initialize Cortex state tables. Safe to call on every startup and across
  * concurrent replicas (advisory lock serializes the init flow).
  */
-export async function initCortexState(pool) {
+export async function initCortexState(pool, injected) {
+    const logger = (injected ?? createNoopLogger()).named("cortex-state");
     const client = await pool.connect();
     try {
         // Serialize concurrent replica startups — cheap, no extra tooling.
@@ -381,11 +383,8 @@ export async function initCortexState(pool) {
            WITH (m = 16, ef_construction = 64)`);
             }
             catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                console.warn(`[state-init] Could not create HNSW index on cortex_regulatory_chunks.embedding ` +
-                    `(pgvector < 0.5.0 or operator class unavailable): ${msg}. ` +
-                    `Cosine similarity queries will fall back to sequential scan. ` +
-                    `Upgrade pgvector and re-run init to get the ANN index.`);
+                logger.warn("could not create HNSW index on cortex_regulatory_chunks.embedding (pgvector < 0.5.0 or operator class unavailable) — " +
+                    "cosine similarity queries fall back to sequential scan; upgrade pgvector and re-run init to get the ANN index", logger.errorFields(err));
             }
             // No boot-time orphan sweep on cortex_runs / cortex_step_executions.
             // Every running row is backed by a DBOS workflow (executeAnalysis,

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

@@ -21,13 +21,17 @@ import { type AuthContext, type RunSession } from "../auth/types.js";
 import type { RunAuthorization, RunAuthorizer } from "../execution/run-authorizer.js";
 import type { StagedInput } from "../execution/staged-input.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
+import type { Logger } from "../lib/logger.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { SandboxClient } from "../sandbox/client.js";
 import type { WorkspaceFilesystem } from "../workspace/filesystem.js";
-import type { ResolveWorkspaceRoot } from "../workspace/paths.js";
-import { type DataProfileInputFile } from "../state/index.js";
+import { type ResolveWorkspaceRoot } from "../workspace/paths.js";
+import { type ProfilerOutput } from "../schemas/data-profile-schemas.js";
+import { type DataProfileInputFile, type DataProfileResult } from "../state/index.js";
 /** The body's construction-time deps — closed over at registration. */
 export interface DataProfileDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly provider: ChatProvider;
     readonly pool: Pool;
     readonly sandboxClient: SandboxClient;
@@ -93,6 +97,23 @@ export interface DataProfileWorkflowInput {
  * The cast defeats the required-`number` type precisely to observe that legacy gap.
  */
 export declare function buildDriftSignature(stagedInputs: readonly StagedInput[]): DataProfileInputFile[] | undefined;
+/**
+ * Project the profiler's structured output plus the staged manifest into the record
+ * persisted on `cortex_analysis_state`.
+ *
+ * That row is the profile's ONLY durable home — the profiler's `runs/data-profile/`
+ * scratch tree is deleted on completion, so nothing here is recoverable from a file
+ * later. The projection is therefore total: every field the profiler reported is
+ * carried through verbatim. A field this drops is not "summarized away", it is
+ * destroyed, and the next agent that needs it can only get it back by re-reading the
+ * raw inputs.
+ *
+ * `undefined` members are dropped by `JSON.stringify` on the way into the jsonb
+ * column, so an optional the profiler left unset simply does not appear in the row —
+ * indistinguishable from a legacy snapshot that predates the field, which is exactly
+ * the reading a consumer must already tolerate.
+ */
+export declare function buildDataProfileResult(profile: ProfilerOutput, stagedInputs: readonly StagedInput[], profiledAt: string): DataProfileResult;
 /**
  * Register the data-profile workflow with DBOS. Returns the registered
  * callable so `triggerDataProfile` can dispatch via `DBOS.startWorkflow`.
@@ -112,6 +133,8 @@ export type DataProfileTriggerResult = "started" | "restarted" | "already_runnin
  * (`registerDataProfileWorkflow`); the route never holds them.
  */
 export interface DataProfileTriggerDeps {
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
     readonly pool: Pool;
     readonly runAuthorizer: RunAuthorizer;
     readonly workflow: (input: DataProfileWorkflowInput) => Promise<void>;

package/dist/tasks/data-profile.js

@@ -23,8 +23,11 @@ import { forSubAgent } from "../auth/types.js";
 import { createDataProfilerAgent } from "../agents/sandbox/data-profiler.js";
 import { runToTerminal } from "../loop/run-to-terminal.js";
 import { durableStep } from "../loop/run-step.js";
+import { createNoopLogger } from "../lib/console-logger.js";
 import { unwrapOrThrow } from "../lib/result.js";
 import { defineTool } from "../tools/define-tool.js";
+import { renderWorkspace } from "../prompts/briefing.js";
+import { toSandboxPath } from "../workspace/paths.js";
 import { estimateDataProfileResources } from "../sandbox/estimate-data-profile-resources.js";
 import { generateExecutionId } from "../sandbox/execution-id.js";
 import { mintSandboxIdentity } from "../sandbox/identity.js";
@@ -69,6 +72,50 @@ export function buildDriftSignature(stagedInputs) {
         return undefined;
     return stagedInputs.map((f) => ({ fileId: f.fileId, size: f.size, mtimeMs: mtimeOf(f) }));
 }
+/**
+ * Project the profiler's structured output plus the staged manifest into the record
+ * persisted on `cortex_analysis_state`.
+ *
+ * That row is the profile's ONLY durable home — the profiler's `runs/data-profile/`
+ * scratch tree is deleted on completion, so nothing here is recoverable from a file
+ * later. The projection is therefore total: every field the profiler reported is
+ * carried through verbatim. A field this drops is not "summarized away", it is
+ * destroyed, and the next agent that needs it can only get it back by re-reading the
+ * raw inputs.
+ *
+ * `undefined` members are dropped by `JSON.stringify` on the way into the jsonb
+ * column, so an optional the profiler left unset simply does not appear in the row —
+ * indistinguishable from a legacy snapshot that predates the field, which is exactly
+ * the reading a consumer must already tolerate.
+ */
+export function buildDataProfileResult(profile, stagedInputs, profiledAt) {
+    return {
+        summary: profile.analysisSummary,
+        files: profile.files.map((f) => ({
+            path: f.path,
+            description: f.description,
+            dataType: f.dataType,
+            format: f.format,
+            rows: f.rows,
+            cols: f.cols,
+            tags: f.tags,
+            warnings: f.warnings,
+            metrics: f.metrics,
+        })),
+        inputFileIds: stagedInputs.map((f) => f.fileId),
+        inputFiles: buildDriftSignature(stagedInputs),
+        profiledAt,
+        domain: profile.domain,
+        subtype: profile.subtype,
+        organism: profile.organism,
+        tissue: profile.tissue,
+        cellType: profile.cellType,
+        condition: profile.condition,
+        accessions: profile.accessions,
+        experimentalDesign: profile.experimentalDesign,
+        qualityAssessment: profile.qualityAssessment,
+    };
+}
 /**
  * Register the data-profile workflow with DBOS. Returns the registered
  * callable so `triggerDataProfile` can dispatch via `DBOS.startWorkflow`.
@@ -82,6 +129,7 @@ export function registerDataProfileWorkflow(deps) {
  * 'failed' on error, and revokes the run authorization on every terminal path.
  */
 export async function runDataProfileBody(input, deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("data-profile").with({ analysisId: input.analysisId });
     // Ownership defaults to true for inputs persisted before the field existed
     // (a #247 workflow recovered across this deploy): those were always
     // Cortex-owned and must be revoked here.
@@ -92,9 +140,9 @@ export async function runDataProfileBody(input, deps) {
         // embedder populated the tree and handed us this manifest in the workflow
         // input. The body never downloads.
         if (stagedInputs.length === 0) {
-            console.warn(`[data-profile] No input files staged for ${analysisId}`);
+            logger.warn("no input files staged");
             if (!unwrapOrThrow(await completeDataProfile(deps.pool, analysisId)))
-                logTerminalNoop(analysisId, "completion");
+                logTerminalNoop(logger, analysisId, "completion");
             await deps.runAuthorizer.revoke(authorization, "data-profile-completed");
             return;
         }
@@ -108,15 +156,33 @@ export async function runDataProfileBody(input, deps) {
             fileId: f.fileId,
         })));
         // 3. Run data-profiler sandbox agent
+        const executionId = generateExecutionId(DATA_PROFILE_AGENT_ID);
+        const workflowId = DBOS.workflowID ?? `${DATA_PROFILE_RUN_LITERAL}:${executionId}`;
+        const childSession = forSubAgent(runSession, DATA_PROFILE_AGENT_ID);
+        // A resolver throw fails the workflow loudly (workspace-root-resolution
+        // contract) — profiling an analysis whose root cannot be resolved is
+        // meaningless, so no softer handling is warranted.
+        const workspaceRoot = deps.resolveWorkspaceRoot(analysisId);
+        const profileWritePrefix = `${workspaceRoot}/runs/${DATA_PROFILE_RUN_LITERAL}/${DATA_PROFILE_STEP_LITERAL}`;
         const fileList = stagedInputs.map((f) => inputArtifactPath(f));
+        // The profiler runs outside `executeAnalysis`, so no scheduler composes a
+        // briefing for it — this prompt IS its briefing, and the sandbox system
+        // prompt names no paths (it is static per agent type, for the prompt cache).
+        // Its workspace frame therefore has to be stated here, in the same words the
+        // step briefing uses.
         const prompt = [
             `Profile all input data files for this analysis.`,
             ``,
+            renderWorkspace({
+                analysisRoot: `/${analysisId}`,
+                workingDir: toSandboxPath(workspaceRoot, analysisId, profileWritePrefix),
+            }),
+            ``,
             `IMPORTANT: You MUST use execute_command to profile files before submitting results. Do NOT submit empty files or placeholder text.`,
             ``,
-            `CRITICAL: File and directory paths may contain spaces. You MUST always double-quote paths in shell commands (e.g. head "data/inputs/My Folder/file.csv"). Unquoted paths with spaces will silently break commands.`,
+            `CRITICAL: File and directory paths may contain spaces. You MUST always double-quote paths in shell commands (e.g. head "/${analysisId}/data/inputs/My Folder/file.csv"). Unquoted paths with spaces will silently break commands.`,
             ``,
-            `The following input files are available (paths relative to analysis root):`,
+            `The following input files are available (paths relative to the analysis root):`,
             ...fileList.map((f) => `- ${f}`),
             ``,
             `Steps:`,
@@ -124,16 +190,9 @@ export async function runDataProfileBody(input, deps) {
             `2. Write a Python script for detailed profiling — use pathlib or os.path for path handling (handles spaces natively)`,
             `3. Call the \`submit_profile\` tool with structured metadata for EVERY file listed above`,
             ``,
-            `The analysis root is mounted at /${analysisId}/. All file paths in your response must be relative to the analysis root and must EXACTLY match the paths listed above.`,
+            `All file paths in your response must be relative to the analysis root and must EXACTLY match the paths listed above.`,
         ].join("\n");
-        const executionId = generateExecutionId(DATA_PROFILE_AGENT_ID);
-        const workflowId = DBOS.workflowID ?? `${DATA_PROFILE_RUN_LITERAL}:${executionId}`;
-        const childSession = forSubAgent(runSession, DATA_PROFILE_AGENT_ID);
-        // A resolver throw fails the workflow loudly (workspace-root-resolution
-        // contract) — profiling an analysis whose root cannot be resolved is
-        // meaningless, so no softer handling is warranted.
-        const workspaceRoot = deps.resolveWorkspaceRoot(analysisId);
-        console.log(`[data-profile] execution=${executionId} analysis=${analysisId} starting sandbox`);
+        logger.info("starting sandbox", { executionId });
         const sandbox = await deps.sandboxClient.createSandbox({
             runId: DATA_PROFILE_RUN_LITERAL,
             stepId: DATA_PROFILE_STEP_LITERAL,
@@ -168,7 +227,7 @@ export async function runDataProfileBody(input, deps) {
                     // The profiler writes Python scripts and intermediate artifacts under
                     // the synthetic step path; the post-agent `rm -rf runs/data-profile/`
                     // cleanup wipes them.
-                    allowedWritePrefix: `${workspaceRoot}/runs/${DATA_PROFILE_RUN_LITERAL}/${DATA_PROFILE_STEP_LITERAL}`,
+                    allowedWritePrefix: profileWritePrefix,
                     nextFunctionId,
                     deadlineMs: () => deadlineAbs,
                 },
@@ -253,21 +312,16 @@ export async function runDataProfileBody(input, deps) {
                 indexed++;
             }
             if (fallbackCount > 0) {
-                console.warn(`[data-profile] ${fallbackCount}/${stagedInputs.length} input file(s) used a deterministic fallback description (analysis=${analysisId}) — profiler omitted them`);
+                logger.warn("input file(s) used a deterministic fallback description — profiler omitted them", {
+                    fallbackCount,
+                    stagedCount: stagedInputs.length,
+                });
             }
-            console.log(`[data-profile] Indexed ${indexed} file(s) for ${analysisId}`);
-            // 5. Complete — store result with input snapshot for staleness detection.
-            if (!unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, {
-                summary: profilerData.analysisSummary,
-                files: profilerData.files.map((f) => ({
-                    path: f.path,
-                    description: f.description,
-                })),
-                inputFileIds: stagedInputs.map((f) => f.fileId),
-                inputFiles: buildDriftSignature(stagedInputs),
-                profiledAt: new Date().toISOString(),
-            }))) {
-                logTerminalNoop(analysisId, "completion");
+            logger.info("indexed file(s)", { indexed });
+            // 5. Complete — store the FULL profiler finding plus the input snapshot for
+            // staleness detection. The scratch tree is gone; this row is all that survives.
+            if (!unwrapOrThrow(await completeDataProfile(deps.pool, analysisId, buildDataProfileResult(profilerData, stagedInputs, new Date().toISOString())))) {
+                logTerminalNoop(logger, analysisId, "completion");
             }
             await deps.runAuthorizer.revoke(authorization, "data-profile-completed");
         }
@@ -276,14 +330,14 @@ export async function runDataProfileBody(input, deps) {
                 await deps.sandboxClient.teardown(sandbox);
             }
             catch (teardownErr) {
-                console.warn(`[data-profile] execution=${executionId} teardown failed (non-fatal):`, teardownErr);
+                logger.warn("teardown failed (non-fatal)", { executionId, ...logger.errorFields(teardownErr) });
             }
         }
     }
     catch (err) {
-        console.error(`[data-profile] Failed for ${analysisId}:`, err);
+        logger.error("profile failed", logger.errorFields(err));
         if (!unwrapOrThrow(await failDataProfile(deps.pool, analysisId, profileFailureReason(err))))
-            logTerminalNoop(analysisId, "failure");
+            logTerminalNoop(logger, analysisId, "failure");
         await deps.runAuthorizer.revoke(authorization, "data-profile-failed");
     }
 }
@@ -293,8 +347,8 @@ export async function runDataProfileBody(input, deps) {
  * there is no `running` row to stamp. Not an error — the ledger correctly moved
  * on; the workflow still revokes its own authorization on the same terminal path.
  */
-function logTerminalNoop(analysisId, write) {
-    console.warn(`[data-profile] ${write} write skipped for ${analysisId}: ledger row not running (cleared or expired concurrently)`);
+function logTerminalNoop(logger, analysisId, write) {
+    logger.warn("terminal write skipped: ledger row not running (cleared or expired concurrently)", { analysisId, write });
 }
 /**
  * Resolve the `RunSession` the workflow runs under. Whether the authorization
@@ -360,6 +414,7 @@ async function startDataProfileWorkflow(deps, params) {
  * Returns what happened, so the caller can surface it (e.g. in the seed response).
  */
 export async function triggerDataProfile(deps, params) {
+    const logger = (deps.logger ?? createNoopLogger()).named("data-profile").with({ analysisId: params.analysisId });
     const { analysisId } = params;
     try {
         // ADVISORY pre-check, not the enforcement — the claim CAS carries the same seed
@@ -371,7 +426,7 @@ export async function triggerDataProfile(deps, params) {
         // a NULL-seed row (`loadDataProfileStatus` would hide the seed of a cleared row).
         const seeded = unwrapOrThrow(await loadSeedInputFileIds(deps.pool, analysisId));
         if (seeded === null || seeded.length === 0) {
-            console.error(`[data-profile] Trigger rejected for ${analysisId}: no seeded input set (missing analysis row or caller skipped seeding)`);
+            logger.error("trigger rejected: no seeded input set (missing analysis row or caller skipped seeding)");
             return "failed";
         }
         // The trigger validates the ledger seed above; it must also validate the manifest
@@ -380,7 +435,7 @@ export async function triggerDataProfile(deps, params) {
         // NULL result while the seed still names files, an incoherence a staleness policy
         // then loops on re-triggering. Refuse the divergence before any claim.
         if (params.stagedInputs.length === 0) {
-            console.error(`[data-profile] Trigger rejected for ${analysisId}: empty manifest dispatched against a seed naming ${seeded.length} file(s)`);
+            logger.error("trigger rejected: empty manifest dispatched against a non-empty seed", { seededCount: seeded.length });
             return "failed";
         }
         const started = unwrapOrThrow(await tryStartDataProfile(deps.pool, analysisId));
@@ -399,7 +454,7 @@ export async function triggerDataProfile(deps, params) {
         return "failed";
     }
     catch (err) {
-        console.error(`[data-profile] Trigger error for ${analysisId}:`, err);
+        logger.error("trigger error", logger.errorFields(err));
         return "failed";
     }
 }
@@ -413,17 +468,18 @@ export async function triggerDataProfile(deps, params) {
  * there is no further channel to report it on.
  */
 async function compensateStartFailure(deps, analysisId, phase, err) {
-    console.error(`[data-profile] ${phase} error for ${analysisId}:`, err);
+    const logger = (deps.logger ?? createNoopLogger()).named("data-profile").with({ analysisId });
+    logger.error("start failed", { phase, ...logger.errorFields(err) });
     const failed = await failDataProfile(deps.pool, analysisId, profileFailureReason(err));
     if (failed.isErr()) {
-        console.error(`[data-profile] Failed to mark ${analysisId} failed after a start error:`, failed.error);
+        logger.error("failed to mark failed after a start error", { phase, err: failed.error });
     }
     else if (!failed.value) {
         // The row this compensation was written to fail is no longer `running` — a
         // concurrent clear/expire already moved it on, so the running-CAS refused the
         // stamp. Nothing wedged at `running`, which is the outcome compensation exists
         // to guarantee; just record the no-op.
-        logTerminalNoop(analysisId, "compensation");
+        logTerminalNoop(logger, analysisId, "compensation");
     }
 }
 /**

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

@@ -0,0 +1,38 @@
+/**
+ * chembl — one tool over the five ChEMBL lookups: compounds, drugs, mechanisms,
+ * bioactivity, targets. "Which database" is the routing decision worth a tool
+ * boundary; "which ChEMBL endpoint" is mechanical, so it rides in `action`.
+ *
+ * The input is a flat object with an `action` discriminator — not a
+ * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs a
+ * top-level `"type":"object"`). Every per-action parameter is therefore optional
+ * in the schema and made conditionally required by `.refine` instead: a
+ * malformed call (a `mechanism` with no `chemblId`, a `bioactivity` with no
+ * `idType`) fails validation at the loop boundary and comes back to the model as
+ * an `is_error` tool result naming the missing field, without reaching `execute`.
+ *
+ * All request logic is the shared ChEMBL client (`tools/lib/chembl-client.ts`);
+ * this file is the routing and the model-facing contract.
+ */
+import type { ChemblActivity, ChemblCompound, ChemblDrug, ChemblMechanism, ChemblTarget } from "../lib/chembl-client.js";
+/** One result shape per action — the key names the records it carries. */
+export type ChemblOutput = {
+    readonly compounds: ChemblCompound[];
+} | {
+    readonly drugs: ChemblDrug[];
+} | {
+    readonly mechanisms: ChemblMechanism[];
+} | {
+    readonly activities: ChemblActivity[];
+} | {
+    readonly targets: ChemblTarget[];
+};
+export declare const chemblTool: import("../define-tool.js").Tool<{
+    action: "targets" | "drug" | "compounds" | "mechanism" | "bioactivity";
+    query?: string | undefined;
+    searchType?: "target" | "smiles" | "compound" | undefined;
+    chemblId?: string | undefined;
+    idType?: "target" | "compound" | undefined;
+    activityType?: string | undefined;
+    limit?: number | undefined;
+}, ChemblOutput>;

package/dist/tools/bio/chembl.js

@@ -0,0 +1,138 @@
+/**
+ * chembl — one tool over the five ChEMBL lookups: compounds, drugs, mechanisms,
+ * bioactivity, targets. "Which database" is the routing decision worth a tool
+ * boundary; "which ChEMBL endpoint" is mechanical, so it rides in `action`.
+ *
+ * The input is a flat object with an `action` discriminator — not a
+ * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs a
+ * top-level `"type":"object"`). Every per-action parameter is therefore optional
+ * in the schema and made conditionally required by `.refine` instead: a
+ * malformed call (a `mechanism` with no `chemblId`, a `bioactivity` with no
+ * `idType`) fails validation at the loop boundary and comes back to the model as
+ * an `is_error` tool result naming the missing field, without reaching `execute`.
+ *
+ * All request logic is the shared ChEMBL client (`tools/lib/chembl-client.ts`);
+ * this file is the routing and the model-facing contract.
+ */
+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. */
+const LIMITS = {
+    /** `compounds` / `bioactivity` — activity-scale reads. */
+    wide: 500,
+    /** `drug` / `targets` — resolution reads, where a long list is noise. */
+    narrow: 25,
+};
+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."),
+    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."),
+    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."),
+    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."),
+    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."),
+    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."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(LIMITS.wide)
+        .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.`),
+})
+    .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'",
+    path: ["query"],
+})
+    .refine((d) => d.action !== "compounds" || d.searchType !== undefined, {
+    message: "searchType is required when action is 'compounds' — 'target', 'compound', or 'smiles', matching what `query` holds",
+    path: ["searchType"],
+})
+    .refine((d) => !(d.action === "mechanism" || d.action === "bioactivity") || (d.chemblId !== undefined && d.chemblId.length > 0), {
+    message: "chemblId is required when action is 'mechanism' or 'bioactivity' — a ChEMBL ID, not a name. " +
+        "Resolve it first: action='compounds' or 'drug' for a molecule ID, action='targets' for a target ID.",
+    path: ["chemblId"],
+})
+    .refine((d) => d.action !== "bioactivity" || d.idType !== undefined, {
+    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})`,
+    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.",
+    inputSchema,
+    execute: async ({ action, query, searchType, chemblId, idType, activityType, limit }) => {
+        switch (action) {
+            case "compounds":
+                return ok({ compounds: await searchCompounds(query, searchType, limit ?? LIMITS.wide) });
+            case "drug":
+                return ok({ drugs: await getDrugInfo(query, limit ?? LIMITS.narrow) });
+            case "mechanism":
+                return ok({ mechanisms: await getMechanism(chemblId) });
+            case "bioactivity":
+                return ok({ activities: await getBioactivity(chemblId, idType, { activityType, limit: limit ?? LIMITS.wide }) });
+            case "targets":
+                return ok({ targets: await searchTargets(query, limit ?? LIMITS.narrow) });
+        }
+    },
+});

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

@@ -0,0 +1,50 @@
+/**
+ * comptox — the single EPA CompTox (CTX) tool: ToxCast/Tox21 bioactivity,
+ * in-vivo hazard, chemical identity + physchem, and exposure behind one
+ * `dataset` discriminator.
+ *
+ * All four datasets key off the same chemical resolution and the same
+ * EPA_CCTE_API_KEY, so the key contract is stated once in the description
+ * rather than four times.
+ *
+ * The input is a flat object with a `dataset` discriminator — not a
+ * `z.discriminatedUnion`, which `defineTool` rejects (the model needs a
+ * top-level `"type":"object"`). `dataType` and `limit` mean different things
+ * per dataset, so `.refine` guards reject a value that belongs to another
+ * dataset (a 'toxval' under dataset 'exposure' would otherwise silently fetch
+ * nothing) and a limit above the dataset's own ceiling.
+ */
+import { type ChemicalDetail, type CtxExposureData, type CtxHazardData, type PropertySummary, type ToxcastBioactivity } from "../lib/ctx-ops.js";
+type ComptoxOutput = {
+    found: false;
+    query: string;
+} | {
+    found: true;
+    chemical: {
+        dtxsid: string;
+        preferredName: string;
+        casrn: string | null;
+    } & ToxcastBioactivity;
+} | ({
+    found: true;
+    dtxsid: string;
+    preferredName: string;
+} & CtxHazardData) | {
+    found: true;
+    detail: ChemicalDetail;
+    properties?: PropertySummary[];
+} | ({
+    found: true;
+    dtxsid: string;
+} & CtxExposureData);
+export declare function createComptoxTool(deps: {
+    apiKey: string;
+}): import("../define-tool.js").Tool<{
+    dataset: "toxcast" | "hazard" | "chemical" | "exposure";
+    query: string;
+    dataType?: "toxval" | "genetox" | "cancer" | "all" | "seem" | "httk" | "functional-use" | "product-data" | undefined;
+    activeOnly?: boolean | undefined;
+    includeProperties?: boolean | undefined;
+    limit?: number | undefined;
+}, ComptoxOutput>;
+export {};