pi-prefix-stabilizer 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+Copyright (c) 2026 ezoushen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE.

package/README.md

@@ -0,0 +1,108 @@
+# pi-prefix-stabilizer
+
+Keep Pi's provider request prefix byte-stable across turns, reloads, and resumes so
+a server-side prefix cache can reuse it.
+
+The extension normalizes install paths inside the system prompt, sorts tool-schema
+lists by name, then fingerprints the normalized system text. It warns when that text
+changes during a session because one early changed token invalidates every cached
+block after it.
+
+## External contract
+
+The provider must offer content-addressed prefix caching whose cache key depends on
+the rendered request prefix. This extension stabilizes bytes; it does not enable or
+configure the server cache.
+
+For path normalization, `packagePathSuffix` must identify the volatile suffix in the
+rendered prompt. `stablePath` is the replacement shown to the model. If tools or the
+model need that path to resolve on disk, create it yourself or opt into
+`createSymlink`.
+
+## If the contract is unmet
+
+Without provider-side prefix caching, requests remain correct but receive no cache
+benefit. If the configured package suffix is absent, no path is rewritten; tool
+sorting and drift detection still run. A genuine normalized-prompt change emits a
+warning for that change, while identical repeats do not re-warn.
+
+A mention of the package suffix is only ever treated as a volatile install path -- and
+so only ever rewritten to `stablePath` -- if it is absolute and actually exists on
+disk. A relative mention or an absolute-looking one that does not exist is left alone:
+it was never an install path, so rewriting it would change the text's meaning rather
+than stabilise a fact.
+
+Symlink creation is off by default. If explicitly enabled and the link cannot be
+created, the failure is written to the configured log when logging is enabled and the
+turn continues. It also never replaces an existing symlink with a bad one: if the
+candidate install root does not exist on disk, whatever is already at `stablePath` is
+left untouched.
+
+In pi's print (`-p`) and json modes there is no UI to notify, so the drift warning that
+would otherwise be silent there is written to stderr instead, once per process.
+
+## Load order
+
+Load `pi-prefix-stabilizer` before `pi-compaction-cache`.
+
+The stabilizer must normalize the ordinary provider payload before the compaction
+extension captures it as the live cache prefix.
+
+```sh
+pi install npm:pi-prefix-stabilizer
+pi install npm:pi-compaction-cache
+```
+
+## Settings
+
+The three JSON settings resolve from `pi-prefix-stabilizer.json` in the global Pi
+config directory, then from a trusted project's Pi config directory, then from the
+environment. Later sources win. Project settings are ignored when the project is
+untrusted.
+
+| JSON key | Default | Environment override | Meaning |
+|---|---|---|---|
+| `stablePath` | `$HOME/.pi/pi-home` | `PI_PREFIX_STABILIZER_STABLE_PATH` | Stable replacement for a volatile package install path. |
+| `packagePathSuffix` | `node_modules/@earendil-works/pi-coding-agent` | `PI_PREFIX_STABILIZER_PACKAGE_PATH_SUFFIX` | Suffix used to find the absolute package root in prompt text. |
+| `createSymlink` | `false` | `PI_PREFIX_STABILIZER_CREATE_SYMLINK=1` | Create or update `stablePath` to point at the discovered package root. |
+
+Two environment-only controls preserve the original operational interface:
+
+| Environment variable | Default | Meaning |
+|---|---|---|
+| `PI_PREFIX_STABILIZER` | enabled | Set to `0` to disable the extension. |
+| `PI_PREFIX_STABILIZER_LOG` | unset | Append JSON records for rewrites, drift, and symlink operations. |
+
+Default installation performs no filesystem writes.
+
+## Measurements
+
+Measured with a large-context model behind a prefix-caching server:
+
+| request | prompt tokens | TTFT | cache hit |
+|---|---:|---:|---:|
+| cold prompt | about 132,000 | 145.33s | 0.00% |
+| byte-identical repeat | about 132,000 | 0.54s | 99.95% |
+| first four characters changed | about 132,000 | 144.68s | 0.00% |
+
+The stable repeat was about 270 times faster to first token. In the incident that
+motivated the package, an install-path change diverged near token 2,649 of a
+118,031-token request; 97.8% of the prompt had to be prefilled again, producing an
+observed 127.5–137.5s delay. At the measured 871-token/s prefill rate, the expected
+delay was 132.5s.
+
+## Reproduce the measurements
+
+1. Capture one rendered provider payload and the server's prompt-token, cached-token,
+   and TTFT metrics.
+2. Send it cold, then repeat it byte-for-byte.
+3. Change a few characters early in the system prompt and send it again.
+4. Compare cached-token counts and TTFT across the three requests.
+5. Enable this extension, repeat the experiment across a package reinstall or other
+   install-path change, and confirm that the normalized payload remains identical.
+6. Reorder tool discovery without changing the tools and confirm that normalization
+   prevents a drift warning; then make a real system-prompt change and confirm one
+   warning is shown.
+
+Cache capacity and eviction policy remain server concerns; test them separately under
+the deployment's real concurrency and request mix.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "pi-prefix-stabilizer",
+  "version": "0.1.0",
+  "description": "Keep Pi's system prompt byte-stable for prefix-cache reuse.",
+  "type": "module",
+  "main": "./prefix-stabilizer.js",
+  "exports": "./prefix-stabilizer.js",
+  "files": [
+    "prefix-stabilizer.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ezoushen/pi-extensions.git",
+    "directory": "extensions/prefix-stabilizer"
+  },
+  "homepage": "https://github.com/ezoushen/pi-extensions/tree/main/extensions/prefix-stabilizer#readme",
+  "bugs": {
+    "url": "https://github.com/ezoushen/pi-extensions/issues"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./prefix-stabilizer.js"
+    ]
+  }
+}

