@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/tools/sandbox/submit-file-metadata.js

@@ -12,19 +12,23 @@
  */
 import { err, ok } from "neverthrow";
 import { SubmitFileMetadataInputSchema } from "../../schemas/file-metadata.js";
-import { defineTool } from "../define-tool.js";
+import { defineTool, withToolCallRecord } from "../define-tool.js";
 export const SUBMIT_FILE_METADATA_TOOL_ID = "submit_file_metadata";
 export function createFileMetadataCell() {
     let knownPaths = null;
-    const descriptions = new Map();
+    const described = new Set();
     return {
         get knownPaths() {
             return knownPaths;
         },
-        descriptions,
+        described,
         expect(paths) {
             knownPaths = new Set(paths);
-            descriptions.clear();
+            described.clear();
+        },
+        fold(paths) {
+            for (const path of paths)
+                described.add(path);
         },
     };
 }
@@ -40,28 +44,21 @@ export function createSubmitFileMetadataTool(cell) {
             "the unknownPaths and describe the remaining files.",
         inputSchema: SubmitFileMetadataInputSchema,
         describeCall: "none",
-        execute: async (input) => {
+        execute: (input) => {
             const knownPaths = cell.knownPaths;
             if (knownPaths === null) {
-                return err({
+                return Promise.resolve(err({
                     error: "No list of files is known yet. The harness asks for the file metadata after the task, with the list of the files.",
                     retryable: false,
-                });
-            }
-            const unknownPaths = [];
-            for (const entry of input.files) {
-                if (!knownPaths.has(entry.path)) {
-                    unknownPaths.push(entry.path);
-                    continue;
-                }
-                cell.descriptions.set(entry.path, entry);
+                }));
             }
-            const remaining = [...knownPaths].filter((path) => !cell.descriptions.has(path));
-            return ok({
-                accepted: unknownPaths.length === 0 && remaining.length === 0,
-                unknownPaths,
-                remaining,
-            });
+            const unknownPaths = input.files.map((entry) => entry.path).filter((path) => !knownPaths.has(path));
+            const described = input.files.map((entry) => entry.path).filter((path) => knownPaths.has(path));
+            const covered = new Set([...cell.described, ...described]);
+            const remaining = [...knownPaths].filter((path) => !covered.has(path));
+            const outcome = { accepted: unknownPaths.length === 0 && remaining.length === 0, unknownPaths, remaining };
+            return Promise.resolve(ok(withToolCallRecord(outcome, { described })));
         },
+        foldCallRecord: (record) => cell.fold(record.described),
     });
 }

package/dist/tools/start-report-session.d.ts

@@ -12,17 +12,23 @@
  * past the anchor of the newest report child, the tool starts nothing and it
  * names that child. The spawn runs last.
  *
+ * Inside a durable step, the child id is the UUIDv5 of the key of the step. A
+ * rerun of the call after the spawn, before the checkpoint of the step, finds
+ * that child. It skips the advice, and it gives the same session and the same
+ * part.
+ *
  * Each degraded condition is a typed outcome in the ok channel: a scope with no
  * thread id, a composition with no eyes, the advice, each refusal of the spawn,
  * and a store fault. The tool never throws for one of them.
  */
-import type { Pool } from "pg";
+import type { Querier } from "../state/db.js";
 import { z } from "zod";
 import type { EnsureSessionStateResult } from "../app/report-session-runtime.js";
 import type { ChromeConfig } from "../lib/chrome.js";
+import { type Connectable } from "../lib/db-result.js";
 import type { AcquireEyes } from "../lib/eyes.js";
 import type { Logger } from "../lib/logger.js";
-import type { ThreadType } from "../memory/thread-store.js";
+import { type ThreadType } from "../memory/thread-store.js";
 import { type Tool } from "./define-tool.js";
 import type { ProvenanceSeam } from "../provenance/seam.js";
 /**
@@ -85,8 +91,8 @@ export type StartReportSessionResult = {
  * a page. A composition that binds a capture seam straight to the spawn still
  * opens the gate of that spawn.
  */
