@inflexa-ai/harness 0.1.1

package/dist/agents/sandbox/shared.js

@@ -0,0 +1,195 @@
+/**
+ * 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 { sandboxOrientCorePrompt, sandboxAnalysisStepStandardsPrompt } from "../../prompts/sandbox-standards.js";
+import { composeSystemPrompt } from "../system-prompt.js";
+// Sandbox-environment introspection.
+import { listAvailablePackagesTool, listAvailableRefsTool } from "../../tools/sandbox/index.js";
+// Context7 docs (pure leaves).
+import { queryDocsTool, resolveLibraryIdTool } from "../../tools/research/context7-docs.js";
+// Run-inspection (dependency-bearing).
+import { createInspectRunTool } from "../../tools/research/inspect-run.js";
+// Bio leaf tools.
+import { checkSafetyPanelTool, getBioactivityTool, getDrugInfoTool, getImpcKoProfileTool, getMechanismTool, getPubchemAssaysTool, getPubchemCrossRefsTool, getTargetSafetyTool, lookupGoTermTool, searchBgeeExpressionTool, searchClinicalTrialsTool, searchCompoundsTool, searchDgidbTool, searchFaersTool, searchGeneTool, searchGeoDatasetsTool, searchGwasCatalogTool, searchInteractionsTool, searchOpenTargetsTool, searchPathwayTool, searchPharmgkbTool, searchPubchemCompoundTool, searchTargetsTool, } from "../../tools/bio/index.js";
+import { createNcbiTools, createChemDbTools } from "../../tools/bio/keys.js";
+// Workspace read surface.
+import { createFileStatTool, createGrepTool, createListFilesTool, createReadFileTool, createWorkspaceSearchTool } from "../../tools/workspace/index.js";
+// Workspace mutate surface.
+import { createEditFileTool, createExecuteCommandTool, createWorkspaceMutator, createWriteFileTool } from "../../tools/workspace/index.js";
+// Skills (declared per agent via meta.skills).
+import { createSkillTools } from "../../tools/sandbox/skills.js";
+import { createReportBlockerTool } from "../../tools/sandbox/report-blocker.js";
+import { toSandboxPath } from "../../workspace/paths.js";
+import { setActiveExecId } from "../../state/index.js";
+import { SANDBOX_AGENT_DEFAULT_MAX_ITERATIONS } 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 const BASE_SANDBOX_TOOLS = ["listAvailablePackages", "listAvailableRefs", "resolveLibraryId", "queryDocs", "inspectRun"];
+/**
+ * Resolve `meta.tools` into the bio/research tools record. Workspace
+ * read/mutate tools are added by `createSandboxAgent` regardless of meta
+ * — they are the always-on substrate, not in the allowlist.
+ */
+function resolveSandboxTools(deps, tools) {
+    const ncbi = createNcbiTools(deps.bioKeys);
+    const chemDb = createChemDbTools(deps.bioKeys);
+    const registry = {
+        listAvailablePackages: listAvailablePackagesTool,
+        listAvailableRefs: listAvailableRefsTool,
+        resolveLibraryId: resolveLibraryIdTool,
+        queryDocs: queryDocsTool,
+        inspectRun: createInspectRunTool(deps.pool),
+        searchPubMed: ncbi.searchPubMed,
+        getArticleDetails: ncbi.getArticleDetails,
+        getArticleFullText: ncbi.getArticleFullText,
+        searchGene: searchGeneTool,
+        searchPathway: searchPathwayTool,
+        lookupGoTerm: lookupGoTermTool,
+        searchInteractions: searchInteractionsTool,
+        searchCompounds: searchCompoundsTool,
+        getBioactivity: getBioactivityTool,
+        searchTargets: searchTargetsTool,
+        getMechanism: getMechanismTool,
+        getDrugInfo: getDrugInfoTool,
+        searchPubchemCompound: searchPubchemCompoundTool,
+        getPubchemCrossRefs: getPubchemCrossRefsTool,
+        getPubchemAssays: getPubchemAssaysTool,
+        searchOpenTargets: searchOpenTargetsTool,
+        getTargetSafety: getTargetSafetyTool,
+        searchPharmgkb: searchPharmgkbTool,
+        searchFaers: searchFaersTool,
+        searchClinicalTrials: searchClinicalTrialsTool,
+        searchGeoDatasets: searchGeoDatasetsTool,
+        searchClinvar: ncbi.searchClinvar,
+        searchDgidb: searchDgidbTool,
+        searchGwasCatalog: searchGwasCatalogTool,
+        searchDisgenet: chemDb.searchDisgenet,
+        searchDrugbank: chemDb.searchDrugbank,
+        searchBgeeExpression: searchBgeeExpressionTool,
+        getImpcKoProfile: getImpcKoProfileTool,
+        checkSafetyPanel: checkSafetyPanelTool,
+        searchToxcast: chemDb.searchToxcast,
+        searchCtxHazard: chemDb.searchCtxHazard,
+        searchCtxChemical: chemDb.searchCtxChemical,
+        searchCtxExposure: chemDb.searchCtxExposure,
+    };
+    const seen = new Set();
+    const resolved = [];
+    for (const name of tools) {
+        if (seen.has(name))
+            continue;
+        seen.add(name);
+        const tool = registry[name];
+        if (!tool) {
+            throw new Error(`createSandboxAgent: unknown SandboxToolName "${name}" — ` + `agent meta references a tool with no harness implementation.`);
+        }
+        resolved.push(tool);
+    }
+    return resolved;
+}
+/** Build the workspace mutate + read tools every sandbox agent receives. In
+ *  `readOnly` mode the write_file/edit_file pair is omitted; execute_command
+ *  and the read tools stay. */
+function buildWorkspaceTools(deps, readOnly) {
+    const { step, sandboxClient, workspaceFs, pool, embedding, lineageCollector } = deps;
+    // Registry tagging is a best-effort watchdog backstop (`run-exec.ts` already
+    // swallows a throw here); fold a `DbError` into a no-op so a registry write
+    // failure neither fails the exec nor surfaces as an unhandled rejection.
+    const markExecActive = (execId) => setActiveExecId(pool, step.runId, step.stepId, execId).match(() => { }, () => { });
+    // The agent's writable working directory: relative paths resolve here, and
+    // writes are confined here. `allowedWritePrefix` is its host path; the
+    // in-sandbox path (the `execute_command` default cwd, see the harness-workspace-tools spec) is the same
+    // location under the `/{analysisId}` mount — derived from the host path so
+    // it is correct for non-step agents (data profiler, ephemeral) too.
+    const hostWorkingDir = step.allowedWritePrefix;
+    const sandboxWorkingDir = toSandboxPath(step.workspaceRoot, step.analysisId, hostWorkingDir);
+    const mutateTools = readOnly
+        ? []
+        : (() => {
+            const mutator = createWorkspaceMutator({
+                sandboxClient,
+                sandbox: step.sandbox,
+                workspaceRoot: step.workspaceRoot,
+                analysisId: step.analysisId,
+                stepId: step.stepId,
+                workflowId: step.workflowId,
+                workingDir: hostWorkingDir,
+                sandboxWorkingDir,
+                nextFunctionId: step.nextFunctionId,
+                deadlineMs: step.deadlineMs,
+                ...(lineageCollector ? { lineageCollector } : {}),
+            });
+            return [createWriteFileTool({ mutator }), createEditFileTool({ mutator, workspaceFilesystem: workspaceFs, workingDir: hostWorkingDir })];
+        })();
+    return [
+        createExecuteCommandTool({
+            sandboxClient,
+            sandbox: step.sandbox,
+            workflowId: step.workflowId,
+            stepId: step.stepId,
+            nextFunctionId: step.nextFunctionId,
+            deadlineMs: step.deadlineMs,
+            defaultCwd: sandboxWorkingDir,
+            markExecActive,
+            ...(lineageCollector ? { lineageCollector, mountRoot: `/${step.analysisId}` } : {}),
+        }),
+        ...mutateTools,
+        createReadFileTool(workspaceFs, hostWorkingDir),
+        createListFilesTool(workspaceFs, hostWorkingDir),
+        createFileStatTool(workspaceFs, hostWorkingDir),
+        createGrepTool(workspaceFs, hostWorkingDir),
+        ...(embedding ? [createWorkspaceSearchTool(pool, embedding)] : []),
+    ];
+}
+/**
+ * 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 function createSandboxAgent(deps, meta, body, opts = {}) {
+    const appendStandards = opts.appendAnalysisStepStandards ?? true;
+    const sandboxLayer = appendStandards ? [sandboxOrientCorePrompt, sandboxAnalysisStepStandardsPrompt] : [sandboxOrientCorePrompt];
+    const agentBody = [body, ...sandboxLayer].map((s) => s.trim()).join("\n\n");
+    // Substitute the concrete in-sandbox paths the agent sees so the orient-core
+    // path model is accurate per step (see the harness-workspace-tools spec), not boilerplate prose.
+    const analysisRoot = `/${deps.step.analysisId}`;
+    const workingDir = toSandboxPath(deps.step.workspaceRoot, deps.step.analysisId, deps.step.allowedWritePrefix);
+    const resolvedBody = agentBody.split("{{WORKING_DIR}}").join(workingDir).split("{{ANALYSIS_ROOT}}").join(analysisRoot);
+    const systemPrompt = composeSystemPrompt(resolvedBody, {
+        includeConversationalStyle: false,
+    });
+    const skillTools = deps.skillsDir ? Object.values(createSkillTools({ skillsDir: deps.skillsDir, skills: meta.skills })) : [];
+    const tools = [
+        ...buildWorkspaceTools(deps, opts.readOnly ?? false),
+        ...skillTools,
+        ...resolveSandboxTools(deps, meta.tools),
+        ...(deps.blockerHolder ? [createReportBlockerTool(deps.blockerHolder)] : []),
+    ];
+    return {
+        id: meta.id,
+        systemPrompt,
+        model: deps.model,
+        tools,
+        maxIterations: meta.defaultMaxSteps ?? SANDBOX_AGENT_DEFAULT_MAX_ITERATIONS,
+    };
+}

package/dist/agents/sandbox/single-cell-agent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Single-Cell Agent — single-cell RNA-seq 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 createSingleCellAgent(deps: SandboxAgentDeps): AgentDefinition;

package/dist/agents/sandbox/single-cell-agent.js

@@ -0,0 +1,25 @@
+/**
+ * Single-Cell Agent — single-cell RNA-seq analysis specialist.
+ */
+import { singleCellAgentPrompt } from "../../prompts/sandbox/single-cell-agent.js";
+import { BASE_SANDBOX_TOOLS, createSandboxAgent } from "./shared.js";
+export const meta = {
+    id: "single-cell-agent",
+    capabilities: [
+        "quality control",
+        "normalization",
+        "clustering",
+        "cell type annotation",
+        "differential expression",
+        "trajectory inference",
+        "cell-cell communication",
+        "TF activity inference",
+        "RNA velocity",
+    ],
+    suitableFor: ["scrna-seq", "snrna-seq", "cytof", "mass-cytometry"],
+    skills: ["single-cell", "shared/omics-general"],
+    tools: [...BASE_SANDBOX_TOOLS, "searchPubMed", "getArticleDetails", "getArticleFullText", "searchGeoDatasets"],
+};
+export function createSingleCellAgent(deps) {
+    return createSandboxAgent(deps, meta, singleCellAgentPrompt);
+}

