@inflexa-ai/harness 0.1.1

package/dist/tools/sandbox/list-available-refs.js

@@ -0,0 +1,147 @@
+/**
+ * listAvailableRefs — list reference data available in the sandbox.
+ */
+import { readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+const REFS_ROOT = "/mnt/refs";
+const REGISTRY_FILE = join(REFS_ROOT, "registry.json");
+function formatCategory(category, entries) {
+    const labels = {
+        atlas_singlecell: "Single-cell reference atlases for label transfer (Pan-Cancer T cell — " +
+            "Zheng 2021, Pan-Cancer Myeloid — Cheng 2021, Tumor Immune Cell Atlas — " +
+            "Nieto 2021, Tabula Sapiens v2). Available as .h5ad (Python: anndata, " +
+            "scanpy, scvi-tools, symphonypy) and/or .rds (R: Seurat, ProjecTILs). " +
+            "Tabula Sapiens ships full + immune_subset variants. " +
+            "Use these for label transfer BEFORE falling back to marker genes.",
+        atlas_azimuth: "Azimuth references (Seurat-native): PBMC v1.0.0 and Tonsil v1.0.0. " +
+            "Each entry is a (ref.Rds, idx.annoy) pair stored under " +
+            "/mnt/refs/atlas_azimuth/{pbmc,tonsil}/. Load with " +
+            "Azimuth::LoadReference(path) where path is the directory containing " +
+            "ref.Rds + idx.annoy (e.g. '/mnt/refs/atlas_azimuth/pbmc'), then " +
+            "Azimuth::RunAzimuth(query, reference = path).",
+        atlas_projectils: "ProjecTILs reference atlases (Seurat .rds): human + mouse, CD8 + CD4. " +
+            "Use ProjecTILs::ProjecTILs.classifier() to assign every CD8 to one of " +
+            "the canonical TCF7+/GZMK+/TEX/TPEX/MAIT substates without re-deriving " +
+            "the classifier from scratch.",
+        celltypist_models: "Pre-staged CellTypist .pkl classifier models (Immune_All_Low backed by " +
+            "the Cross-Tissue Immune Cell Atlas; Immune_All_High; Pan_Fetal_Human; " +
+            "COVID19_Immune_Landscape). CELLTYPIST_FOLDER env var is preset, so " +
+            "celltypist.annotate_cells(model='Immune_All_Low') resolves with no " +
+            "network call.",
+        marker_panels: "Marker gene panels: PanglaoDB (community, parquet long-format), " +
+            "CellMarker 2.0 (tumor-context, parquet long-format), and the Cortex " +
+            "hand-curated panel for Stage 1 substates (TCF7+ memory CD8, exhausted " +
+            "CD8, effector-memory CD8, proliferating T, cDC1/cDC2/LAMP3+ DC, SPP1+ " +
+            "TAM, C1Q+ TAM, Tregs) — JSON with full provenance.",
+        gene_signatures: "Curated gene signatures from key tumor-immune papers: Sade-Feldman " +
+            "2018 exhausted CD8 (Table S2), Jerby-Arnon 2018 malignant resistance " +
+            "program (Table S1, Stage 3 classifier substrate), Tirosh 2016 AXL/MITF " +
+            "programs, Puram 2017 p-EMT (Table S5, HNSCC), Reactome cGAS-STING " +
+            "pathway (Stage 2.3 type-I IFN). JSON with PMID/DOI per entry.",
+        normal_reference: "Normal-tissue references for safety firing checks: GTEx v8 per-tissue " +
+            "median TPM (parquet) + sample attributes (parquet). Use to quantify " +
+            "off-target activation of any nominated classifier across healthy tissues.",
+        gene_mappings: "Gene ID Conversion Tables: Entrez/Ensembl/RefSeq/UniProt to symbol (NCBI); " +
+            "orthologs (Ensembl Compara) — file: orthologs_{tax_id}.parquet, columns: " +
+            "tax_id, ensembl_gene_id, entrez_id, symbol, relationship, other_tax_id, " +
+            "other_ensembl_gene_id, other_entrez_id, other_symbol; symmetric — to find " +
+            "human orthologs of Macaca fascicularis genes, open orthologs_9541.parquet " +
+            "and filter other_tax_id == '9606'; cross-division (e.g. yeast↔mouse) " +
+            "requires pivoting through human: yeast→human via orthologs_4896.parquet, " +
+            "then human→mouse via orthologs_9606.parquet",
+        omnipath: "OmniPath (interactions, regulons, annotations)",
+        reactome: "Reactome Pathways",
+        progeny: "PROGENy Pathway Weights (decoupler: source/target/weight/padj)",
+        collectri: "CollecTRI TF-Target Regulons (decoupler: source/target/mor)",
+        dorothea: "DoRothEA TF Regulons (decoupler: source/target/weight/confidence)",
+        lincs: "LINCS L1000 Drug Perturbation Consensus Signatures (up/down gene sets)",
+        hpa: "Human Protein Atlas (tissue RNA expression, target safety/secretome, full 107-column atlas)",
+        wikipathways: "WikiPathways Gene Sets",
+        msigdb: "MSigDB Gene Set Collections",
+        safety_targets: "Curated Off-Target Safety Panel (CSV + JSON: chembl_id, gene_symbol, uniprot, organ_system, severity, clinical_consequence)",
+    };
+    const lines = [`\n## ${labels[category] ?? category}`];
+    const grouped = new Map();
+    for (const e of entries) {
+        const key = e.organism ?? e.tax_id ?? e.subtype ?? "general";
+        if (!grouped.has(key))
+            grouped.set(key, []);
+        grouped.get(key).push(e);
+    }
+    for (const [group, items] of grouped) {
+        if (grouped.size > 1)
+            lines.push(`\n### ${group}`);
+        for (const e of items) {
+            const path = join(REFS_ROOT, e.local_path);
+            const name = basename(e.local_path);
+            const info = [e.rows != null ? `${e.rows.toLocaleString()} rows` : null, e.subtype, e.dataset].filter(Boolean).join(", ");
+            lines.push(`  ${name}: ${path}${info ? `  (${info})` : ""}`);
+        }
+    }
+    return lines.join("\n");
+}
+export const listAvailableRefsTool = defineTool({
+    id: "list_available_refs",
+    description: "List all reference data available in the sandbox: single-cell atlases for " +
+        "label transfer (Pan-Cancer T/Myeloid, TICA, Tabula Sapiens, Azimuth PBMC/Tonsil), " +
+        "ProjecTILs CD8/CD4 atlases, CellTypist models, marker panels (PanglaoDB, " +
+        "CellMarker 2.0, Cortex curated), gene signatures (Sade-Feldman, Jerby-Arnon, " +
+        "Tirosh, Puram, cGAS-STING), normal-tissue references (GTEx v8), gene mappings, " +
+        "UniProt, OmniPath networks, Reactome, PROGENy, CollecTRI, DoRothEA, " +
+        "WikiPathways, MSigDB, LINCS L1000, HPA, and the curated off-target safety " +
+        "panel. Returns file paths for h5ad/rds/pkl/parquet/GMT/CSV/JSON resources. " +
+        "No data can be downloaded at runtime — only what this tool returns is available.",
+    inputSchema: z.object({}),
+    execute: async () => {
+        // A missing reference-store mount is an expected environment state —
+        // model it as an `available: false` data variant with a fallback note.
+        try {
+            const raw = await readFile(REGISTRY_FILE, "utf-8");
+            const registry = JSON.parse(raw);
+            const header = [
+                `Reference Store (build ${registry.build_id}, ${registry.generated_at})`,
+                `Total files: ${registry.summary.total_output_files}`,
+                `Mount: ${REFS_ROOT}`,
+            ].join("\n");
+            const categoryOrder = [
+                "atlas_singlecell",
+                "atlas_azimuth",
+                "atlas_projectils",
+                "celltypist_models",
+                "marker_panels",
+                "gene_signatures",
+                "normal_reference",
+                "safety_targets",
+                "progeny",
+                "collectri",
+                "dorothea",
+                "omnipath",
+                "lincs",
+                "msigdb",
+                "wikipathways",
+                "reactome",
+                "hpa",
+                "gene_mappings",
+            ];
+            const known = new Set(categoryOrder);
+            const allCategories = [
+                ...categoryOrder.filter((c) => registry.files.by_category[c]),
+                ...Object.keys(registry.files.by_category).filter((c) => !known.has(c)),
+            ];
+            const sections = allCategories.map((c) => formatCategory(c, registry.files.by_category[c]));
+            return ok({ available: true, content: header + "\n" + sections.join("\n") });
+        }
+        catch {
+            return ok({
+                available: false,
+                content: "Reference store not available. The reference store may not be mounted at /mnt/refs. " +
+                    "Gene mappings, UniProt, OmniPath, Reactome, PROGENy, CollecTRI, DoRothEA, " +
+                    "WikiPathways, MSigDB, LINCS L1000, HPA, and the curated off-target safety panel " +
+                    "cannot be loaded from pre-staged files.",
+            });
+        }
+    },
+});

package/dist/tools/sandbox/report-blocker.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `report_blocker` — a step agent's honest exit when it cannot fulfil its
+ * step (see the harness-sandbox-agents spec). There is no `submit`/`done` tool: a step's deliverable is
+ * its persisted files, so a clean end-of-turn after writing them is the
+ * implicit success. Calling `report_blocker` is the alternative to
+ * improvising an inline result the harness would launder into a green run.
+ *
+ * Mirrors the synthesizer's blocker (`execution/run-synthesis.ts`): the
+ * workflow body owns a per-run `BlockerHolder` and reads `holder.outcome`
+ * after `runAgent`. The tool only records the reason and tells the agent to
+ * stop — the body decides the terminal status.
+ */
+import { type Tool } from "../define-tool.js";
+export interface BlockerOutcome {
+    readonly kind: "blocker";
+    readonly reason: string;
+}
+/** Per-run mutable cell the sandbox-step body reads after the loop. */
+export interface BlockerHolder {
+    outcome: BlockerOutcome | null;
+}
+export declare function createBlockerHolder(): BlockerHolder;
+export declare function createReportBlockerTool(holder: BlockerHolder): Tool;

package/dist/tools/sandbox/report-blocker.js

@@ -0,0 +1,39 @@
+/**
+ * `report_blocker` — a step agent's honest exit when it cannot fulfil its
+ * step (see the harness-sandbox-agents spec). There is no `submit`/`done` tool: a step's deliverable is
+ * its persisted files, so a clean end-of-turn after writing them is the
+ * implicit success. Calling `report_blocker` is the alternative to
+ * improvising an inline result the harness would launder into a green run.
+ *
+ * Mirrors the synthesizer's blocker (`execution/run-synthesis.ts`): the
+ * workflow body owns a per-run `BlockerHolder` and reads `holder.outcome`
+ * after `runAgent`. The tool only records the reason and tells the agent to
+ * stop — the body decides the terminal status.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+export function createBlockerHolder() {
+    return { outcome: null };
+}
+export function createReportBlockerTool(holder) {
+    return defineTool({
+        id: "report_blocker",
+        description: "Terminal. Call this when you cannot fulfil the step — required inputs " +
+            "are missing or unreadable, the requested analysis is infeasible with " +
+            "the available data/packages, or you cannot produce the persisted " +
+            "deliverables (scripts, output files, figures). Pass a clear reason. Do " +
+            "NOT improvise an inline result and narrate it; if you cannot persist " +
+            "real output files, report a blocker. Stop after calling.",
+        inputSchema: z.object({ reason: z.string().min(1) }),
+        execute: async (input) => {
+            if (holder.outcome === null) {
+                holder.outcome = { kind: "blocker", reason: input.reason };
+            }
+            return ok({
+                recorded: true,
+                message: "Blocker recorded. You are done — stop now and do not take further actions.",
+            });
+        },
+    });
+}

package/dist/tools/sandbox/skills.d.ts

@@ -0,0 +1,72 @@
+/**
+ * `skill_search` + `skill_read` — a sandbox agent's access to its declared
+ * skills (method decision trees, API references, worked examples) living as
+ * `SKILL.md` + reference files under `SKILLS_DIR/{skill}/`.
+ *
+ * Dependency-bearing factory (see the harness-durable-runtime spec): captures `skillsDir` and the agent's
+ * declared skill allowlist (`meta.skills`). Both tools are confined to that
+ * allowlist — an agent cannot read another agent's skills.
+ *
+ * `skill_search` is a keyword/substring match over the declared skills' text
+ * files (no embedding index): the per-agent skill set is a handful of
+ * directories, so a bounded scan is enough to route the agent to the right
+ * reference. Expected outcomes are data variants — never throws on a missing
+ * skill, an undeclared skill, or no matches.
+ */
+export interface SkillToolsDeps {
+    /** Absolute path to the skills tree (one subdirectory per skill). */
+    readonly skillsDir: string;
+    /** The agent's declared skills (`meta.skills`) — the access allowlist. */
+    readonly skills: readonly string[];
+}
+interface SkillMatch {
+    readonly skill: string;
+    readonly path: string;
+    readonly line: number;
+    readonly snippet: string;
+    readonly score: number;
+}
+type SkillSearchOutput = {
+    status: "no_skills";
+} | {
+    status: "no_matches";
+    query: string;
+} | {
+    status: "ok";
+    query: string;
+    matches: SkillMatch[];
+};
+type SkillReadOutput = {
+    status: "skill_not_declared";
+    skill: string;
+} | {
+    status: "out_of_scope";
+    skill: string;
+    path: string;
+} | {
+    status: "not_found";
+    skill: string;
+    path: string;
+} | {
+    status: "truncated";
+    skill: string;
+    path: string;
+    content: string;
+    totalSize: number;
+} | {
+    status: "ok";
+    skill: string;
+    path: string;
+    content: string;
+};
+export declare function createSkillTools(deps: SkillToolsDeps): {
+    skillSearch: import("../define-tool.js").Tool<{
+        query: string;
+        topK?: number | undefined;
+    }, SkillSearchOutput>;
+    skillRead: import("../define-tool.js").Tool<{
+        skill: string;
+        path: string;
+    }, SkillReadOutput>;
+};
+export {};

package/dist/tools/sandbox/skills.js

@@ -0,0 +1,144 @@
+/**
+ * `skill_search` + `skill_read` — a sandbox agent's access to its declared
+ * skills (method decision trees, API references, worked examples) living as
+ * `SKILL.md` + reference files under `SKILLS_DIR/{skill}/`.
+ *
+ * Dependency-bearing factory (see the harness-durable-runtime spec): captures `skillsDir` and the agent's
+ * declared skill allowlist (`meta.skills`). Both tools are confined to that
+ * allowlist — an agent cannot read another agent's skills.
+ *
+ * `skill_search` is a keyword/substring match over the declared skills' text
+ * files (no embedding index): the per-agent skill set is a handful of
+ * directories, so a bounded scan is enough to route the agent to the right
+ * reference. Expected outcomes are data variants — never throws on a missing
+ * skill, an undeclared skill, or no matches.
+ */
+import { readFile, readdir, stat } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+/** Bounds — keep a search over a deep skill tree cheap and context-safe. */
+const MAX_FILE_BYTES = 512 * 1024;
+const MAX_SNIPPET = 240;
+const DEFAULT_TOP_K = 10;
+const MAX_TOP_K = 25;
+const TEXT_EXT = /\.(md|markdown|txt|py|r|R|json|ya?ml|csv|tsv)$/;
+async function collectTextFiles(dir, acc) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const e of entries) {
+        const full = join(dir, e.name);
+        if (e.isDirectory()) {
+            await collectTextFiles(full, acc);
+        }
+        else if (TEXT_EXT.test(e.name)) {
+            acc.push(full);
+        }
+    }
+}
+export function createSkillTools(deps) {
+    const allowed = new Set(deps.skills);
+    const skillSearch = defineTool({
+        id: "skill_search",
+        description: "Search your skills (method decision trees, API references, worked " +
+            "examples) by keyword. Start here when picking a method or verifying an " +
+            "API detail. Returns matching skill files with a line snippet — then " +
+            "`skill_read` the file. No matches returns a data variant.",
+        inputSchema: z.object({
+            query: z.string().min(1).describe("Keywords to match (e.g. 'PyDESeq2 contrast syntax')."),
+            topK: z.number().int().min(1).max(MAX_TOP_K).optional().describe(`Max results to return. Defaults to ${DEFAULT_TOP_K}.`),
+        }),
+        execute: async ({ query, topK }) => {
+            if (allowed.size === 0) {
+                return ok({ status: "no_skills" });
+            }
+            const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+            const matches = [];
+            for (const skill of allowed) {
+                const skillRoot = resolve(deps.skillsDir, skill);
+                const files = [];
+                await collectTextFiles(skillRoot, files);
+                for (const file of files) {
+                    let content;
+                    try {
+                        const s = await stat(file);
+                        if (s.size > MAX_FILE_BYTES)
+                            continue;
+                        content = await readFile(file, "utf8");
+                    }
+                    catch {
+                        continue;
+                    }
+                    const lower = content.toLowerCase();
+                    const distinct = tokens.filter((t) => lower.includes(t)).length;
+                    if (distinct === 0)
+                        continue;
+                    const lines = content.split(/\r?\n/);
+                    const hitIdx = lines.findIndex((l) => {
+                        const ll = l.toLowerCase();
+                        return tokens.some((t) => ll.includes(t));
+                    });
+                    const line = lines[hitIdx] ?? "";
+                    matches.push({
+                        skill,
+                        path: relative(skillRoot, file).split(sep).join("/"),
+                        line: hitIdx + 1,
+                        snippet: line.trim().slice(0, MAX_SNIPPET),
+                        score: distinct,
+                    });
+                }
+            }
+            if (matches.length === 0) {
+                return ok({ status: "no_matches", query });
+            }
+            matches.sort((a, b) => b.score - a.score);
+            return ok({
+                status: "ok",
+                query,
+                matches: matches.slice(0, topK ?? DEFAULT_TOP_K),
+            });
+        },
+    });
+    const skillRead = defineTool({
+        id: "skill_read",
+        description: "Read a file from one of your skills (e.g. its SKILL.md or a reference " +
+            "found via skill_search). Confined to your declared skills. Undeclared " +
+            "skills and missing paths return a data variant.",
+        inputSchema: z.object({
+            skill: z.string().min(1).describe("Skill name (one of your declared skills)."),
+            path: z.string().min(1).describe("File path within the skill, e.g. 'SKILL.md' or 'references/pydeseq2-api.md'."),
+        }),
+        execute: async ({ skill, path }) => {
+            if (!allowed.has(skill)) {
+                return ok({ status: "skill_not_declared", skill });
+            }
+            const skillRoot = resolve(deps.skillsDir, skill);
+            const target = resolve(skillRoot, path);
+            if (target !== skillRoot && !target.startsWith(skillRoot + sep)) {
+                return ok({ status: "out_of_scope", skill, path });
+            }
+            let content;
+            try {
+                const s = await stat(target);
+                if (!s.isFile())
+                    return ok({ status: "not_found", skill, path });
+                if (s.size > MAX_FILE_BYTES) {
+                    content = (await readFile(target)).subarray(0, MAX_FILE_BYTES).toString("utf8");
+                    return ok({ status: "truncated", skill, path, content, totalSize: s.size });
+                }
+                content = await readFile(target, "utf8");
+            }
+            catch {
+                return ok({ status: "not_found", skill, path });
+            }
+            return ok({ status: "ok", skill, path, content });
+        },
+    });
+    return { skillSearch, skillRead };
+}

