Proposal: ordered atomic edits[] for single-file batch editing

[yltx]

Summary

I propose extending the native edit tool with an optional ordered edits[] form for multiple literal replacements in one file, while preserving the existing old_string / new_string single-edit form.

The goal is to reduce model round trips for several deterministic edits in one observed file without switching to an opaque shell script or weakening fs-observation-policy.

{
  "file_path": "tasktracker/cli.py",
  "edits": [
    { "old_string": "old block 1", "new_string": "new block 1" },
    { "old_string": "old block 2", "new_string": "new block 2" }
  ]
}

Motivation and measured cost

In one real development session, five distinct edits to the same already-read file were expressed as five serial edit calls. Those five calls alone required:

• 5 model requests
• 5 tool calls
• 11,310 input tokens
• 1,183 output tokens
• 64,000 cache-read tokens

The local filesystem operation itself is fast; the dominant cost is the model round trip after each tool result.

This is related to existing reports about file-operation friction and extra rounds:

• 提案：文件工具"三车道"场景路由——完善"用 read 别用 shell"的指引（附实测数据） #2509 describes dozens of read → edit round trips for bulk mechanical transforms.
• Should edit guidance explicitly prohibit parallel edits to the same file? #3017 discusses same-file edits needing sequential execution and stale retry cost.
• [Ideas] edit 工具是否应该明确提示：同一文件的多个编辑不能并行执行？ #3029 includes community experience with single-file chained edits / multiple patches.
• FS_NOT_OBSERVED fires on every first edit of a bash-inspected file — the observation contract never says bash does not count #3153 records repeated observation failures and the resulting extra steps.

A shell/script lane remains appropriate for repository-wide mechanical transforms. This proposal targets the middle case: several precise, reviewable literal edits to one observed file.

Proposed semantics

• Keep the current single-edit form unchanged.
• Add a mutually exclusive edits[] form.
• Apply operations in array order; operation N sees the in-memory result of operation N-1.
• Each operation requires exactly one match unless its own replace_all is true.
• Validate all operations before publishing the file.
• If any operation fails, write nothing and report the failing operation index.
• Perform one observed-version check and one file publication.
• Atomicity is limited to one request for one file; this is not a cross-file transaction.
• Bound the model-facing batch size with a configurable positive integer, for example a default of 32.

The provider-level request could use a non-empty operation tuple so direct callers cannot submit an empty successful edit:

interface FsEditOperation {
  oldString: string
  newString: string
  replaceAll: boolean
}

interface FsEditRequest {
  edits: readonly [FsEditOperation, ...FsEditOperation[]]
}

Why not only use shell or apply_patch?

This keeps the existing native literal-edit properties:

• observed-version/CAS protection
• structured unique-match validation
• native diff presentation
• precise per-operation diagnostics
• no partial writes
• replayable model-visible tool arguments and results

It is deliberately narrower than a general patch language.

Prototype evidence

I implemented and tested a local prototype across dsh-fs, fs-local, fs-e2b, and tool-fs.

Verification included:

• ordered replacements
• later-operation failure leaving the file unchanged
• single/batch mutual exclusion
• configurable operation limit
• diff presentation for multiple operations
• focused filesystem tests and a full repository build

A real headless run with gpt-5.6-sol, xhigh used exactly:

1. one read
2. one edit call containing two edits[] operations
3. one verification read

The model used the batch form correctly and the file was updated once.

Trade-offs

• The edit schema and prompt become slightly larger, causing a one-time request-prefix/KV-cache change.
• Every filesystem provider must implement the stronger all-or-nothing request contract.
• The JSON schema subset may not express exact-one-of single versus batch forms, so executor validation may still enforce mutual exclusion.

Request for maintainer direction

Would this ordered single-file batch form fit the intended native filesystem-tool direction?

I have a working prototype and measured before/after behavior, but I am posting this as a design proposal because CONTRIBUTING.md currently asks external contributors to use Discussions rather than unsolicited PRs. If maintainers want the code, I can rework it on the latest master with the required provider, snapshot, generated-catalog, bilingual documentation, and Agent Note coverage.

[argszero]

Source-verified feasibility review at cd5ef81481 (0.1.2-alpha.1) — your proposal is well-shaped, and the existing seam supports it with less friction than the trade-off list suggests. One naming collision will need resolving, though.

1. The atomicity seam already exists — the batch slots in cleanly.