package/dist/agents/sandbox/spatial-omics-agent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Spatial Omics Agent — spatially-resolved transcriptomics and proteomics 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 createSpatialOmicsAgent(deps: SandboxAgentDeps): AgentDefinition;

package/dist/agents/sandbox/spatial-omics-agent.js

@@ -0,0 +1,15 @@
+/**
+ * Spatial Omics Agent — spatially-resolved transcriptomics and proteomics specialist.
+ */
+import { spatialOmicsAgentPrompt } from "../../prompts/sandbox/spatial-omics-agent.js";
+import { BASE_SANDBOX_TOOLS, createSandboxAgent } from "./shared.js";
+export const meta = {
+    id: "spatial-omics-agent",
+    capabilities: ["spatial statistics", "spatial domain detection", "deconvolution", "niche analysis", "spatial autocorrelation", "ligand-receptor spatial"],
+    suitableFor: ["visium", "merfish", "slide-seq", "codex", "xenium", "mibi", "imc"],
+    skills: ["spatial-omics", "shared/omics-general"],
+    tools: [...BASE_SANDBOX_TOOLS, "searchPubMed", "getArticleDetails", "getArticleFullText", "searchGeoDatasets"],
+};
+export function createSpatialOmicsAgent(deps) {
+    return createSandboxAgent(deps, meta, spatialOmicsAgentPrompt);
+}