package/dist/tools/workspace/edit-file.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `edit_file` — sandbox-gated workspace edit, confined to the agent's writable
+ * working directory. Composes the read seam (fetch current content) with a
+ * search/replace and the `WorkspaceMutator` seam (write the result) — same
+ * resolution + confinement contract as `write_file`, no path logic of its own
+ * (see the harness-workspace-tools spec).
+ *
+ * Edit semantics: replace `old_string` with `new_string`. `old_string` MUST
+ * occur in the file; when `replace_all` is false (default) it MUST occur
+ * exactly once. Provenance hashes the post-edit content — recorded by the
+ * mutator.
+ */
+import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
+import type { WorkspaceMutator, WriteFileResult } from "./mutator.js";
+/** Outcome of an `edit_file` call — expected outcomes are data variants, never throws. */
+export type EditFileResult = {
+    readonly status: "file_not_found";
+    readonly path: string;
+} | {
+    readonly status: "not_found";
+    readonly path: string;
+} | {
+    readonly status: "not_unique";
+    readonly path: string;
+    readonly occurrences: number;
+} | Exclude<WriteFileResult, {
+    status: "ok";
+}> | {
+    readonly status: "ok";
+    readonly path: string;
+    readonly replacements: number;
+    readonly bytesWritten: number;
+};
+export interface EditFileDeps {
+    readonly mutator: WorkspaceMutator;
+    /** Read seam used to fetch current file content for search/replace. */
+    readonly workspaceFilesystem: WorkspaceFilesystem;
+    /** Absolute host working directory — relative read/write paths resolve here. */
+    readonly workingDir: string;
+}
+export declare function createEditFileTool(deps: EditFileDeps): import("../define-tool.js").Tool<{
+    path: string;
+    old_string: string;
+    new_string: string;
+    replace_all: boolean;
+}, EditFileResult>;

