@inflexa-ai/harness 0.1.1

package/dist/agents/sandbox/index.js

@@ -0,0 +1,96 @@
+/**
+ * Sandbox agent catalog + composition root.
+ *
+ * `createSandboxAgents(deps)` returns one `AgentDefinition` per sandbox
+ * agent — the harness loop's substrate. `SANDBOX_AGENT_META` exposes the
+ * meta record the planner-facing catalog (`harness/agents/sandbox-catalog.ts`)
+ * derives from.
+ *
+ * Adding a new sandbox agent: add the per-agent file under
+ * `harness/agents/sandbox/`, import its `meta` + `create*` factory below,
+ * and add one entry to each of the two arrays. Both wire-ups type-check
+ * against `SandboxToolName`, so any inconsistency surfaces at compile time.
+ */
+import { createBulkTranscriptomicsAgent, meta as bulkTranscriptomicsMeta } from "./bulk-transcriptomics-agent.js";
+import { createCheminformaticsAgent, meta as cheminformaticsMeta } from "./cheminformatics-agent.js";
+import { createChromatinAgent, meta as chromatinMeta } from "./chromatin-agent.js";
+import { createDataProfilerAgent, meta as dataProfilerMeta } from "./data-profiler.js";
+import { createDnaMethylationAgent, meta as dnaMethylationMeta } from "./dna-methylation-agent.js";
+import { createDrugRepurposingAgent, meta as drugRepurposingMeta } from "./drug-repurposing-agent.js";
+import { createEnrichmentAgent, meta as enrichmentMeta } from "./enrichment-agent.js";
+import { createEphemeralExecutorAgent, meta as ephemeralExecutorMeta } from "./ephemeral-executor.js";
+import { createGenomicVariantAgent, meta as genomicVariantMeta } from "./genomic-variant-agent.js";
+import { createImmuneProfilingAgent, meta as immuneProfilingMeta } from "./immune-profiling-agent.js";
+import { createMetabolomicsAgent, meta as metabolomicsMeta } from "./metabolomics-agent.js";
+import { createMicrobiomeAgent, meta as microbiomeMeta } from "./microbiome-agent.js";
+import { createMultiOmicsIntegrationAgent, meta as multiOmicsIntegrationMeta } from "./multi-omics-integration-agent.js";
+import { createMultimodalScAgent, meta as multimodalScMeta } from "./multimodal-sc-agent.js";
+import { createNetworkAgent, meta as networkMeta } from "./network-agent.js";
+import { createPkpdClinicalResponseAgent, meta as pkpdClinicalResponseMeta } from "./pkpd-clinical-response-agent.js";
+import { createProteomicsAgent, meta as proteomicsMeta } from "./proteomics-agent.js";
+import { createScientificExecutorAgent, meta as scientificExecutorMeta } from "./scientific-executor.js";
+import { createSingleCellAgent, meta as singleCellMeta } from "./single-cell-agent.js";
+import { createSpatialOmicsAgent, meta as spatialOmicsMeta } from "./spatial-omics-agent.js";
+import { createStatisticalModelingAgent, meta as statisticalModelingMeta } from "./statistical-modeling-agent.js";
+import { createTranslationalSafetyAgent, meta as translationalSafetyMeta } from "./translational-safety-agent.js";
+export { BASE_SANDBOX_TOOLS, createSandboxAgent } from "./shared.js";
+export { SANDBOX_AGENT_DEFAULT_MAX_ITERATIONS } from "./types.js";
+/**
+ * Per-agent meta — id, planner-facing description, tool allowlist. The
+ * source of truth that `harness/agents/sandbox-catalog.ts`'s planner
+ * catalog derives from.
+ */
+export const SANDBOX_AGENT_META = {
+    [dataProfilerMeta.id]: dataProfilerMeta,
+    [bulkTranscriptomicsMeta.id]: bulkTranscriptomicsMeta,
+    [singleCellMeta.id]: singleCellMeta,
+    [multimodalScMeta.id]: multimodalScMeta,
+    [spatialOmicsMeta.id]: spatialOmicsMeta,
+    [proteomicsMeta.id]: proteomicsMeta,
+    [metabolomicsMeta.id]: metabolomicsMeta,
+    [genomicVariantMeta.id]: genomicVariantMeta,
+    [dnaMethylationMeta.id]: dnaMethylationMeta,
+    [chromatinMeta.id]: chromatinMeta,
+    [microbiomeMeta.id]: microbiomeMeta,
+    [enrichmentMeta.id]: enrichmentMeta,
+    [networkMeta.id]: networkMeta,
+    [statisticalModelingMeta.id]: statisticalModelingMeta,
+    [multiOmicsIntegrationMeta.id]: multiOmicsIntegrationMeta,
+    [cheminformaticsMeta.id]: cheminformaticsMeta,
+    [translationalSafetyMeta.id]: translationalSafetyMeta,
+    [pkpdClinicalResponseMeta.id]: pkpdClinicalResponseMeta,
+    [immuneProfilingMeta.id]: immuneProfilingMeta,
+    [drugRepurposingMeta.id]: drugRepurposingMeta,
+    [scientificExecutorMeta.id]: scientificExecutorMeta,
+    [ephemeralExecutorMeta.id]: ephemeralExecutorMeta,
+};
+/**
+ * Build every sandbox `AgentDefinition` from the shared deps. The returned
+ * record's keys are the agent ids; `runAgent` consumes each value.
+ */
+export function createSandboxAgents(deps) {
+    return {
+        [dataProfilerMeta.id]: createDataProfilerAgent(deps),
+        [bulkTranscriptomicsMeta.id]: createBulkTranscriptomicsAgent(deps),
+        [singleCellMeta.id]: createSingleCellAgent(deps),
+        [multimodalScMeta.id]: createMultimodalScAgent(deps),
+        [spatialOmicsMeta.id]: createSpatialOmicsAgent(deps),
+        [proteomicsMeta.id]: createProteomicsAgent(deps),
+        [metabolomicsMeta.id]: createMetabolomicsAgent(deps),
+        [genomicVariantMeta.id]: createGenomicVariantAgent(deps),
+        [dnaMethylationMeta.id]: createDnaMethylationAgent(deps),
+        [chromatinMeta.id]: createChromatinAgent(deps),
+        [microbiomeMeta.id]: createMicrobiomeAgent(deps),
+        [enrichmentMeta.id]: createEnrichmentAgent(deps),
+        [networkMeta.id]: createNetworkAgent(deps),
+        [statisticalModelingMeta.id]: createStatisticalModelingAgent(deps),
+        [multiOmicsIntegrationMeta.id]: createMultiOmicsIntegrationAgent(deps),
+        [cheminformaticsMeta.id]: createCheminformaticsAgent(deps),
+        [translationalSafetyMeta.id]: createTranslationalSafetyAgent(deps),
+        [pkpdClinicalResponseMeta.id]: createPkpdClinicalResponseAgent(deps),
+        [immuneProfilingMeta.id]: createImmuneProfilingAgent(deps),
+        [drugRepurposingMeta.id]: createDrugRepurposingAgent(deps),
+        [scientificExecutorMeta.id]: createScientificExecutorAgent(deps),
+        [ephemeralExecutorMeta.id]: createEphemeralExecutorAgent(deps),
+    };
+}

