@inflexa-ai/harness 0.1.1

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

@@ -0,0 +1,39 @@
+/**
+ * read_file tool — reads a workspace file via the workspace read seam.
+ *
+ * Dependency-bearing factory (see the harness-durable-runtime spec): captures the `WorkspaceFilesystem`
+ * at construction. Expected outcomes are data variants — a missing path is
+ * `not_found`, a path that escapes the analysis tree is `out_of_scope`, an
+ * oversize read is `truncated`. Only unexpected I/O errors throw; the loop
+ * wraps them as `is_error`.
+ */
+import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
+type ReadFileOutput = {
+    status: "invalid_input";
+    path: string;
+    reason: string;
+} | {
+    status: "ok";
+    path: string;
+    mode: "head" | "tail" | "full";
+    content: string;
+} | {
+    status: "truncated";
+    path: string;
+    mode: "head" | "tail" | "full";
+    content: string;
+    totalSize: number;
+    returnedBytes: number;
+} | {
+    status: "not_found";
+    path: string;
+} | {
+    status: "out_of_scope";
+    path: string;
+};
+export declare function createReadFileTool(fs: WorkspaceFilesystem, workingDir?: string): import("../define-tool.js").Tool<{
+    path: string;
+    headLines?: number | undefined;
+    tailLines?: number | undefined;
+}, ReadFileOutput>;
+export {};

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

@@ -0,0 +1,93 @@
+/**
+ * read_file tool — reads a workspace file via the workspace read seam.
+ *
+ * Dependency-bearing factory (see the harness-durable-runtime spec): captures the `WorkspaceFilesystem`
+ * at construction. Expected outcomes are data variants — a missing path is
+ * `not_found`, a path that escapes the analysis tree is `out_of_scope`, an
+ * oversize read is `truncated`. Only unexpected I/O errors throw; the loop
+ * wraps them as `is_error`.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { unwrapOrThrow } from "../../lib/result.js";
+/** Default cap — large enough for typical CSV/MD/JSON, small enough to keep tool results out of context-blowing territory. */
+const DEFAULT_MAX_BYTES = 256 * 1024;
+const ReadFileInputSchema = z.object({
+    path: z
+        .string()
+        .min(1)
+        .describe("Workspace path. Relative paths resolve against your working directory; " +
+        "an absolute '/<analysisId>/...' path is resolved against the analysis " +
+        "root (use absolute to read input data, the data profile, or other " +
+        "steps' outputs)."),
+    headLines: z
+        .number()
+        .int()
+        .min(1)
+        .max(10_000)
+        .optional()
+        .describe("Read only the first N lines (head). Use for inspecting CSV/TSV " +
+        "headers, profile summaries, or the top of any large file. Mutually " +
+        "exclusive with tailLines."),
+    tailLines: z
+        .number()
+        .int()
+        .min(1)
+        .max(10_000)
+        .optional()
+        .describe("Read only the last N complete lines (tail). Use for logs and any " + "file where the tail is what matters. Mutually exclusive with headLines."),
+});
+export function createReadFileTool(fs, workingDir) {
+    return defineTool({
+        id: "read_file",
+        description: "Read a workspace file: input data, prior-run outputs, current-run " +
+            "outputs, step summaries, run syntheses, or the data profile. Returns " +
+            "the file content as UTF-8 text. Output is capped at " +
+            `${DEFAULT_MAX_BYTES} bytes; pass headLines or tailLines to read a ` +
+            "specific window of a large file (typical for bio CSV/TSV/log files). " +
+            "Oversize reads come back truncated with a marker. Missing paths and " +
+            "paths outside the analysis tree return a data variant — not an error.",
+        inputSchema: ReadFileInputSchema,
+        execute: async ({ path, headLines, tailLines }, ctx) => {
+            if (headLines !== undefined && tailLines !== undefined) {
+                return ok({
+                    status: "invalid_input",
+                    path,
+                    reason: "headLines and tailLines are mutually exclusive",
+                });
+            }
+            const result = unwrapOrThrow(await fs.readFile({
+                session: ctx.session,
+                path,
+                maxBytes: DEFAULT_MAX_BYTES,
+                headLines,
+                tailLines,
+                workingDir,
+            }));
+            const mode = headLines !== undefined ? "head" : tailLines !== undefined ? "tail" : "full";
+            switch (result.kind) {
+                case "ok":
+                    return ok({
+                        status: "ok",
+                        path,
+                        mode,
+                        content: result.content.toString("utf8"),
+                    });
+                case "truncated":
+                    return ok({
+                        status: "truncated",
+                        path,
+                        mode,
+                        content: result.content.toString("utf8"),
+                        totalSize: result.totalSize,
+                        returnedBytes: result.content.length,
+                    });
+                case "not_found":
+                    return ok({ status: "not_found", path });
+                case "out_of_scope":
+                    return ok({ status: "out_of_scope", path });
+            }
+        },
+    });
+}

