@inflexa-ai/harness 0.1.1 → 0.2.0

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

@@ -5,6 +5,7 @@
  */
 import type { ResultAsync } from "neverthrow";
 import { type DbError } from "../lib/db-result.js";
+import type { Organism } from "../schemas/data-profile-schemas.js";
 import type { Querier } from "./db.js";
 /**
  * One profiled input file's **drift signature**. `fileId` is a path identity the
@@ -18,13 +19,53 @@ export interface DataProfileInputFile {
     size: number;
     mtimeMs: number;
 }
-/** The profile snapshot `completeDataProfile` persists and `loadDataProfileStatus` reads back. */
+/**
+ * One profiled file's persisted record.
+ *
+ * `path` + `description` are the original pair every snapshot carries. Everything
+ * below them is **optional on read** for the same reason `DataProfileResult.inputFiles`
+ * is: a snapshot written before the record was widened carries only the pair, and a
+ * reader must render that row rather than reject it. A writer fills in whatever the
+ * profiler reported.
+ */
+export interface DataProfileFile {
+    path: string;
+    description: string;
+    /** Semantic data type (count-matrix, variants, clinical-metadata, document, …). */
+    dataType?: string;
+    /** File format (CSV, h5ad, VCF, BAM, …). */
+    format?: string;
+    rows?: number | null;
+    cols?: number | null;
+    /** Searchable labels the profiler attached. */
+    tags?: string[];
+    /** Quality issues specific to this file. */
+    warnings?: string[];
+    /** Flat format-specific metrics (sparsity, medianLibrarySize, tiTvRatio, …). */
+    metrics?: Record<string, string | number | boolean>;
+}
+/** Dataset-wide quality findings the profiler recorded. */
+export interface DataProfileQualityAssessment {
+    concerns: string[];
+    strengths: string[];
+}
+/**
+ * The profile snapshot `completeDataProfile` persists and `loadDataProfileStatus` reads back.
+ *
+ * This row is the **only** durable home of the profile: the profiler's `runs/data-profile/`
+ * scratch tree is wiped when profiling completes, so there is no file to fall back on. It
+ * therefore carries the profiler's full finding, not a summary of it — anything dropped here
+ * is destroyed, and a downstream agent can only recover it by re-reading the raw input files.
+ *
+ * Every field past `summary` / `files` / `inputFileIds` / `profiledAt` is **optional on read**:
+ * a snapshot written before the record was widened carries only those four, and a reader must
+ * render it rather than throw. There is no parse at the read boundary (the jsonb column is cast
+ * straight to this type), so optionality *is* the compatibility mechanism — exactly as it
+ * already is for `inputFiles`.
+ */
 export interface DataProfileResult {
     summary: string;
-    files: Array<{
-        path: string;
-        description: string;
-    }>;
+    files: DataProfileFile[];
     /** Which files the profile covered — the audit record. */
     inputFileIds: string[];
     /**
@@ -35,6 +76,24 @@ export interface DataProfileResult {
      */
     inputFiles?: DataProfileInputFile[];
     profiledAt: string;
+    /** Scientific domain (transcriptomics, cheminformatics, clinical, …). */
+    domain?: string;
+    /** Specific subtype within the domain (bulk-rna-seq, single-cell, LC-MS/MS, …). */
+    subtype?: string;
+    /**
+     * Subject organism with its provenance and confidence. Explicit `null` is a real,
+     * distinct value — the profiler looked and no input identified an organism — as
+     * opposed to absent, which means the snapshot predates this field.
+     */
+    organism?: Organism | null;
+    tissue?: string | null;
+    cellType?: string | null;
+    condition?: string | null;
+    /** Public dataset accessions found in any input (GSE/SRP/PRJNA/E-MTAB/phs/EGAS). */
+    accessions?: string[];
+    /** Conditions, groups, comparisons, replicates, pairing. */
+    experimentalDesign?: string;
+    qualityAssessment?: DataProfileQualityAssessment;
 }
 export interface DataProfileStatus {
     status: "pending" | "running" | "completed" | "failed";

package/dist/state/index.d.ts

@@ -9,8 +9,8 @@
 export { initCortexState } from "./init.js";
 export type { Querier } from "./db.js";
 export { upsertAnalysis, resolveAnalysisBilling, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.js";
-export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
-export type { RegisterArtifactInput, InputArtifactMeta } from "./artifacts.js";
+export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
+export type { RegisterArtifactInput, InputArtifactMeta, StepArtifactRef } 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 type { InsertRunInput } from "./runs.js";
@@ -21,7 +21,7 @@ export type { ActiveSandboxRow } from "./active-sandboxes.js";
 export { insertPlan, loadPlan } from "./plans.js";
 export type { InsertPlanInput } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, } from "./data-profile.js";
-export type { DataProfileStatus, DataProfileResult, DataProfileInputFile } from "./data-profile.js";
+export type { DataProfileStatus, DataProfileResult, DataProfileInputFile, DataProfileFile, DataProfileQualityAssessment } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
 export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
 export type { AnalysisStateRow, ArtifactRow, CortexRunRow, StepExecutionRow, CortexPlanRow } from "./schema.js";

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/tasks/data-profile.d.ts

@@ -24,8 +24,9 @@ import type { BioToolKeys } from "../tools/bio/keys.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 {
     readonly provider: ChatProvider;
@@ -93,6 +94,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`.

package/dist/tasks/data-profile.js

@@ -25,6 +25,8 @@ import { runToTerminal } from "../loop/run-to-terminal.js";
 import { durableStep } from "../loop/run-step.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 +71,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`.
@@ -108,15 +154,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,15 +188,8 @@ 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`);
         const sandbox = await deps.sandboxClient.createSandbox({
             runId: DATA_PROFILE_RUN_LITERAL,
@@ -168,7 +225,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,
                 },
@@ -256,17 +313,9 @@ export async function runDataProfileBody(input, deps) {
                 console.warn(`[data-profile] ${fallbackCount}/${stagedInputs.length} input file(s) used a deterministic fallback description (analysis=${analysisId}) — profiler omitted them`);
             }
             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(),
-            }))) {
+            // 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(analysisId, "completion");
             }
             await deps.runAuthorizer.revoke(authorization, "data-profile-completed");

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 {};