-export interface StartReportSessionToolDeps {
-    readonly pool: Pool;
+export type StartReportSessionToolDeps = {
+    readonly pool: Querier & Connectable;
     readonly chrome: ChromeConfig;
     /**
      * The eyes seam of the composition. A bound seam gives a browser for one
@@ -107,7 +113,9 @@ export interface StartReportSessionToolDeps {
      */
     readonly provenance?: ProvenanceSeam;
     readonly logger?: Logger;
-}
+    /** The key of the durable step that runs the call, `undefined` outside one. Defaults to {@link durableStepKey}. */
+    readonly stepKey?: () => string | undefined;
+};
 /**
  * Make the tool that starts a report session, over one Postgres pool and the
  * eyes of the composition.

package/dist/tools/start-report-session.js

@@ -12,6 +12,11 @@
  * past the anchor of the newest report child, the tool starts nothing and it
  * names that child. The spawn runs last.
  *
+ * Inside a durable step, the child id is the UUIDv5 of the key of the step. A
+ * rerun of the call after the spawn, before the checkpoint of the step, finds
+ * that child. It skips the advice, and it gives the same session and the same
+ * part.
+ *
  * Each degraded condition is a typed outcome in the ok channel: a scope with no
  * thread id, a composition with no eyes, the advice, each refusal of the spawn,
  * and a store fault. The tool never throws for one of them.
@@ -21,7 +26,9 @@ import { z } from "zod";
 import { compositionHasEyes, createReportSessionSpawn } from "../app/spawn-report-session.js";
 import { createNoopLogger } from "../lib/console-logger.js";
 import { describeDbError } from "../lib/db-result.js";
+import { createThreadStore } from "../memory/thread-store.js";
 import { defineTool } from "./define-tool.js";
+import { durableStepKey, stepUuid } from "./workspace/edit-file.js";
 /**
  * The character bound of each brief field. The whole brief lands in one durable
  * message row, thus the schema holds no unbounded string out of the store.
@@ -107,12 +114,14 @@ export function createStartReportSessionTool(deps) {
     const spawnDeps = {
         pool: deps.pool,
         chrome: deps.chrome,
-        ...(deps.eyes ? { eyes: deps.eyes } : {}),
-        ...(deps.anchorSession ? { anchorSession: deps.anchorSession } : {}),
-        ...(deps.provenance ? { provenance: deps.provenance } : {}),
-        ...(deps.logger ? { logger: deps.logger } : {}),
+        eyes: deps.eyes,
+        anchorSession: deps.anchorSession,
+        provenance: deps.provenance,
+        logger: deps.logger,
     };
     const spawn = createReportSessionSpawn(spawnDeps);
+    const threads = createThreadStore(deps.pool);
+    const stepKey = deps.stepKey ?? durableStepKey;
     // The gate reads the routes of the very spawn below, thus the two answers
     // come from one value. The routes are fixed at construction, thus the gate
     // reads one boolean and never a live probe of the sidecar.
@@ -132,7 +141,6 @@ export function createStartReportSessionTool(deps) {
             "`no_browser` means that this deployment has no browser for the report agent, thus no report session can start; tell the user. " +
             "`refused`, `parent_not_found`, `parent_not_a_conversation`, and `failed` mean that nothing started, and `detail` gives the reason where there is one.",
         inputSchema: startReportSessionInput,
-        executionMode: "inline",
         describeCall: "none",
         execute: async (input, ctx) => {
             const brief = {
@@ -143,16 +151,35 @@ export function createStartReportSessionTool(deps) {
                 openQuestions: input.openQuestions,
             };
             const { scope } = ctx.session;
-            if (scope.kind !== "analysis" || scope.threadId === undefined || scope.threadId.length === 0) {
+            if (scope.threadId === undefined || scope.threadId.length === 0) {
                 return ok({ outcome: "refused", detail: NO_THREAD_SCOPE_DETAIL });
             }
             const parentThreadId = scope.threadId;
+            // Inside a durable step the child id comes from the step, thus a rerun of
+            // the call finds the child of its first run. The advice would name that
+            // child as an existing session, thus a found child skips the advice, and
+            // the spawn gives the child back with no second write.
+            const key = stepKey();
+            const childThreadId = key === undefined ? undefined : stepUuid(key);
+            let rerun = false;
+            if (childThreadId !== undefined) {
+                const earlier = await threads.getThread(childThreadId);
+                if (earlier.isErr()) {
+                    logger.warn("the child of an earlier run did not read", {
+                        parentThreadId,
+                        reason: earlier.error.type,
+                        ...logger.errorFields(earlier.error.cause),
+                    });
+                    return ok(toOutcome(earlier.error));
+                }
+                rerun = earlier.value !== null;
+            }
             // The eyes gate has priority over the advice, and the advice costs two
             // reads. The spawn holds the same gate before each read of its own,
             // thus a blind composition reaches the `no_browser` refusal of the
             // spawn with no read and no write. As a result the tool copies no
             // detail line of the spawn.
-            if (eyesAvailable) {
+            if (eyesAvailable && !rerun) {
                 const delta = await spawn.reportSessionDelta(parentThreadId);
                 if (delta.isErr()) {
                     logger.warn("the report session delta did not read", {
@@ -172,7 +199,7 @@ export function createStartReportSessionTool(deps) {
                     return ok({ outcome: "existing-session", threadId: newestChild.threadId, title: newestChild.title });
                 }
             }
-            const spawned = await spawn.spawnReportSession(parentThreadId, brief);
+            const spawned = await spawn.spawnReportSession(parentThreadId, brief, childThreadId);
             if (spawned.isOk()) {
                 const child = spawned.value;
                 // The part rides the started arm only. The existing-session arm

package/dist/tools/terminal-text.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The text of a terminal call: a clarification question or a blocker reason.
+ *
+ * A terminal call whose text is a placeholder ends a run with nothing. A small
+ * model emits such a call when it drafts several calls at once and fills the
+ * text later, or never. The input schema of the tool names the fault, the call
+ * gets an error result, and the loop continues with the real work.
+ */
+import { z } from "zod";
+export declare const MIN_TERMINAL_TEXT = 4;
+/** The reason a text cannot end a run, or undefined when it can. */
+export declare function degenerateTerminalText(text: string): string | undefined;
+/** The text of a terminal call. The schema refuses a placeholder, and the issue says what to do instead. */
+export declare function terminalTextSchema(description: string): z.ZodString;

