wiki-viewer 1.5.2 → 1.7.0

package/.next/standalone/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-viewer",
-  "version": "1.5.2",
+  "version": "1.7.0",
   "description": "Local file viewer and wiki — view markdown, HTML, PDFs, notebooks, office docs, and more from any directory",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,7 @@
     "better-auth": "^1.6.12",
     "better-sqlite3": "^12.10.0",
     "chokidar": "^5.0.0",
+    "jszip": "^3.10.1",
     "kysely": "0.28.5",
     "next": "16.2.4",
     "proper-lockfile": "^4.1.2",
@@ -103,7 +104,6 @@
     "gray-matter": "^4.0.3",
     "hast-util-to-html": "^9.0.5",
     "highlight.js": "^11.11.1",
-    "jszip": "^3.10.1",
     "lowlight": "^3.3.0",
     "lucide-react": "^0.525.0",
     "mammoth": "^1.12.0",

package/.next/standalone/packages/wiki-viewer-mcp/bench-e2e.mjs

@@ -0,0 +1,166 @@
+/**
+ * End-to-end MCP benchmark — measures the FULL stack a remote agent crosses,
+ * minus the LLM: MCP stdio JSON-RPC -> shim fetch (keep-alive or not) -> HTTP
+ * -> Next standalone server -> route handler -> disk.
+ *
+ * It spawns the real Next standalone server on a loopback port with an
+ * isolated temp ROOT_DIR + temp HOME (seeded agent registry), then drives the
+ * REAL wiki-viewer-mcp shim over stdio via the MCP SDK client.
+ *
+ * Run from repo root:
+ *   node packages/wiki-viewer-mcp/bench-e2e.mjs
+ * Requires: `npm run build` (root) and shim built (npm --prefix packages/wiki-viewer-mcp run build).
+ * Env: BENCH_ITERS (default 50), BENCH_WARMUP (default 10), BENCH_URL (skip spawning, hit a remote instance)
+ */
+import { spawn } from "node:child_process";
+import { mkdtemp, writeFile, mkdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const ITERS = Number(process.env.BENCH_ITERS) || 50;
+const WARMUP = Number(process.env.BENCH_WARMUP) || 10;
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.resolve(HERE, "../..");
+
+function sha256hex(buf) {
+	return createHash("sha256").update(buf).digest("hex");
+}
+function pct(s, p) { return s[Math.min(s.length - 1, Math.floor((p / 100) * s.length))]; }
+function stats(label, samples) {
+	const s = [...samples].sort((a, b) => a - b);
+	const mean = s.reduce((a, b) => a + b, 0) / s.length;
+	return { label, p50: pct(s, 50), p95: pct(s, 95), p99: pct(s, 99), mean, max: s[s.length - 1] };
+}
+async function timeIt(fn) { const t = performance.now(); await fn(); return performance.now() - t; }
+
+function waitForLog(child, re, timeoutMs = 30000) {
+	return new Promise((resolve, reject) => {
+		const to = setTimeout(() => reject(new Error("server start timeout")), timeoutMs);
+		const onData = (d) => {
+			const s = d.toString();
+			if (re.test(s)) { clearTimeout(to); child.stdout.off("data", onData); child.stderr.off("data", onData); resolve(); }
+		};
+		child.stdout.on("data", onData);
+		child.stderr.on("data", onData);
+	});
+}
+
+async function main() {
+	let serverProc = null;
+	let baseUrl = process.env.BENCH_URL;
+	let tmpHome, tmpRoot;
+	const TOKEN = randomBytes(32).toString("hex");
+	const AGENT_ID = "ai:bench";
+
+	if (!baseUrl) {
+		const PORT = 3917;
+		tmpHome = await mkdtemp(path.join(tmpdir(), "bench-e2e-home-"));
+		tmpRoot = await mkdtemp(path.join(tmpdir(), "bench-e2e-root-"));
+		// Seed registry: ~/.wiki-viewer/agents.json with our agent + hashed token
+		const tokenHash = sha256hex(TOKEN);
+		await mkdir(path.join(tmpHome, ".wiki-viewer"), { recursive: true });
+		const now = new Date().toISOString();
+		await writeFile(
+			path.join(tmpHome, ".wiki-viewer", "agents.json"),
+			JSON.stringify({
+				version: 1,
+				agents: {
+					[AGENT_ID]: {
+						id: AGENT_ID, displayName: "Bench", tokenHash,
+						scope: { paths: ["**/*"], ops: ["read", "mutate", "delete"] },
+						createdAt: now, lastSeen: now,
+					},
+				},
+			}, null, 2),
+			{ mode: 0o600 },
+		);
+		await writeFile(path.join(tmpRoot, "bench.md"), "# Doc\n\n" + "lorem ipsum dolor sit amet. ".repeat(40));
+
+		serverProc = spawn("node", [path.join(REPO, ".next/standalone/server.js")], {
+			env: {
+				...process.env,
+				HOME: tmpHome,
+				ROOT_DIR: tmpRoot,
+				PORT: String(PORT),
+				HOSTNAME: "127.0.0.1",
+				WIKI_ALLOW_INSECURE: "1",
+				NODE_ENV: "production",
+			},
+			stdio: ["ignore", "pipe", "pipe"],
+		});
+		await waitForLog(serverProc, /Ready|started server|Listening|localhost:|127\.0\.0\.1:/i);
+		baseUrl = `http://127.0.0.1:${PORT}`;
+		// settle
+		await new Promise((r) => setTimeout(r, 500));
+	}
+
+	// Drive the REAL shim over stdio
+	const transport = new StdioClientTransport({
+		command: "node",
+		args: [path.join(HERE, "dist/index.js")],
+		env: {
+			...process.env,
+			WIKI_VIEWER_URL: baseUrl,
+			WIKI_VIEWER_TOKEN: TOKEN,
+			WIKI_VIEWER_AGENT_ID: AGENT_ID,
+		},
+	});
+	const client = new Client({ name: "bench", version: "0" }, { capabilities: {} });
+	await client.connect(transport);
+
+	const call = (name, args) => client.callTool({ name, arguments: args });
+
+	const bodyBase = "# Doc\n\n" + "lorem ipsum dolor sit amet. ".repeat(40);
+
+	// Warm + measure read_file
+	const readS = [], writeS = [], editS = [];
+	for (let i = 0; i < WARMUP + ITERS; i++) {
+		const t = await timeIt(async () => { await call("read_file", { path: "bench.md" }); });
+		if (i >= WARMUP) readS.push(t);
+	}
+	// write_file (whole file) — read once to prime sha cache in shim
+	await call("read_file", { path: "bench.md" });
+	for (let i = 0; i < WARMUP + ITERS; i++) {
+		const t = await timeIt(async () => {
+			await call("write_file", { path: "bench.md", content: bodyBase + "\n\nw " + i, force: true });
+		});
+		if (i >= WARMUP) writeS.push(t);
+	}
+	// edit_file (read+replace+write inside one tool call)
+	await call("write_file", { path: "bench.md", content: bodyBase + "\n\nseed", force: true });
+	for (let i = 0; i < WARMUP + ITERS; i++) {
+		const find = i === 0 ? "seed" : "e " + (i - 1);
+		const t = await timeIt(async () => {
+			await call("edit_file", { path: "bench.md", find, replace: "e " + i });
+		});
+		if (i >= WARMUP) editS.push(t);
+	}
+
+	const results = [stats("read_file", readS), stats("write_file (whole-file)", writeS), stats("edit_file (read+write)", editS)];
+	console.log(`\nE2E MCP benchmark — full stack minus LLM  (iters=${ITERS}, warmup=${WARMUP})`);
+	console.log(`target: ${baseUrl}${serverProc ? " (local standalone)" : " (remote)"}\n`);
+	console.log(["tool".padEnd(26), "p50", "p95", "p99", "mean", "max"].join("  "));
+	for (const r of results) {
+		console.log([
+			r.label.padEnd(26),
+			`${r.p50.toFixed(1)}ms`.padStart(8),
+			`${r.p95.toFixed(1)}ms`.padStart(8),
+			`${r.p99.toFixed(1)}ms`.padStart(8),
+			`${r.mean.toFixed(1)}ms`.padStart(8),
+			`${r.max.toFixed(1)}ms`.padStart(8),
+		].join("  "));
+	}
+	console.log("");
+
+	await client.close();
+	if (serverProc) serverProc.kill("SIGTERM");
+	if (tmpHome) await rm(tmpHome, { recursive: true, force: true });
+	if (tmpRoot) await rm(tmpRoot, { recursive: true, force: true });
+	process.exit(0);
+}
+main().catch((e) => { console.error(e); process.exit(1); });

package/.next/standalone/packages/wiki-viewer-mcp/bench-latency.mjs

@@ -0,0 +1,87 @@
+/**
+ * Latency-model benchmark: proves how per-call TCP/TLS handshakes (no keep-alive)
+ * vs pooled keep-alive connections behave under WAN-like RTT.
+ *
+ * It does NOT need the full Next server — it runs a tiny local HTTP server that
+ * sleeps RTT/2 before responding (modeling one-way latency), then compares:
+ *   A) fetch with a fresh connection each call (no keep-alive)
+ *   B) fetch over a pooled keep-alive agent (undici)
+ *
+ * For each, it models a "write" (1 request) and an "edit" (2 requests: GET+PUT).
+ *
+ * Run: node packages/wiki-viewer-mcp/bench-latency.mjs [rttMs]
+ */
+import http from "node:http";
+import { Agent, fetch as undiciFetch } from "undici";
+
+const RTT = Number(process.argv[2] ?? process.env.RTT_MS ?? 80); // round-trip ms
+const ITERS = Number(process.env.ITERS ?? 30);
+const ONE_WAY = RTT / 2;
+
+function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
+
+// Local server that injects one-way latency on both receive and send.
+const server = http.createServer(async (req, res) => {
+	// drain body
+	for await (const _ of req) { /* consume */ }
+	await sleep(ONE_WAY);           // network: client -> server
+	res.writeHead(200, { "Content-Type": "application/json", ETag: '"sha256:abc"', "X-File-Size": "1024" });
+	res.end(JSON.stringify({ sha256: "sha256:abc", size: 1024 }));
+});
+
+function pct(s, p) { return s[Math.min(s.length - 1, Math.floor((p / 100) * s.length))]; }
+function summarize(label, samples) {
+	const s = [...samples].sort((a, b) => a - b);
+	const mean = s.reduce((a, b) => a + b, 0) / s.length;
+	return `${label.padEnd(40)} p50=${pct(s, 50).toFixed(0)}ms  p95=${pct(s, 95).toFixed(0)}ms  mean=${mean.toFixed(0)}ms`;
+}
+
+async function bench(label, doCall) {
+	const samples = [];
+	for (let i = 0; i < ITERS + 5; i++) {
+		const t = performance.now();
+		await doCall();
+		if (i >= 5) samples.push(performance.now() - t);
+	}
+	return summarize(label, samples);
+}
+
+async function main() {
+	await new Promise((r) => server.listen(0, "127.0.0.1", r));
+	const port = server.address().port;
+	const base = `http://127.0.0.1:${port}/x`;
+
+	// A) No keep-alive: force a fresh connection per request.
+	const noKa = new Agent({ pipelining: 0, connections: 1, keepAliveTimeout: 1, keepAliveMaxTimeout: 1 });
+	// B) Pooled keep-alive.
+	const ka = new Agent({ keepAliveTimeout: 30_000, keepAliveMaxTimeout: 60_000, connections: 10 });
+
+	const req = (dispatcher, method) =>
+		undiciFetch(base, { method, dispatcher, headers: { "content-type": "application/octet-stream" }, body: method === "PUT" ? "x".repeat(1024) : undefined })
+			.then((r) => r.arrayBuffer());
+
+	// Model a COLD connection: TCP(1 RTT) + TLS(≈2 RTT) handshake before the
+	// request even goes out. Real HTTPS over WAN pays this on every call when
+	// the client doesn't reuse connections. We add it explicitly because
+	// loopback can't reproduce handshake cost.
+	const HANDSHAKE_RTTS = Number(process.env.HANDSHAKE_RTTS ?? 3); // TCP+TLS ≈ 3 RTT
+	const freshReq = async (method) => {
+		await sleep(HANDSHAKE_RTTS * RTT); // cold-connection handshake penalty
+		const d = new Agent({ keepAliveTimeout: 1, connections: 1 });
+		await req(d, method);
+		await d.close();
+	};
+
+	console.log(`\nlatency model — RTT=${RTT}ms, iters=${ITERS}\n`);
+	console.log(await bench("write  · fresh conn per call (no keep-alive)", () => freshReq("PUT")));
+	console.log(await bench("write  · pooled keep-alive", () => req(ka, "PUT")));
+	console.log(await bench("edit   · fresh conn per call (GET+PUT)", async () => { await freshReq("GET"); await freshReq("PUT"); }));
+	console.log(await bench("edit   · pooled keep-alive (GET+PUT)", async () => { await req(ka, "GET"); await req(ka, "PUT"); }));
+	console.log("");
+	console.log("Note: 'fresh conn' pays TCP handshake (+~1 RTT) per call; real HTTPS adds TLS (+1-2 RTT).");
+	console.log("");
+
+	await noKa.close(); await ka.close();
+	server.close();
+}
+main().catch((e) => { console.error(e); process.exit(1); });

package/.next/standalone/packages/wiki-viewer-mcp/bench-payload.mjs

@@ -0,0 +1,45 @@
+/**
+ * Payload-size model: how much does whole-file PUT cost vs a diff/patch,
+ * across realistic .md sizes and uplink speeds? Decides whether a server-side
+ * patch endpoint is worth building.
+ *
+ * Pure arithmetic model (no network needed): upload_time = bytes / uplink_Bps.
+ * A small edit changes ~1 line; a patch payload ≈ the changed region + framing.
+ *
+ * Run: node packages/wiki-viewer-mcp/bench-payload.mjs
+ */
+const DOC_SIZES = [
+	{ label: "small note (2 KB)", bytes: 2 * 1024 },
+	{ label: "typical doc (20 KB)", bytes: 20 * 1024 },
+	{ label: "long doc (100 KB)", bytes: 100 * 1024 },
+	{ label: "big doc (500 KB)", bytes: 500 * 1024 },
+];
+// Uplink speeds (bytes/sec). Home/office uplinks are often the bottleneck.
+const UPLINKS = [
+	{ label: "fast (10 MB/s)", bps: 10 * 1024 * 1024 },
+	{ label: "typical home up (2 Mbps = 0.25 MB/s)", bps: 0.25 * 1024 * 1024 },
+	{ label: "slow / shared (0.5 Mbps)", bps: 0.0625 * 1024 * 1024 },
+];
+const PATCH_PAYLOAD = 300; // bytes: a one-line str-replace patch + JSON framing
+
+function ms(bytes, bps) { return (bytes / bps) * 1000; }
+
+console.log("\nupload-time model — whole-file PUT vs ~300B patch (transfer only)\n");
+for (const up of UPLINKS) {
+	console.log(`uplink: ${up.label}`);
+	console.log("  " + ["doc".padEnd(22), "whole-file", "patch", "speedup"].join("  "));
+	for (const d of DOC_SIZES) {
+		const whole = ms(d.bytes, up.bps);
+		const patch = ms(PATCH_PAYLOAD, up.bps);
+		const speedup = whole / patch;
+		console.log("  " + [
+			d.label.padEnd(22),
+			`${whole.toFixed(0)}ms`.padStart(10),
+			`${patch.toFixed(1)}ms`.padStart(7),
+			`${speedup.toFixed(0)}x`.padStart(7),
+		].join("  "));
+	}
+	console.log("");
+}
+console.log("Note: this is transfer time only; add RTT + handshake (now pooled) on top.");
+console.log("Whole-file PUT also re-sends unchanged bytes every edit; patch sends only the change.\n");

package/.next/standalone/packages/wiki-viewer-mcp/dist/http-client.js

@@ -114,6 +114,8 @@ export class WikiViewerClient {
             collabRevision: collab.collabRevision,
             collabSnapshot: collab.collabSnapshot,
             fetchedAt: Date.now(),
+            // Cache the text body (bounded) so edit_file can skip a re-GET.
+            body: text !== null && bodyBuf.byteLength <= cache.MAX_CACHED_BODY_BYTES ? text : undefined,
         };
         cache.set(path, state);
         return { body: bodyBuf, text, sha256, size, mtime, contentType, ...collab };
@@ -134,23 +136,50 @@ export class WikiViewerClient {
             params["mkdirs"] = "true";
         if (opts.force)
             params["force"] = "true";
-        const body = typeof content === "string"
+        const encoded = typeof content === "string"
             ? new TextEncoder().encode(content)
             : content;
-        const res = await this._fetch(this.url(`/api/agent/fs/file/${encodeFilePath(path)}`, params), {
+        const body = encoded;
+        const doPut = (headers) => this._fetch(this.url(`/api/agent/fs/file/${encodeFilePath(path)}`, params), {
             method: "PUT",
-            headers: this.headers({ "Content-Type": "application/octet-stream", ...extraHeaders }),
+            headers: this.headers({ "Content-Type": "application/octet-stream", ...headers }),
             body,
         });
+        let res = await doPut(extraHeaders);
+        // Auto-recover from "If-Match required" (overwrite without a known sha):
+        // the server demands a precondition for existing files. Transparently fetch
+        // the current sha and retry once, instead of bubbling a 412 to the agent
+        // (which would cost it an extra read + retry round-trip of its own).
+        if (res.status === 412 &&
+            !extraHeaders["If-Match"] &&
+            !opts.force &&
+            opts.ifMatch === undefined) {
+            let body412;
+            try {
+                body412 = await res.clone().json();
+            }
+            catch { /* ignore */ }
+            const code = body412?.error;
+            if (code === "PRECONDITION_REQUIRED") {
+                const cur = await this.readFile(path);
+                if (cur?.sha256) {
+                    res = await doPut({ ...extraHeaders, "If-Match": cur.sha256 });
+                }
+            }
+        }
         await this.assertOk(res, path);
         const result = await res.json();
-        // Update cache after successful write
+        // Update cache after a successful write. Preserve known collab fields from a
+        // prior read (do NOT clobber to not-markdown), refresh sha + body.
+        const prior = cache.get(path);
+        const text = typeof content === "string" ? content : null;
         cache.set(path, {
             sha256: result.sha256,
-            collabState: "not-markdown",
-            collabRevision: null,
-            collabSnapshot: null,
+            collabState: prior?.collabState ?? "not-markdown",
+            collabRevision: prior?.collabRevision ?? null,
+            collabSnapshot: prior?.collabSnapshot ?? null,
             fetchedAt: Date.now(),
+            body: text !== null && encoded.byteLength <= cache.MAX_CACHED_BODY_BYTES ? text : undefined,
         });
         return result;
     }

package/.next/standalone/packages/wiki-viewer-mcp/dist/index.js

@@ -24,6 +24,31 @@ import * as z from "zod";
 import { parseArgs } from "node:util";
 import { WikiViewerClient, IfMatchError, CollabActiveError, WikiViewerError } from "./http-client.js";
 import * as stateCache from "./state-cache.js";
+/**
+ * Enable pooled HTTP keep-alive for the global fetch the client uses.
+ *
+ * Without this, every tool call opens a fresh connection and pays a full
+ * TCP + TLS handshake (~3 RTT) before the request even goes out. Over a WAN
+ * link that turns a sub-100ms write into 300ms-1s+, and multiplies across the
+ * GET+PUT an edit performs. Reusing connections removes that per-call penalty.
+ *
+ * Wrapped in try/catch + dynamic import so a missing/edge undici never breaks
+ * startup; it just falls back to default (non-pooled) fetch.
+ */
+async function enableKeepAlive() {
+    try {
+        const { Agent, setGlobalDispatcher } = await import("undici");
+        setGlobalDispatcher(new Agent({
+            keepAliveTimeout: 30_000,
+            keepAliveMaxTimeout: 60_000,
+            connections: 16,
+            pipelining: 1,
+        }));
+    }
+    catch {
+        // undici unavailable — default fetch still works, just without pooling.
+    }
+}
 import { register, RegistrationDeniedError, RegistrationExpiredError, RegistrationTimeoutError, } from "./register.js";
 // ─── Config ───────────────────────────────────────────────────────────────────
 function requireEnv(name) {
@@ -221,12 +246,34 @@ export function createServer(client) {
                     const block = checkCollabBlock(path);
                     if (block)
                         return err(block);
-                    // Read → transform → PUT with If-Match
+                    // Fast path: if a prior read cached this file's text + sha, transform
+                    // from cache and do a conditional PUT (If-Match=cached sha). This
+                    // skips the GET round-trip. If the file changed server-side the PUT
+                    // 412s (IfMatchError) and we fall back to a fresh read+retry — so the
+                    // result is always against current content, never a stale write.
+                    const cached = stateCache.get(path);
+                    if (cached?.body !== undefined &&
+                        cached.sha256 &&
+                        cached.collabState !== "active" &&
+                        cached.body.includes(find)) {
+                        const newContent = cached.body.replace(find, replace);
+                        try {
+                            const writeResult = await client.writeFile(path, newContent, {
+                                ifMatch: cached.sha256,
+                            });
+                            return ok(`Edited: ${path}\nReplaced ${JSON.stringify(find)} → ${JSON.stringify(replace)}\nNew sha256: ${writeResult.sha256}`);
+                        }
+                        catch (e) {
+                            if (!(e instanceof IfMatchError))
+                                throw e;
+                            // File changed since our cached read — fall through to re-read.
+                        }
+                    }
+                    // Slow path: read → transform → PUT with If-Match.
                     const readResult = await client.readFile(path);
                     if (readResult.text === null) {
                         return err(`edit_file: "${path}" appears to be binary — cannot do text replacement.`);
                     }
-                    // Check collab state from fresh read
                     if (readResult.collabState === "active") {
                         return err(collabActiveMessage(path, readResult.collabSnapshot));
                     }
@@ -338,6 +385,7 @@ function buildJsonSchema(val) {
 }
 // ─── Entrypoints ─────────────────────────────────────────────────────────────
 async function main() {
+    await enableKeepAlive();
     const client = createClient();
     const server = createServer(client);
     const transport = new StdioServerTransport();

package/.next/standalone/packages/wiki-viewer-mcp/dist/state-cache.js

@@ -2,6 +2,8 @@
  * Per-path cache for last-known file metadata from GET responses.
  * Drives If-Match and collab-state checks on subsequent writes.
  */
+/** Don't cache bodies larger than this (avoid unbounded memory). */
+export const MAX_CACHED_BODY_BYTES = 256 * 1024;
 const cache = new Map();
 export function set(path, state) {
     cache.set(normalisePath(path), state);

package/.next/standalone/packages/wiki-viewer-mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-viewer-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MCP filesystem adapter for wiki-viewer agent API",
   "license": "MIT",
   "type": "module",

package/.next/standalone/packages/wiki-viewer-mcp/src/http-client.ts

@@ -51,6 +51,22 @@ export class CollabActiveError extends WikiViewerError {
   }
 }
 
+/** PATCH endpoint absent (old server) or method not allowed — caller should fall back to read+PUT. */
+export class PatchUnsupportedError extends WikiViewerError {
+  constructor(path: string, status: number) {
+    super(status, "PATCH_UNSUPPORTED", `Server does not support PATCH for ${path}`, undefined);
+    this.name = "PatchUnsupportedError";
+  }
+}
+
+/** Server-side str-replace found a different number of matches than expected. */
+export class MatchCountError extends WikiViewerError {
+  constructor(path: string, public readonly found: number, public readonly expected: number, body?: unknown) {
+    super(422, "MATCH_COUNT_MISMATCH", `${path}: expected ${expected} match(es), found ${found}`, body);
+    this.name = "MatchCountError";
+  }
+}
+
 // ─── Response shapes ─────────────────────────────────────────────────────────
 
 export interface ReadResult {
@@ -189,6 +205,8 @@ export class WikiViewerClient {
       collabRevision: collab.collabRevision,
       collabSnapshot: collab.collabSnapshot,
       fetchedAt: Date.now(),
+      // Cache the text body (bounded) so edit_file can skip a re-GET.
+      body: text !== null && bodyBuf.byteLength <= cache.MAX_CACHED_BODY_BYTES ? text : undefined,
     };
     cache.set(path, state);
 
@@ -221,28 +239,119 @@ export class WikiViewerClient {
     if (opts.mkdirs) params["mkdirs"] = "true";
     if (opts.force) params["force"] = "true";
 
-    const body: BodyInit = typeof content === "string"
-      ? (new TextEncoder().encode(content) as unknown as Uint8Array<ArrayBuffer>)
-      : (content as unknown as Uint8Array<ArrayBuffer>);
+    const encoded: Uint8Array = typeof content === "string"
+      ? new TextEncoder().encode(content)
+      : content;
+    const body = encoded as unknown as Uint8Array<ArrayBuffer>;
 
-    const res = await this._fetch(
-      this.url(`/api/agent/fs/file/${encodeFilePath(path)}`, params),
-      {
+    const doPut = (headers: Record<string, string>) =>
+      this._fetch(this.url(`/api/agent/fs/file/${encodeFilePath(path)}`, params), {
         method: "PUT",
-        headers: this.headers({ "Content-Type": "application/octet-stream", ...extraHeaders }),
+        headers: this.headers({ "Content-Type": "application/octet-stream", ...headers }),
         body,
-      },
+      });
+
+    let res = await doPut(extraHeaders);
+
+    // Auto-recover from "If-Match required" (overwrite without a known sha):
+    // the server demands a precondition for existing files. Transparently fetch
+    // the current sha and retry once, instead of bubbling a 412 to the agent
+    // (which would cost it an extra read + retry round-trip of its own).
+    if (
+      res.status === 412 &&
+      !extraHeaders["If-Match"] &&
+      !opts.force &&
+      opts.ifMatch === undefined
+    ) {
+      let body412: unknown;
+      try { body412 = await res.clone().json(); } catch { /* ignore */ }
+      const code = (body412 as Record<string, unknown> | undefined)?.error;
+      if (code === "PRECONDITION_REQUIRED") {
+        const cur = await this.readFile(path);
+        if (cur?.sha256) {
+          res = await doPut({ ...extraHeaders, "If-Match": cur.sha256 });
+        }
+      }
+    }
+
+    await this.assertOk(res, path);
+
+    const result: WriteResult = await res.json() as WriteResult;
+    // Update cache after a successful write. Preserve known collab fields from a
+    // prior read (do NOT clobber to not-markdown), refresh sha + body.
+    const prior = cache.get(path);
+    const text = typeof content === "string" ? content : null;
+    cache.set(path, {
+      sha256: result.sha256,
+      collabState: prior?.collabState ?? "not-markdown",
+      collabRevision: prior?.collabRevision ?? null,
+      collabSnapshot: prior?.collabSnapshot ?? null,
+      fetchedAt: Date.now(),
+      body: text !== null && encoded.byteLength <= cache.MAX_CACHED_BODY_BYTES ? text : undefined,
+    });
+    return result;
+  }
+
+  // ── patch_file (server-side str-replace) ─────────────────────────────────────
+
+  /**
+   * Server-side exact str-replace: sends only {find, replace} instead of the
+   * whole file. Requires If-Match (auto-filled from cache if not given).
+   * Throws PatchUnsupportedError on 404/405 so callers can fall back to
+   * read+PUT against older servers, and MatchCountError on 422.
+   */
+  async patchFile(
+    path: string,
+    find: string,
+    replace: string,
+    opts: { ifMatch?: string; expectedOccurrences?: number; ifCollabMatch?: number } = {},
+  ): Promise<WriteResult> {
+    const ifMatch = opts.ifMatch ?? cache.get(path)?.sha256;
+    const headers: Record<string, string> = { "Content-Type": "application/json" };
+    if (ifMatch) headers["If-Match"] = ifMatch;
+    if (opts.ifCollabMatch !== undefined) headers["If-Collab-Match"] = String(opts.ifCollabMatch);
+
+    const payload: Record<string, unknown> = { find, replace };
+    if (opts.expectedOccurrences !== undefined) payload.expectedOccurrences = opts.expectedOccurrences;
+
+    const res = await this._fetch(
+      this.url(`/api/agent/fs/file/${encodeFilePath(path)}`),
+      { method: "PATCH", headers: this.headers(headers), body: JSON.stringify(payload) },
     );
+
+    // 405 = method not allowed (endpoint absent). 404 is ambiguous: our handler
+    // returns 404 {error:"NOT_FOUND"} for a missing FILE, but an old server with
+    // no PATCH route returns a bare 404. Only treat 404 as "unsupported" when the
+    // body is NOT our structured NOT_FOUND (so a missing file surfaces normally).
+    if (res.status === 405) {
+      throw new PatchUnsupportedError(path, res.status);
+    }
+    if (res.status === 404) {
+      let body: unknown;
+      try { body = await res.clone().json(); } catch { /* not JSON → likely no route */ }
+      const code = (body as Record<string, unknown> | undefined)?.error;
+      if (code !== "NOT_FOUND") throw new PatchUnsupportedError(path, 404);
+      // else fall through to assertOk → throws WikiViewerError(404) for missing file
+    }
+    if (res.status === 422) {
+      let body: unknown;
+      try { body = await res.json(); } catch { /* ignore */ }
+      const b = body as Record<string, unknown> | undefined;
+      throw new MatchCountError(path, Number(b?.found ?? -1), Number(b?.expected ?? -1), body);
+    }
     await this.assertOk(res, path);
 
     const result: WriteResult = await res.json() as WriteResult;
-    // Update cache after successful write
+    const prior = cache.get(path);
     cache.set(path, {
       sha256: result.sha256,
-      collabState: "not-markdown",
-      collabRevision: null,
-      collabSnapshot: null,
+      collabState: prior?.collabState ?? "not-markdown",
+      collabRevision: prior?.collabRevision ?? null,
+      collabSnapshot: prior?.collabSnapshot ?? null,
       fetchedAt: Date.now(),
+      // We don't have the full new body here without reconstructing it; drop the
+      // stale cached body so the next edit re-reads rather than patching blind.
+      body: undefined,
     });
     return result;
   }