dsh-better-edit 0.8.1 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/CHANGELOG.md +162 -97
  2. package/README.md +2 -2
  3. package/README.zh.md +3 -3
  4. package/cordis.patch.yml +1 -1
  5. package/lib/constants.js +19 -4
  6. package/lib/contract.js +136 -79
  7. package/lib/domain-errors.js +570 -0
  8. package/lib/edit-diff.js +33 -7
  9. package/lib/file-encoding-state.js +27 -7
  10. package/lib/file-view.js +305 -82
  11. package/lib/fs-bridge.js +23 -7
  12. package/lib/hash-store.js +404 -278
  13. package/lib/hashline/anchor-pipeline.js +586 -378
  14. package/lib/hashline/hash-assign.js +21 -22
  15. package/lib/hashline/hash.js +6 -6
  16. package/lib/hashline/index.js +1 -1
  17. package/lib/hashline/resolve.js +1 -1
  18. package/lib/hashline/served-guard.js +181 -0
  19. package/lib/index.js +2 -2
  20. package/lib/mutation/engine.js +392 -96
  21. package/lib/mutation.js +22 -130
  22. package/lib/noop-guard.js +20 -9
  23. package/lib/prompts.js +20 -18
  24. package/lib/read-and-serve.js +44 -20
  25. package/lib/sandbox.js +1 -1
  26. package/lib/session-view.js +57 -43
  27. package/lib/snapshot-store/index.js +97 -0
  28. package/lib/snapshot-store/lineage-store.js +400 -0
  29. package/lib/snapshot-store/migrate.js +80 -0
  30. package/lib/snapshot-store/pairing.js +412 -0
  31. package/lib/snapshot-store/txn.js +63 -0
  32. package/lib/snapshot-store/vacuum.js +243 -0
  33. package/lib/store-lifecycle.js +13 -1
  34. package/lib/store-retry.js +34 -0
  35. package/lib/tool-edit.js +90 -44
  36. package/lib/tool-read.js +29 -1
  37. package/lib/tool-str-replace-editor.js +59 -24
  38. package/lib/tool-undo.js +25 -8
  39. package/lib/types/constants.d.ts +5 -2
  40. package/lib/types/contract.d.ts +76 -71
  41. package/lib/types/domain-errors.d.ts +410 -0
  42. package/lib/types/edit-response.d.ts +1 -1
  43. package/lib/types/file-encoding-state.d.ts +1 -0
  44. package/lib/types/file-view.d.ts +35 -6
  45. package/lib/types/hash-store.d.ts +38 -19
  46. package/lib/types/hashline/anchor-pipeline.d.ts +117 -36
  47. package/lib/types/hashline/hash-assign.d.ts +5 -5
  48. package/lib/types/hashline/hash.d.ts +1 -1
  49. package/lib/types/hashline/index.d.ts +2 -2
  50. package/lib/types/hashline/served-guard.d.ts +100 -0
  51. package/lib/types/index.d.ts +2 -2
  52. package/lib/types/mutation/engine.d.ts +49 -30
  53. package/lib/types/mutation.d.ts +1 -39
  54. package/lib/types/noop-guard.d.ts +4 -4
  55. package/lib/types/prompts.d.ts +1 -1
  56. package/lib/types/read-and-serve.d.ts +6 -0
  57. package/lib/types/sandbox.d.ts +1 -1
  58. package/lib/types/session-view.d.ts +38 -9
  59. package/lib/types/snapshot-store/index.d.ts +28 -0
  60. package/lib/types/snapshot-store/lineage-store.d.ts +96 -0
  61. package/lib/types/snapshot-store/migrate.d.ts +16 -0
  62. package/lib/types/snapshot-store/pairing.d.ts +99 -0
  63. package/lib/types/snapshot-store/txn.d.ts +12 -0
  64. package/lib/types/snapshot-store/vacuum.d.ts +79 -0
  65. package/lib/types/store-lifecycle.d.ts +0 -1
  66. package/lib/types/store-retry.d.ts +6 -0
  67. package/lib/types/tool-edit.d.ts +2 -2
  68. package/lib/types/tool-str-replace-editor.d.ts +10 -4
  69. package/lib/types/utils.d.ts +5 -6
  70. package/lib/types/workspace-context.d.ts +0 -1
  71. package/lib/undo-edit.js +27 -11
  72. package/lib/utils.js +12 -12
  73. package/lib/workspace-context.js +4 -8
  74. package/lib/write-hook.js +13 -4
  75. package/package.json +9 -10