package/dist/tools/terminal-text.js

@@ -0,0 +1,51 @@
+/**
+ * The text of a terminal call: a clarification question or a blocker reason.
+ *
+ * A terminal call whose text is a placeholder ends a run with nothing. A small
+ * model emits such a call when it drafts several calls at once and fills the
+ * text later, or never. The input schema of the tool names the fault, the call
+ * gets an error result, and the loop continues with the real work.
+ */
+import { z } from "zod";
+// oxlint-disable-next-line eslint-js/no-restricted-syntax -- the anchored placeholder words and their n/a spellings, at the start of the text; the alternation is the guard's own word list.
+const PLACEHOLDER_TEXT = /^\s*(?:placeholder|todo|tbd|skip|n\/?a|none|null|test|x+|\.+|-+)\b/i;
+export const MIN_TERMINAL_TEXT = 4;
+/** The reason a text cannot end a run, or undefined when it can. */
+export function degenerateTerminalText(text) {
+    const trimmed = text.trim();
+    if (trimmed.length < MIN_TERMINAL_TEXT)
+        return `The text has ${trimmed.length} characters, and a real question or reason has at least ${MIN_TERMINAL_TEXT}.`;
+    if (PLACEHOLDER_TEXT.test(trimmed) || holdsStandaloneWord(trimmed, "placeholder"))
+        return "The text is a placeholder.";
+    return undefined;
+}
+/** The text of a terminal call. The schema refuses a placeholder, and the issue says what to do instead. */
+export function terminalTextSchema(description) {
+    return z
+        .string()
+        .min(1)
+        .check(z.superRefine((text, ctx) => {
+        const degenerate = degenerateTerminalText(text);
+        if (degenerate !== undefined)
+            ctx.addIssue({ code: "custom", message: `${degenerate} Give the real text, or continue the work.` });
+    }))
+        .describe(description);
+}
+/** Whether `word` occurs in `text` as a standalone word, case-insensitively. */
+function holdsStandaloneWord(text, word) {
+    const lower = text.toLowerCase();
+    const needle = word.toLowerCase();
+    let at = lower.indexOf(needle);
+    while (at >= 0) {
+        const boundedBefore = at === 0 || !isWordChar(lower.charAt(at - 1));
+        const end = at + needle.length;
+        const boundedAfter = end >= lower.length || !isWordChar(lower.charAt(end));
+        if (boundedBefore && boundedAfter)
+            return true;
+        at = lower.indexOf(needle, at + 1);
+    }
+    return false;
+}
+function isWordChar(char) {
+    return (char >= "a" && char <= "z") || (char >= "A" && char <= "Z") || (char >= "0" && char <= "9") || char === "_";
+}