package/dist/agents/sandbox/metabolomics-agent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Metabolomics Agent — metabolomics and lipidomics analysis specialist.
+ */
+import type { AgentDefinition } from "../../loop/types.js";
+import { type SandboxAgentDeps } from "./shared.js";
+import type { AgentMeta } from "./types.js";
+export declare const meta: AgentMeta;
+export declare function createMetabolomicsAgent(deps: SandboxAgentDeps): AgentDefinition;

package/dist/agents/sandbox/metabolomics-agent.js

@@ -0,0 +1,15 @@
+/**
+ * Metabolomics Agent — metabolomics and lipidomics analysis specialist.
+ */
+import { metabolomicsAgentPrompt } from "../../prompts/sandbox/metabolomics-agent.js";
+import { BASE_SANDBOX_TOOLS, createSandboxAgent } from "./shared.js";
+export const meta = {
+    id: "metabolomics-agent",
+    capabilities: ["peak detection", "feature alignment", "metabolite annotation", "normalization", "statistical analysis", "pathway mapping"],
+    suitableFor: ["untargeted-metabolomics", "targeted-metabolomics", "lipidomics"],
+    skills: ["metabolomics", "shared/omics-general"],
+    tools: [...BASE_SANDBOX_TOOLS, "searchPubMed", "getArticleDetails", "getArticleFullText"],
+};
+export function createMetabolomicsAgent(deps) {
+    return createSandboxAgent(deps, meta, metabolomicsAgentPrompt);
+}

