@inflexa-ai/harness 0.1.1

package/dist/tools/workspace/execute-command.js

@@ -0,0 +1,95 @@
+/**
+ * `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 { posix as posixPath } from "node:path";
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { feedExecFrame } from "../../provenance/exec-frame.js";
+import { boundExecResult } from "./result-bounds.js";
+import { runSandboxExec } from "./run-exec.js";
+const ExecuteCommandInputSchema = z.object({
+    command: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe("argv array — e.g. ['python', 'scripts/run.py'] or ['head', '-n', '50', 'data/inputs/x.csv']. " +
+        "Not passed through a shell; quoting and globbing are not expanded."),
+    cwd: z
+        .string()
+        .optional()
+        .describe("Working directory inside the sandbox. Defaults to your working " +
+        "directory; a relative value is resolved against it, an absolute " +
+        "'/<analysisId>/...' value is used as-is."),
+    env: z.record(z.string(), z.string()).optional().describe("Extra environment variables for this command."),
+    timeoutSeconds: z.number().int().positive().optional().describe("Per-command timeout in seconds; capped by the step deadline."),
+});
+export function createExecuteCommandTool(deps) {
+    const { sandboxClient, sandbox, workflowId, stepId, nextFunctionId, deadlineMs, defaultCwd, markExecActive, lineageCollector, mountRoot } = deps;
+    return defineTool({
+        id: "execute_command",
+        // `awaitExec`-recv is body-only (`DBOS.recv`), so this runs unwrapped in
+        // the workflow body; durability is self-owned (submit step + body recv). See the harness-tools spec.
+        executionMode: "workflow",
+        description: "Run a command in the sandbox and return its stdout/stderr/exit code. " +
+            "Use for scripts, CLI tools, shell pipes, and anything the workspace " +
+            "tools don't express. stdout and stderr are each capped at 8 KiB; oversize " +
+            "streams come back with truncation markers. Failures are returned as data, " +
+            "not thrown. stdout/stderr are EPHEMERAL and are NOT a deliverable — use " +
+            "this to confirm a command ran, not to produce results. Do NOT compute " +
+            "analysis results via 'python -c' / inline one-liners and read them from " +
+            "stdout; that work is lost. Write a script and persist its outputs to output/.",
+        inputSchema: ExecuteCommandInputSchema,
+        execute: async ({ command, cwd, env, timeoutSeconds }, ctx) => {
+            const execId = `${workflowId}:${stepId}:${nextFunctionId()}`;
+            const effectiveCwd = cwd === undefined ? defaultCwd : cwd.startsWith("/") ? cwd : posixPath.join(defaultCwd, cwd);
+            const result = await runSandboxExec({
+                sandboxClient,
+                sandbox,
+                execId,
+                command,
+                cwd: effectiveCwd,
+                ...(env === undefined ? {} : { env }),
+                ...(timeoutSeconds === undefined ? {} : { timeoutSeconds }),
+                deadlineMs: deadlineMs(),
+                emit: ctx.emit,
+                ...(markExecActive ? { markExecActive } : {}),
+            });
+            // Thread the runtime file-I/O frame into the step's lineage collector.
+            // Best-effort: a collector failure must never fail the exec.
+            if (lineageCollector && mountRoot) {
+                try {
+                    feedExecFrame({
+                        collector: lineageCollector,
+                        mountRoot,
+                        command,
+                        exitCode: result.exitCode,
+                        durationMs: result.durationMs,
+                        ...(result.provenance ? { provenance: result.provenance } : {}),
+                    });
+                }
+                catch (err) {
+                    console.warn(`[execute_command] provenance frame handling failed (non-fatal) for ${execId}: ${err instanceof Error ? err.message : err}`);
+                }
+            }
+            return ok({ status: "ok", ...boundExecResult(result) });
+        },
+    });
+}

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

@@ -0,0 +1,24 @@
+/**
+ * `file_stat` tool — type + size of a workspace path over the read seam.
+ *
+ * Dependency-bearing factory (see the harness-durable-runtime spec): captures the `WorkspaceFilesystem`
+ * and the optional working directory relative paths resolve against (see the harness-workspace-tools spec).
+ * Expected outcomes are data variants — `not_found` / `out_of_scope`.
+ */
+import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
+type FileStatOutput = {
+    status: "ok";
+    path: string;
+    type: "file" | "directory";
+    size: number;
+} | {
+    status: "not_found";
+    path: string;
+} | {
+    status: "out_of_scope";
+    path: string;
+};
+export declare function createFileStatTool(fs: WorkspaceFilesystem, workingDir?: string): import("../define-tool.js").Tool<{
+    path: string;
+}, FileStatOutput>;
+export {};

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

