pi-cache-optimizer 2.0.1 → 2.1.0

package/{extension.ts → index.ts}

@@ -7,7 +7,7 @@ import {
 } from "node:fs";
 import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import type { BuildSystemPromptOptions, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 /**
@@ -47,8 +47,47 @@ const CACHE_PROVIDER_IDS: CacheProviderId[] = ["deepseek", "openai", "claude", "
 const OPENAI_CACHE_KEY_ENV = "PI_CACHE_OPTIMIZER_OPENAI_CACHE_KEY";
 const OPENAI_PROMPT_CACHE_KEY_PREFIX = "pi-dsco-";
 const NO_AUTO_CONFIG_ENV = "PI_CACHE_OPTIMIZER_NO_AUTO_CONFIG";
+const NO_SKILL_COMPRESSION_ENV = "PI_CACHE_OPTIMIZER_NO_SKILL_COMPRESSION";
 const DEEPSEEK_API_KEY_ENV = "DEEPSEEK_API_KEY";
 
+// WORM-flag: if optimizeSystemPrompt ever detects that its blind-replace
+// logic has accidentally truncated the trellis `<workflow-state>` block
+// (or any structural marker from an upstream extension), we flip this.
+// publishStatus reads it once, appends a footer warning, then resets it.
+// The flag surface is kept separate from the regular cache-stats counter
+// so that a one-turn glitch doesn't poison the persisted metrics.
+let promptTruncationDetected = false;
+
+// Minimum count of skills before compression is worth applying.
+// Below this, pi's verbose XML block is small enough that the overhead of
+// an additional one-line index isn't worth the loss of per-skill
+// description hints. The 31-skill snapshot in this repo was 13.3 KB; one
+// or two skills is well under 1 KB and not worth touching.
+const SKILL_COMPRESSION_MIN_COUNT = 4;
+
+// Minimum trimmed length for a candidate to qualify as a stable-prefix "part".
+//
+// `optimizeSystemPrompt` removes each accepted candidate from the dynamic
+// remainder via `rest.replace(part, "")`. Short or character-class candidates
+// (think: `S`, `- u`, `- (`, `- }`) match the FIRST occurrence of those bytes
+// anywhere in `rest`, ripping unrelated text out of the prompt and yielding a
+// non-deterministic dynamic remainder per request. Both behaviors poison the
+// provider's prompt-prefix cache.
+//
+// The threshold also caps the upstream string-vs-array regression we saw with
+// trellis 0.5.16 / 0.6.0-beta.17 (subagent tool registration passing
+// `promptGuidelines: "<long string>"` instead of `["<long string>"]`, which
+// pi then iterates char-by-char). Even if a similar bug recurs upstream, this
+// extension will not lift its single-character byproducts into the stable
+// prefix candidate list.
+//
+// 8 chars is comfortably above all single-bullet (`- X` = 3 chars) and
+// short-token noise while leaving every legitimate guideline / tool snippet /
+// context-file payload above the bar. If a real future guideline is shorter
+// than 8 chars, the cost is that it is not lifted into the stable prefix; the
+// dynamic-remainder path still includes it untouched.
+const MIN_STABLE_CANDIDATE_LENGTH = 8;
+
 const ASSISTANT_MESSAGE_MODEL_TOKEN_KEYS = ["model", "name"];
 const OPENAI_REASONING_MODEL_PATTERN = /(^|[/\s:_-])o[1345]($|[-_.:/\s])/;
 
@@ -143,6 +182,121 @@ function formatSkillsForPrompt(skills: NonNullable<BuildSystemPromptOptions["ski
   return lines.join("\n");
 }
 
+/**
+ * Compressed alternative to `formatSkillsForPrompt`.
+ *
+ * Pi emits a four-line XML block per skill (`<name>`, `<description>`,
+ * `<location>`) plus a three-sentence preamble. With 31 skills active in
+ * this repo that block measured 13.3 KB — 61.5 % of the total system
+ * prompt. The full description text matters when the model has to decide
+ * which skill to load, but the model can read SKILL.md on demand: the
+ * names alone plus a known location pattern is enough to identify
+ * candidates.
+ *
+ * This compressed form preserves:
+ *   1. The instruction to read SKILL.md when a task matches a skill name.
+ *   2. The relative-path resolution rule (parent of SKILL.md is the
+ *      skill directory).
+ *   3. Discoverability of every skill: name + location prefix per skill.
+ *
+ * It drops:
+ *   - Per-skill description text (model loads it via `read` when a name
+ *     matches a task).
+ *   - The `<available_skills>` XML envelope and per-skill XML overhead
+ *     (~110 bytes per skill of pure structure, plus the location path).
+ *
+ * Output shape is a single text block grouped by skill-root directory so
+ * the model can compute each skill's full path by name. Names are sorted
+ * alphabetically within each group for determinism (cache stability).
+ */
+function formatSkillsForPromptCompressed(
+  skills: NonNullable<BuildSystemPromptOptions["skills"]>,
+): string {
+  const visibleSkills = skills.filter((skill) => !skill.disableModelInvocation);
+  if (visibleSkills.length === 0) return "";
+
+  const groups = new Map<string, string[]>();
+  for (const skill of visibleSkills) {
+    // skill.filePath = .../<skill-name>/SKILL.md, so dirname is the
+    // skill directory and dirname-of-dirname is the skills root.
+    const skillDir = dirname(skill.filePath);
+    const root = dirname(skillDir);
+    const list = groups.get(root) ?? [];
+    list.push(skill.name);
+    groups.set(root, list);
+  }
+
+  // Sort group entries by root for determinism: same skill set under the
+  // same roots must always produce the same string, otherwise the
+  // provider prompt-prefix cache loses on prompt builder runs that
+  // happened to iterate the underlying Map in different orders.
+  const sortedGroups = [...groups.entries()].sort(([a], [b]) =>
+    a < b ? -1 : a > b ? 1 : 0,
+  );
+
+  const lines: string[] = [
+    "",
+    "",
+    "The following skills provide specialized instructions for specific tasks. When a skill name matches the task you are doing, read the SKILL.md at the listed location to load the full instructions. When a SKILL.md references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
+  ];
+
+  for (const [root, names] of sortedGroups) {
+    names.sort();
+    lines.push("");
+    lines.push(`Skills under ${root}/<name>/SKILL.md:`);
+    // Wrap the name list at ~80 columns for readability without
+    // affecting determinism. Each line is `  name1, name2, name3,`.
+    let buf = "  ";
+    for (let i = 0; i < names.length; i++) {
+      const name = names[i];
+      const piece = (buf === "  " ? "" : ", ") + name;
+      if (buf.length > 2 && buf.length + piece.length > 80) {
+        lines.push(`${buf},`);
+        buf = `  ${name}`;
+      } else {
+        buf += piece;
+      }
+    }
+    if (buf.length > 2) lines.push(buf);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Replace pi's verbose `<available_skills>` block in `prompt` with the
+ * compressed one-index form. Idempotent: if the verbose form is not
+ * present (compression already applied, or skill count below threshold),
+ * the prompt is returned unchanged.
+ *
+ * Opt-out: set `PI_CACHE_OPTIMIZER_NO_SKILL_COMPRESSION=1`.
+ *
+ * Pre-conditions for compression to fire:
+ *   - opts.skills present and visible-skill count >= SKILL_COMPRESSION_MIN_COUNT
+ *   - Verbose block (built from the same `opts.skills`) is found in
+ *     `prompt` (substring match, no regex). This anchors the substitution
+ *     to pi's own emitter; if pi changes the format, we no-op rather
+ *     than mangle.
+ */
+function compressSkillsInSystemPrompt(
+  prompt: string,
+  opts: BuildSystemPromptOptions,
+): string {
+  if (isEnabledEnv(process.env[NO_SKILL_COMPRESSION_ENV])) return prompt;
+  if (!opts.skills || opts.skills.length === 0) return prompt;
+
+  const visible = opts.skills.filter((skill) => !skill.disableModelInvocation);
+  if (visible.length < SKILL_COMPRESSION_MIN_COUNT) return prompt;
+
+  const verbose = formatSkillsForPrompt(opts.skills);
+  if (!verbose || !prompt.includes(verbose)) return prompt;
+
+  const compressed = formatSkillsForPromptCompressed(opts.skills);
+  if (!compressed || compressed.length >= verbose.length) return prompt;
+
+  return prompt.replace(verbose, compressed);
+}
+
 function buildStableCandidates(opts: BuildSystemPromptOptions): string[] {
   const candidates: string[] = [];
 
@@ -172,12 +326,67 @@ function buildStableCandidates(opts: BuildSystemPromptOptions): string[] {
   }
 
   if (opts.skills && opts.skills.length > 0) {
+    // Push BOTH forms so `optimizeSystemPrompt` finds whichever is
+    // actually present in the prompt. The `rest.includes(part)`
+    // short-circuit skips the form that isn't there. The two strings
+    // are mutually distinguishable (the verbose form contains the
+    // literal `<available_skills>` envelope; the compressed form
+    // contains `Skills under ` and no XML tags) so they cannot
+    // accidentally match each other.
     candidates.push(formatSkillsForPrompt(opts.skills));
+    candidates.push(formatSkillsForPromptCompressed(opts.skills));
   }
 
   return candidates;
 }
 
+/**
+ * Strip per-turn churn from trellis `<session-overview>` block.
+ *
+ * Trellis injects a session-overview that includes `RECENT COMMITS`
+ * (shifts on every git commit), `Working directory: Clean/N uncommitted`
+ * (shifts on every edit/commit), and `Line count: N / 2000` (shifts on
+ * every journal append). These fields are at the tail of the
+ * session-overview and poison the prompt-prefix cache for everything
+ * that follows.
+ *
+ * This function surgically removes those three churn fields from the
+ * `<session-overview>...</session-overview>` block. The remaining
+ * fields (DEVELOPER, GIT STATUS branch-only, CURRENT TASK, ACTIVE
+ * TASKS, MY TASKS, JOURNAL FILE active-file-only, PACKAGES, PATHS)
+ * are stable within a session and become cache-friendlier.
+ *
+ * No-op when the `<session-overview>` tag is not present (e.g.
+ * trellis hook chose not to inject it, or a different extension
+ * owns the prompt).
+ */
+function stripSessionOverviewChurn(prompt: string): string {
+  const startTag = "<session-overview>";
+  const endTag = "</session-overview>";
+
+  const startIdx = prompt.indexOf(startTag);
+  if (startIdx === -1) return prompt;
+
+  const endIdx = prompt.indexOf(endTag, startIdx + startTag.length);
+  if (endIdx === -1) return prompt;
+
+  const before = prompt.slice(0, startIdx + startTag.length);
+  const inner = prompt.slice(startIdx + startTag.length, endIdx);
+  const after = prompt.slice(endIdx);
+
+  let cleaned = inner
+    // Drop the RECENT COMMITS section (from the heading through the
+    // next heading or end of inner). The model sees commit history
+    // via `git log`; carrying it in every system prompt is redundant.
+    .replace(/\n## RECENT COMMITS\n[\s\S]*?(?=\n## |$)/, "")
+    // Drop "Working directory: ..." (Git status tail churn).
+    .replace(/\nWorking directory:[^\n]*/g, "")
+    // Drop "Line count: N / NNNN" (Journal tail churn).
+    .replace(/\nLine count:[^\n]*/g, "");
+
+  return before + cleaned + after;
+}
+
 function optimizeSystemPrompt(
   original: string,
   opts: BuildSystemPromptOptions,
@@ -187,9 +396,11 @@ function optimizeSystemPrompt(
   let rest = original;
 
   // Stable layer: content likely to be identical across sessions/turns.
+  // Short / single-char candidates are dropped: see MIN_STABLE_CANDIDATE_LENGTH.
   for (const candidate of buildStableCandidates(opts)) {
     const part = candidate.trim();
-    if (!part || seen.has(part) || !rest.includes(part)) continue;
+    if (!part || part.length < MIN_STABLE_CANDIDATE_LENGTH) continue;
+    if (seen.has(part) || !rest.includes(part)) continue;
 
     stableParts.push(part);
     seen.add(part);
@@ -205,10 +416,27 @@ function optimizeSystemPrompt(
     return { systemPrompt: original, stablePrefix: "", changed: false };
   }
 
+  const systemPrompt =
+    stablePrefix +
+    (dynamicRemainder.length > 0 ? "\n\n---\n\n" + dynamicRemainder : "");
+
+  // Sanity check: if trellis (or another extension) injected structural
+  // markers into the prompt that happen to share a substring with one of
+  // our stable candidates, the blind `rest.replace(part, "")` could
+  // silently eat part of the dynamic layer. We anchor on
+  // `<workflow-state>` because it is the most stable structural marker
+  // trellis emits and is never a stable candidate itself.
+  //
+  // When the marker was present in the original but is missing in the
+  // result, the reorder is unsafe — fall back to the original prompt
+  // so the model gets a complete prompt, and flag the footer warning.
+  if (original.includes("<workflow-state>") && !systemPrompt.includes("<workflow-state>")) {
+    promptTruncationDetected = true;
+    return { systemPrompt: original, stablePrefix: "", changed: false };
+  }
+
   return {
-    systemPrompt:
-      stablePrefix +
-      (dynamicRemainder.length > 0 ? "\n\n---\n\n" + dynamicRemainder : ""),
+    systemPrompt,
     stablePrefix,
     changed: true,
   };
@@ -1005,6 +1233,20 @@ function emitDeepseekApiKeyHintIfNeeded(
   );
 }
 
+// Internal helpers exported only so the task verification script
+// (.trellis/tasks/.../verify.ts) can exercise them. They are not part of the
+// extension's public API; pi only invokes the default export below.
+export const __internals_for_tests = {
+  buildStableCandidates,
+  optimizeSystemPrompt,
+  stripSessionOverviewChurn,
+  formatSkillsForPrompt,
+  formatSkillsForPromptCompressed,
+  compressSkillsInSystemPrompt,
+  MIN_STABLE_CANDIDATE_LENGTH,
+  SKILL_COMPRESSION_MIN_COUNT,
+};
+
 export default function (pi: ExtensionAPI) {
   const warnedModels = new Set<string>();
   let cacheStatsByProvider: Partial<Record<CacheProviderId, CacheStats>> = emptyAllCacheStats();
@@ -1086,7 +1328,17 @@ export default function (pi: ExtensionAPI) {
     await rollOverStatsIfNeeded(ctx);
 
     const adapter = selectAdapterForModel(model);
-    const statusText = adapter ? formatCacheStats(adapter, getStatsForAdapter(adapter)) : undefined;
+    let statusText: string | undefined = adapter ? formatCacheStats(adapter, getStatsForAdapter(adapter)) : undefined;
+
+    // If optimizeSystemPrompt detected structural truncation on this or
+    // a recent turn, flag it once in the footer so the user knows to
+    // /reload before continuing. The flag resets after emission so a
+    // single-turn glitch does not permanently taint the footer.
+    if (promptTruncationDetected && statusText !== undefined) {
+      statusText = statusText + " ⚠️ integrity";
+      promptTruncationDetected = false;
+    }
+
     if (statusText === lastStatusText) return;
 
     lastStatusText = statusText;
@@ -1111,13 +1363,45 @@ export default function (pi: ExtensionAPI) {
   });
 
   pi.on("before_agent_start", async (event, _ctx) => {
-    const optimized = optimizeSystemPrompt(event.systemPrompt, event.systemPromptOptions);
+    // Step 1: strip per-turn churn from <session-overview>.
+    // Removing RECENT COMMITS, Working directory status, and
+    // Journal line count makes more of the session-overview stable
+    // across turns, which DeepSeek's prefix cache can then retain.
+    const strippedPrompt = stripSessionOverviewChurn(event.systemPrompt);
+
+    // Step 2: compress skills XML → one-line index.
+    // The compressed form is identical-string-equivalent to the
+    // verbose one as far as cache-stability is concerned because both
+    // are deterministic from the same `event.systemPromptOptions.skills`.
+    // No-op if opted out, below SKILL_COMPRESSION_MIN_COUNT, or if pi
+    // emitted a format we don't recognize.
+    const compressedPrompt = compressSkillsInSystemPrompt(
+      strippedPrompt,
+      event.systemPromptOptions,
+    );
+
+    // Step 3: lift stable content above dynamic content for cache
+    // stability. Operates on the (stripped + compressed) prompt so the
+    // cache key derived from `stablePrefix` reflects what actually
+    // ships to the provider.
+    const optimized = optimizeSystemPrompt(compressedPrompt, event.systemPromptOptions);
     latestPromptCacheKey = buildPromptCacheKey(optimized.stablePrefix);
 
     if (optimized.changed && optimized.systemPrompt.trim().length > 0) {
       return { systemPrompt: optimized.systemPrompt };
     }
 
+    // Reorder didn't apply but compression might have. Return the
+    // compressed (or stripped) prompt directly so we still benefit from
+    // the volume cut even when reorder is a no-op (e.g., short sessions
+    // where no stable candidate is long enough).
+    if (compressedPrompt !== strippedPrompt && compressedPrompt.trim().length > 0) {
+      return { systemPrompt: compressedPrompt };
+    }
+    if (strippedPrompt !== event.systemPrompt && strippedPrompt.trim().length > 0) {
+      return { systemPrompt: strippedPrompt };
+    }
+
     return {};
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-cache-optimizer",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "Pi extension that improves provider-side KV/prompt cache hit rates (DeepSeek, OpenAI, Claude, Gemini) by reordering the system prompt, requesting long retention, and showing footer cache stats. Renamed from pi-deepseek-cache-optimizer.",
   "keywords": [
     "pi-package",
@@ -16,10 +16,12 @@
   "author": "freescheme",
   "license": "MIT",
   "files": [
-    "extension.ts"
+    "index.ts"
   ],
   "pi": {
-    "extensions": ["./extension.ts"],
+    "extensions": [
+      "./index.ts"
+    ],
     "image": "https://img.shields.io/badge/Pi-Cache%20Optimizer-4A90D9"
   },
   "peerDependencies": {
@@ -27,6 +29,6 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/jiangge/pi-deepseek-cache-optimizer.git"
+    "url": "git+https://github.com/jiangge/pi-cache-optimizer.git"
   }
 }