package/dist/tools/workspace/edit-file.js

@@ -0,0 +1,100 @@
+/**
+ * `edit_file` — sandbox-gated workspace edit, confined to the agent's writable
+ * working directory. Composes the read seam (fetch current content) with a
+ * search/replace and the `WorkspaceMutator` seam (write the result) — same
+ * resolution + confinement contract as `write_file`, no path logic of its own
+ * (see the harness-workspace-tools spec).
+ *
+ * Edit semantics: replace `old_string` with `new_string`. `old_string` MUST
+ * occur in the file; when `replace_all` is false (default) it MUST occur
+ * exactly once. Provenance hashes the post-edit content — recorded by the
+ * mutator.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { unwrapOrThrow } from "../../lib/result.js";
+const EditFileInputSchema = z.object({
+    path: z
+        .string()
+        .min(1)
+        .describe("File path (relative to your working directory, or absolute " + "'/<analysisId>/...'). Read the file first to get the exact text to replace."),
+    old_string: z
+        .string()
+        .min(1)
+        .describe("The exact text to find and replace. Must occur in the file. When " +
+        "replace_all=false (default), must occur exactly once — include " +
+        "enough surrounding context to make it unique."),
+    new_string: z.string().describe("The replacement text."),
+    replace_all: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("If true, replace every occurrence. If false (default), old_string " + "must occur exactly once or the edit returns a `not_unique` data variant."),
+});
+function replaceString(content, oldString, newString, replaceAll) {
+    if (!content.includes(oldString))
+        return { kind: "not_found" };
+    if (replaceAll) {
+        const parts = content.split(oldString);
+        return { kind: "ok", content: parts.join(newString), replacements: parts.length - 1 };
+    }
+    const first = content.indexOf(oldString);
+    const last = content.lastIndexOf(oldString);
+    if (first !== last) {
+        let count = 0;
+        let idx = -1;
+        while ((idx = content.indexOf(oldString, idx + 1)) !== -1)
+            count++;
+        return { kind: "not_unique", count };
+    }
+    return {
+        kind: "ok",
+        content: content.slice(0, first) + newString + content.slice(first + oldString.length),
+        replacements: 1,
+    };
+}
+export function createEditFileTool(deps) {
+    return defineTool({
+        id: "edit_file",
+        // Body-only `awaitExec`-recv → runs unwrapped in the workflow body (see the harness-tools spec).
+        executionMode: "workflow",
+        description: "Edit a file in your working directory by replacing specific text. " +
+            "Read the file first to get the exact text. When replace_all is false " +
+            "(default), old_string must occur exactly once. Returns `out_of_prefix` " +
+            "/ `out_of_scope` / `file_not_found` / `not_found` / `not_unique` data " +
+            "variants — never throws on expected outcomes.",
+        inputSchema: EditFileInputSchema,
+        execute: async ({ path, old_string, new_string, replace_all }, ctx) => {
+            const read = unwrapOrThrow(await deps.workspaceFilesystem.readFile({
+                session: ctx.session,
+                path,
+                workingDir: deps.workingDir,
+            }));
+            if (read.kind === "not_found")
+                return ok({ status: "file_not_found", path });
+            if (read.kind === "out_of_scope")
+                return ok({ status: "out_of_scope", path });
+            const replaced = replaceString(read.content.toString("utf8"), old_string, new_string, replace_all);
+            if (replaced.kind === "not_found")
+                return ok({ status: "not_found", path });
+            if (replaced.kind === "not_unique") {
+                return ok({ status: "not_unique", path, occurrences: replaced.count });
+            }
+            const result = await deps.mutator.writeFile({
+                path,
+                content: replaced.content,
+                toolName: "edit_file",
+                emit: ctx.emit,
+            });
+            if (result.status !== "ok")
+                return ok(result);
+            return ok({
+                status: "ok",
+                path: result.path,
+                replacements: replaced.replacements,
+                bytesWritten: result.bytesWritten,
+            });
+        },
+    });
+}

package/dist/tools/workspace/execute-command.d.ts

@@ -0,0 +1,80 @@
+/**
+ * `execute_command` — the single chokepoint through which sandbox commands
+ * run.
+ *
+ * Dependency-bearing factory (see the harness-durable-runtime spec): captures a `SandboxClient`, the
+ * live `SandboxRef` for the step, and the per-call execId minter. No other
+ * tool, agent, or workflow step is permitted to POST to sandbox-server's
+ * `/exec` directly — `SandboxClient` is intentionally injected only here so
+ * the durability / idempotency / liveness story `harness-sandbox-exec`
+ * owns holds uniformly across all sandbox command execution.
+ *
+ * `execId` is derived as `${workflowId}:${stepId}:${functionId}` so replays
+ * land on the cached DBOS step output rather than re-submitting; the same
+ * `execId` is the step name `submitExec` uses (`sandbox.submit-exec.${execId}`).
+ *
+ * Provenance for files written *inside* the sandbox by the executed command
+ * is NOT recorded here — sandbox-server emits provenance frames (see
+ * `sandbox-provenance-tracking`), and artifact registration reconciles them.
+ * The harness-side mutate tools (`write_file`, `edit_file`) hash and record
+ * the writes *they* perform, but `execute_command`'s opaque commands do not.
+ */
+import type { SandboxClient } from "../../sandbox/client.js";
+import type { SandboxRef } from "../../sandbox/types.js";
+import type { ProvenanceCollector } from "../../provenance/collector.js";
+export interface ExecuteCommandDeps {
+    readonly sandboxClient: SandboxClient;
+    /** Live sandbox handle for the step. Created once per step at composition root. */
+    readonly sandbox: SandboxRef;
+    /** Stable across replay. The workflow's DBOS workflow id. */
+    readonly workflowId: string;
+    /** Stable across replay. The sandbox step's identifier within the workflow. */
+    readonly stepId: string;
+    /**
+     * Mints a stable per-call function id. The composition root closes over a
+     * monotonic counter; the agent loop's tool-call order is replay-deterministic
+     * (the LLM call wrapping it is a cached DBOS step), so the counter reaches
+     * the same value at each call site on replay.
+     */
+    readonly nextFunctionId: () => string;
+    /** Absolute unix-ms deadline for `awaitExec`. Typically derived from `step.timeout`. */
+    readonly deadlineMs: () => number;
+    /**
+     * In-sandbox absolute path of the agent's working directory (e.g.
+     * `/{resourceId}/runs/{runId}/{stepId}`). Used as the default `cwd` so a
+     * command's relative paths match `write_file`/`read_file` relative paths,
+     * and as the base a supplied relative `cwd` resolves against (see the harness-workspace-tools spec).
+     */
+    readonly defaultCwd: string;
+    /** Tag the active-sandbox row with the in-flight execId for the liveness watchdog. */
+    readonly markExecActive?: (execId: string) => Promise<void>;
+    /**
+     * Step-scoped lineage collector. Each exec's `ExecResult.provenance`
+     * frame is fed here (reads → inputs, writes → outputs) so post-step
+     * registration carries real input/script edges. Omit to skip capture.
+     */
+    readonly lineageCollector?: ProvenanceCollector;
+    /** Analysis resource mount root (`/{resourceId}`) — strips frame paths to relative. */
+    readonly mountRoot?: string;
+}
+export declare function createExecuteCommandTool(deps: ExecuteCommandDeps): import("../define-tool.js").Tool<{
+    command: string[];
+    cwd?: string | undefined;
+    env?: Record<string, string> | undefined;
+    timeoutSeconds?: number | undefined;
+}, {
+    execId: string;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    stdoutTruncated: boolean;
+    stderrTruncated: boolean;
+    stdoutTotalLength: number;
+    stderrTotalLength: number;
+    durationMs: number | null;
+    timedOut: boolean;
+    syntheticFailure?: {
+        readonly reason: string;
+    };
+    status: "ok";
+}>;