package/dist/agents/sandbox/microbiome-agent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Microbiome Agent — amplicon and metagenomic analysis specialist.
+ */
+import type { AgentDefinition } from "../../loop/types.js";
+import { type SandboxAgentDeps } from "./shared.js";
+import type { AgentMeta } from "./types.js";
+export declare const meta: AgentMeta;
+export declare function createMicrobiomeAgent(deps: SandboxAgentDeps): AgentDefinition;

package/dist/agents/sandbox/microbiome-agent.js

@@ -0,0 +1,15 @@
+/**
+ * Microbiome Agent — amplicon and metagenomic analysis specialist.
+ */
+import { microbiomeAgentPrompt } from "../../prompts/sandbox/microbiome-agent.js";
+import { BASE_SANDBOX_TOOLS, createSandboxAgent } from "./shared.js";
+export const meta = {
+    id: "microbiome-agent",
+    capabilities: ["diversity analysis", "differential abundance", "taxonomic profiling", "functional profiling", "compositional analysis"],
+    suitableFor: ["16s-amplicon", "its-amplicon", "shotgun-metagenomics", "functional-profiling"],
+    skills: ["microbiome", "shared/omics-general"],
+    tools: [...BASE_SANDBOX_TOOLS, "searchPubMed", "getArticleDetails", "getArticleFullText"],
+};
+export function createMicrobiomeAgent(deps) {
+    return createSandboxAgent(deps, meta, microbiomeAgentPrompt);
+}

package/dist/agents/sandbox/multi-omics-integration-agent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Multi-Omics Integration Agent — cross-modality data integration specialist.
+ */
+import type { AgentDefinition } from "../../loop/types.js";
+import { type SandboxAgentDeps } from "./shared.js";
+import type { AgentMeta } from "./types.js";
+export declare const meta: AgentMeta;
+export declare function createMultiOmicsIntegrationAgent(deps: SandboxAgentDeps): AgentDefinition;

package/dist/agents/sandbox/multi-omics-integration-agent.js

@@ -0,0 +1,33 @@
+/**
+ * Multi-Omics Integration Agent — cross-modality data integration specialist.
+ */
+import { multiOmicsIntegrationAgentPrompt } from "../../prompts/sandbox/multi-omics-integration-agent.js";
+import { BASE_SANDBOX_TOOLS, createSandboxAgent } from "./shared.js";
+export const meta = {
+    id: "multi-omics-integration-agent",
+    capabilities: [
+        "multi-omics integration",
+        "factor analysis",
+        "supervised integration",
+        "network fusion",
+        "cross-modality analysis",
+        "preclinical target context (mouse KO, cross-species expression)",
+    ],
+    suitableFor: ["multi-omics", "cross-modality-integration"],
+    skills: ["multi-omics-integration", "shared/omics-general"],
+    tools: [
+        ...BASE_SANDBOX_TOOLS,
+        "searchPubMed",
+        "getArticleDetails",
+        "getArticleFullText",
+        "searchGene",
+        "searchPathway",
+        "lookupGoTerm",
+        "searchInteractions",
+        "searchBgeeExpression",
+        "getImpcKoProfile",
+    ],
+};
+export function createMultiOmicsIntegrationAgent(deps) {
+    return createSandboxAgent(deps, meta, multiOmicsIntegrationAgentPrompt);
+}