package/dist/tools/workspace/result-bounds.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Per-stream byte caps for sandbox `ExecResult`s. The mutate-surface tools
+ * (`execute_command`, `write_file`, `edit_file`) all return a tool result
+ * derived from one `ExecResult`; they share one cap so the truncation
+ * shape is uniform across the surface and the cap can be tuned in one
+ * place.
+ *
+ * The cap is well below the loop's overall result budget so a chatty
+ * command cannot blow the context window even when stdout AND stderr both
+ * cap out at the limit.
+ */
+import type { ExecResult } from "../../sandbox/types.js";
+/** Per-stream cap. 8 KiB — multi-KB but well under the loop result budget. */
+export declare const EXEC_STREAM_BYTE_CAP: number;
+export interface BoundedStream {
+    readonly content: string;
+    readonly truncated: boolean;
+    readonly totalLength: number;
+    readonly returnedBytes: number;
+}
+export interface BoundedExecResult {
+    readonly execId: string;
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly stdoutTruncated: boolean;
+    readonly stderrTruncated: boolean;
+    readonly stdoutTotalLength: number;
+    readonly stderrTotalLength: number;
+    readonly durationMs: number | null;
+    readonly timedOut: boolean;
+    readonly syntheticFailure?: {
+        readonly reason: string;
+    };
+}
+/**
+ * Apply per-stream truncation to an `ExecResult`. `exitCode`, `durationMs`,
+ * `timedOut`, and `syntheticFailure` pass through unchanged regardless of
+ * stream truncation — the discriminants the loop and the model rely on are
+ * preserved.
+ */
+export declare function boundExecResult(result: ExecResult, cap?: number): BoundedExecResult;

package/dist/tools/workspace/result-bounds.js

@@ -0,0 +1,50 @@
+/**
+ * Per-stream byte caps for sandbox `ExecResult`s. The mutate-surface tools
+ * (`execute_command`, `write_file`, `edit_file`) all return a tool result
+ * derived from one `ExecResult`; they share one cap so the truncation
+ * shape is uniform across the surface and the cap can be tuned in one
+ * place.
+ *
+ * The cap is well below the loop's overall result budget so a chatty
+ * command cannot blow the context window even when stdout AND stderr both
+ * cap out at the limit.
+ */
+/** Per-stream cap. 8 KiB — multi-KB but well under the loop result budget. */
+export const EXEC_STREAM_BYTE_CAP = 8 * 1024;
+function boundStream(stream, cap = EXEC_STREAM_BYTE_CAP) {
+    const totalLength = Buffer.byteLength(stream, "utf8");
+    if (totalLength <= cap) {
+        return { content: stream, truncated: false, totalLength, returnedBytes: totalLength };
+    }
+    const buf = Buffer.from(stream, "utf8").subarray(0, cap);
+    const content = buf.toString("utf8");
+    return {
+        content,
+        truncated: true,
+        totalLength,
+        returnedBytes: Buffer.byteLength(content, "utf8"),
+    };
+}
+/**
+ * Apply per-stream truncation to an `ExecResult`. `exitCode`, `durationMs`,
+ * `timedOut`, and `syntheticFailure` pass through unchanged regardless of
+ * stream truncation — the discriminants the loop and the model rely on are
+ * preserved.
+ */
+export function boundExecResult(result, cap = EXEC_STREAM_BYTE_CAP) {
+    const outStream = boundStream(result.stdout, cap);
+    const errStream = boundStream(result.stderr, cap);
+    return {
+        execId: result.execId,
+        exitCode: result.exitCode,
+        stdout: outStream.content,
+        stderr: errStream.content,
+        stdoutTruncated: outStream.truncated,
+        stderrTruncated: errStream.truncated,
+        stdoutTotalLength: outStream.totalLength,
+        stderrTotalLength: errStream.totalLength,
+        durationMs: result.durationMs,
+        timedOut: result.timedOut,
+        ...(result.syntheticFailure ? { syntheticFailure: result.syntheticFailure } : {}),
+    };
+}