@@ -0,0 +1,243 @@
1
+ import { SERVED_TTL_MS } from "../constants.js";
2
+ import { withBusyRetry } from "../store-retry.js";
3
+ import { withTransaction } from "./txn.js";
4
+ export const VACUUM_GLOBAL_BUDGET_BYTES = 50 * 1024 * 1024;
5
+ export const VACUUM_SOFT_OVERFLOW_BYTES = 100 * 1024 * 1024;
6
+ export const VACUUM_PER_PATH_BUDGET_BYTES = 10 * 1024 * 1024;
7
+ export const VACUUM_MAX_SNAPSHOTS_PER_PATH = 10;
8
+ export const VACUUM_MIN_SNAPSHOTS_PER_PATH = 2;
9
+ export const VACUUM_LINEAGE_BYTES_PER_LINE = 40;
10
+ export const VACUUM_RETIRED_PIN_MS = 60 * 60 * 1000;
11
+ const vacuumStmtsCache = new WeakMap();
12
+ /**
13
+ * One statement set per store handle. `vacuum.ts` is a row-family module, so it owns its own
14
+ * prepared statements and retries each `.run` itself (the `txn.ts` rule: statement-level retry
15
+ * belongs to the statement's family).
16
+ */
17
+ function vacuumStmts(db) {
18
+ const cached = vacuumStmtsCache.get(db);
19
+ if (cached !== undefined)
20
+ return cached;
21
+ const built = buildVacuumStmts(db);
22
+ vacuumStmtsCache.set(db, built);
23
+ return built;
24
+ }
25
+ function buildVacuumStmts(db) {
26
+ const listStmt = db.prepare("SELECT snapshot_id, path, snapshot_hash, line_count, created_at FROM file_snapshots " +
27
+ "WHERE committed = 1 ORDER BY created_at ASC, snapshot_id ASC");
28
+ // WHY — pinning is a two-table predicate (spec §3.6.1): a lease still active inside the session
29
+ // TTL, a lease retired inside the 1-hour grace, or an undo restore target. The `updated_at` half
30
+ // is the LRU-on-access semantic: a re-serve refreshes the row (`lineage-store.ts` upsert
31
+ // `ON CONFLICT … updated_at = excluded.updated_at`), moving that snapshot back out of the window.
32
+ const pinnedStmt = db.prepare("SELECT DISTINCT fs.snapshot_id AS snapshot_id FROM file_snapshots fs " +
33
+ "WHERE fs.committed = 1 AND (" +
34
+ "EXISTS (SELECT 1 FROM served_leases sl WHERE sl.file_path = fs.path " +
35
+ "AND sl.served_snapshot_hash = fs.snapshot_hash " +
36
+ "AND ((sl.retired_at IS NULL AND sl.updated_at >= ?) OR sl.retired_at >= ?)) " +
37
+ "OR EXISTS (SELECT 1 FROM file_undo fu WHERE fu.path = fs.path " +
38
+ "AND fu.snapshot_hash = fs.snapshot_hash))");
39
+ const deleteLineageStmt = db.prepare("DELETE FROM line_lineage WHERE snapshot_id = ?");
40
+ const deleteSnapshotStmt = db.prepare("DELETE FROM file_snapshots WHERE snapshot_id = ?");
41
+ return {
42
+ // SAFETY: the SELECT list matches VacuumSnapshotRow field-for-field; node:sqlite returns one
43
+ // record per row with exactly those columns.
44
+ listSnapshots: () => listStmt.all(),
45
+ // SAFETY: same shape contract for the pin probe — one `snapshot_id` column per row.
46
+ listPinned: (...params) => pinnedStmt.all(...params),
47
+ deleteLineage: (snapshotId) => {
48
+ withBusyRetry(() => {
49
+ deleteLineageStmt.run(snapshotId);
50
+ });
51
+ },
52
+ deleteSnapshot: (snapshotId) => {
53
+ withBusyRetry(() => {
54
+ deleteSnapshotStmt.run(snapshotId);
55
+ });
56
+ },
57
+ };
58
+ }
59
+ /** The lineage price of one snapshot: `40 bytes × line_count`, floored at one line for an empty file. */
60
+ function lineageBytes(row, perLine) {
61
+ return perLine * Math.max(1, row.line_count);
62
+ }
63
+ /**
64
+ * The per-path window, sized against the path's NEWEST version (the file size retention is meant
65
+ * for) and clamped into `[minVersions, maxVersions]`.
66
+ */
67
+ function perPathRetention(newestLineCount) {
68
+ const snapshotLineageBytes = VACUUM_LINEAGE_BYTES_PER_LINE * Math.max(1, newestLineCount);
69
+ const window = Math.floor(VACUUM_PER_PATH_BUDGET_BYTES / snapshotLineageBytes);
70
+ return Math.min(VACUUM_MAX_SNAPSHOTS_PER_PATH, Math.max(VACUUM_MIN_SNAPSHOTS_PER_PATH, window));
71
+ }
72
+ // WHY — report throttles (spec §3.6.1): the vacuum runs after every authoritative materialization
73
+ // and at store open, so an unthrottled warning would fire on every read and edit while the store
74
+ // stays over the soft cap — and a nested materialization skips on every read. Two transition-in
75
+ // sets keyed by `context` (the stable `<store>:<site>` identity the callers pass): the overflow
76
+ // warn fires on the false → true transition and re-arms when a pass reports no deferred bytes; the
77
+ // skip warn fires once per context, because a skip is a property of the call site, not of the
78
+ // store's byte state. Observability only: never throws, never evicts, never alters the result.
79
+ // BOUND (A2): each ledger holds at most `REPORT_CONTEXT_CAP` contexts and evicts the oldest inserted
80
+ // first, so the state is capped rather than unbounded across distinct store paths. A process that
81
+ // touches more distinct `(store, site)` contexts than the cap can re-report an evicted context once
82
+ // — observability only, and strictly cheaper than the leak an unbounded global Set would be.
83
+ export const REPORT_CONTEXT_CAP = 256;
84
+ const overflowReported = new Map();
85
+ const skipReported = new Map();
86
+ /** Insert `context` into a capped ledger, dropping the oldest entry once the cap is reached. */
87
+ function rememberReported(ledger, context) {
88
+ if (ledger.size >= REPORT_CONTEXT_CAP) {
89
+ const oldest = ledger.keys().next();
90
+ if (oldest.done !== true)
91
+ ledger.delete(oldest.value);
92
+ }
93
+ ledger.set(context, true);
94
+ }
95
+ /**
96
+ * The single report owner for a vacuum pass: every trigger calls this with the module's result and
97
+ * its stable context. A `skippedInTransaction` pass is reported as a skip — never as a zero
98
+ * result — so "0 bytes deferred" can never be read as "nothing to do". A swept pass is reported
99
+ * when it deferred bytes or crossed the soft cap. Never throws: a diagnostic failure must not fail
100
+ * the caller.
101
+ */
102
+ export function reportVacuum(result, context) {
103
+ try {
104
+ if (result.skippedInTransaction) {
105
+ if (skipReported.has(context))
106
+ return;
107
+ rememberReported(skipReported, context);
108
+ console.warn(`dsh-better-edit: snapshot vacuum skipped inside an open transaction (${context}) — the ` +
109
+ `sweep owns its transaction and runs at the next outermost boundary.`);
110
+ return;
111
+ }
112
+ if (result.deferredBytes <= 0 && !result.overSoftOverflow) {
113
+ overflowReported.delete(context);
114
+ return;
115
+ }
116
+ if (overflowReported.has(context))
117
+ return;
118
+ rememberReported(overflowReported, context);
119
+ console.warn(`dsh-better-edit: snapshot vacuum soft overflow (${context}): ` +
120
+ `totalBytes=${result.totalBytes} pinnedBytes=${result.pinnedBytes} ` +
121
+ `deferredBytes=${result.deferredBytes} — pinned snapshots are never evicted and this ` +
122
+ `state is expected to lapse as leases expire.`);
123
+ }
124
+ catch {
125
+ // SAFETY: observability only — a broken diagnostic sink must never fail the caller.
126
+ }
127
+ }
128
+ /**
129
+ * Enforce store retention across all paths (spec §3.6.1). The pass is one oldest-first sweep of
130
+ * every committed snapshot: a snapshot is deleted when the running total is over the global budget,
131
+ * or when its path already retains more than its retention window. Pinned snapshots are skipped
132
+ * unconditionally — they are the versions a live anchor can still resolve through — and the
133
+ * resulting deferral is reported, never resolved by evicting a pin.
134
+ *
135
+ * The pass is idempotent and safe with no candidates: it returns the zero result and never throws
136
+ * on an empty store.
137
+ */
138
+ export function vacuumSnapshots(db, options = {}) {
139
+ // WHY — the guard is about ATOMICITY, not nesting safety (TM probe M1): the `withTransaction`
140
+ // below would nest cleanly inside a caller-owned unit — it joins it — but the caller's later
141
+ // COMMIT then commits a partially applied sweep if any statement between the first and the last
142
+ // delete fails (measured: a mid-loop ABORT inside a caller unit leaves the pair invariant broken
143
+ // — `lineageLessSnapshots = 1` — even after COMMIT; the same ABORT at the outermost boundary
144
+ // rolls the whole sweep back). Deferring keeps every sweep one atomic unit; the result says so,
145
+ // so the deferral is visible instead of reading as a clean sweep.
146
+ if (db.isTransaction) {
147
+ return {
148
+ evicted: 0,
149
+ totalBytes: 0,
150
+ pinnedBytes: 0,
151
+ deferredBytes: 0,
152
+ overSoftOverflow: false,
153
+ skippedInTransaction: true,
154
+ };
155
+ }
156
+ const now = Date.now();
157
+ const stmts = vacuumStmts(db);
158
+ const rows = stmts.listSnapshots();
159
+ const empty = {
160
+ evicted: 0,
161
+ totalBytes: 0,
162
+ pinnedBytes: 0,
163
+ deferredBytes: 0,
164
+ overSoftOverflow: false,
165
+ skippedInTransaction: false,
166
+ };
167
+ if (rows.length === 0)
168
+ return empty;
169
+ const pinned = new Set(stmts
170
+ .listPinned(now - SERVED_TTL_MS, now - VACUUM_RETIRED_PIN_MS)
171
+ .map((row) => row.snapshot_id));
172
+ // WHY — an in-flight materialization protects its own row: it names the snapshot before the serve
173
+ // grants `served_leases`, so the sweep treats it exactly like a live pin (spec §3.6.1).
174
+ for (const id of options.protectSnapshotIds ?? [])
175
+ pinned.add(id);
176
+ // WHY — rows ascend by `created_at`, so the last row seen for a path is its newest version — the
177
+ // file size the per-path window is sized against.
178
+ const newestLineCount = new Map();
179
+ const pathCounts = new Map();
180
+ let total = 0;
181
+ for (const row of rows) {
182
+ newestLineCount.set(row.path, row.line_count);
183
+ pathCounts.set(row.path, (pathCounts.get(row.path) ?? 0) + 1);
184
+ total += lineageBytes(row, VACUUM_LINEAGE_BYTES_PER_LINE);
185
+ }
186
+ const evict = [];
187
+ let pinnedBytes = 0;
188
+ for (const row of rows) {
189
+ const cost = lineageBytes(row, VACUUM_LINEAGE_BYTES_PER_LINE);
190
+ if (pinned.has(row.snapshot_id)) {
191
+ pinnedBytes += cost;
192
+ continue;
193
+ }
194
+ const retention = perPathRetention(newestLineCount.get(row.path) ?? row.line_count);
195
+ const retained = pathCounts.get(row.path) ?? 0;
196
+ if (total > VACUUM_GLOBAL_BUDGET_BYTES || retained > retention) {
197
+ evict.push(row.snapshot_id);
198
+ total -= cost;
199
+ pathCounts.set(row.path, retained - 1);
200
+ }
201
+ }
202
+ if (evict.length > 0)
203
+ deleteVacuumSnapshots(db, stmts, evict);
204
+ const deferredBytes = Math.max(0, total - VACUUM_GLOBAL_BUDGET_BYTES);
205
+ const result = {
206
+ evicted: evict.length,
207
+ totalBytes: total,
208
+ pinnedBytes,
209
+ deferredBytes,
210
+ overSoftOverflow: deferredBytes > VACUUM_SOFT_OVERFLOW_BYTES - VACUUM_GLOBAL_BUDGET_BYTES,
211
+ skippedInTransaction: false,
212
+ };
213
+ return result;
214
+ }
215
+ /**
216
+ * Delete the evicted snapshots and their lineage in one transaction. `withTransaction` is the
217
+ * store's single re-entrant owner: at the outermost boundary it opens its own `BEGIN IMMEDIATE`;
218
+ * invoked inside a caller-owned unit it joins that unit instead of raising "cannot start a
219
+ * transaction within a transaction" — nesting-safe, which is exactly why `vacuumSnapshots`
220
+ * refuses to run inside a unit at all (M1: a joined sweep can be partially committed by its
221
+ * caller). The explicit `line_lineage` delete comes first — child before parent. MEASURED (P1):
222
+ * node:sqlite enables `enableForeignKeyConstraints` by default AND `hash-store` sets `PRAGMA
223
+ * foreign_keys = ON`, so on every opener in use the `line_lineage → file_snapshots` cascade would
224
+ * remove these rows anyway. The explicit delete is kept as belt-and-braces — measured to remove
225
+ * `1 → 0` lineage rows per eviction, i.e. it is not a delete that deletes nothing — so the pair
226
+ * invariant does not depend on a per-connection pragma. Dropping it is therefore masked by the
227
+ * cascade on every current opener (GREEN meaning 4, P1 matrix), never evidence that it is dead.
228
+ *
229
+ * Do NOT add a repair here for the mirror shape — a `file_snapshots` row with no `line_lineage`
230
+ * rows, the codebase's "orphan snapshot row": the adopt/serve path already detects, warns about
231
+ * and repairs it (the lineage adopt branch, `src/hash-store.ts:849-861`), proven by
232
+ * `test/core/hash-store.test.ts:1665-1706` ("keep the snapshot row, empty the lineage" → served
233
+ * anchors + lease + `lineage: 2` + a "repairing corrupt lineage" warning). An eager repair in this
234
+ * module would make a second owner that can disagree with the first while both appear to work.
235
+ */
236
+ function deleteVacuumSnapshots(db, stmts, snapshotIds) {
237
+ withTransaction(db, () => {
238
+ for (const id of snapshotIds) {
239
+ stmts.deleteLineage(id);
240
+ stmts.deleteSnapshot(id);
241
+ }
242
+ });
243
+ }
@@ -19,6 +19,7 @@ import { hashStorePath, loadConfig } from "./paths.js";
19
19
  import { workspaceCwd } from "./workspace-context.js";