package/dist/agents/sandbox/multimodal-sc-agent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Multimodal Single-Cell Agent — multi-modal single-cell integration specialist.
+ */
+import type { AgentDefinition } from "../../loop/types.js";
+import { type SandboxAgentDeps } from "./shared.js";
+import type { AgentMeta } from "./types.js";
+export declare const meta: AgentMeta;
+export declare function createMultimodalScAgent(deps: SandboxAgentDeps): AgentDefinition;

package/dist/agents/sandbox/multimodal-sc-agent.js

@@ -0,0 +1,15 @@
+/**
+ * Multimodal Single-Cell Agent — multi-modal single-cell integration specialist.
+ */
+import { multimodalScAgentPrompt } from "../../prompts/sandbox/multimodal-sc-agent.js";
+import { BASE_SANDBOX_TOOLS, createSandboxAgent } from "./shared.js";
+export const meta = {
+    id: "multimodal-sc-agent",
+    capabilities: ["multimodal integration", "joint embedding", "cross-modality analysis", "protein quantification", "chromatin accessibility"],
+    suitableFor: ["cite-seq", "multiome", "tea-seq", "dogma-seq"],
+    skills: ["multimodal-single-cell", "shared/omics-general"],
+    tools: [...BASE_SANDBOX_TOOLS, "searchPubMed", "getArticleDetails", "getArticleFullText"],
+};
+export function createMultimodalScAgent(deps) {
+    return createSandboxAgent(deps, meta, multimodalScAgentPrompt);
+}

package/dist/agents/sandbox/network-agent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Network Agent — network and regulatory analysis specialist.
+ */
+import type { AgentDefinition } from "../../loop/types.js";
+import { type SandboxAgentDeps } from "./shared.js";
+import type { AgentMeta } from "./types.js";
+export declare const meta: AgentMeta;
+export declare function createNetworkAgent(deps: SandboxAgentDeps): AgentDefinition;

package/dist/agents/sandbox/network-agent.js

@@ -0,0 +1,25 @@
+/**
+ * Network Agent — network and regulatory analysis specialist.
+ */
+import { networkAgentPrompt } from "../../prompts/sandbox/network-agent.js";
+import { BASE_SANDBOX_TOOLS, createSandboxAgent } from "./shared.js";
+export const meta = {
+    id: "network-agent",
+    capabilities: ["network analysis", "co-expression networks", "regulatory analysis", "module detection", "TF activity inference"],
+    suitableFor: ["expression-matrices", "correlation-matrices", "general-omics"],
+    skills: ["network-regulatory", "shared/omics-general"],
+    tools: [
+        ...BASE_SANDBOX_TOOLS,
+        "searchPubMed",
+        "getArticleDetails",
+        "getArticleFullText",
+        "searchGene",
+        "searchPathway",
+        "lookupGoTerm",
+        "searchInteractions",
+    ],
+    defaultMaxSteps: 35,
+};
+export function createNetworkAgent(deps) {
+    return createSandboxAgent(deps, meta, networkAgentPrompt);
+}

package/dist/agents/sandbox/pkpd-clinical-response-agent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * PK/PD & Clinical Response Agent — PK/PD modeling and clinical response specialist.
+ */
+import type { AgentDefinition } from "../../loop/types.js";
+import { type SandboxAgentDeps } from "./shared.js";
+import type { AgentMeta } from "./types.js";
+export declare const meta: AgentMeta;
+export declare function createPkpdClinicalResponseAgent(deps: SandboxAgentDeps): AgentDefinition;