package/dist/tools/workspace/run-exec.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Internal helper used by the three mutate tools to drive one sandbox exec
+ * through the `SandboxClient`. Centralises the submit/await pair, exec-id
+ * derivation, and intermediate-event forwarding so all three tools share
+ * one chokepoint — the contract `execute_command` makes structural is that
+ * `write_file` / `edit_file` are layered on top of it, not parallel side
+ * paths into sandbox-server.
+ *
+ * Not a registered tool — `defineTool` is called by the user-facing tools
+ * (`execute-command.ts`, `write-file.ts`, `edit-file.ts`) which wrap this.
+ */
+import type { SandboxClient } from "../../sandbox/client.js";
+import type { ExecResult, SandboxRef } from "../../sandbox/types.js";
+import type { EmitFn } from "../define-tool.js";
+export interface RunExecArgs {
+    readonly sandboxClient: SandboxClient;
+    readonly sandbox: SandboxRef;
+    readonly execId: string;
+    readonly command: readonly string[];
+    readonly cwd?: string;
+    readonly env?: Record<string, string>;
+    readonly timeoutSeconds?: number;
+    readonly deadlineMs: number;
+    readonly emit: EmitFn;
+    /**
+     * Tag the active-sandbox registry row with this execId before awaiting, so
+     * the liveness watchdog can target the in-flight exec when the sandbox dies
+     * mid-command. Best-effort: a registry write failure must not fail the exec.
+     */
+    readonly markExecActive?: (execId: string) => Promise<void>;
+}
+export declare function runSandboxExec(args: RunExecArgs): Promise<ExecResult>;

package/dist/tools/workspace/run-exec.js

@@ -0,0 +1,34 @@
+/**
+ * Internal helper used by the three mutate tools to drive one sandbox exec
+ * through the `SandboxClient`. Centralises the submit/await pair, exec-id
+ * derivation, and intermediate-event forwarding so all three tools share
+ * one chokepoint — the contract `execute_command` makes structural is that
+ * `write_file` / `edit_file` are layered on top of it, not parallel side
+ * paths into sandbox-server.
+ *
+ * Not a registered tool — `defineTool` is called by the user-facing tools
+ * (`execute-command.ts`, `write-file.ts`, `edit-file.ts`) which wrap this.
+ */
+export async function runSandboxExec(args) {
+    const body = {
+        command: [...args.command],
+        execId: args.execId,
+        ...(args.cwd === undefined ? {} : { cwd: args.cwd }),
+        ...(args.env === undefined ? {} : { env: args.env }),
+        ...(args.timeoutSeconds === undefined ? {} : { timeoutSeconds: args.timeoutSeconds }),
+    };
+    await args.sandboxClient.submitExec(args.sandbox, body);
+    if (args.markExecActive) {
+        try {
+            await args.markExecActive(args.execId);
+        }
+        catch {
+            // Watchdog targeting is a backstop; the awaitExec deadline still bounds
+            // the exec if the registry tag never lands.
+        }
+    }
+    return args.sandboxClient.awaitExec(args.sandbox, args.execId, (event) => args.emit({
+        type: "data-sandbox-event",
+        data: { execId: args.execId, event },
+    }), args.deadlineMs);
+}

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

@@ -0,0 +1,37 @@
+/**
+ * showFile tool — references existing analysis artifacts as a UI stream event.
+ *
+ * Emits a `data-file-reference` event carrying `{ title?, files: [{ path,
+ * runId?, caption? }] }`. Cortex does not resolve file metadata — the UI
+ * resolves `fileId`, `mimeType`, `size`, and presigned URLs against the
+ * artifact service at render time.
+ *
+ * The `id` is derived deterministically from the file group, so an identical
+ * re-emission carries the same id (downstream reconciliation handles dedup).
+ * The card payload is built by the shared `buildFileReferenceCardData`, so the
+ * live emit and the reconstruct-on-read path produce byte-identical cards.
+ */
+import { deriveRunId, fileGroupHash } from "../../memory/card-builders.js";
+import { validatePath } from "../lib/path-validation.js";
+type ShowFileOutput = {
+    shown: false;
+    reason: "invalid_path";
+} | {
+    shown: true;
+    id: string;
+};
+export declare const showFileTool: import("../define-tool.js").Tool<{
+    files: {
+        path: string;
+        caption?: string | undefined;
+    }[];
+    title?: string | undefined;
+}, ShowFileOutput>;
+/** Exposed for tests. */
+export declare const __testing: {
+    validatePath: typeof validatePath;
+    deriveRunId: typeof deriveRunId;
+    groupHash: typeof fileGroupHash;
+    MAX_FILES: number;
+};
+export {};

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