package/dist/agents/sandbox/statistical-modeling-agent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Statistical Modeling Agent — survival analysis, ML, and biomarker discovery 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 createStatisticalModelingAgent(deps: SandboxAgentDeps): AgentDefinition;

package/dist/agents/sandbox/statistical-modeling-agent.js

@@ -0,0 +1,37 @@
+/**
+ * Statistical Modeling Agent — survival analysis, ML, and biomarker discovery specialist.
+ */
+import { statisticalModelingAgentPrompt } from "../../prompts/sandbox/statistical-modeling-agent.js";
+import { BASE_SANDBOX_TOOLS, createSandboxAgent } from "./shared.js";
+export const meta = {
+    id: "statistical-modeling-agent",
+    capabilities: [
+        "survival analysis",
+        "machine learning",
+        "classification",
+        "regression",
+        "mixed-effects models",
+        "biomarker discovery",
+        "feature selection",
+        "biomarker qualification",
+        "predictive vs prognostic biomarker testing",
+        "cutpoint optimization",
+        "multi-marker panel development",
+        "ROC and precision-recall analysis",
+    ],
+    suitableFor: [
+        "survival",
+        "classification",
+        "regression",
+        "mixed-models",
+        "biomarker-discovery",
+        "biomarker-qualification",
+        "treatment-response",
+        "patient-stratification",
+    ],
+    skills: ["statistical-modeling", "shared/omics-general"],
+    tools: [...BASE_SANDBOX_TOOLS, "searchPubMed", "getArticleDetails", "getArticleFullText"],
+};
+export function createStatisticalModelingAgent(deps) {
+    return createSandboxAgent(deps, meta, statisticalModelingAgentPrompt);
+}