package/dist/agents/sandbox/pkpd-clinical-response-agent.js

@@ -0,0 +1,59 @@
+/**
+ * PK/PD & Clinical Response Agent — PK/PD modeling and clinical response specialist.
+ */
+import { pkpdClinicalResponseAgentPrompt } from "../../prompts/sandbox/pkpd-clinical-response-agent.js";
+import { BASE_SANDBOX_TOOLS, createSandboxAgent } from "./shared.js";
+export const meta = {
+    id: "pkpd-clinical-response-agent",
+    capabilities: [
+        "non-compartmental PK analysis",
+        "population PK covariate modeling",
+        "exposure-response modeling",
+        "dose-response curve fitting",
+        "clinical response classification",
+        "RECIST evaluation",
+        "responder stratification",
+        "therapeutic window identification",
+        "waterfall and spider plots",
+        "pharmacodynamic biomarker tracking",
+        "PD marker time-series analysis",
+        "PK-PD hysteresis analysis",
+        "tissue-of-action expression lookup",
+        "preclinical KO tolerability prior",
+    ],
+    suitableFor: [
+        "pharmacokinetic-data",
+        "concentration-time-data",
+        "dose-response-data",
+        "clinical-response-data",
+        "exposure-response-data",
+        "pk-omics-integration",
+        "pharmacodynamic-biomarker-data",
+        "longitudinal-pd-data",
+    ],
+    skills: ["pkpd-clinical-response", "statistical-modeling", "shared/omics-general"],
+    tools: [
+        ...BASE_SANDBOX_TOOLS,
+        "searchPubMed",
+        "getArticleDetails",
+        "getArticleFullText",
+        "searchGene",
+        "searchPathway",
+        "lookupGoTerm",
+        "searchInteractions",
+        "searchClinicalTrials",
+        "searchFaers",
+        "searchPharmgkb",
+        "searchCompounds",
+        "getBioactivity",
+        "searchTargets",
+        "getMechanism",
+        "getDrugInfo",
+        "searchDgidb",
+        "searchBgeeExpression",
+        "getImpcKoProfile",
+    ],
+};
+export function createPkpdClinicalResponseAgent(deps) {
+    return createSandboxAgent(deps, meta, pkpdClinicalResponseAgentPrompt);
+}

package/dist/agents/sandbox/proteomics-agent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Proteomics Agent — mass spectrometry and protein quantification specialist.
+ */
+import type { AgentDefinition } from "../../loop/types.js";
+import { type SandboxAgentDeps } from "./shared.js";
+import type { AgentMeta } from "./types.js";
+export declare const meta: AgentMeta;
+export declare function createProteomicsAgent(deps: SandboxAgentDeps): AgentDefinition;

package/dist/agents/sandbox/proteomics-agent.js

@@ -0,0 +1,15 @@
+/**
+ * Proteomics Agent — mass spectrometry and protein quantification specialist.
+ */
+import { proteomicsAgentPrompt } from "../../prompts/sandbox/proteomics-agent.js";
+import { BASE_SANDBOX_TOOLS, createSandboxAgent } from "./shared.js";
+export const meta = {
+    id: "proteomics-agent",
+    capabilities: ["protein quantification", "differential abundance", "imputation", "normalization", "PTM analysis", "phosphoproteomics"],
+    suitableFor: ["dda-proteomics", "dia-proteomics", "tmt-proteomics", "olink", "somascan"],
+    skills: ["proteomics", "shared/omics-general"],
+    tools: [...BASE_SANDBOX_TOOLS, "searchPubMed", "getArticleDetails", "getArticleFullText"],
+};
+export function createProteomicsAgent(deps) {
+    return createSandboxAgent(deps, meta, proteomicsAgentPrompt);
+}