package/dist/tools/workspace/decision-record.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The decision record of a rendered script, as the file tools keep it true
+ * after the render. `knowledge_template` writes the record beside the
+ * script with the digest of the bytes it wrote. A later change of the
+ * script through `edit_file` appends an entry to `unvetted_edits` with the
+ * digest after the change, and `execute_command` compares the script it is
+ * about to run with the last recorded digest, thus a change by any other
+ * path is recorded before the script runs. The record then connects the
+ * cited decision to the bytes that ran, and an empty `unvetted_edits` is a
+ * fact and not an assumption.
+ */
+import type { AgentSession } from "../../auth/types.js";
+import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
+import type { MutateToolName, WorkspaceMutator, WriteRecord } from "./mutator.js";
+/**
+ * The path of the decision record of one rendered script inside the step:
+ * `output/decision_record_<script stem>.json`. One record per render, thus a
+ * step that renders two scripts keeps both records.
+ */
+export declare function decisionRecordPath(scriptFile: string): string;
+/**
+ * The record path of a script path, or `undefined` when the path is not a
+ * script under `scripts/`. A relative `scripts/x.R` gives the relative
+ * record path, and an absolute `/<analysisId>/.../scripts/x.R` gives the
+ * absolute one, beside it in the same step.
+ */
+export declare function decisionRecordPathFor(scriptPath: string): string | undefined;
+export declare function scriptSha256(content: string | Uint8Array): string;
+/** One change of a script after its render, as the record keeps it. */
+export type UnvettedEdit = {
+    readonly path: string;
+    readonly note: string;
+    /** The digest of the script after the change. */
+    readonly sha256: string;
+};
+/** The digest the record expects of the script now: the last recorded change, else the bytes the render wrote. */
+export declare function expectedScriptSha256(record: Readonly<Record<string, unknown>>): string | undefined;
+export type NoteScriptChangeArgs = {
+    readonly filesystem: WorkspaceFilesystem;
+    readonly mutator: WorkspaceMutator;
+    readonly session: AgentSession;
+    /** Absolute host base for a relative path; the analysis root when absent. */
+    readonly workingDir?: string;
+    readonly invocationId: string;
+    /** The tool that made the change, for the provenance of the record write. */
+    readonly toolName: MutateToolName;
+    /** The script path as the tool received it, relative or absolute. */
+    readonly scriptPath: string;
+    readonly note: string;
+    /** The digest of the script after the change. */
+    readonly sha256: string;
+};
+/**
+ * The outcome of a change note. `noted` carries the record of the write,
+ * thus the calling tool carries it as its call record, and its fold hands it
+ * to `recordWrite`.
+ */
+export type ScriptChangeNote = {
+    readonly status: "noted";
+    readonly write: WriteRecord;
+} | {
+    readonly status: "no_record" | "refused";
+};
+/**
+ * Append a change to the record of a script. `no_record` when the path is
+ * not a script under `scripts/`, or when no record exists for it, which is
+ * the state of every script an agent wrote itself. `refused` when the
+ * mutator refused the write of the record, for example a record of another
+ * step, outside the writable prefix of this one.
+ */
+export declare function noteScriptChange(args: NoteScriptChangeArgs): Promise<ScriptChangeNote>;
+export type ReconcileScriptRecordArgs = Omit<NoteScriptChangeArgs, "note" | "sha256">;
+/**
+ * Compare a script with the digest its record expects, before the script
+ * runs. A difference is a change that no tool of the host recorded, and it
+ * is noted with the digest of the bytes that are about to run. `unchanged`
+ * when the digests agree, `no_record` when the script has no record.
+ */
+export declare function reconcileScriptRecord(args: ReconcileScriptRecordArgs): Promise<ScriptChangeNote | {
+    readonly status: "unchanged";
+}>;