20
20
  import { errCode, splitLines } from "./utils.js";
21
21
  import { HASH_STORE_BUSY_TIMEOUT, SERVED_TTL_MS } from "./constants.js";
22
+ import { reportVacuum } from "./snapshot-store/index.js";
22
23
  // ---- throttling state (owned here) ----
23
24
  let lastPruneMsByStore = new Map();
24
25
  let lastJanitorMs = 0;
@@ -209,7 +210,9 @@ export async function onStoreOpen(storePath, stmts, store) {
209
210
  try {
210
211
  const cfg = loadConfig();
211
212
  if (cfg.undo_ttl_s !== -1) {
212
- stmts.undoPruneOlderThan(Date.now() - cfg.undo_ttl_s * 1000);
213
+ // Pair-atomic: route through the store face (both tables, one txn) — the
214
+ // half-pair statement must not stay reachable from the janitor (P1).
215
+ store.pruneUndoOlderThan(Date.now() - cfg.undo_ttl_s * 1000);
213
216
  }
214
217
  }
215
218
  catch (error) {
@@ -226,6 +229,15 @@ export async function onStoreOpen(storePath, stmts, store) {
226
229
  catch (error) {
227
230
  console.warn(`dsh-better-edit: pruneMissing throttling check failed: ${error instanceof Error ? error.message : String(error)}`);
228
231
  }
232
+ // Snapshot vacuum — the deterministic boundary (spec §3.6.1): on this store the open path is
233
+ // the only place that can reclaim a store that crashed over budget. This trigger owns the
234
+ // report (the single report owner is `reportVacuum`; the sweep never writes to the console).
235
+ try {
236
+ reportVacuum(store.vacuumSnapshots(), `store open ${storePath}`);
237
+ }
238
+ catch (error) {
239
+ console.warn(`dsh-better-edit: snapshot vacuum failed at store open for ${storePath}: ${error instanceof Error ? error.message : String(error)}`);
240
+ }
229
241
  }
230
242
  export async function onAppStart() {
231
243
  await runCentralJanitorIfDue();
@@ -0,0 +1,34 @@
1
+ /**
2
+ * Shared sqlite busy-retry policy — a leaf module so `hash-store` and the
3
+ * row-family modules (e.g. `snapshot-store`) use one policy without a cycle.
4
+ * @module dsh-better-edit/store-retry
5
+ */
6
+ function isBusyError(error) {
7
+ if (error && typeof error === "object") {
8
+ const errcode = error.errcode;
9
+ if (typeof errcode === "number")
10
+ return errcode === 5 || errcode === 6;
11
+ }
12
+ return error instanceof Error && /busy|locked/i.test(error.message);
13
+ }
14
+ function sleepSync(ms) {
15
+ const sab = new Int32Array(new SharedArrayBuffer(4));
16
+ Atomics.wait(sab, 0, 0, ms);
17
+ }
18
+ const BUSY_RETRIES = 3;
19
+ const BUSY_RETRY_DELAY_MS = 100;
20
+ export function withBusyRetry(fn) {
21
+ let lastError;
22
+ for (let attempt = 0; attempt <= BUSY_RETRIES; attempt++) {
23
+ try {
24
+ return fn();
25
+ }
26
+ catch (error) {
27
+ lastError = error;
28
+ if (!isBusyError(error) || attempt === BUSY_RETRIES)
29
+ throw error;
30
+ sleepSync(BUSY_RETRY_DELAY_MS);
31
+ }
32
+ }
33
+ throw lastError;
34
+ }
package/lib/tool-edit.js CHANGED
@@ -1,8 +1,8 @@
1
1
  /**
2
2
  * The dsh `edit` tool: hash-anchored literal range edits that shadow the
3
3
  * built-in `edit` on the agent's own scope layer. Now the sole mutation tool
4
- * (batch_edit removed, ADR-0007): payload is { path: string|null, edits: [[remove_from,remove_to,replacement_text],...] }
5
- * single-file atomic batch, null path inference via anchors.
4
+ * (batch_edit removed, ADR-0007): payload is { file: string|null, edits: [{anchor_from,anchor_to,replace_with},...] }
5
+ * single-file atomic batch, legacy null file inference via anchors.
6
6
  * @module dsh-better-edit/tool-edit
7
7
  */
8
8
  import { defineTool } from "@deepseek-ai/dsh-tools";
@@ -11,6 +11,7 @@ import { abortIf } from "./utils.js";
11
11
  import { execute } from "./mutation.js";
12
12
  import { EDIT_DESCRIPTION } from "./prompts.js";
13
13
  import { codeOf } from "./utils.js";
14
+ import { DomainError, formatError } from "./domain-errors.js";
14
15
  import { execCwd, execSessionKey } from "./workspace-context.js";
15
16
  import { withWorkspace } from "./workspace-context.js";
16
17
  import { findSnapshotPathsByHashes } from "./hash-store.js";
@@ -20,17 +21,21 @@ async function resolveNullPath(edits) {
20
21
  return undefined;
21
22
  const first = edits[0];
22
23
  try {
23
- const h1 = parseHashRef(first.remove_from).hash;
24
- const h2 = parseHashRef(first.remove_to).hash;
24
+ const h1 = parseHashRef(first.anchor_from).hash;
25
+ const h2 = parseHashRef(first.anchor_to).hash;
25
26
  const matches = await findSnapshotPathsByHashes([h1, h2]);
26
27
  if (matches.length === 1) {
27
28
  return {
28
- path: matches[0],
29
- warning: `[MODEL] [E_BAD_PAYLOAD] Autocorrected: missing "path" resolved to ${matches[0]} — the only file whose stored hashes contain both anchors.`,
29
+ file: matches[0],
30
+ warning: formatError("E_BAD_PAYLOAD", {
31
+ message: `Autocorrected: missing "file" resolved to ${matches[0]} — the only file whose stored hashes contain both anchors.`,
32
+ }),
30
33
  };
31
34
  }
32
35
  if (matches.length > 1) {
33
- throw new Error(`[MODEL] [E_BAD_PAYLOAD] Edit request requires a non-empty "path" string; the anchors match multiple known files: ${matches.join(", ")}. Include the intended path.`);
36
+ throw new DomainError("E_BAD_PAYLOAD", {
37
+ message: `Edit request requires a non-empty "file" string; the anchors match multiple known files: ${matches.join(", ")}. Include the intended file.`,
38
+ });
34
39
  }
35
40
  }
36
41
  catch (e) {
@@ -40,25 +45,58 @@ async function resolveNullPath(edits) {
40
45
  }
41
46
  return undefined;
42
47
  }
48
+ /**
49
+ * E_UNKNOWN producer: the edit tool boundary is where raw unexpected errors
50
+ * surface. DomainError members and aborts pass through untouched; anything else
51
+ * becomes a typed E_UNKNOWN with its name + first line.
52
+ */
53
+ function wrapUnexpected(error, signal) {
54
+ if (error instanceof DomainError)
55
+ throw error;
56
+ if (signal?.aborted)
57
+ throw error;
58
+ if (error instanceof Error && error.message === "Operation aborted")
59
+ throw error;
60
+ const errorName = error instanceof Error ? error.name : typeof error;
61
+ const message = error instanceof Error ? error.message : String(error);
62
+ throw new DomainError("E_UNKNOWN", { errorName, message });
63
+ }
43
64
  export function buildEditTool(io, sandbox) {
44
65
  return defineTool({
45
66
  name: "edit",
46
67
  description: EDIT_DESCRIPTION,
47
68
  parameters: {
48
- path: {
69
+ file: {
49
70
  oneOf: [
50
- { type: "string", description: "File path; null infers it from anchors" },
51
- { type: "null", description: "null infers path from anchors" },
71
+ { type: "string", description: "Text file to edit (a file, never a directory)" },
72
+ // N1: no description — ADR-0015 keeps the legacy null path admissible
73
+ // but undocumented, so the schema admits without teaching.
74
+ { type: "null" },
52
75
  ],
53
76
  },
54
77
  edits: {
55
78
  type: "array",
56
- description: "Ordered list of edit tuples [remove_from, remove_to, replacement_text] — one edit per tuple, single-file atomic",
79
+ description: "Ordered list of edit items — one edit per item, single-file atomic; each item is a named object, legacy tuples still fold pre-validation",
57
80
  items: {
58
- type: "json",
59
- description: "[remove_from, remove_to, replacement_text]",
81
+ oneOf: [
82
+ {
83
+ type: "object",
84
+ additionalProperties: false,
85
+ properties: {
86
+ anchor_from: { type: "string", required: true },
87
+ anchor_to: { type: "string", required: true },
88
+ replace_with: { type: "string", required: true },
89
+ },
90
+ },
91
+ { type: "array", items: { type: "string" } },
92
+ ],
60
93
  },
61
94
  },
95
+ mode: {
96
+ type: "string",
97
+ enum: ["general", "literal"],
98
+ description: 'How to treat bytes reproducing served rows: "general" refuses them, "literal" declares them as intended file content',
99
+ },
62
100
  ...(sandbox.escalationModes.length > 0 ? sandbox.schemaFields() : {}),
63
101
  },
64
102
  output: {
@@ -67,41 +105,49 @@ export function buildEditTool(io, sandbox) {
67
105
  },
68
106
  async execute(args, exec) {
69
107
  return withWorkspace(execCwd(exec), async () => {
70
- const cwd = execCwd(exec);
71
- const sessionKey = execSessionKey(exec);
72
- const signal = exec.signal;
73
- const canonical = normReq(args);
74
- assertEditRequest(canonical);
75
- const req = canonical;
76
- let resolvedPath = req.path;
77
- let pathWarning;
78
- if (resolvedPath === null) {
79
- const resolved = await resolveNullPath(req.edits);
80
- if (resolved) {
81
- resolvedPath = resolved.path;
82
- pathWarning = resolved.warning;
108
+ try {
109
+ const cwd = execCwd(exec);
110
+ const sessionKey = execSessionKey(exec);
111
+ const signal = exec.signal;
112
+ const canonical = normReq(args);
113
+ assertEditRequest(canonical);
114
+ const req = canonical;
115
+ let resolvedFile = req.file;
116
+ let fileWarning;
117
+ if (resolvedFile === null) {
118
+ const resolved = await resolveNullPath(req.edits);
119
+ if (resolved) {
120
+ resolvedFile = resolved.file;
121
+ fileWarning = resolved.warning;
122
+ }
123
+ else {
124
+ throw new DomainError("E_BAD_PAYLOAD", {
125
+ message: "Edit request file is null and could not be inferred from anchors — anchors match no known file. Include the intended file.",
126
+ });
127
+ }
83
128
  }
84
- else {
85
- throw new Error("[MODEL] [E_BAD_PAYLOAD] Edit request path is null and could not be inferred from anchors — anchors match no known file. Include the intended path.");
129
+ const sandboxPolicy = await sandbox.resolvePolicy("edit", { file: resolvedFile, edits: req.edits }, exec);
130
+ abortIf(signal);
131
+ const items = [];
132
+ for (let index = 0; index < req.edits.length; index++) {
133
+ const e = req.edits[index];
134
+ items.push({
135
+ index,
136
+ file: resolvedFile,
137
+ absolutePath: await io.resolve(resolvedFile, cwd, signal),
138
+ anchor_from: e.anchor_from,
139
+ anchor_to: e.anchor_to,
140
+ replace_with: e.replace_with,
141
+ fileWarning: index === 0 ? fileWarning : undefined,
142
+ ...(req.mode !== undefined ? { mode: req.mode } : {}),
143
+ });
86
144
  }
145
+ // Deep seam: one interface, all lifecycle branching concentrates in Mutation
146
+ return execute({ io, items, sessionKey, signal, exec, sandbox, sandboxPolicy });
87
147
  }
88
- const sandboxPolicy = await sandbox.resolvePolicy("edit", { path: resolvedPath, edits: req.edits }, exec);
89
- abortIf(signal);
90
- const items = [];
91
- for (let index = 0; index < req.edits.length; index++) {
92
- const e = req.edits[index];
93
- items.push({
94
- index,
95
- path: resolvedPath,
96
- absolutePath: await io.resolve(resolvedPath, cwd, signal),
97
- remove_from: e.remove_from,
98
- remove_to: e.remove_to,
99
- replacement_text: e.replacement_text,
100
- pathWarning: index === 0 ? pathWarning : undefined,
101
- });
148
+ catch (error) {
149
+ throw wrapUnexpected(error, exec.signal);
102
150
  }
103
- // Deep seam: one interface, all lifecycle branching concentrates in Mutation
104
- return execute({ io, items, sessionKey, signal, exec, sandbox, sandboxPolicy });
105
151
  });
106
152
  },
107
153
  });
package/lib/tool-read.js CHANGED
@@ -10,6 +10,8 @@ import { normalizeRequest as normReq, assertReadRequest, pathSchema } from "./co
10
10
  import { readAndServe } from "./read-and-serve.js";
11
11
  import { READ_DESCRIPTION } from "./prompts.js";
12
12
  import { normalizeEncoding } from "./encoding.js";
13
+ import { DomainError } from "./domain-errors.js";
14
+ import { MAX_READ_WINDOWS } from "./file-view.js";
13
15
  import { renderTextWarning } from "./render-text-warning.js";
14
16
  import { execCwd, execSessionKey } from "./workspace-context.js";
15
17
  import { withWorkspace } from "./workspace-context.js";
@@ -34,6 +36,29 @@ export function buildReadTool(io) {
34
36
  type: "number",
35
37
  description: "Maximum number of lines to read",
36
38
  },
39
+ // Upstream enforces the 16-window cap twice (TypeBox schema + preview); the dsh
40
+ // value-schema DSL has no maxItems on array nodes, so the bound is enforced in
41
+ // file-view's normWindows and stated in the description to stay discoverable.
42
+ windows: {
43
+ type: "array",
44
+ description: `Optional array of up to ${MAX_READ_WINDOWS} line windows to read in a single turn; every window's rows are served, so anchors from all of them are usable in one edit`,
45
+ items: {
46
+ type: "object",
47
+ additionalProperties: false,
48
+ properties: {
49
+ offset: {
50
+ type: "number",
51
+ required: true,
52
+ description: "Line number to start reading from (1-indexed)",
53
+ },
54
+ limit: {
55
+ type: "number",
56
+ required: true,
57
+ description: "Maximum number of lines to read",
58
+ },
59
+ },
60
+ },
61
+ },
37
62
  encoding: {
38
63
  type: "string",
39
64
  description: "Text encoding for Reopen with Encoding (e.g. gbk, shift_jis, windows-1251). Case-insensitive.",
@@ -56,7 +81,9 @@ export function buildReadTool(io) {
56
81
  if (encoding !== undefined) {
57
82
  const norm = normalizeEncoding(String(encoding));
58
83
  if (!norm)
59
- throw new Error(`[E_BAD_ENCODING] Unknown encoding: ${String(encoding)}. Supported: utf8, gbk, big5, shift_jis, euc-kr, windows-1251, iso-8859-1`);
84
+ throw new DomainError("E_BAD_PAYLOAD", {
85
+ message: `Unknown encoding: ${String(encoding)}. Supported: utf8, gbk, big5, shift_jis, euc-kr, windows-1251, iso-8859-1`,
86
+ });
60
87
  }
61
88
  const canonical = normReq(args);
62
89
  assertReadRequest(canonical);
@@ -66,6 +93,7 @@ export function buildReadTool(io) {
66
93
  signal,
67
94
  offset: canonical.offset,
68
95
  limit: canonical.limit,
96
+ windows: canonical.windows,
69
97
  encoding: encoding,
70
98
  });
71
99
  // Record the present observation with the fs policy gate so later