@@ -0,0 +1,37 @@
+/**
+ * `file_stat` tool — type + size of a workspace path over the read seam.
+ *
+ * Dependency-bearing factory (see the harness-durable-runtime spec): captures the `WorkspaceFilesystem`
+ * and the optional working directory relative paths resolve against (see the harness-workspace-tools spec).
+ * Expected outcomes are data variants — `not_found` / `out_of_scope`.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { unwrapOrThrow } from "../../lib/result.js";
+const FileStatInputSchema = z.object({
+    path: z
+        .string()
+        .min(1)
+        .describe("Path to stat. Relative paths resolve against your working directory; " + "an absolute '/<analysisId>/...' path against the analysis root."),
+});
+export function createFileStatTool(fs, workingDir) {
+    return defineTool({
+        id: "file_stat",
+        description: "Stat a workspace path: whether it is a file or directory and its size " +
+            "in bytes. Use before reading to size a file. Missing and out-of-scope " +
+            "paths return a data variant, not an error.",
+        inputSchema: FileStatInputSchema,
+        execute: async ({ path }, ctx) => {
+            const result = unwrapOrThrow(await fs.stat({ session: ctx.session, path, workingDir }));
+            switch (result.kind) {
+                case "ok":
+                    return ok({ status: "ok", path, type: result.type, size: result.size });
+                case "not_found":
+                    return ok({ status: "not_found", path });
+                case "out_of_scope":
+                    return ok({ status: "out_of_scope", path });
+            }
+        },
+    });
+}

package/dist/tools/workspace/grep.d.ts

@@ -0,0 +1,57 @@
+/**
+ * grep tool — pattern search over the workspace read seam.
+ *
+ * Dependency-bearing factory (see the harness-durable-runtime spec): captures the `WorkspaceFilesystem`.
+ * JS implementation over `list` + `readFile` — no ripgrep binary required.
+ * Expected outcomes are data variants: no matches → `no_matches`; over-cap →
+ * `truncated` with a marker; missing path → `not_found`; escape attempt →
+ * `out_of_scope`. Only unexpected I/O failures throw.
+ */
+import type { ListEntry, WorkspaceFilesystem } from "../../workspace/filesystem.js";
+interface Match {
+    readonly file: string;
+    readonly line: number;
+    readonly preview: string;
+}
+type GrepOutput = {
+    status: "invalid_pattern";
+    pattern: string;
+    error: string;
+} | {
+    status: "out_of_scope";
+    path: string;
+} | {
+    status: "not_found";
+    path: string;
+} | {
+    status: "no_matches";
+    path: string;
+    pattern: string;
+} | {
+    status: "truncated";
+    path: string;
+    pattern: string;
+    matches: Match[];
+    cap: {
+        maxMatches: number;
+        maxBytesPerLine: number;
+    };
+} | {
+    status: "ok";
+    path: string;
+    pattern: string;
+    matches: Match[];
+};
+export declare function createGrepTool(fs: WorkspaceFilesystem, workingDir?: string): import("../define-tool.js").Tool<{
+    pattern: string;
+    path: string;
+    ignoreCase?: boolean | undefined;
+}, GrepOutput>;
+/** Exposed for tests — the caps `grep` enforces. */
+export declare const GREP_LIMITS: {
+    readonly DEFAULT_MAX_MATCHES: 50;
+    readonly DEFAULT_MAX_MATCH_BYTES: 512;
+    readonly MAX_GREP_FILE_BYTES: number;
+};
+export type GrepListEntry = ListEntry;
+export {};

package/dist/tools/workspace/grep.js

