ds4-context-engine 0.3.3 → 0.3.5

package/docs/PORTABLE_AGENT_TOOLS.md

@@ -0,0 +1,86 @@
+# Optional portable agent tools
+
+These features are separate opt-ins, also gated by the DS4 master `enabled` switch. They do not implement inference rewind, forced sampling, or native KV-cache integration. Pi remains the agent runtime.
+
+Enable only the features you want, then reload:
+
+```text
+/context config set editing.postEditReport true
+/context config set reading.adaptive true
+/context config set artifacts.adaptiveBudget true
+/context config set jobs.enabled true
+/reload
+```
+
+All four default to `false`. Configuration writes apply on the next session load, not immediately. The default target is the trusted project configuration; add `--global` for the agent-directory file. Disable with the same commands using `false`, then reload.
+
+## Post-edit reports
+
+`editing.postEditReport` works with native ordinary edits, independently of `editing.anchored`. Enable both to combine reports with [`[upto]` ranges](ANCHORED_EDITING.md).
+
+After a successful edit, the tool result content and details include:
+
+- actual old/new changed ranges from Pi's native unified patch;
+- total line delta and cumulative shift for subsequent lines;
+- bounded numbered context from the updated content, encoded as quoted JSON data.
+
+Regions combine nearby changes in the same native patch hunk. Zero-length ranges identify insertion/deletion boundaries. Coordinates refer to the completed write, not future file state. Reports include at most six regions and six short context lines per region; rendered report text stays below 6000 characters. The native patch/diff remains available and the TUI continues to display the native diff. There is no separate file read after the write and no change to matching or mutation queues. If reporting fails, the successful edit result is retained rather than encouraging a duplicate write.
+
+## Adaptive reads
+
+`reading.adaptive` changes only the default line limit of the native `read` tool:
+
+| Execution-time model window | Default lines |
+| --- | ---: |
+| <= 8192 tokens | 120 |
+| <= 16384 tokens | 240 |
+| larger | 500 |
+| missing/invalid model window | native default |
+
+Explicit positive integer `offset`/`limit` values are honored; native byte limits can still shorten a response. Images, path resolution, access errors and cancellation remain native. The model is checked on each execution, so switching models does not require reload. Arguments are copied, not rewritten in canonical tool calls.
+
+Use the native continuation notice, e.g. `offset=121`, to read more. There is deliberately no shared `more` cursor, which could become ambiguous after concurrent reads, branching or compaction. This does not reduce the native reader's full-file I/O or memory use.
+
+Both file overrides skip initial registration if their built-in tool is missing or visibly overridden. Disabling an already-enabled instance restores the native definition; fresh disabled loads register nothing. Compatibility is tested against the project's Pi dependency, currently `0.84.3`. Custom SDK/remote filesystem integrations are not covered by these local wrappers.
+
+## Adaptive tool-result/artifact budget
+
+`artifacts.adaptiveBudget` operates only where artifact offload already operates: DS4 enabled, managed context, and artifact storage enabled/available.
+
+The per-context policy uses the same calibrated active input budget as the planner, after output reserve and safety margin. It subtracts estimated system/tool-schema overhead, other messages and non-text blocks, then shares 75% of remaining capacity among candidate text results. It can only lower `artifacts.maxInlineToolResultChars` and `artifacts.excerptChars`, never raise them. The reference-metadata floor is 1600 characters or the configured inline maximum, whichever is smaller.
+
+This is estimated budgeting, not a tokenizer-exact fit guarantee. Irreducible metadata, errors, missing provenance or unavailable storage can still leave a context oversized. The existing planner and fallback behavior remain responsible; there is no recursive `ctx.compact()` call inside the context hook.
+
+Canonical Pi messages stay unchanged. Only privacy-prepared provider-facing text is transformed, with the original tool identity, source IDs and non-text blocks preserved. Artifact storage/search caps and branch/privacy checks remain unchanged. Rebuild uses the conservative adaptive floor so earlier small-budget artifacts remain reconstructible; consequently it may reconstruct more small artifacts than the fixed-threshold policy. A result is not replaced with a larger estimated result.
+
+## Managed local bash jobs
+
+The `bash_job` tool is implemented in a separate optional module, not in the portable core. It does not replace `bash` and is not a new agent loop or a separate published package.
+
+Examples of tool arguments:
+
+```json
+{"action":"start","command":"npm test","timeout":300}
+{"action":"list"}
+{"action":"status","id":"<returned-job-id>"}
+{"action":"stop","id":"<returned-job-id>"}
+```
+
+### Authorization and execution
+
+- Requires an active built-in local `bash`, an unclaimed `bash_job` name, a trusted project, and local UI confirmation for every start. Missing UI or refused confirmation means no command starts. Tool-call arguments are revalidated, and the confirmed command/cwd/timeout are snapshotted.
+- Executes in the current working directory using Pi's public local BashOperations. It **does not inherit** custom bash-only permission hooks, remote/sandbox behavior, SDK shell settings/command prefixes, or session-specific `PI_*` injection. It must not be used to bypass those controls. The confirmation explicitly identifies the local execution boundary.
+- Status/stop/list use opaque IDs owned by the current session and originating branch entry, never arbitrary PIDs. Stop remains available for owned jobs even if bash is later deactivated.
+- Four running jobs maximum; sixteen retained records maximum. Oldest completed records/logs are evicted first. Timeout defaults to 300 seconds; valid range is 1–3600 seconds.
+
+### Output and lifecycle
+
+Logs combine stdout/stderr in native arrival order. Each private local log is capped at 8 MiB; reaching the cap or a write error stops the job. Status returns at most 512 bytes of head plus 512 bytes of non-overlapping tail, quoted in JSON, and the local output path. For larger logs, read that path while the session remains open. `outputTruncated` also indicates omitted middle output; `status=output-limit` distinguishes a capped log. A nonzero exit code is reported, not hidden.
+
+Successful start returns immediately; subsequent agent cancellation does not silently kill the independently running job. Cancelling a status request does not stop it. Use `stop` explicitly. Completion marks project indexing dirty but does not trigger another model turn.
+
+Jobs survive compaction. The extension appends a bounded canonical **metadata snapshot** after compaction, without command/output text or a follow-up model request. Refresh status before acting on any old snapshot. Branch navigation stops jobs no longer visible from the new branch; ancestor-owned jobs remain visible. Session replacement, reload and graceful shutdown stop jobs and remove their logs. State is not persisted in SQLite, Memory or Pins and is not restored after restart.
+
+Native Pi handles process-tree cancellation. There is no rollback of command side effects and no guarantee of controlling deliberately escaped daemons. Forced process termination/crashes can leave temporary logs; abrupt-exit cleanup is not guaranteed. Raw logs can contain secrets: do not publish or persist them blindly. Linux tests do not establish Windows execution success.
+
+Architecture: [ADR 060](ADR/060-optional-portable-agent-tools.md).