package/prefix-stabilizer.js

@@ -0,0 +1,285 @@
+// extensions/prefix-stabilizer/prefix-stabilizer.ts
+import { appendFileSync, symlinkSync, readlinkSync, rmSync, mkdirSync, existsSync as existsSync2 } from "node:fs";
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { dirname, join as join2 } from "node:path";
+
+// shared/settings.ts
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+
+// shared/announce.ts
+var stderrAnnounced = /* @__PURE__ */ new Set();
+function announce(ctx, message, level, reason = message) {
+  if (ctx?.hasUI === false) {
+    if (stderrAnnounced.has(reason)) return;
+    stderrAnnounced.add(reason);
+    try {
+      process.stderr.write(`${message}
+`);
+    } catch {
+    }
+    return;
+  }
+  try {
+    ctx?.ui?.notify?.(message, level);
+  } catch {
+  }
+}
+
+// shared/settings.ts
+var announcedConfigErrors = /* @__PURE__ */ new Set();
+function readConfig(path, ctx) {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    if (!announcedConfigErrors.has(path)) {
+      announcedConfigErrors.add(path);
+      const message = error instanceof Error ? error.message : String(error);
+      announce(ctx, `settings: could not parse ${path} (${message}); using defaults.`, "warning", `settings-parse:${path}`);
+    }
+    return {};
+  }
+}
+function resolveSettings(name, definitions, context, runtime = {}) {
+  const environment = runtime.environment ?? process.env;
+  const globalPath = join(runtime.agentDir ?? getAgentDir(), `${name}.json`);
+  const projectPath = join(context.cwd, CONFIG_DIR_NAME, `${name}.json`);
+  const globalConfig = readConfig(globalPath, context);
+  const projectConfig = context.isProjectTrusted() ? readConfig(projectPath, context) : {};
+  const resolved = {};
+  for (const key of Object.keys(definitions)) {
+    const definition = definitions[key];
+    let value = definition.default;
+    let provenance = { source: "default" };
+    if (definition.discover) {
+      try {
+        const discovered = definition.discover();
+        if (discovered !== void 0) {
+          value = discovered.value;
+          provenance = { source: "discovered", name: definition.discoverName ?? "discovery" };
+        }
+      } catch {
+      }
+    }
+    if (Object.hasOwn(globalConfig, key)) {
+      value = globalConfig[key];
+      provenance = { source: "global", path: globalPath };
+    }
+    if (Object.hasOwn(projectConfig, key)) {
+      value = projectConfig[key];
+      provenance = { source: "project", path: projectPath };
+    }
+    const environmentValue = environment[definition.env];
+    if (environmentValue !== void 0) {
+      value = definition.parseEnv ? definition.parseEnv(environmentValue) : environmentValue;
+      provenance = { source: "environment", name: definition.env };
+    }
+    resolved[key] = { value, provenance };
+  }
+  return resolved;
+}
+
+// extensions/prefix-stabilizer/prefix-stabilizer.ts
+var DISABLED = process.env.PI_PREFIX_STABILIZER === "0";
+var LOG_PATH = process.env.PI_PREFIX_STABILIZER_LOG;
+var SETTINGS = {
+  stablePath: {
+    default: join2(homedir(), ".pi", "pi-home"),
+    env: "PI_PREFIX_STABILIZER_STABLE_PATH"
+  },
+  packagePathSuffix: {
+    default: "node_modules/@earendil-works/pi-coding-agent",
+    env: "PI_PREFIX_STABILIZER_PACKAGE_PATH_SUFFIX"
+  },
+  createSymlink: {
+    default: false,
+    env: "PI_PREFIX_STABILIZER_CREATE_SYMLINK",
+    parseEnv: (value) => value === "1" || value.toLowerCase() === "true"
+  }
+};
+var BOUNDARY = /[\s"'`(<\[]/;
+function log(o) {
+  if (!LOG_PATH) return;
+  try {
+    appendFileSync(LOG_PATH, JSON.stringify({ t: (/* @__PURE__ */ new Date()).toISOString(), ...o }) + "\n");
+  } catch {
+  }
+}
+function ensureSymlink(root, stablePath) {
+  try {
+    if (!existsSync2(root)) {
+      log({ symlink_skip: stablePath, invalid_target: root });
+      return;
+    }
+    if (existsSync2(stablePath)) {
+      let cur = null;
+      try {
+        cur = readlinkSync(stablePath);
+      } catch {
+        cur = null;
+      }
+      if (cur === root) return;
+      rmSync(stablePath, { force: true });
+    }
+    mkdirSync(dirname(stablePath), { recursive: true });
+    symlinkSync(root, stablePath);
+    log({ symlink: stablePath, target: root });
+  } catch (e) {
+    log({ symlink_error: String(e) });
+  }
+}
+function normalisePaths(s, roots, packagePathSuffix, stablePath) {
+  let out = s;
+  let i = out.indexOf(packagePathSuffix);
+  while (i >= 0) {
+    let start = i;
+    while (start > 0 && !BOUNDARY.test(out[start - 1])) start--;
+    const candidate = out.slice(start, i + packagePathSuffix.length);
+    const isInstallRoot = candidate.startsWith("/") && existsSync2(candidate);
+    if (!isInstallRoot) {
+      i = out.indexOf(packagePathSuffix, i + packagePathSuffix.length);
+      continue;
+    }
+    roots.add(candidate);
+    out = out.slice(0, start) + stablePath + out.slice(i + packagePathSuffix.length);
+    i = out.indexOf(packagePathSuffix, start + stablePath.length);
+  }
+  return out;
+}
+function sortToolsSection(s) {
+  if (!s.includes("<tools>")) return s;
+  const lines = s.split("\n");
+  const idx = [];
+  for (let i = 0; i < lines.length; i++) if (lines[i].startsWith("- ")) idx.push(i);
+  if (idx.length < 2) return s;
+  const nameOf = (l) => l.slice(2).split(":")[0];
+  const sorted = idx.map((i) => lines[i]).sort((a, b) => nameOf(a) < nameOf(b) ? -1 : nameOf(a) > nameOf(b) ? 1 : 0);
+  idx.forEach((lineNo, k) => {
+    lines[lineNo] = sorted[k];
+  });
+  return lines.join("\n");
+}
+function toolName(t) {
+  if (!t || typeof t !== "object") return "";
+  const o = t;
+  return String(o.name ?? o.function?.name ?? o.custom?.name ?? "");
+}
+function sortToolArray(tools) {
+  if (!Array.isArray(tools) || tools.length < 2) return { v: tools, changed: false };
+  const before = tools.map(toolName);
+  const sorted = [...tools].sort((a, b) => {
+    const x = toolName(a), y = toolName(b);
+    return x < y ? -1 : x > y ? 1 : 0;
+  });
+  const changed = sorted.some((t, i) => t !== tools[i]);
+  void before;
+  return { v: changed ? sorted : tools, changed };
+}
+function walk(v, roots, packagePathSuffix, stablePath) {
+  if (typeof v === "string") {
+    let s = v;
+    if (s.includes(packagePathSuffix)) {
+      s = normalisePaths(s, roots, packagePathSuffix, stablePath);
+    }
+    s = sortToolsSection(s);
+    return s === v ? { v, n: 0 } : { v: s, n: 1 };
+  }
+  if (Array.isArray(v)) {
+    let n = 0;
+    const out = v.map((x) => {
+      const r = walk(x, roots, packagePathSuffix, stablePath);
+      n += r.n;
+      return r.v;
+    });
+    return n ? { v: out, n } : { v, n: 0 };
+  }
+  if (v && typeof v === "object") {
+    let n = 0;
+    const out = {};
+    for (const [k, val] of Object.entries(v)) {
+      const r = walk(val, roots, packagePathSuffix, stablePath);
+      n += r.n;
+      out[k] = r.v;
+    }
+    return n ? { v: out, n } : { v, n: 0 };
+  }
+  return { v, n: 0 };
+}
+function systemText(payload) {
+  const parts = [];
+  const push = (c) => {
+    if (typeof c === "string") parts.push(c);
+    else if (Array.isArray(c)) {
+      for (const b of c) if (b && typeof b === "object" && typeof b.text === "string") parts.push(b.text);
+    }
+  };
+  for (const f of ["system", "instructions"]) if (typeof payload[f] === "string") parts.push(payload[f]);
+  const msgs = payload.messages;
+  if (Array.isArray(msgs)) {
+    for (const m of msgs)
+      if (m && typeof m === "object" && m.role === "system") push(m.content);
+  }
+  return parts.join("\n").replace(/\r\n/g, "\n").replace(/[ \t]+$/gm, "");
+}
+function activate(pi, bootCtx) {
+  if (DISABLED) return;
+  let announced = false;
+  let fingerprint = null;
+  pi.on("before_provider_request", (event, ctx) => {
+    const payload = event?.payload;
+    if (!payload) return;
+    const settings = resolveSettings("pi-prefix-stabilizer", SETTINGS, {
+      cwd: ctx?.cwd ?? process.cwd(),
+      isProjectTrusted: () => ctx?.isProjectTrusted?.() ?? false,
+      hasUI: ctx?.hasUI,
+      ui: ctx?.ui
+    });
+    const stablePath = settings.stablePath.value;
+    const packagePathSuffix = settings.packagePathSuffix.value;
+    const roots = /* @__PURE__ */ new Set();
+    const out = { ...payload };
+    let n = 0;
+    for (const field of ["messages", "system", "instructions"]) {
+      if (!(field in payload)) continue;
+      const r = walk(payload[field], roots, packagePathSuffix, stablePath);
+      if (r.n) {
+        out[field] = r.v;
+        n += r.n;
+      }
+    }
+    const ts = sortToolArray(payload.tools);
+    if (ts.changed) {
+      out.tools = ts.v;
+      n += 1;
+    }
+    if (settings.createSymlink.value) {
+      for (const root of roots) if (root !== stablePath) ensureSymlink(root, stablePath);
+    }
+    if (n && !announced) {
+      announced = true;
+      log({ first_rewrite: true, replacements: n, roots: [...roots] });
+    }
+    const fp = createHash("sha1").update(systemText(n ? out : payload)).digest("hex").slice(0, 12);
+    if (fingerprint === null) {
+      fingerprint = fp;
+    } else if (fp !== fingerprint) {
+      const msg = `prefix-stabilizer: the system prompt changed mid-session (${fingerprint} -> ${fp}). The server's KV prefix cache is invalidated from that point on, so this turn re-prefills the whole context. Usual causes: a package/MCP server added or removed, rules/AGENTS.md edited, a skill added, or cwd changed.`;
+      log({ drift: true, from: fingerprint, to: fp });
+      announce(
+        { hasUI: ctx?.hasUI ?? bootCtx?.hasUI, ui: ctx?.ui ?? bootCtx?.ui },
+        msg,
+        void 0,
+        "prefix-stabilizer:drift"
+      );
+      fingerprint = fp;
+    }
+    if (!n) return;
+    return out;
+  });
+}
+export {
+  activate as default
+};