@@ -0,0 +1,154 @@
+/**
+ * grep tool — pattern search over the workspace read seam.
+ *
+ * Dependency-bearing factory (see the harness-durable-runtime spec): captures the `WorkspaceFilesystem`.
+ * JS implementation over `list` + `readFile` — no ripgrep binary required.
+ * Expected outcomes are data variants: no matches → `no_matches`; over-cap →
+ * `truncated` with a marker; missing path → `not_found`; escape attempt →
+ * `out_of_scope`. Only unexpected I/O failures throw.
+ */
+import { posix as posixPath } from "node:path";
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { unwrapOrThrow } from "../../lib/result.js";
+const DEFAULT_MAX_MATCHES = 50;
+const DEFAULT_MAX_MATCH_BYTES = 512;
+/** Files larger than this aren't grepped — keeps a stray binary blob from blocking the seam. */
+const MAX_GREP_FILE_BYTES = 1024 * 1024;
+const MAX_DIR_DEPTH = 8;
+const GrepInputSchema = z.object({
+    pattern: z
+        .string()
+        .min(1)
+        .describe("Regular expression to match. Anchored per line; case-sensitive unless " + "`ignoreCase` is true."),
+    path: z
+        .string()
+        .min(1)
+        .describe("Workspace path to a file or directory. Directories are searched " + "recursively up to a bounded depth."),
+    ignoreCase: z.boolean().optional().describe("Case-insensitive match. Defaults to false."),
+});
+export function createGrepTool(fs, workingDir) {
+    return defineTool({
+        id: "grep",
+        description: "Regex search over workspace files (input data, prior runs, step " +
+            "outputs, summaries, syntheses, data profile). Pass a file or a " +
+            "directory path; directories are walked recursively. Results are " +
+            `capped at ${DEFAULT_MAX_MATCHES} matches and ${DEFAULT_MAX_MATCH_BYTES} ` +
+            "bytes per line — narrow your path or pattern if you hit the cap. " +
+            "No matches and out-of-scope paths return data variants, not errors.",
+        inputSchema: GrepInputSchema,
+        execute: async ({ pattern, path, ignoreCase }, ctx) => {
+            let regex;
+            try {
+                regex = new RegExp(pattern, ignoreCase === true ? "i" : "");
+            }
+            catch (err) {
+                return ok({
+                    status: "invalid_pattern",
+                    pattern,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            const statResult = unwrapOrThrow(await fs.stat({ session: ctx.session, path, workingDir }));
+            if (statResult.kind === "out_of_scope") {
+                return ok({ status: "out_of_scope", path });
+            }
+            if (statResult.kind === "not_found") {
+                return ok({ status: "not_found", path });
+            }
+            const matches = [];
+            let truncated = false;
+            const session = ctx.session;
+            async function searchFile(filePath) {
+                if (matches.length >= DEFAULT_MAX_MATCHES) {
+                    truncated = true;
+                    return;
+                }
+                const read = unwrapOrThrow(await fs.readFile({
+                    session,
+                    path: filePath,
+                    maxBytes: MAX_GREP_FILE_BYTES,
+                    workingDir,
+                }));
+                if (read.kind === "not_found" || read.kind === "out_of_scope")
+                    return;
+                const buf = read.content;
+                if (looksBinary(buf))
+                    return;
+                const text = buf.toString("utf8");
+                if (read.kind === "truncated")
+                    truncated = true;
+                const lines = text.split(/\r?\n/);
+                for (let i = 0; i < lines.length; i++) {
+                    if (matches.length >= DEFAULT_MAX_MATCHES) {
+                        truncated = true;
+                        return;
+                    }
+                    const line = lines[i];
+                    if (regex.test(line)) {
+                        matches.push({
+                            file: filePath,
+                            line: i + 1,
+                            preview: line.length > DEFAULT_MAX_MATCH_BYTES ? line.slice(0, DEFAULT_MAX_MATCH_BYTES) : line,
+                        });
+                    }
+                }
+            }
+            async function walk(dirPath, depth) {
+                if (depth > MAX_DIR_DEPTH)
+                    return;
+                if (matches.length >= DEFAULT_MAX_MATCHES) {
+                    truncated = true;
+                    return;
+                }
+                const list = unwrapOrThrow(await fs.list({ session, path: dirPath, workingDir }));
+                if (list.kind !== "ok")
+                    return;
+                for (const entry of list.entries) {
+                    if (matches.length >= DEFAULT_MAX_MATCHES) {
+                        truncated = true;
+                        return;
+                    }
+                    const child = posixPath.join(dirPath, entry.name);
+                    if (entry.type === "directory") {
+                        await walk(child, depth + 1);
+                    }
+                    else {
+                        await searchFile(child);
+                    }
+                }
+            }
+            if (statResult.type === "file") {
+                await searchFile(path);
+            }
+            else {
+                await walk(path, 0);
+            }
+            if (matches.length === 0) {
+                return ok({ status: "no_matches", path, pattern });
+            }
+            if (truncated) {
+                return ok({
+                    status: "truncated",
+                    path,
+                    pattern,
+                    matches,
+                    cap: { maxMatches: DEFAULT_MAX_MATCHES, maxBytesPerLine: DEFAULT_MAX_MATCH_BYTES },
+                });
+            }
+            return ok({ status: "ok", path, pattern, matches });
+        },
+    });
+}
+/** Quick binary heuristic — skip files with NULs in the first kibibyte. */
+function looksBinary(buf) {
+    const probe = buf.subarray(0, Math.min(buf.length, 1024));
+    return probe.includes(0);
+}
+/** Exposed for tests — the caps `grep` enforces. */
+export const GREP_LIMITS = {
+    DEFAULT_MAX_MATCHES,
+    DEFAULT_MAX_MATCH_BYTES,
+    MAX_GREP_FILE_BYTES,
+};

package/dist/tools/workspace/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Workspace barrel — the workspace tool surfaces.
+ *
+ * Read surface (sandbox-independent): semantic file search, raw read + grep
+ * over the workspace filesystem seam, plus file/plan display.
+ *
+ * Mutate surface (sandbox-gated): `execute_command` (single chokepoint for
+ * sandbox commands), `write_file` and `edit_file` scoped to the step's
+ * writable artifact directory. Each mutate factory captures a `SandboxClient`
+ * and the step coordinates; only `execute_command` is permitted to drive
+ * sandbox-server's `/exec` — `write_file` / `edit_file` ride the same
+ * submit/await path through `runSandboxExec`.
+ */
+export * from "./workspace-search.js";
+export * from "./show-file.js";
+export * from "./show-plan.js";
+export * from "./read-file.js";
+export * from "./list-files.js";
+export * from "./file-stat.js";
+export * from "./grep.js";
+export * from "./mutator.js";
+export * from "./execute-command.js";
+export * from "./write-file.js";
+export * from "./edit-file.js";
+export { EXEC_STREAM_BYTE_CAP, boundExecResult } from "./result-bounds.js";
+export type { BoundedExecResult } from "./result-bounds.js";

package/dist/tools/workspace/index.js

@@ -0,0 +1,27 @@
+/**
+ * Workspace barrel — the workspace tool surfaces.
+ *
+ * Read surface (sandbox-independent): semantic file search, raw read + grep
+ * over the workspace filesystem seam, plus file/plan display.
+ *
+ * Mutate surface (sandbox-gated): `execute_command` (single chokepoint for
+ * sandbox commands), `write_file` and `edit_file` scoped to the step's
+ * writable artifact directory. Each mutate factory captures a `SandboxClient`
+ * and the step coordinates; only `execute_command` is permitted to drive
+ * sandbox-server's `/exec` — `write_file` / `edit_file` ride the same
+ * submit/await path through `runSandboxExec`.
+ */
+// Read surface
+export * from "./workspace-search.js";
+export * from "./show-file.js";
+export * from "./show-plan.js";
+export * from "./read-file.js";
+export * from "./list-files.js";
+export * from "./file-stat.js";
+export * from "./grep.js";
+// Mutate surface
+export * from "./mutator.js";
+export * from "./execute-command.js";
+export * from "./write-file.js";
+export * from "./edit-file.js";
+export { EXEC_STREAM_BYTE_CAP, boundExecResult } from "./result-bounds.js";

package/dist/tools/workspace/list-files.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `list_files` tool — directory listing over the workspace read seam.
+ *
+ * Dependency-bearing factory (see the harness-durable-runtime spec): captures the `WorkspaceFilesystem`
+ * and the optional working directory relative paths resolve against (see the harness-workspace-tools spec).
+ * Expected outcomes are data variants — a missing path is `not_found`, a path
+ * escaping the analysis tree is `out_of_scope`.
+ */
+import type { ListEntry, WorkspaceFilesystem } from "../../workspace/filesystem.js";
+type ListFilesOutput = {
+    status: "ok";
+    path: string;
+    entries: readonly ListEntry[];
+} | {
+    status: "not_found";
+    path: string;
+} | {
+    status: "out_of_scope";
+    path: string;
+};
+export declare function createListFilesTool(fs: WorkspaceFilesystem, workingDir?: string): import("../define-tool.js").Tool<{
+    path: string;
+}, ListFilesOutput>;
+export {};

package/dist/tools/workspace/list-files.js

@@ -0,0 +1,38 @@
+/**
+ * `list_files` tool — directory listing over the workspace read seam.
+ *
+ * Dependency-bearing factory (see the harness-durable-runtime spec): captures the `WorkspaceFilesystem`
+ * and the optional working directory relative paths resolve against (see the harness-workspace-tools spec).
+ * Expected outcomes are data variants — a missing path is `not_found`, a path
+ * escaping the analysis tree is `out_of_scope`.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { unwrapOrThrow } from "../../lib/result.js";
+const ListFilesInputSchema = z.object({
+    path: z
+        .string()
+        .min(1)
+        .describe("Directory path. Relative paths resolve against your working directory; " + "an absolute '/<analysisId>/...' path against the analysis root."),
+});
+export function createListFilesTool(fs, workingDir) {
+    return defineTool({
+        id: "list_files",
+        description: "List the entries (files and directories, with file sizes) in a " +
+            "workspace directory. Faster than `ls` via execute_command. Missing " +
+            "and out-of-scope paths return a data variant, not an error.",
+        inputSchema: ListFilesInputSchema,
+        execute: async ({ path }, ctx) => {
+            const result = unwrapOrThrow(await fs.list({ session: ctx.session, path, workingDir }));
+            switch (result.kind) {
+                case "ok":
+                    return ok({ status: "ok", path, entries: result.entries });
+                case "not_found":
+                    return ok({ status: "not_found", path });
+                case "out_of_scope":
+                    return ok({ status: "out_of_scope", path });
+            }
+        },
+    });
+}

package/dist/tools/workspace/mutator.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The workspace mutate seam — `{ writeFile }` confined to one agent's writable
+ * working directory. The write-side counterpart to `WorkspaceFilesystem`
+ * (see the harness-workspace-tools spec).
+ *
+ * It lives here (next to `run-exec`) rather than under `workspace/` because the
+ * write path is sandbox-coupled: a write is one `SandboxClient` exec, not a
+ * host `fs` call. The seam owns the whole gauntlet that `write_file` and
+ * `edit_file` previously each re-implemented inline — resolve + confine to the
+ * working directory, derive the in-sandbox path, and write the bytes through
+ * the sandbox — so the confinement invariant is concentrated in one place
+ * instead of being a per-tool convention.
+ */
+import type { ProvenanceCollector } from "../../provenance/collector.js";
+import type { SandboxClient } from "../../sandbox/client.js";
+import type { SandboxRef } from "../../sandbox/types.js";
+import type { EmitFn } from "../define-tool.js";
+import { type BoundedExecResult } from "./result-bounds.js";
+/** Outcome of a confined write. Expected outcomes are data variants — never throws. */
+export type WriteFileResult = {
+    readonly status: "ok";
+    readonly path: string;
+    readonly bytesWritten: number;
+} | {
+    readonly status: "out_of_scope";
+    readonly path: string;
+} | {
+    readonly status: "out_of_prefix";
+    readonly path: string;
+} | ({
+    readonly status: "write_failed";
+    readonly path: string;
+} & BoundedExecResult);
+/**
+ * Agent-visible name of the tool driving a confined write. Rides the write args
+ * so a successful write is attributed to the invoking tool in provenance
+ * (`inflexa:tool` in the signed document) — the seam records the write without
+ * inspecting its caller.
+ */
+export type MutateToolName = "write_file" | "edit_file";
+export interface WorkspaceMutatorDeps {
+    readonly sandboxClient: SandboxClient;
+    readonly sandbox: SandboxRef;
+    /** Absolute host root of this analysis's workspace tree — used by the resolver. */
+    readonly workspaceRoot: string;
+    readonly analysisId: string;
+    readonly stepId: string;
+    readonly workflowId: string;
+    /** Absolute host working directory: relative paths resolve here AND writes are confined here. */
+    readonly workingDir: string;
+    /**
+     * In-sandbox absolute path of `workingDir` (mirrors `execute_command`'s
+     * `defaultCwd`). Passed as the write exec's `cwd` so sandbox-server roots
+     * its tree-differ here and reports the written file as a live delta — an
+     * empty `cwd` disables the differ, so write-only files (e.g. scripts/)
+     * would never reach the live file tree.
+     */
+    readonly sandboxWorkingDir: string;
+    readonly nextFunctionId: () => string;
+    readonly deadlineMs: () => number;
+    /**
+     * Step-scoped lineage collector. On a successful confined write the seam
+     * records a file-tool provenance record here — hash and size computed
+     * in-process from the exact bytes written. Omit to skip recording; the
+     * write itself proceeds unchanged.
+     */
+    readonly lineageCollector?: ProvenanceCollector;
+}
+export interface WorkspaceMutator {
+    /**
+     * Resolve `path` against the working directory (relative) or analysis root
+     * (absolute `/{analysisId}/...`), confine the result to the working
+     * directory, and write `content` through the sandbox. `toolName` names the
+     * invoking tool so a successful write is attributed to it in provenance.
+     */
+    writeFile(args: {
+        readonly path: string;
+        readonly content: string;
+        readonly toolName: MutateToolName;
+        readonly emit: EmitFn;
+    }): Promise<WriteFileResult>;
+}
+export declare function createWorkspaceMutator(deps: WorkspaceMutatorDeps): WorkspaceMutator;

package/dist/tools/workspace/mutator.js

@@ -0,0 +1,81 @@
+/**
+ * The workspace mutate seam — `{ writeFile }` confined to one agent's writable
+ * working directory. The write-side counterpart to `WorkspaceFilesystem`
+ * (see the harness-workspace-tools spec).
+ *
+ * It lives here (next to `run-exec`) rather than under `workspace/` because the
+ * write path is sandbox-coupled: a write is one `SandboxClient` exec, not a
+ * host `fs` call. The seam owns the whole gauntlet that `write_file` and
+ * `edit_file` previously each re-implemented inline — resolve + confine to the
+ * working directory, derive the in-sandbox path, and write the bytes through
+ * the sandbox — so the confinement invariant is concentrated in one place
+ * instead of being a per-tool convention.
+ */
+import { computeSha256 } from "../../lib/fs-helpers.js";
+import { resolveForWrite } from "../../workspace/paths.js";
+import { boundExecResult } from "./result-bounds.js";
+import { runSandboxExec } from "./run-exec.js";
+const WRITE_BYTES_PROGRAM = [
+    "import sys,base64,os",
+    "p=sys.argv[1]",
+    "os.makedirs(os.path.dirname(p), exist_ok=True)",
+    "open(p,'wb').write(base64.b64decode(sys.argv[2]))",
+].join("\n");
+export function createWorkspaceMutator(deps) {
+    return {
+        async writeFile({ path, content, toolName, emit }) {
+            const scoped = resolveForWrite({
+                workspaceRoot: deps.workspaceRoot,
+                analysisId: deps.analysisId,
+                workingDir: deps.workingDir,
+                path,
+            });
+            if (scoped.kind === "out_of_scope")
+                return { status: "out_of_scope", path };
+            if (scoped.kind === "out_of_prefix")
+                return { status: "out_of_prefix", path };
+            // Analysis-root-relative, forward-slashed: the sandbox path prepends
+            // the `/{analysisId}` mount; the provenance record uses the bare tail
+            // (the collector normalizes it step-relative itself).
+            const relative = scoped.relative.split("\\").join("/");
+            const sandboxPath = `/${deps.analysisId}/${relative}`;
+            const contentBytes = Buffer.from(content, "utf8");
+            const execId = `${deps.workflowId}:${deps.stepId}:${deps.nextFunctionId()}`;
+            const result = await runSandboxExec({
+                sandboxClient: deps.sandboxClient,
+                sandbox: deps.sandbox,
+                execId,
+                command: ["python3", "-c", WRITE_BYTES_PROGRAM, sandboxPath, contentBytes.toString("base64")],
+                cwd: deps.sandboxWorkingDir,
+                deadlineMs: deps.deadlineMs(),
+                emit,
+            });
+            if (result.exitCode !== 0) {
+                return { status: "write_failed", path: sandboxPath, ...boundExecResult(result) };
+            }
+            // Attest the write in-process from the exact bytes just written — the
+            // seam owns write provenance the same way it owns confinement. The
+            // sandbox exec frame this write produces is deliberately not fed to
+            // `feedExecFrame`: doing so would mint a `python3`+base64 command
+            // record, the very misattribution this file-tool record supersedes.
+            //
+            // `timestamp` is a write-time wall clock — normally a replay hazard in
+            // provenance, but safe here because the record contributes only producer
+            // IDENTITY downstream: the bridge drops it (the cli's file-tool ref has no
+            // timestamp field) and the signed `inflexa:FileToolWrite` activity carries
+            // just the tool name, so a re-execution's fresh stamp changes nothing in
+            // the attested graph. Do NOT start forwarding it into an identifier or a
+            // formal PROV position without making it replay-stable first.
+            if (deps.lineageCollector) {
+                deps.lineageCollector.recordFileToolWrite({
+                    path: relative,
+                    hash: computeSha256(contentBytes),
+                    size: contentBytes.length,
+                    toolName,
+                    timestamp: new Date().toISOString(),
+                });
+            }
+            return { status: "ok", path: sandboxPath, bytesWritten: contentBytes.length };
+        },
+    };
+}