@@ -0,0 +1,54 @@
+/**
+ * showFile tool — references existing analysis artifacts as a UI stream event.
+ *
+ * Emits a `data-file-reference` event carrying `{ title?, files: [{ path,
+ * runId?, caption? }] }`. Cortex does not resolve file metadata — the UI
+ * resolves `fileId`, `mimeType`, `size`, and presigned URLs against the
+ * artifact service at render time.
+ *
+ * The `id` is derived deterministically from the file group, so an identical
+ * re-emission carries the same id (downstream reconciliation handles dedup).
+ * The card payload is built by the shared `buildFileReferenceCardData`, so the
+ * live emit and the reconstruct-on-read path produce byte-identical cards.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { buildFileReferenceCardData, deriveRunId, fileGroupHash, MAX_FILES } from "../../memory/card-builders.js";
+import { defineTool } from "../define-tool.js";
+import { validatePath } from "../lib/path-validation.js";
+const ShowFileInputSchema = z.object({
+    title: z.string().optional().describe("Group heading shown above the card or gallery"),
+    files: z
+        .array(z.object({
+        path: z.string().describe("Analysis-rooted file path (e.g., 'runs/run-abc/step-1/figures/volcano.png')"),
+        caption: z.string().optional().describe("One-sentence context rendered beside this file"),
+    }))
+        .min(1)
+        .max(MAX_FILES)
+        .describe(`1 to ${MAX_FILES} files; multiple files render as a gallery`),
+});
+export const showFileTool = defineTool({
+    id: "show_file",
+    description: "Display one or more existing analysis artifacts (images, CSVs, PDFs, notebooks, logs) in chat by path. " +
+        "Paths must be analysis-rooted (no leading slash, no `..`). Up to 10 files per call — multiple render as a gallery. " +
+        "Do NOT read a file and paste its bytes elsewhere; this tool references the file directly. " +
+        "File content is fetched when the user views the card — you do not need to provide it.",
+    inputSchema: ShowFileInputSchema,
+    execute: async (input, ctx) => {
+        const card = buildFileReferenceCardData(input);
+        // A malformed/traversal path yields no card — an expected outcome the model can self-correct
+        // (a data variant, not a thrown error). Zod already guarantees 1..MAX_FILES entries, so
+        // `invalid_path` is the only reason the builder returns null here.
+        if (card === null) {
+            return ok({ shown: false, reason: "invalid_path" });
+        }
+        await ctx.emit({
+            type: "data-file-reference",
+            source: ctx.session.provenance,
+            data: card,
+        });
+        return ok({ shown: true, id: card.id });
+    },
+});
+/** Exposed for tests. */
+export const __testing = { validatePath, deriveRunId, groupHash: fileGroupHash, MAX_FILES };

package/dist/tools/workspace/show-plan.d.ts

@@ -0,0 +1,23 @@
+/**
+ * showPlan tool — references a stored plan by id.
+ *
+ * Validates that the plan exists and is scoped to the current analysis,
+ * then emits a `data-plan` event with the full plan content embedded so the
+ * UI can render it without a follow-up fetch.
+ *
+ * Dependency-bearing: the database `Pool` is captured by the factory
+ * (see the harness-durable-runtime spec). The analysis id is read from the request-scoped `Session`.
+ */
+import type { Pool } from "pg";
+type ShowPlanOutput = {
+    shown: false;
+    reason: "plan_not_found";
+} | {
+    shown: true;
+    id: string;
+};
+export declare function createShowPlanTool(pool: Pool): import("../define-tool.js").Tool<{
+    planId: string;
+    title?: string | undefined;
+}, ShowPlanOutput>;
+export {};

package/dist/tools/workspace/show-plan.js