package/docs/releases/0.3.3.md

@@ -1,6 +1,6 @@
 # DS4 Context Engine 0.3.3
 
-Status: candidate, not yet published.
+Status: published 2026-09-04 as stable, printed under the npm `latest` dist-tag, tagged `v0.3.3`.
 
 This release adds a configurable transport retry policy for compaction summary requests on top of the 0.3.2 stable candidate. It carries forward 0.3.2 without changing canonical records, SQLite schema, runtime contracts, retention limits, privacy policy, compaction validation, or fallback semantics.
 
@@ -43,7 +43,7 @@ ds4-context-reference-adapter
 ds4-context-engine
 ```
 
-Both adapters depend exactly on `ds4-context-core@0.3.3`. Publication uses npm's default `latest` tag for all three packages. GitHub Actions remains validation-only with OIDC and package-write permissions denied.
+Both adapters depend exactly on `ds4-context-core@0.3.3`. Publication uses npm's default `latest` tag for all three packages: `latest` now resolves to `0.3.3` (previously `0.3.2`), `beta` remains `0.3.0-beta.3`, `alpha` remains `0.3.0-alpha.5`, and `rc` remains `0.2.0-rc.1`. GitHub Actions remains validation-only with OIDC and package-write permissions denied.
 
 ## Candidate validation
 
@@ -58,3 +58,23 @@ Local candidate verification on Node.js `26.5.1`:
 - Version, exact core dependencies, package-lock entries, extension constant, and reference-adapter constant are synchronized to `0.3.3`.
 
 Validation-only CI is recorded below with the release commit. Exact registry verification and the annotated tag are recorded after execution.
+
+## Validation-only CI
+
+Release commit `5d636cc` (chore(release): prepare 0.3.3); CI run `33921584110` on Node `22.19.0` and `24.x`. The first Node 22.19.0 attempt hit a one-off `upgrade-rebuild` migration test timeout (5 s default) on the shared runner; the exact same test passes locally and on the re-run, and the rerun completed `success` on both Node versions.
+
+## Registry verification and tag
+
+Published manually in dependency order with npm's default `latest` tag after `npm whoami` confirmed `alucard_24`:
+
+- `ds4-context-core@0.3.3`; shasum `5db4c81a9c6a8861bf6612d499abec7fb576e411`;
+- `ds4-context-reference-adapter@0.3.3`; shasum `7a251de9735968776d21ed16a2e10786ea2bc2ef`;
+- `ds4-context-engine@0.3.3`; shasum `cb107f9e28d89e860b3b05118f374a9c9969b58c`.
+
+`npm run registry:check -- 0.3.3` passed: fresh-install exact core/adapters, public core/KV exports, compiled reference conformance, packaged quality corpus, installed `ds4-context-storage` CLI shim probe, and published Pi extension startup through isolated offline RPC state. The first check attempt hit a stale npm cache ETARGET for `ds4-context-engine@0.3.3`; a direct registry query confirmed all three artifacts and dist-tags, and the retry passed.
+
+npm dist-tags for all three packages: `latest=0.3.3`, `beta=0.3.0-beta.3`, `alpha=0.3.0-alpha.5`, `rc=0.2.0-rc.1`.
+
+Annotated tag `v0.3.3` was pushed and the GitHub Release was created:
+
+https://github.com/Alucard24/ds4-context-engine/releases/tag/v0.3.3

package/docs/releases/0.3.4.md

@@ -0,0 +1,81 @@
+# DS4 Context Engine 0.3.4
+
+Status: published as stable on npm under `latest`; annotated tag `v0.3.4` points to validated release commit `5845a64`.
+
+## Added since 0.3.3
+
+Five independent opt-ins, all default-off and gated by the master `enabled` switch:
+
+- **`editing.anchored`**: exact, inclusive `head[upto]tail` replacements, expanded under Pi's native mutation queue. Literal escaping, mixed-batch exactness, native cancellation/line endings and real result diffs are preserved. No generation-time marker forcing.
+- **`editing.postEditReport`**: bounded changed-line ranges, line delta and numbered updated context derived from the actual native patch, without rereading the file. Works independently of anchored editing.
+- **`reading.adaptive`**: execution-time model-aware default read windows of 120/240/500 lines. Explicit limits, images and native byte caps remain native.
+- **`artifacts.adaptiveBudget`**: per-context estimated caps can only lower configured inline/excerpt limits. Privacy-prepared provider context, source provenance, non-expanding replacements and conservative artifact rebuild are covered.
+- **`jobs.enabled`**: separate local `bash_job` start/status/stop/list tool with trusted-project and local UI confirmation for every start, session/branch ownership, bounded output/concurrency/timeouts and lifecycle cleanup. Jobs survive compaction with a metadata-only reminder, not session replacement/reload/shutdown.
+
+See [anchored editing](../ANCHORED_EDITING.md), [portable agent tools](../PORTABLE_AGENT_TOOLS.md), [ADR 059](../ADR/059-optional-anchored-editing.md) and [ADR 060](../ADR/060-optional-portable-agent-tools.md).
+
+## Safety and compatibility
+
+Pi JSONL remains canonical and append-only; SQLite remains disposable/rebuildable with schema `15`. No live database intervention, provider/backend integration or Pi upgrade is part of this release.
+
+Unchanged contracts: `ds4-context-config-v1`, `runtime-adapter-v1`, `ds4-context-persistence-tool-v1`, `ds4-context-persistence-result-v1`. Pi remains pinned to `0.84.3`; Node.js requirement remains `>=22.19.0`.
+
+Local tool wrappers must not be combined with remote/sandbox replacements. `bash_job` does not inherit bash-only permission hooks or SDK shell settings; its confirmation explicitly identifies this boundary. Stop does not roll back shell side effects or guarantee ownership of escaped daemons. Linux execution tests do not establish Windows correctness. Adaptive budgets are estimates; real-provider token savings, latency and reliability have not been measured. No operational KV reuse, rewind, forced sampling or marker insertion is added.
+
+## Update and enable
+
+Install the exact package and fully restart Pi to load the matching compiled core:
+
+```bash
+pi install npm:ds4-context-engine@0.3.4
+```
+
+In a trusted project, enable only the features you want:
+
+```text
+/context config set editing.anchored true
+/context config set editing.postEditReport true
+/context config set reading.adaptive true
+/context config set artifacts.adaptiveBudget true
+/context config set jobs.enabled true
+/reload
+/context config show
+```
+
+Add `--global` to each `set` to target the agent-directory configuration instead of the project file. Trusted project settings take precedence. Configuration writes do not change the active session until reload/startup. Use `false` to disable. The DS4 master `enabled` switch must also be true.
+
+## Package policy and validation
+
+All three packages use `0.3.4`: `ds4-context-core`, `ds4-context-reference-adapter`, `ds4-context-engine`. Both adapters depend exactly on `ds4-context-core@0.3.4`. Publication is manual in that order using npm's stable `latest` tag. GitHub Actions remains validation-only, with OIDC and package-write permissions denied.
+
+Candidate validation on Node.js `26.5.1`, from a sanitized release source with a fresh `npm ci`:
+
+- `npm run check`: **78 files / 485 tests passed**, including native edit queue/matching regressions, independent opt-ins and real local bash execution/stop/timeout.
+- `npm run quality:compare`: passed; frozen-corpus candidate score `0.9875` versus baseline `0.808156`.
+- `npm run schema:context-persistence`: passed, `1266` bytes / `317` estimated tokens (limits `1500` / `320`).
+- `npm run latency:check` against exact `ds4-context-core@0.1.2`: passed; disabled-planning p95 ratio `0.885863`, maximum `1.1`. This is not a provider latency/savings measurement.
+- `npm run pack:check`: clean-consumer core **231 files**, reference adapter **7**, engine **84**, with eight real offline Pi registry scenarios.
+- All three `npm pack --dry-run --json` inventories and `git diff --check` passed.
+- Versions, exact core dependencies, lockfile and runtime version constants are synchronized. No dependency upgrade was performed.
+
+Pre-existing local `allowScripts` additions and `.serena/` are excluded from release commits and public packages.
+
+The initial CI run `33965143704` on candidate `4e665e3` passed Node `22.19.0`. Node `24.x` exceeded the default 5-second timeout in the existing disk-backed schema-v10 upgrade fixture (484 tests passed, one timeout). That individual correctness test now has a bounded 15-second timeout, with all assertions unchanged; no runtime/storage behavior changed.
+
+Final validation-only CI run [`33965385188`](https://github.com/Alucard24/ds4-context-engine/actions/runs/33965385188) on `5845a64` passed both Node `22.19.0` and `24.x`, including the full test suite and clean-consumer package checks.
+
+## Registry verification and release
+
+Published manually as `alucard_24`, in dependency order, from reviewed tarballs built in a clean committed worktree:
+
+- `ds4-context-core@0.3.4`: shasum `c1f1f6c5eec392e43f8b6a0917581e5d02141c84`;
+- `ds4-context-reference-adapter@0.3.4`: shasum `61402dc240af5963f4cbbf5f69752fe9a451170d`;
+- `ds4-context-engine@0.3.4`: shasum `99b9ba52c2bc628f5fb197ea5356459963994b89`.
+
+`npm run registry:check -- 0.3.4` passed: fresh exact-version installation, matching adapter/core dependencies, public core exports, compiled reference conformance, packaged quality corpus, storage CLI usage probe and isolated offline Pi extension startup. Registry SHA-1 and integrity values match the local tarballs for all three packages.
+
+Verified dist-tags for all three: `latest=0.3.4`, `beta=0.3.0-beta.3`, `alpha=0.3.0-alpha.5`, `rc=0.2.0-rc.1`.
+
+Annotated tag `v0.3.4` targets `5845a64`, the tested/published source. This post-publication evidence update is documentation-only.
+
+GitHub Release: https://github.com/Alucard24/ds4-context-engine/releases/tag/v0.3.4

package/docs/releases/0.3.5.md

@@ -0,0 +1,70 @@
+# DS4 Context Engine 0.3.5
+
+Status: local release gates passed; commit, push and coordinated publication authorized. Validation-only CI, publication and registry verification are pending.
+
+## Added since 0.3.4
+
+Bounded compaction optimizations, enabled by default when DS4 custom compaction is enabled:
+
+- **`compaction.directUpdate=true`**: one validated previous-summary plus new-source request when the complete sanitized prompt fits. The immutable `task-state` node retains predecessor edges, transitive source IDs and a source hash bound to both inputs. Oversized updates retain hierarchical segmentation/aggregation; no synthetic segment or source truncation is introduced.
+- **`compaction.inputBudget="summary"`**: use the calibrated hard input limit rather than the ordinary context fill target, additionally capped by model context minus safety margin and actual summary output headroom. Configured/model hard limits and calibration remain authoritative; ordinary context planning is unchanged.
+- **`compaction.maxConcurrentSegments=2`** (integer 1–2): overlap only independent segment requests. Node identities, sources, graph edges and usage follow source order, never completion order. Failure or cancellation stops scheduling, aborts siblings and drains every started worker before Pi fallback; no partial graph is installed. Aggregation stays ordered and bounded.
+- **Metadata-only diagnostics**: `/context compaction` reports path, effective provider/model, full-update prompt size, logical calls, concurrency, retries and monotonic wall timings for preparation, generation, aggregation, persistence and total DS4 hook duration. Timings are process-local, exclude native fallback, and are not persisted in canonical JSONL.
+
+Transport documentation now explicitly distinguishes **three total attempts** from three retries; runtime transport policy is unchanged.
+
+See [compaction controls](../COMPACTION.md#latency-controls) and [ADR-061](../ADR/061-compaction-latency.md).
+
+## Compatibility and limitations
+
+Pi cut points, atomic tool exchanges, summary validation and bounded exact-value repair, privacy classification, immutable provenance and JSONL rebuild remain in place. Schema-v2 compaction metadata reuses the existing `task-state` kind. Pi JSONL remains canonical and append-only; SQLite remains disposable/rebuildable at schema `15`.
+
+Unchanged contracts: `ds4-context-config-v1`, `runtime-adapter-v1`, `ds4-context-persistence-tool-v1`, `ds4-context-persistence-result-v1`. The new configuration keys are additive; absent keys use the new defaults. The five optional portable tools/features introduced in 0.3.4 remain default-off. Pi stays pinned to `0.84.3`; Node.js remains `>=22.19.0`. No dependency upgrade, live database maintenance or Pi upgrade is part of this release.
+
+Mock-provider tests establish call counts, bounded overlap and deterministic safety properties, not real-provider speedups, semantic equivalence or a guaranteed compaction duration. A larger prompt may take longer to process. Rate-limit errors are not transport-retried; providers with restrictive concurrency should use `maxConcurrentSegments=1`. Cancellation is cooperative: accepted work may still be billed and providers ignoring abort may delay settlement. Linux validation does not establish Windows execution correctness.
+
+## Update and configure
+
+Install the exact coordinated package and **fully restart Pi** to load its matching compiled core:
+
+```bash
+pi install npm:ds4-context-engine@0.3.5
+```
+
+No extra opt-in is needed for the three new defaults when DS4 and custom compaction are enabled. Inspect configuration and subsequent compaction diagnostics with:
+
+```text
+/context config show
+/context compaction
+```
+
+For a legacy-path comparison in a trusted project:
+
+```text
+/context config set compaction.directUpdate false
+/context config set compaction.inputBudget context
+/context config set compaction.maxConcurrentSegments 1
+/reload
+```
+
+Use `true`, `summary`, and `2` to restore the new defaults. Add `--global` to each `set` for agent-directory configuration; trusted project settings take precedence. Disabling DS4 custom compaction still delegates to Pi.
+
+## Package policy and validation
+
+All three packages use `0.3.5`: `ds4-context-core`, `ds4-context-reference-adapter`, `ds4-context-engine`. Both adapters depend exactly on `ds4-context-core@0.3.5`. Publication is manual in that order under npm's stable `latest` tag. GitHub Actions remains validation-only with OIDC and package-write permissions denied.
+
+Candidate validation on Node.js `26.5.1`, from a sanitized release source with a fresh `npm ci`:
+
+- `npm run check`: **80 files / 508 tests passed**, including exact full-prompt budget boundaries, direct-update evidence/privacy, immutable graph rebuild, out-of-order segments, abort/failure drainage and transport retry cancellation.
+- `npm run quality:compare`: passed; frozen-corpus candidate score `0.9875` versus baseline `0.808156`. This is a planner corpus, not a real-provider summary-quality comparison.
+- `npm run schema:context-persistence`: passed, `1266` bytes / `317` estimated tokens (limits `1500` / `320`).
+- `npm run latency:check` against freshly installed exact `ds4-context-core@0.1.2`: passed; disabled-planning p95 ratio `0.903863`, maximum `1.1`. This is not a compaction/provider latency measurement.
+- `npm run pack:check`: passed in a clean consumer, core **235 files**, reference adapter **7**, engine **87**, including isolated offline Pi extension startup and registry scenarios.
+- All three `npm pack --dry-run --json` inventories and `git diff --check` passed. Tarball inventories exclude sessions, databases, credentials, test state and `.serena/`.
+- Manifests, exact core dependencies, lockfile and runtime version constants are synchronized. The lockfile contains only coordinated version changes; no dependency upgrade was performed.
+
+Pre-existing local `allowScripts` additions and `.serena/` are excluded from release commits and public packages.
+
+## Registry verification and release
+
+Pending successful local gates, validation-only CI, manual publication and exact registry verification. No release tag has been created yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ds4-context-engine",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Non-destructive, provider-independent context management for Pi.",
   "type": "module",
   "license": "MIT",
@@ -62,7 +62,7 @@
     ]
   },
   "dependencies": {
-    "ds4-context-core": "0.3.3"
+    "ds4-context-core": "0.3.5"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "0.84.3",

package/src/extension/adaptive-read-tool.ts

@@ -0,0 +1,47 @@
+import {
+  createReadToolDefinition,
+  defineTool,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type ReadToolOptions,
+} from "@earendil-works/pi-coding-agent";
+
+export function adaptiveReadLimit(contextWindow: number | undefined): number | undefined {
+  if (contextWindow === undefined || !Number.isFinite(contextWindow) || contextWindow <= 0) return undefined;
+  return contextWindow <= 8192 ? 120 : contextWindow <= 16384 ? 240 : 500;
+}
+
+export function createAdaptiveReadTool(cwd: string, options?: ReadToolOptions) {
+  const base = createReadToolDefinition(cwd, options);
+  return defineTool({
+    ...base,
+    description: `${base.description} Without an explicit limit, DS4 uses 120/240/500 lines for small/medium/large model context windows.`,
+    async execute(id, input, signal, onUpdate, ctx) {
+      // Tool-call hooks can mutate arguments after schema validation.
+      if (!input || typeof input.path !== "string"
+        || (input.offset !== undefined && (!Number.isSafeInteger(input.offset) || input.offset < 1))
+        || (input.limit !== undefined && (!Number.isSafeInteger(input.limit) || input.limit < 1))) {
+        throw new Error("Read requires path and optional positive integer offset/limit");
+      }
+      const limit = input.limit ?? adaptiveReadLimit(ctx.model?.contextWindow);
+      // Private copy only. Images and all byte/line-ending handling stay native.
+      return createReadToolDefinition(ctx.cwd || cwd, options).execute(
+        id, { ...input, ...(limit !== undefined ? { limit } : {}) }, signal, onUpdate, ctx,
+      );
+    },
+  });
+}
+
+export function createAdaptiveReadRegistration(pi: ExtensionAPI) {
+  let registered = false;
+  return (enabled: boolean, ctx: ExtensionContext): void => {
+    if (!enabled && !registered) return;
+    const existing = pi.getAllTools().find((tool) => tool.name === "read");
+    if (!registered && existing?.sourceInfo.source !== "builtin") {
+      if (ctx.hasUI) ctx.ui.notify("DS4 adaptive read not registered: native read is unavailable or already overridden.", "warning");
+      return;
+    }
+    pi.registerTool(enabled ? createAdaptiveReadTool(ctx.cwd) : createReadToolDefinition(ctx.cwd));
+    registered = true;
+  };
+}

package/src/extension/anchored-edit-tool.ts

@@ -0,0 +1,157 @@
+import { constants } from "node:fs";
+import { access, readFile, writeFile } from "node:fs/promises";
+import { Type, type Static } from "@earendil-works/pi-ai";
+import {
+  createEditToolDefinition,
+  defineTool,
+  type EditOperations,
+  type EditToolOptions,
+  type ExtensionAPI,
+  type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { normalizeEditText, resolveAnchoredEdit, UPTO_MARKER } from "./anchored-edit.ts";
+import { addPostEditReport, createReportingEditTool } from "./post-edit-report.ts";
+
+export const ANCHORED_EDIT_PARAMS = Type.Object({
+  path: Type.String({ description: "Path to the file to edit (relative or absolute)" }),
+  edits: Type.Array(Type.Object({
+    oldText: Type.String({
+      description: "Unique old text, or head[upto]tail for an inclusive range: head unique in the original file, tail unique after head. Anchors match exactly; newlines immediately after [upto] are separators.",
+    }),
+    newText: Type.String({ description: "Replacement for the entire old span, including both anchors." }),
+    literal: Type.Optional(Type.Boolean({
+      description: "Treat [upto] as ordinary text instead of a range marker. Default false.",
+    })),
+  })),
+});
+export type AnchoredEditInput = Static<typeof ANCHORED_EDIT_PARAMS>;
+
+const localOperations: EditOperations = {
+  access: (path) => access(path, constants.R_OK | constants.W_OK),
+  readFile: (path) => readFile(path),
+  writeFile: (path, content) => writeFile(path, content, "utf8"),
+};
+
+function usesAnchors(edit: Partial<AnchoredEditInput["edits"][number]>): boolean {
+  return edit.literal !== true && typeof edit.oldText === "string" && edit.oldText.includes(UPTO_MARKER);
+}
+
+// tool_call handlers can mutate already-validated arguments. Recheck before I/O.
+function validateInput(input: AnchoredEditInput): void {
+  if (!input || typeof input.path !== "string" || !Array.isArray(input.edits) || input.edits.length === 0) {
+    throw new Error("Edit input requires a path and at least one replacement in edits");
+  }
+  for (const [index, edit] of input.edits.entries()) {
+    if (!edit || typeof edit.oldText !== "string" || typeof edit.newText !== "string"
+      || (edit.literal !== undefined && typeof edit.literal !== "boolean")) {
+      throw new Error(`Invalid edits[${index}]: expected oldText/newText strings and optional literal boolean`);
+    }
+  }
+}
+
+/**
+ * Expand inside native edit's read operation, NOT in prepareArguments/tool_call.
+ * Native edit holds its shared mutation queue from access/read through write.
+ * Per-call copies keep expanded file contents out of canonical tool arguments.
+ */
+export function createAnchoredEditTool(cwd: string, options?: EditToolOptions, postEditReport = false) {
+  const base = createEditToolDefinition(cwd, options);
+  const operations = options?.operations ?? localOperations;
+  return defineTool({
+    ...base,
+    description: "Edit a single file with unique, non-overlapping replacements against its original content. For large old spans, use head[upto]tail in oldText to replace the inclusive range between exact anchors. Use literal: true to match [upto] literally.",
+    promptSnippet: "Edit files with exact text or compact [upto] anchored ranges; supports disjoint edits[]",
+    promptGuidelines: [
+      "Use edit with edits[] for precise file changes. Match every edit against the original file; reject overlaps and merge nearby changes instead of overlapping edits.",
+      "For large old spans, prefer oldText containing first lines, [upto], then final lines. The head must be unique in the file and the tail unique after the head; include both anchors in newText if you want to keep them.",
+      "Copy anchors exactly from inspected content. Newlines immediately after [upto] are separators, not part of the tail anchor. Never omit the tail or use multiple markers. Use literal: true when oldText contains literal [upto] text.",
+      "All oldText in a batch containing anchors must match exactly. Native fuzzy fallback is available only in calls without anchored edits.",
+      "Keep ordinary oldText as small as possible while unique. Re-read after anchor or overlap errors; do not guess or broaden a destructive range.",
+    ],
+    parameters: ANCHORED_EDIT_PARAMS,
+    // Native argument preparation also supports JSON-string/single-object edits
+    // and legacy top-level oldText/newText. It preserves optional literal flags.
+    prepareArguments: base.prepareArguments,
+    async execute(toolCallId, input, signal, onUpdate, ctx) {
+      validateInput(input);
+      // The targeted Pi version binds cwd at construction.
+      const executionCwd = ctx.cwd || cwd;
+      if (!input.edits.some(usesAnchors)) {
+        const ordinary = await createEditToolDefinition(executionCwd, options).execute(toolCallId, input, signal, onUpdate, ctx);
+        return postEditReport ? addPostEditReport(ordinary) : ordinary;
+      }
+      const requests = input.edits.map((edit) => ({ ...edit }));
+      const edits = requests.map((edit) => ({ oldText: edit.oldText, newText: edit.newText }));
+      const ranges: Array<{ editIndex: number; startLine: number; endLine: number }> = [];
+      const delegate = createEditToolDefinition(executionCwd, {
+        ...options,
+        operations: {
+          access: (path) => operations.access(path),
+          writeFile: (path, content) => operations.writeFile(path, content),
+          async readFile(path) {
+            const buffer = await operations.readFile(path);
+            if (signal?.aborted) throw new Error("Operation aborted");
+            const original = normalizeEditText(buffer.toString("utf8").replace(/^\uFEFF/, ""));
+            for (const [index, edit] of requests.entries()) {
+              if (!usesAnchors(edit)) {
+                // Native fuzzy fallback changes the coordinate space for the
+                // WHOLE batch. Prevent it from relocating an exact anchored span.
+                if (!original.includes(normalizeEditText(edit.oldText))) {
+                  throw new Error(`edits[${index}] in ${input.path}: anchored batches require exact ordinary oldText; re-read the file or use a separate marker-free call`);
+                }
+                continue;
+              }
+              try {
+                const span = resolveAnchoredEdit(original, edit.oldText);
+                edits[index]!.oldText = span.oldText;
+                ranges.push({ editIndex: index, startLine: span.startLine, endLine: span.endLine });
+              } catch (error) {
+                throw new Error(`edits[${index}] in ${input.path}: ${error instanceof Error ? error.message : String(error)}`);
+              }
+            }
+            return buffer;
+          },
+        },
+      });
+      // Native batch validation, overlap/no-op checks, cancellation, BOM/EOL
+      // restoration, write and diff generation all remain on the native path.
+      const nativeResult = await delegate.execute(toolCallId, { path: input.path, edits }, signal, onUpdate, ctx);
+      const result = postEditReport ? addPostEditReport(nativeResult) : nativeResult;
+      return {
+        ...result,
+        content: [...result.content, {
+          type: "text" as const,
+          text: `Anchored replacements (original lines): ${ranges.map((range) => `edits[${range.editIndex}] ${range.startLine}-${range.endLine}`).join(", ")}.`,
+        }],
+        details: result.details && { ...result.details, anchoredRanges: ranges },
+      };
+    },
+    renderCall(args, theme, context) {
+      // The native preview matcher does not understand markers. Do not run a
+      // misleading pre-execution preview; renderResult supplies the actual diff.
+      const anchored = Array.isArray(args.edits) && args.edits.some((edit) => edit && usesAnchors(edit));
+      return base.renderCall!(args, theme, anchored ? { ...context, argsComplete: false } : context);
+    },
+  });
+}
+
+/** Session-bound opt-in. Do not claim tools reported as extension-/SDK-owned. */
+export function createAnchoredEditRegistration(pi: ExtensionAPI) {
+  let registered = false;
+  return (features: boolean | { anchored: boolean; postEditReport: boolean }, ctx: ExtensionContext): void => {
+    const anchored = typeof features === "boolean" ? features : features.anchored;
+    const postEditReport = typeof features === "boolean" ? false : features.postEditReport;
+    const enabled = anchored || postEditReport;
+    if (!enabled && !registered) return;
+    const existing = pi.getAllTools().find((tool) => tool.name === "edit");
+    if (!registered && existing?.sourceInfo.source !== "builtin") {
+      if (ctx.hasUI) ctx.ui.notify("DS4 anchored edit not registered: native edit is unavailable or already overridden.", "warning");
+      return;
+    }
+    // Pi has no unregisterTool API. After an enabled session, restore the native
+    // definition on disable. A fresh reload while disabled registers nothing.
+    pi.registerTool(anchored ? createAnchoredEditTool(ctx.cwd, undefined, postEditReport)
+      : postEditReport ? createReportingEditTool(ctx.cwd) : createEditToolDefinition(ctx.cwd));
+    registered = true;
+  };
+}

package/src/extension/anchored-edit.ts

@@ -0,0 +1,53 @@
+/** Portable text semantics; no filesystem access or inference-time forcing. */
+export const UPTO_MARKER = "[upto]";
+
+export interface AnchoredEditSpan {
+  /** Offsets in LF-normalized, BOM-free original content (UTF-16 code units). */
+  start: number;
+  end: number;
+  oldText: string;
+  startLine: number;
+  endLine: number;
+}
+
+export function normalizeEditText(text: string): string {
+  return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+/** Count overlapping occurrences as ambiguous too. Tail uniqueness is suffix-only. */
+function uniqueAnchor(content: string, anchor: string, from: number, label: string): number {
+  if (!anchor.trim()) throw new Error(`${label} anchor must contain non-whitespace text`);
+  const position = content.indexOf(anchor, from);
+  if (position < 0) throw new Error(`${label} anchor not found${from > 0 ? " after head" : ""}`);
+  if (content.indexOf(anchor, position + 1) >= 0) {
+    throw new Error(`${label} anchor is not unique${from > 0 ? " after head" : ""}`);
+  }
+  return position;
+}
+
+/**
+ * Resolve one DS4-style range. Both anchors are included in the replacement.
+ * As in DS4, newlines immediately after the marker are separators, not part of
+ * the tail needle. No trimming of anchor spaces, fuzzy matching or automatic
+ * forcer's size/line thresholds. The caller supplies the original normalized file.
+ */
+export function resolveAnchoredEdit(content: string, oldText: string): AnchoredEditSpan {
+  const old = normalizeEditText(oldText);
+  const marker = old.indexOf(UPTO_MARKER);
+  if (marker < 0) throw new Error("Anchored oldText must contain one [upto] marker");
+  if (old.indexOf(UPTO_MARKER, marker + UPTO_MARKER.length) >= 0) {
+    throw new Error("Anchored oldText contains more than one [upto] marker; use literal: true for literal text");
+  }
+  const head = old.slice(0, marker);
+  const tail = old.slice(marker + UPTO_MARKER.length).replace(/^\n+/, "");
+  const start = uniqueAnchor(content, head, 0, "Head");
+  const tailStart = uniqueAnchor(content, tail, start + head.length, "Tail");
+  const end = tailStart + tail.length;
+  return {
+    start,
+    end,
+    oldText: content.slice(start, end),
+    startLine: content.slice(0, start).split("\n").length,
+    endLine: content.slice(0, end - 1).split("\n").length,
+  };
+}