agentic-file-tools

A standalone, harness-neutral file-tool stack for Node agent runtimes. It packages the read, write, edit, multi-file patch, read-before-write, snapshot, and undo behavior that are comparable to modern harnesses support for file-tools, and can be plugged into any harness.

Install

npm install agentic-file-tools

Node 22 or newer is required.

Minimal usage

import { createFileToolsRuntime } from "agentic-file-tools";

const files = createFileToolsRuntime({ root: process.cwd() });

const read = await files.read({ path: "src/index.ts" });
console.log(read.content[0].text);

await files.edit({
  path: "src/index.ts",
  oldText: "export const version = 1;",
  newText: "export const version = 2;",
});

await files.dispose();

Existing files must be read before mutation. A complete read permits replacement writes; scoped reads and recorded search hits permit exact edits only within the known line ranges, plus a configurable five-line bleed. New files are exempt.

Generic tool definitions

The runtime exposes plain JSON Schema and SDK-independent execute functions:

const runtime = createFileToolsRuntime({ root: "/workspace" });

for (const tool of Object.values(runtime.tools)) {
  harness.register({
    name: tool.name,
    description: tool.description,
    inputSchema: tool.parameters,
    execute: (args, context) => tool.execute(context.callId, args, context.signal),
  });
}

The tool names are read, write, edit, multi_patch, and undo_edit. Direct runtime methods are also available. There are no OpenAI, Anthropic, Pi, TypeBox, or OpenClaw dependencies.

Read and write behavior

• read handles UTF-8 text plus PNG, JPEG, GIF, and WebP images detected from bytes, not extensions.
• Text reads accept one-based offset and limit, adapt their output cap to the model context window, and return a continuation offset.
• write creates or atomically replaces files and can append.
• edit applies exact anchored replacements, rejects missing or ambiguous anchors, supports ordered edit batches and replaceAll.
• A missing-file edit with an empty old string becomes a create operation.
• Snake-case aliases such as file_path, old_string, new_string, and replace_all are accepted.

All local paths are confined to root. Traversal and symlink escapes are rejected. @path and local file:// forms are accepted. A harness running tools in a container can map paths such as /workspace/src/a.ts back to a host root with containerWorkdir: "/workspace".

Multi-file patches

await runtime.multiPatch({
  atomic: true,
  patches: [
    { path: "a.txt", oldText: "before-a", newText: "after-a" },
    { path: "b.txt", oldText: "before-b", newText: "after-b" },
  ],
});

Patches are validated before writes and are atomic by default. A failed commit rolls back earlier writes. Set dryRun: true for hashes, line spans, and change counts without mutation, or atomic: false to apply valid patches and report skipped ones.

Snapshots and undo

Every mutation attempts a pre-change snapshot. Snapshot bookkeeping is best-effort and cannot break the requested file operation.

The default MemorySnapshotStore is isolated to one runtime. Use the bundled file-backed store when undo history must survive process or runtime recreation:

import { FileSnapshotStore, createFileToolsRuntime } from "agentic-file-tools";

const runtime = createFileToolsRuntime({
  root: "/workspace",
  sessionId: "agent-session-42",
  snapshotStore: new FileSnapshotStore({
    directory: "/var/lib/my-harness/file-snapshots",
    limits: { maxCountPerPath: 25 },
  }),
});

await runtime.undo({ path: "src/index.ts", steps: 1 });

File-backed snapshots use atomic data/metadata writes, per-path and total-byte retention, a per-file size cap, session isolation, and default exclusions for .git, node_modules, dist, build, and .openclaw.

Search and persisted read state

Search is intentionally supplied by the harness. Feed its results into the same safety gate:

await runtime.recordSearchHits([
  { path: "src/index.ts", lineSpan: { start: 120, end: 123 } },
]);

exportReadState() and restoreReadState() allow a harness to persist session state. Content hashes make stale records fail closed.

Adapters and events

Provide a FileAdapter to use a container, remote filesystem, browser filesystem, or hosted sandbox. The included LocalFileAdapter uses root-bounded canonical paths and atomic local writes; agentic-file-tools/testing exports MemoryFileAdapter.

Pass onEvent globally or per operation for JSON-serializable read, snapshot, write, edit, restore, and snapshot-skip events. An AbortSignal can cancel work at operation boundaries. Callback failures are isolated from file operations.

See FEATURES.md for the extraction ledger and PLAN.md for the package boundary.