@@ -0,0 +1,44 @@
+/**
+ * showPlan tool — references a stored plan by id.
+ *
+ * Validates that the plan exists and is scoped to the current analysis,
+ * then emits a `data-plan` event with the full plan content embedded so the
+ * UI can render it without a follow-up fetch.
+ *
+ * Dependency-bearing: the database `Pool` is captured by the factory
+ * (see the harness-durable-runtime spec). The analysis id is read from the request-scoped `Session`.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { buildPlanCardData } from "../../memory/card-builders.js";
+import { scopeResource } from "../../auth/types.js";
+import { unwrapOrThrow } from "../../lib/result.js";
+import { defineTool } from "../define-tool.js";
+const PLAN_ID_REGEX = /^pln-[a-f0-9]{8}$/;
+export function createShowPlanTool(pool) {
+    return defineTool({
+        id: "show_plan",
+        description: "Display a previously generated plan in chat by its planId. " +
+            "Use when the user asks to see a plan again, or to reference a historical plan. " +
+            "Get planIds from `inspect-run` (each run carries its planId) or `generatePlan` (newly created). " +
+            "The plan content is embedded in the chat part so the UI renders it directly.",
+        inputSchema: z.object({
+            planId: z.string().regex(PLAN_ID_REGEX, "planId must match pln-<8hex>").describe("Plan ID from generatePlan or inspect-run"),
+            title: z.string().optional().describe("Optional display heading"),
+        }),
+        execute: async ({ planId, title }, ctx) => {
+            const resourceId = scopeResource(ctx.session.scope).resourceId;
+            // "Plan not found" / "plan no longer parses" are expected outcomes —
+            // discriminated data variants the model reasons about, not errors.
+            const card = unwrapOrThrow(await buildPlanCardData(pool, planId, resourceId, title));
+            if (!card)
+                return ok({ shown: false, reason: "plan_not_found" });
+            await ctx.emit({
+                type: "data-plan",
+                source: ctx.session.provenance,
+                data: card,
+            });
+            return ok({ shown: true, id: card.id });
+        },
+    });
+}

package/dist/tools/workspace/workspace-search.d.ts

@@ -0,0 +1,25 @@
+/**
+ * workspaceSearch tool — vector semantic search over the analysis workspace.
+ *
+ * Dependency-bearing factory (see the harness-durable-runtime spec): the pgvector `Pool` and the
+ * `EmbeddingProvider` are captured at construction; `execute` closes over
+ * them — no ambient lookups, no global pool accessor.
+ *
+ * The per-analysis index is the `search_{analysisId}` table written by the
+ * workflow's write-time indexing. A query embeds the search text and ranks
+ * rows by cosine similarity. "Nothing indexed yet" (the index table does not
+ * exist) is an expected outcome — an empty result list, not an error.
+ */
+import type { Pool } from "pg";
+import type { EmbeddingProvider } from "../../providers/types.js";
+export declare function createWorkspaceSearchTool(pool: Pool, embedding: EmbeddingProvider): import("../define-tool.js").Tool<{
+    query: string;
+    limit: number;
+    type?: "output" | "input" | "summary" | "synthesis" | undefined;
+}, {
+    results: {
+        id: string;
+        score: number;
+        metadata: unknown;
+    }[];
+}>;

package/dist/tools/workspace/workspace-search.js