package/dist/agents/sandbox/scientific-executor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Scientific Executor — versatile general-purpose analysis executor.
+ * Non-plannable: invoked outside the plan DAG.
+ */
+import type { AgentDefinition } from "../../loop/types.js";
+import { type SandboxAgentDeps } from "./shared.js";
+import type { AgentMeta } from "./types.js";
+export declare const meta: AgentMeta;
+export declare function createScientificExecutorAgent(deps: SandboxAgentDeps): AgentDefinition;

package/dist/agents/sandbox/scientific-executor.js

@@ -0,0 +1,56 @@
+/**
+ * Scientific Executor — versatile general-purpose analysis executor.
+ * Non-plannable: invoked outside the plan DAG.
+ */
+import { scientificExecutorPrompt } from "../../prompts/sandbox/scientific-executor.js";
+import { BASE_SANDBOX_TOOLS, createSandboxAgent } from "./shared.js";
+export const meta = {
+    id: "scientific-executor",
+    capabilities: [
+        "differential expression",
+        "statistical testing",
+        "clustering",
+        "dimensionality reduction",
+        "pathway enrichment",
+        "machine learning",
+        "visualization",
+        "data transformation",
+    ],
+    suitableFor: ["bulk-rna-seq", "single-cell", "proteomics", "metabolomics", "genomics", "transcriptomics", "general-omics"],
+    skills: [
+        "bulk-transcriptomics",
+        "single-cell",
+        "multimodal-single-cell",
+        "spatial-omics",
+        "proteomics",
+        "metabolomics",
+        "genomic-variants",
+        "dna-methylation",
+        "chromatin-regulation",
+        "microbiome",
+        "enrichment",
+        "network-regulatory",
+        "statistical-modeling",
+        "multi-omics-integration",
+        "cheminformatics",
+        "translational-safety",
+        "pkpd-clinical-response",
+        "immune-profiling",
+        "drug-repurposing",
+        "shared/omics-general",
+    ],
+    tools: [
+        ...BASE_SANDBOX_TOOLS,
+        "searchPubMed",
+        "getArticleDetails",
+        "getArticleFullText",
+        "searchGene",
+        "searchPathway",
+        "lookupGoTerm",
+        "searchInteractions",
+    ],
+    plannable: false,
+};
+export function createScientificExecutorAgent(deps) {
+    return createSandboxAgent(deps, meta, scientificExecutorPrompt);
+}