fs-local's editText (fs-local/src/index.ts:225-270) is already: withLock(targetKey) → probe (stale-version guard) → readForEdit → applyLiteralEdit (a pure in-memory transform, fsio.ts:759, throwing FS_EDIT_NOT_FOUND / FS_AMBIGUOUS_EDIT) → restoreLineEndings → one writeFileAtomic → versionAfterWrite. A batch is exactly the same skeleton with the applyLiteralEdit step looped: one probe (one observed-version check), one read, N ordered ops, one write. Because the transform is pure, "validate all operations before publishing the file" falls out for free — the file is only ever written once, after every op has succeeded. "Report the failing operation index" is likewise free: the loop knows the index and the per-op error code is already distinct (FS_EDIT_NOT_FOUND vs FS_AMBIGUOUS_EDIT).

2. Naming collision: FsEditRequest already exists.

packages/fs/fs/src/types.ts:147-154:

export interface FsEditRequest {
  oldString: string
  newString: string
  replaceAll: boolean
}

Your proposed provider type (FsEditRequest { edits: readonly [FsEditOperation, ...] }) collides with it, and the current type is exported through the fs service surface (fs/src/index.ts:33) and consumed by all providers (fs-local, fs-e2b:405, fs-sandbox) plus tests. Either rename your batch type (e.g. FsEditBatchRequest) or — arguably cleaner — keep FsEditRequest as the per-operation element (it already is) and add the non-empty tuple as a new request shape. Worth deciding before touching the abstract method at fs/src/index.ts:256-266, since that signature is the contract every provider implements.

3. Diff presentation needs no new view — mostly.

presentResult (tool-fs/src/edit.ts:160-165) renders from whole-file before/after via computeHunkDiffs → diffsFromMeta. If the batch outcome keeps whole-file before/after (original content vs post-all-ops content — which is what the current FsEditOutcome already carries, fs/src/types.ts:157+), the existing card renders all hunks at once with zero schema change — the same path replace_all already exercises for multi-hunk files. The one real gap is presentCall (edit.ts:150-157), which reads args.old_string/args.new_string directly for the call-time card; it needs an edits[] branch (one snippet per op, or a combined card).

4. fs-e2b gets the biggest win — worth stating in the proposal.

fs-e2b/src/index.ts:405 overrides editText across the sandbox round trip. N serial edits = N sandbox RTTs; a batch = 1 RTT with N ops. The measured token savings are the model-side story; the RTT collapse is the provider-side one.

5. Observation policy and escalation stay single-decision.

The tool flow is one ctx.waterfall('fs/edit-intent', ...) (observed-version fetch) + one ctx.emit('fs/observed', ...) (edit.ts:126/:140) + one sandbox escalation resolution (resolvePolicy, edit.ts:116). A batch preserves all three as single decisions — the observation burden is identical to a single edit, which is the strongest form of "no weakening of fs-observation-policy". The sandbox_permissions/justification fields apply once to the whole batch, which is consistent with one request = one escalation decision.

6. Schema vs executor enforcement — confirmed your instinct.

The defineTool parameters block is a flat object (edit.ts:86-91; no oneOf/anyOf in this schema DSL), so exact-one-of single-vs-batch cannot be expressed there — executor-level validation in parseEditArgs (edit.ts:47-57) is the right place, and per-op variants of the existing checks (non-empty old_string, old_string !== new_string) slot in naturally.

7. Remaining surface for your prototype to be complete (all in tool-fs/src/edit.ts): the system-prompt section text (:77-81, one sentence about the batch form), parseEditArgs per-op validation + mutual exclusion, and the presentCall branch above.

Net: the design is compatible with the native literal-edit direction as it stands today; the main decisions are the type-name resolution and whether the batch loop lives in each provider (required for the lock+single-write guarantee) or behind a shared helper. The Discussions-first posture is exactly right per CONTRIBUTING — hoping a maintainer weighs in.

[yltx]

Thanks for the source-level review — this is very helpful.\n\nI agree that reusing \FsEditRequest\ for the batch container would unnecessarily change an already exported public type. Before any upstream submission, I’ll preserve the existing per-operation shape and introduce a separately named batch request/input, with the provider boundary accepting or normalizing the single and batch forms as appropriate.\n\nThe prototype has since been rebased onto the latest \master. It already covers the remaining \ ool-fs\ surface you identified: the system-prompt guidance, executor-level single/batch mutual exclusion and per-operation validation, and the \presentCall\ batch branch. It also includes provider tests for ordered dependent operations, one publication, and no rename/write when a later operation fails.\n\nGood point about \s-e2b: collapsing N sandbox round trips into one is a separate provider-side benefit beyond the model-request and token savings. I’ll add that to the proposal.\n\nI’ll continue to wait for maintainer direction before opening a PR, per \CONTRIBUTING.md.