@@ -0,0 +1,78 @@
+/**
+ * workspaceSearch tool — vector semantic search over the analysis workspace.
+ *
+ * Dependency-bearing factory (see the harness-durable-runtime spec): the pgvector `Pool` and the
+ * `EmbeddingProvider` are captured at construction; `execute` closes over
+ * them — no ambient lookups, no global pool accessor.
+ *
+ * The per-analysis index is the `search_{analysisId}` table written by the
+ * workflow's write-time indexing. A query embeds the search text and ranks
+ * rows by cosine similarity. "Nothing indexed yet" (the index table does not
+ * exist) is an expected outcome — an empty result list, not an error.
+ */
+import { err, ok, okAsync } from "neverthrow";
+import { z } from "zod";
+import { scopeResource } from "../../auth/types.js";
+import { tryQuery } from "../../lib/db-result.js";
+import { unwrapOrThrow } from "../../lib/result.js";
+import { defineTool } from "../define-tool.js";
+/** pgvector / Postgres "undefined_table" — the index has no rows indexed yet. */
+const UNDEFINED_TABLE = "42P01";
+/** True when a captured driver cause is the "undefined_table" SQLSTATE. */
+function isUndefinedTable(cause) {
+    return !!cause && typeof cause === "object" && cause.code === UNDEFINED_TABLE;
+}
+function indexName(analysisId) {
+    const name = `search_${analysisId.replace(/-/g, "_")}`;
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+        throw new Error(`workspaceSearch: unusable analysis id "${analysisId}"`);
+    }
+    return name;
+}
+export function createWorkspaceSearchTool(pool, embedding) {
+    return defineTool({
+        id: "workspace_search",
+        description: "Semantic search over the analysis workspace — input data, analysis " +
+            "outputs, step summaries, run syntheses, and the data profile. Returns " +
+            "ranked file paths with descriptions and metadata; read a file " +
+            "separately to see its contents. Optionally filter by entry type.",
+        inputSchema: z.object({
+            query: z.string().min(1).describe("What to search for, in natural language"),
+            type: z.enum(["input", "output", "summary", "synthesis"]).optional().describe("Restrict results to one workspace entry type"),
+            limit: z.number().int().min(1).max(50).default(8).describe("Maximum number of results to return"),
+        }),
+        execute: async ({ query, type, limit }, ctx) => {
+            const [vector] = unwrapOrThrow(await embedding.embed([query], ctx.session));
+            if (!vector)
+                return ok({ results: [] });
+            const table = indexName(scopeResource(ctx.session.scope).resourceId);
+            const literal = `[${vector.join(",")}]`;
+            const values = [literal, limit];
+            let filter = "";
+            if (type) {
+                values.push(type);
+                filter = `WHERE metadata->>'type' = $3`;
+            }
+            const rows = unwrapOrThrow(await tryQuery("workspaceSearch.query", async () => {
+                const result = await pool.query(`SELECT vector_id AS id,
+                    1 - (embedding <=> $1::vector) AS score,
+                    metadata
+             FROM "${table}"
+             ${filter}
+             ORDER BY embedding <=> $1::vector
+             LIMIT $2`, values);
+                return result.rows;
+            }).orElse((e) => 
+            // "Nothing indexed yet" — the per-analysis index table does not
+            // exist. That is absence, not a failure: recover into ok([]).
+            isUndefinedTable(e.cause) ? okAsync([]) : err(e)));
+            return ok({
+                results: rows.map((r) => ({
+                    id: r.id,
+                    score: r.score,
+                    metadata: r.metadata,
+                })),
+            });
+        },
+    });
+}

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

@@ -0,0 +1,16 @@
+/**
+ * `write_file` — sandbox-gated workspace write, confined to the agent's
+ * writable working directory.
+ *
+ * A thin adapter over the `WorkspaceMutator` seam (see the harness-durable-runtime / harness-workspace-tools specs): the
+ * mutator owns resolve + confine + sandbox write + provenance. This tool only
+ * declares the input schema and forwards. `edit_file` rides the same seam.
+ */
+import type { WorkspaceMutator } from "./mutator.js";
+export interface WriteFileDeps {
+    readonly mutator: WorkspaceMutator;
+}
+export declare function createWriteFileTool(deps: WriteFileDeps): import("../define-tool.js").Tool<{
+    path: string;
+    content: string;
+}, import("./mutator.js").WriteFileResult>;

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

@@ -0,0 +1,33 @@
+/**
+ * `write_file` — sandbox-gated workspace write, confined to the agent's
+ * writable working directory.
+ *
+ * A thin adapter over the `WorkspaceMutator` seam (see the harness-durable-runtime / harness-workspace-tools specs): the
+ * mutator owns resolve + confine + sandbox write + provenance. This tool only
+ * declares the input schema and forwards. `edit_file` rides the same seam.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+const WriteFileInputSchema = z.object({
+    path: z
+        .string()
+        .min(1)
+        .describe("File path. Relative paths resolve against your working directory " +
+        "(e.g. 'output/result.csv', 'scripts/run.py'); an absolute " +
+        "'/<analysisId>/...' path is resolved against the analysis root."),
+    content: z.string().describe("UTF-8 file content."),
+});
+export function createWriteFileTool(deps) {
+    return defineTool({
+        id: "write_file",
+        // Body-only `awaitExec`-recv → runs unwrapped in the workflow body (see the harness-tools spec).
+        executionMode: "workflow",
+        description: "Write a UTF-8 text file in your working directory. Relative paths " +
+            "resolve against it; a path outside it returns an `out_of_prefix` data " +
+            "variant (no I/O), and one escaping the analysis tree returns " +
+            "`out_of_scope`.",
+        inputSchema: WriteFileInputSchema,
+        execute: async ({ path, content }, ctx) => ok(await deps.mutator.writeFile({ path, content, toolName: "write_file", emit: ctx.emit })),
+    });
+}