package/dist/agents/sandbox/shared.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Sandbox-agent composition root.
+ *
+ * `createSandboxAgent(deps, meta, body, opts?)` produces a fully dep-bound
+ * `AgentDefinition` for one sandbox agent (see the harness-durable-runtime spec): SOUL kernel + the
+ * agent's own prompt body + sandbox standards composed into a single
+ * static `systemPrompt` string (no processors at request time, see the harness-providers spec),
+ * the workspace mutate trio (`execute_command`, `write_file`, `edit_file`)
+ * bound to the shared `SandboxClient` and the step's `allowedWritePrefix`,
+ * the workspace read tools (`read_file`, `grep`) over the shared
+ * `WorkspaceFilesystem`, and the bio/literature/context7/run-inspection
+ * tools its `meta.tools` allowlist names.
+ *
+ * Tool resolution is a single registry lookup — every name in `meta.tools`
+ * must map to a concrete `Tool`; unknown names throw at composition time
+ * so misconfigured agents fail at startup, not at the first LLM call.
+ */
+import type { Pool } from "pg";
+import type { AgentDefinition } from "../../loop/types.js";
+import type { ChatProvider, EmbeddingProvider } from "../../providers/types.js";
+import type { SandboxClient } from "../../sandbox/client.js";
+import type { SandboxRef } from "../../sandbox/types.js";
+import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
+import type { ProvenanceCollector as LineageCollector } from "../../provenance/collector.js";
+import { type BioToolKeys } from "../../tools/bio/keys.js";
+import { type BlockerHolder } from "../../tools/sandbox/report-blocker.js";
+import type { AgentMeta, SandboxToolName } from "./types.js";
+/**
+ * Tools every sandbox agent receives — sandbox-environment introspection,
+ * library docs, and run inspection. Spread into each agent's
+ * `meta.tools` so planner-facing metadata and the resolved tool record
+ * stay in sync. Keep minimal — only tools every agent genuinely needs.
+ */
+export declare const BASE_SANDBOX_TOOLS: readonly SandboxToolName[];
+/** Per-step coordinates the composition root threads through every mutate tool. */
+export interface SandboxStepCoords {
+    readonly sandbox: SandboxRef;
+    /** Absolute host root of this analysis's workspace tree (resolved at the workflow body). */
+    readonly workspaceRoot: string;
+    readonly analysisId: string;
+    readonly runId: string;
+    readonly stepId: string;
+    readonly workflowId: string;
+    /** Absolute writable artifact directory for this step (e.g. stepWritePrefix(...)). */
+    readonly allowedWritePrefix: string;
+    /** Stable per-call function id minter (monotonic; replay-deterministic). */
+    readonly nextFunctionId: () => string;
+    /** Absolute unix-ms deadline for `awaitExec`. */
+    readonly deadlineMs: () => number;
+}
+/** The shared dependency graph every sandbox agent draws from. */
+export interface SandboxAgentDeps {
+    readonly provider: ChatProvider;
+    readonly pool: Pool;
+    readonly sandboxClient: SandboxClient;
+    readonly workspaceFs: WorkspaceFilesystem;
+    /** Embedding provider for in-sandbox semantic `workspace_search`. Omit to skip that tool. */
+    readonly embedding?: EmbeddingProvider;
+    /**
+     * Step-scoped lineage collector fed by each `execute_command`'s
+     * `ExecResult.provenance` frame. Records the input/script edges post-step
+     * registration translates into provenance parents.
+     */
+    readonly lineageCollector?: LineageCollector;
+    /** Model id provenance label — the provider owns the wire model. */
+    readonly model: string;
+    /** Absolute path to the skills tree. Omit to skip the skill tools. */
+    readonly skillsDir?: string;
+    /** Per-step coordinates resolved at the workflow body. */
+    readonly step: SandboxStepCoords;
+    /** API keys for the external bio/chem data sources. */
+    readonly bioKeys: BioToolKeys;
+    /**
+     * Per-run blocker cell (see the harness-sandbox-agents spec). When present, the agent gets a
+     * `report_blocker` tool that records `{ kind: "blocker", reason }` into it;
+     * the sandbox-step body reads `holder.outcome` after the loop. Omit for
+     * agents that have no terminal status to declare (ephemeral, data profiler).
+     */
+    readonly blockerHolder?: BlockerHolder;
+}
+/** Per-agent override for the prompt composition and tool surface. */
+export interface SandboxAgentPromptOptions {
+    /** Append `sandboxAnalysisStepStandardsPrompt`. Defaults to true. */
+    readonly appendAnalysisStepStandards?: boolean;
+    /**
+     * Enforced read-only: omit `write_file` + `edit_file` from the workspace
+     * surface. `execute_command` and all read tools stay. Pair with a sandbox
+     * provisioned with no read-write mount (ephemeral) so no writable location
+     * exists outside container-local `/tmp`. Defaults to false.
+     */
+    readonly readOnly?: boolean;
+}
+/**
+ * Build one sandbox `AgentDefinition`. The system prompt is composed once
+ * (SOUL kernel + agent body + sandbox standards) — no processors, no
+ * conversational layer (sandbox agents are not user-facing). Tools are
+ * resolved against the closed allowlist; the workspace surface is always
+ * wired regardless of meta.
+ */
+export declare function createSandboxAgent(deps: SandboxAgentDeps, meta: AgentMeta, body: string, opts?: SandboxAgentPromptOptions): AgentDefinition;