package/dist/tools/workspace/decision-record.js

@@ -0,0 +1,127 @@
+/**
+ * The decision record of a rendered script, as the file tools keep it true
+ * after the render. `knowledge_template` writes the record beside the
+ * script with the digest of the bytes it wrote. A later change of the
+ * script through `edit_file` appends an entry to `unvetted_edits` with the
+ * digest after the change, and `execute_command` compares the script it is
+ * about to run with the last recorded digest, thus a change by any other
+ * path is recorded before the script runs. The record then connects the
+ * cited decision to the bytes that ran, and an empty `unvetted_edits` is a
+ * fact and not an assumption.
+ */
+import { createHash } from "node:crypto";
+import { posix as posixPath } from "node:path";
+import { z } from "zod";
+import { unwrapOrThrow } from "../../lib/result.js";
+import { safeParseJsonAs } from "../../lib/parse-json.js";
+import { isUnknownArray } from "../../lib/unknown-array.js";
+import { UnknownRecordSchema } from "../../lib/unknown-containers.js";
+/**
+ * The path of the decision record of one rendered script inside the step:
+ * `output/decision_record_<script stem>.json`. One record per render, thus a
+ * step that renders two scripts keeps both records.
+ */
+export function decisionRecordPath(scriptFile) {
+    const dot = scriptFile.lastIndexOf(".");
+    const suffix = scriptFile.slice(dot + 1);
+    const isSuffixAlnum = dot !== -1 &&
+        suffix.length > 0 &&
+        Array.from(suffix).every((char) => (char >= "a" && char <= "z") || (char >= "A" && char <= "Z") || (char >= "0" && char <= "9"));
+    const stem = isSuffixAlnum ? scriptFile.slice(0, dot) : scriptFile;
+    return `output/decision_record_${stem}.json`;
+}
+/**
+ * The record path of a script path, or `undefined` when the path is not a
+ * script under `scripts/`. A relative `scripts/x.R` gives the relative
+ * record path, and an absolute `/<analysisId>/.../scripts/x.R` gives the
+ * absolute one, beside it in the same step.
+ */
+export function decisionRecordPathFor(scriptPath) {
+    const dir = posixPath.dirname(scriptPath);
+    if (posixPath.basename(dir) !== "scripts")
+        return undefined;
+    const record = decisionRecordPath(posixPath.basename(scriptPath));
+    return dir === "scripts" ? record : posixPath.join(posixPath.dirname(dir), record);
+}
+export function scriptSha256(content) {
+    return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+const LastEditRecordSchema = z.looseObject({ sha256: z.string() });
+/** The digest the record expects of the script now: the last recorded change, else the bytes the render wrote. */
+export function expectedScriptSha256(record) {
+    const edits = isUnknownArray(record.unvetted_edits) ? record.unvetted_edits : [];
+    const parsed = LastEditRecordSchema.safeParse(edits.at(-1));
+    if (parsed.success)
+        return parsed.data.sha256;
+    return typeof record.written_sha256 === "string" ? record.written_sha256 : undefined;
+}
+/**
+ * Append a change to the record of a script. `no_record` when the path is
+ * not a script under `scripts/`, or when no record exists for it, which is
+ * the state of every script an agent wrote itself. `refused` when the
+ * mutator refused the write of the record, for example a record of another
+ * step, outside the writable prefix of this one.
+ */
+export async function noteScriptChange(args) {
+    const recordPath = decisionRecordPathFor(args.scriptPath);
+    if (!recordPath)
+        return { status: "no_record" };
+    const read = unwrapOrThrow(await args.filesystem.readFile({ session: args.session, path: recordPath, workingDir: args.workingDir }));
+    if (read.kind !== "ok")
+        return { status: "no_record" };
+    let record;
+    try {
+        const parsed = safeParseJsonAs(read.content.toString("utf8"), UnknownRecordSchema);
+        if (!parsed.success)
+            return { status: "no_record" };
+        record = parsed.data;
+    }
+    catch {
+        return { status: "no_record" };
+    }
+    const edits = isUnknownArray(record.unvetted_edits) ? record.unvetted_edits : [];
+    const entry = { path: args.scriptPath, note: args.note, sha256: args.sha256 };
+    const next = { ...record, unvetted_edits: [...edits, entry] };
+    const written = await args.mutator.writeFile({
+        path: recordPath,
+        content: `${JSON.stringify(next, null, 2)}\n`,
+        toolName: args.toolName,
+        invocationId: args.invocationId,
+        session: args.session,
+    });
+    return written.status === "ok" ? { status: "noted", write: written.record } : { status: "refused" };
+}
+/**
+ * Compare a script with the digest its record expects, before the script
+ * runs. A difference is a change that no tool of the host recorded, and it
+ * is noted with the digest of the bytes that are about to run. `unchanged`
+ * when the digests agree, `no_record` when the script has no record.
+ */
+export async function reconcileScriptRecord(args) {
+    const recordPath = decisionRecordPathFor(args.scriptPath);
+    if (!recordPath)
+        return { status: "no_record" };
+    const base = args.workingDir !== undefined ? { workingDir: args.workingDir } : {};
+    const record = unwrapOrThrow(await args.filesystem.readFile({ session: args.session, path: recordPath, ...base }));
+    if (record.kind !== "ok")
+        return { status: "no_record" };
+    let expected;
+    try {
+        const parsed = safeParseJsonAs(record.content.toString("utf8"), UnknownRecordSchema);
+        if (!parsed.success)
+            return { status: "no_record" };
+        expected = expectedScriptSha256(parsed.data);
+    }
+    catch {
+        return { status: "no_record" };
+    }
+    if (expected === undefined)
+        return { status: "no_record" };
+    const script = unwrapOrThrow(await args.filesystem.readFile({ session: args.session, path: args.scriptPath, ...base }));
+    if (script.kind !== "ok")
+        return { status: "no_record" };
+    const actual = scriptSha256(script.content);
+    if (actual === expected)
+        return { status: "unchanged" };
+    return noteScriptChange({ ...args, note: "the script changed by a path no file tool recorded, before it ran", sha256: actual });
+}

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

@@ -12,10 +12,31 @@
  * capture-group references, and exactly one of `replace_all=true` or
  * `expected_matches` gates the write. Provenance hashes the post-edit
  * content — the mutator records it through the fold of this tool.
+ *
+ * Inside a durable step, the edit records its intent before the write lands:
+ * the hash of the file before, the hash after, and the result. A rerun of the
+ * step after the write, before its checkpoint, finds the file at the hash
+ * after and gives back the stored result, thus the edit never applies twice.
+ * The file at the hash before applies the edit again, and any other hash is a
+ * conflict.
  */
-import { type WithToolCallRecord } from "../define-tool.js";
+import { type ResultAsync } from "neverthrow";
+import { z } from "zod";
+import { type Tool, type WithToolCallRecord } from "../define-tool.js";
+import { type DomainError } from "../../lib/result.js";
 import type { WorkspaceFilesystem } from "../../workspace/filesystem.js";
 import type { WorkspaceMutator, WriteFileResult, WriteRecord } from "./mutator.js";
+/** The `ok` outcome of an `edit_file` call. */
+export type EditFileOk = {
+    readonly status: "ok";
+    readonly path: string;
+    readonly replacements: number;
+    readonly bytesWritten: number;
+    /** Regex mode only: 1-based line numbers where the matches started. */
+    lines?: readonly number[];
+    /** True when the file is a rendered script and its decision record now lists this edit. */
+    decision_record_noted?: true;
+};
 /** Outcome of an `edit_file` call — expected outcomes are data variants, never throws. */
 export type EditFileResult = {
     readonly status: "file_not_found";
@@ -44,15 +65,34 @@ export type EditFileResult = {
     readonly lines: readonly number[];
 } | Exclude<WriteFileResult, {
     status: "ok";
-}> | WithToolCallRecord<{
-    readonly status: "ok";
+}> | WithToolCallRecord<EditFileOk, readonly WriteRecord[]>;
+declare const EditFileInputSchema: z.ZodObject<{
+    path: z.ZodString;
+    old_string: z.ZodString;
+    new_string: z.ZodString;
+    replace_all: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    regex: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    expected_matches: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** The intent of one `edit_file` call inside a durable step. */
+export type EditIntent = {
+    /** `${workflowId}:${stepId}` of the step that runs the call. */
+    readonly key: string;
+    readonly analysisId: string;
+    /** The `/{analysisId}/…` path of the edited file. */
     readonly path: string;
-    readonly replacements: number;
-    readonly bytesWritten: number;
-    /** Regex mode only: 1-based line numbers where the matches started. */
-    readonly lines?: readonly number[];
-}, WriteRecord>;
-export interface EditFileDeps {
+    readonly hashBefore: string;
+    readonly hashAfter: string;
+    readonly result: EditFileOk;
+    readonly callRecord: readonly WriteRecord[];
+};
+/** Keeps the intent of each `edit_file` call that runs inside a durable step. */
+export type EditIntentStore = {
+    /** A second put of one key replaces the intent. */
+    put(intent: EditIntent): ResultAsync<void, DomainError>;
+    get(key: string): ResultAsync<EditIntent | null, DomainError>;
+};
+export type EditFileDeps = {
     readonly mutator: WorkspaceMutator;
     /** Read seam used to fetch current file content for search/replace. */
     readonly workspaceFilesystem: WorkspaceFilesystem;
@@ -62,12 +102,13 @@ export interface EditFileDeps {
      * root, matching the session-scoped mutator's write prefix.
      */
     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;
-    regex: boolean;
-    expected_matches?: number | undefined;
-}, EditFileResult>;
+    readonly intents: EditIntentStore;
+    /** The key of the durable step that runs the call, `undefined` outside one. Defaults to {@link durableStepKey}. */
+    readonly stepKey?: () => string | undefined;
+};
+/** The key of the DBOS step that runs the call, or `undefined` outside a workflow, where nothing reruns. */
+export declare function durableStepKey(): string | undefined;
+/** An id that each run of one durable step gives again: the UUIDv5 of the step key. With no step key, nothing reruns, thus the id is random. */
+export declare function stepUuid(stepKey: string | undefined): string;
+export declare function createEditFileTool(deps: EditFileDeps): Tool<z.infer<typeof EditFileInputSchema>, EditFileResult>;
+export {};