package/dist/agents/sandbox/translational-safety-agent.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Translational Safety Agent — drug safety / toxicology / adverse-event 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 createTranslationalSafetyAgent(deps: SandboxAgentDeps): AgentDefinition;

package/dist/agents/sandbox/translational-safety-agent.js

@@ -0,0 +1,59 @@
+/**
+ * Translational Safety Agent — drug safety / toxicology / adverse-event specialist.
+ */
+import { translationalSafetyAgentPrompt } from "../../prompts/sandbox/translational-safety-agent.js";
+import { BASE_SANDBOX_TOOLS, createSandboxAgent } from "./shared.js";
+export const meta = {
+    id: "translational-safety-agent",
+    capabilities: [
+        "safety biomarker analysis",
+        "structural safety assessment",
+        "adverse event profiling",
+        "target safety assessment",
+        "CYP liability analysis",
+        "drug-drug interaction assessment",
+        "in-vitro toxicology screening",
+        "CTCAE grading",
+        "hepatotoxicity assessment",
+        "cardiotoxicity assessment",
+        "nephrotoxicity assessment",
+        "hematological toxicity assessment",
+        "mouse KO phenotype lookup",
+        "cross-species baseline expression lookup",
+    ],
+    suitableFor: [
+        "safety-biomarkers",
+        "adverse-events",
+        "toxicity-data",
+        "compound-safety",
+        "clinical-safety-labs",
+        "drug-interaction-data",
+        "pharmacogenomic-data",
+    ],
+    skills: ["translational-safety", "cheminformatics", "shared/omics-general"],
+    tools: [
+        ...BASE_SANDBOX_TOOLS,
+        "checkSafetyPanel",
+        "searchPubMed",
+        "getArticleDetails",
+        "getArticleFullText",
+        "searchGene",
+        "searchPathway",
+        "lookupGoTerm",
+        "searchInteractions",
+        "searchOpenTargets",
+        "getTargetSafety",
+        "searchFaers",
+        "searchPharmgkb",
+        "searchDgidb",
+        "searchToxcast",
+        "searchCtxHazard",
+        "searchCtxChemical",
+        "searchCtxExposure",
+        "searchBgeeExpression",
+        "getImpcKoProfile",
+    ],
+};
+export function createTranslationalSafetyAgent(deps) {
+    return createSandboxAgent(deps, meta, translationalSafetyAgentPrompt);
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Sandbox-agent shared types.
+ *
+ * `SandboxToolName` is the closed allowlist of tools any sandbox agent may
+ * declare in its `AgentMeta.tools`. The `createSandboxAgent` resolver maps
+ * each name to a concrete `Tool` (pure leaf or fully dep-bound factory
+ * output) — unknown names throw at composition time, not at first LLM call.
+ *
+ * `searchDisgenet` and `searchDrugbank` require keys (`DISGENET_API_KEY`,
+ * `DRUGBANK_API_KEY`); without the key the underlying header builder
+ * throws on first call, which the harness surfaces as a tool `is_error`
+ * envelope. `searchGwasCatalog` is fully public.
+ */
+/** Closed allowlist of tools any sandbox agent may declare. */
+export type SandboxToolName = "listAvailablePackages" | "listAvailableRefs" | "resolveLibraryId" | "queryDocs" | "inspectRun" | "searchPubMed" | "getArticleDetails" | "getArticleFullText" | "searchGene" | "searchPathway" | "lookupGoTerm" | "searchInteractions" | "searchCompounds" | "getBioactivity" | "searchTargets" | "getMechanism" | "getDrugInfo" | "searchPubchemCompound" | "getPubchemCrossRefs" | "getPubchemAssays" | "searchOpenTargets" | "getTargetSafety" | "searchPharmgkb" | "searchFaers" | "searchClinicalTrials" | "searchGeoDatasets" | "searchClinvar" | "searchDgidb" | "searchGwasCatalog" | "searchDisgenet" | "searchDrugbank" | "searchBgeeExpression" | "getImpcKoProfile" | "checkSafetyPanel" | "searchToxcast" | "searchCtxHazard" | "searchCtxChemical" | "searchCtxExposure";
+/** Planner-facing metadata + tool allowlist for one sandbox agent. */
+export interface AgentMeta {
+    /** Stable agent id — also the key in the catalog and the `AgentDefinition.id`. */
+    readonly id: string;
+    /** Capabilities surfaced to the planner. */
+    readonly capabilities: readonly string[];
+    /** Omics / data types this agent handles. */
+    readonly suitableFor: readonly string[];
+    /** Skill directory names loaded into the agent's workspace. */
+    readonly skills: readonly string[];
+    /** Bio/literature tools the agent may use (workspace + sandbox tools are always wired). */
+    readonly tools: readonly SandboxToolName[];
+    /** Per-agent override for `maxIterations`; defaults to {@link SANDBOX_AGENT_DEFAULT_MAX_ITERATIONS}. */
+    readonly defaultMaxSteps?: number;
+    /** False for agents the planner must NOT assign to plan steps (executors, the profiler). */
+    readonly plannable?: boolean;
+}
+/** Default runaway-guard for sandbox agents. */
+export declare const SANDBOX_AGENT_DEFAULT_MAX_ITERATIONS = 50;

package/dist/agents/sandbox/types.js

@@ -0,0 +1,15 @@
+/**
+ * Sandbox-agent shared types.
+ *
+ * `SandboxToolName` is the closed allowlist of tools any sandbox agent may
+ * declare in its `AgentMeta.tools`. The `createSandboxAgent` resolver maps
+ * each name to a concrete `Tool` (pure leaf or fully dep-bound factory
+ * output) — unknown names throw at composition time, not at first LLM call.
+ *
+ * `searchDisgenet` and `searchDrugbank` require keys (`DISGENET_API_KEY`,
+ * `DRUGBANK_API_KEY`); without the key the underlying header builder
+ * throws on first call, which the harness surfaces as a tool `is_error`
+ * envelope. `searchGwasCatalog` is fully public.
+ */
+/** Default runaway-guard for sandbox agents. */
+export const SANDBOX_AGENT_DEFAULT_MAX_ITERATIONS = 50;

package/dist/agents/sandbox/validate-skills.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Boot-time skill validation.
+ *
+ * Verifies that SKILLS_DIR exists and every skill name declared by a sandbox
+ * agent resolves to a readable SKILL.md. Catches Dockerfile drift and typos
+ * in agent meta before the first analysis runs.
+ */
+/**
+ * Minimal shape this validator reads — `id` for diagnostics and `skills`
+ * for the per-agent skill list. Declared structurally so `AgentMeta` types
+ * with `readonly` arrays work without a cast at the call site.
+ */
+interface AgentMetaLike {
+    readonly id: string;
+    readonly skills: readonly string[];
+}
+export declare function validateAgentSkills(skillsDir: string, catalog: Readonly<Record<string, AgentMetaLike>>): void;
+export {};

package/dist/agents/sandbox/validate-skills.js

@@ -0,0 +1,40 @@
+/**
+ * Boot-time skill validation.
+ *
+ * Verifies that SKILLS_DIR exists and every skill name declared by a sandbox
+ * agent resolves to a readable SKILL.md. Catches Dockerfile drift and typos
+ * in agent meta before the first analysis runs.
+ */
+import { statSync } from "node:fs";
+import { join } from "node:path";
+export function validateAgentSkills(skillsDir, catalog) {
+    try {
+        const s = statSync(skillsDir);
+        if (!s.isDirectory()) {
+            throw new Error(`SKILLS_DIR "${skillsDir}" is not a directory`);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`SKILLS_DIR "${skillsDir}" is not accessible: ${msg}. ` + `Set SKILLS_DIR to a directory containing skill subfolders (one SKILL.md each).`, { cause: err });
+    }
+    const missing = [];
+    for (const meta of Object.values(catalog)) {
+        for (const skill of meta.skills) {
+            const skillFile = join(skillsDir, skill, "SKILL.md");
+            try {
+                const s = statSync(skillFile);
+                if (!s.isFile()) {
+                    missing.push({ agentId: meta.id, skill, expectedPath: skillFile });
+                }
+            }
+            catch {
+                missing.push({ agentId: meta.id, skill, expectedPath: skillFile });
+            }
+        }
+    }
+    if (missing.length > 0) {
+        const lines = missing.map((m) => `  - agent "${m.agentId}" declares skill "${m.skill}" but ${m.expectedPath} is missing`).join("\n");
+        throw new Error(`Skill validation failed: ${missing.length} declared skill(s) not found under SKILLS_DIR="${skillsDir}":\n${lines}`);
+    }
+}

package/dist/agents/sandbox-catalog.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Planner-facing sandbox-agent catalog.
+ *
+ * Derives from `harness/agents/sandbox/index.ts` `SANDBOX_AGENT_META` —
+ * the source of truth — by projecting `{ id, capabilities, suitableFor }`
+ * and filtering on the `plannable` flag. `generatePlan` consumes the
+ * rendered markdown via `formatAgentCatalog()` to fill its prompt's
+ * `{{AGENT_CATALOG}}` placeholder.
+ */
+/** Planner-facing metadata for one sandbox agent. */
+export interface PlannerAgentMeta {
+    readonly id: string;
+    readonly capabilities: readonly string[];
+    readonly suitableFor: readonly string[];
+}
+/** The sandbox agents the planner may assign to analysis-plan steps. */
+export declare const PLANNABLE_AGENT_CATALOG: readonly PlannerAgentMeta[];
+/**
+ * Ids of the agents the planner may assign — the `z.enum` domain for
+ * `PlanStepSchema.agent`. A non-empty tuple, as `z.enum` requires.
+ */
+export declare const PLANNABLE_AGENT_IDS: readonly [string, ...string[]];
+/**
+ * Every sandbox agent id — plannable agents plus the workflow-dedicated
+ * ones (`data-profiler`, the executors). Plan validation checks step
+ * assignments against this set.
+ */
+export declare const KNOWN_AGENT_IDS: readonly string[];
+/**
+ * Render the catalog as the markdown block the planner prompt expects in
+ * place of its `{{AGENT_CATALOG}}` placeholder.
+ */
+export declare function formatAgentCatalog(catalog?: readonly PlannerAgentMeta[]): string;

package/dist/agents/sandbox-catalog.js

@@ -0,0 +1,44 @@
+/**
+ * Planner-facing sandbox-agent catalog.
+ *
+ * Derives from `harness/agents/sandbox/index.ts` `SANDBOX_AGENT_META` —
+ * the source of truth — by projecting `{ id, capabilities, suitableFor }`
+ * and filtering on the `plannable` flag. `generatePlan` consumes the
+ * rendered markdown via `formatAgentCatalog()` to fill its prompt's
+ * `{{AGENT_CATALOG}}` placeholder.
+ */
+import { SANDBOX_AGENT_META } from "./sandbox/index.js";
+/** The sandbox agents the planner may assign to analysis-plan steps. */
+export const PLANNABLE_AGENT_CATALOG = Object.values(SANDBOX_AGENT_META)
+    .filter((meta) => meta.plannable !== false)
+    .map((meta) => ({
+    id: meta.id,
+    capabilities: [...meta.capabilities],
+    suitableFor: [...meta.suitableFor],
+}));
+/**
+ * Ids of the agents the planner may assign — the `z.enum` domain for
+ * `PlanStepSchema.agent`. A non-empty tuple, as `z.enum` requires.
+ */
+export const PLANNABLE_AGENT_IDS = (() => {
+    const ids = PLANNABLE_AGENT_CATALOG.map((meta) => meta.id);
+    if (ids.length === 0) {
+        throw new Error("PLANNABLE_AGENT_CATALOG is empty");
+    }
+    return ids;
+})();
+/**
+ * Every sandbox agent id — plannable agents plus the workflow-dedicated
+ * ones (`data-profiler`, the executors). Plan validation checks step
+ * assignments against this set.
+ */
+export const KNOWN_AGENT_IDS = Object.keys(SANDBOX_AGENT_META);
+/**
+ * Render the catalog as the markdown block the planner prompt expects in
+ * place of its `{{AGENT_CATALOG}}` placeholder.
+ */
+export function formatAgentCatalog(catalog = PLANNABLE_AGENT_CATALOG) {
+    return catalog
+        .map((meta) => `- **${meta.id}**: capabilities: [${meta.capabilities.join(", ")}], ` + `suitable for: [${meta.suitableFor.join(", ")}]`)
+        .join("\n");
+}

package/dist/agents/system-prompt.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Harness system-prompt composition.
+ *
+ * SOUL is static text — there is no processor pipeline. `composeSystemPrompt`
+ * concatenates the SOUL kernel, the optional SOUL conversational layer, and an
+ * agent's own prompt into the single `AgentDefinition.systemPrompt` string the
+ * loop sends as the cacheable prefix.
+ *
+ * `includeConversationalStyle` toggles the conversational block: the
+ * user-facing conversation agent keeps it; internal tool-only specialists
+ * (planner, run-synthesizer) and sandbox agents omit it — their tight tool
+ * loops compete with conversational discipline.
+ */
+export interface ComposeSystemPromptOptions {
+    /**
+     * Include the SOUL conversational layer (personality, response policy,
+     * 7-step reasoning). Default `true` — opt out for internal specialists.
+     */
+    readonly includeConversationalStyle?: boolean;
+}
+/**
+ * Compose an agent's full system prompt: SOUL kernel, the optional SOUL
+ * conversational layer, then the agent's own prompt — joined by blank lines.
+ */
+export declare function composeSystemPrompt(agentPrompt: string, options?: ComposeSystemPromptOptions): string;

package/dist/agents/system-prompt.js

@@ -0,0 +1,23 @@
+/**
+ * Harness system-prompt composition.
+ *
+ * SOUL is static text — there is no processor pipeline. `composeSystemPrompt`
+ * concatenates the SOUL kernel, the optional SOUL conversational layer, and an
+ * agent's own prompt into the single `AgentDefinition.systemPrompt` string the
+ * loop sends as the cacheable prefix.
+ *
+ * `includeConversationalStyle` toggles the conversational block: the
+ * user-facing conversation agent keeps it; internal tool-only specialists
+ * (planner, run-synthesizer) and sandbox agents omit it — their tight tool
+ * loops compete with conversational discipline.
+ */
+import { SOULKernelPrompt, SOULConversationalPrompt } from "../prompts/SOUL.js";
+/**
+ * Compose an agent's full system prompt: SOUL kernel, the optional SOUL
+ * conversational layer, then the agent's own prompt — joined by blank lines.
+ */
+export function composeSystemPrompt(agentPrompt, options = {}) {
+    const includeConversational = options.includeConversationalStyle ?? true;
+    const sections = includeConversational ? [SOULKernelPrompt, SOULConversationalPrompt, agentPrompt] : [SOULKernelPrompt, agentPrompt];
+    return sections.map((s) => s.trim()).join("\n\n");
+}

package/dist/app/chat-turn.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Chat-turn preparation — the host-agnostic assembly half of one chat turn.
+ *
+ * This is the PREPARATION half of a conversation turn, lifted out of the HTTP
+ * route so callers other than the route (e.g. a CLI) can reuse it. It owns,
+ * in order: thread-ownership resolution, best-effort title seeding, analysis
+ * status load, and message assembly. It deliberately owns NONE of the
+ * transport orchestration (streaming/SSE/queue/status codes) — that stays in
+ * the caller. A turn is `prepareChatTurn → runAgent(own emit) → appendTurn`.
+ *
+ * Returns a typed result: `not_found` when the `threadId` is owned by a
+ * different analysis (indistinguishable from absent), otherwise `ok` with the
+ * assembled `messages` and the standalone `userMessage` the caller persists.
+ */
+import type { Pool } from "pg";
+import { type AssembledMessages } from "./message-assembly.js";
+export interface PrepareChatTurnDeps {
+    readonly pool: Pool;
+}
+export interface PrepareChatTurnParams {
+    readonly analysisId: string;
+    readonly threadId: string;
+    readonly userInput: string;
+}
+export type PrepareChatTurnResult = ({
+    readonly kind: "ok";
+} & AssembledMessages) | {
+    readonly kind: "not_found";
+};
+/**
+ * Prepare one chat turn: resolve thread ownership, seed the title, load
+ * analysis status, and assemble the message array. Input sanitization stays
+ * inside {@link assembleMessages} (applied once to the new user input only).
+ */
+export declare function prepareChatTurn(deps: PrepareChatTurnDeps, params: PrepareChatTurnParams): Promise<PrepareChatTurnResult>;