@pi-unipi/unipi 2.4.2 → 2.6.0

package/packages/updater/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/updater",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "description": "Auto-updater, changelog browser, and readme browser for Unipi — checks npm registry, renders CHANGELOG.md and README.md files in TUI overlays",
   "type": "module",
   "main": "index.ts",
@@ -34,7 +34,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.4.1"
+    "@pi-unipi/core": "2.6.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.80.0",

package/packages/utility/README.md

@@ -16,6 +16,7 @@ The diff rendering is the standout feature — Shiki-powered syntax-highlighted
 | `/unipi:name-badge` | Toggle name badge overlay |
 | `/unipi:badge-gen` | Generate session name via LLM and enable badge |
 | `/unipi:util-settings` | Unified settings for badge and diff rendering |
+| `/unipi:prefix-cache` | Show privacy-safe request-prefix transitions and provider cache token counters |
 
 ### Examples
 
@@ -32,6 +33,14 @@ The diff rendering is the standout feature — Shiki-powered syntax-highlighted
 
 Utility registers with the info-screen dashboard, showing module status and diagnostic results. The footer subscribes to utility events for its extension status segment.
 
+## Provider prefix-cache diagnostics
+
+`/unipi:prefix-cache` observes Pi's provider-native request payloads without modifying them. It reports session-local cache epochs, exact structural prefix extensions, retries, request-envelope/history boundaries, and provider-reported `cacheRead`/`cacheWrite` token totals.
+
+The fingerprints are keyed HMAC-SHA-256 values using a random in-memory key that is discarded on reload. Raw prompts, messages, tool arguments, tool schemas, and provider payloads are never retained or logged by this diagnostic. Fingerprints therefore cannot be compared across process lifetimes. A reported prefix extension means the request is structurally eligible for reuse; provider TTL, routing, and cache policy still decide whether a hit occurs.
+
+`/unipi:cleanup` includes private `~/.unipi/tool-results/` artifacts in the normal temporary-file retention policy (7 days by default). Use dry-run mode to review candidates before deletion.
+
 The diff rendering feature wraps Pi's built-in `write` and `edit` tools. When enabled, these tools show syntax-highlighted diffs instead of plain output. This is a transparent replacement — the agent doesn't need to know about it.
 
 ## Agent Tools

package/packages/utility/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/utility",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "description": "Utility commands and tools for Pi coding agent — lifecycle, diagnostics, cache, analytics, display, batch execution",
   "type": "module",
   "main": "src/index.ts",
@@ -36,7 +36,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.4.1",
+    "@pi-unipi/core": "2.6.0",
     "diff": "^7.0.0",
     "shiki": "^4.0.2"
   },

package/packages/utility/src/index.ts

@@ -32,6 +32,7 @@ import { registerEnhancedWriteTool, registerEnhancedEditTool } from "./diff/wrap
 import { getLifecycle } from "./lifecycle/process.js";
 import { getAnalyticsCollector } from "./analytics/collector.js";
 import { registerInfoScreen } from "./info-screen.js";
+import { PrefixCacheTracker, formatPrefixCacheStats } from "./prefix-cache.js";
 
 /** Re-export readBadgeSettings for cross-package use */
 export { readBadgeSettings } from "./tui/badge-settings.js";
@@ -61,6 +62,7 @@ const ALL_COMMANDS = [
   UTILITY_COMMANDS.BADGE_TOGGLE,
   UTILITY_COMMANDS.BADGE_SETTINGS,
   UTILITY_COMMANDS.UTIL_SETTINGS,
+  UTILITY_COMMANDS.PREFIX_CACHE,
 ].map((cmd) => `unipi:${cmd}`);
 
 /** All tools registered by this module */
@@ -73,6 +75,52 @@ export default function (pi: ExtensionAPI) {
   // Initialize analytics collector
   const analytics = getAnalyticsCollector();
 
+  // Session-local provider prefix observability. The random HMAC key and all
+  // payload-derived fingerprints remain in memory and are discarded on reload.
+  const prefixCache = new PrefixCacheTracker();
+  pi.registerCommand(`unipi:${UTILITY_COMMANDS.PREFIX_CACHE}`, {
+    description: "Show privacy-safe provider prefix-cache diagnostics",
+    handler: async (_args, ctx) => {
+      const report = formatPrefixCacheStats(prefixCache.getSnapshot());
+      if (ctx.hasUI) {
+        ctx.ui.notify(report, "info");
+      } else {
+        pi.sendMessage({ customType: "unipi-response", content: report, display: true }, { deliverAs: "followUp" });
+      }
+    },
+  });
+
+  pi.on("session_start", () => {
+    // A replacement/reloaded session has a distinct provider prefix lineage.
+    // The extension factory is normally recreated, but reset explicitly so
+    // custom hosts that reuse one factory cannot leak counts across sessions.
+    prefixCache.reset();
+  });
+
+  pi.on("before_provider_request", (event, ctx) => {
+    prefixCache.observeRequest(event.payload, ctx.model);
+    // Observe only: never replace or mutate provider payloads.
+  });
+
+  pi.on("agent_end", (event) => {
+    prefixCache.observeMessages(event.messages);
+  });
+
+  pi.on("model_select", (event) => {
+    if (event.previousModel && (
+      event.previousModel.provider !== event.model.provider ||
+      event.previousModel.id !== event.model.id ||
+      event.previousModel.api !== event.model.api
+    )) {
+      prefixCache.markBoundary("envelope_changed");
+    }
+  });
+  pi.on("thinking_level_select", (event) => {
+    if (event.previousLevel !== event.level) prefixCache.markBoundary("envelope_changed");
+  });
+  pi.on("session_compact", () => prefixCache.markBoundary("history_rewritten"));
+  pi.on("session_tree", () => prefixCache.markBoundary("history_rewritten"));
+
   // Register cleanup on shutdown
   lifecycle.registerCleanup(async () => {
     analytics.disable();

package/packages/utility/src/lifecycle/cleanup.ts

@@ -121,6 +121,34 @@ function cleanDbs(options: Required<CleanupOptions>): CleanupResult {
   return result;
 }
 
+/** Clean private tool-result artifacts after the configured temp retention. */
+function cleanToolResults(options: Required<CleanupOptions>): CleanupResult {
+  const result: CleanupResult = {
+    category: "tool-results",
+    removed: 0,
+    bytesFreed: 0,
+    paths: [],
+  };
+  const dir = expandHome("~/.unipi/tool-results");
+  if (!existsSync(dir)) return result;
+
+  let entries: string[];
+  try { entries = readdirSync(dir); } catch { return result; }
+  for (const entry of entries) {
+    if (!/^(?:tool-result|mcp-[a-zA-Z0-9_-]+|helper)-[a-f0-9-]+\.txt$/.test(entry)) continue;
+    const path = join(dir, entry);
+    try {
+      const stats = statSync(path);
+      if (!stats.isFile() || !isStale(path, options.tempMaxAgeDays)) continue;
+      result.paths.push(path);
+      result.bytesFreed += stats.size;
+      if (!options.dryRun) unlinkSync(path);
+      result.removed++;
+    } catch { /* best effort */ }
+  }
+  return result;
+}
+
 /** Clean temp files matching unipi patterns */
 function cleanTemps(options: Required<CleanupOptions>): CleanupResult {
   const result: CleanupResult = {
@@ -288,6 +316,7 @@ export function cleanupStale(options: CleanupOptions = {}): CleanupReport {
   const results: CleanupResult[] = [
     cleanDbs(opts),
     cleanTemps(opts),
+    cleanToolResults(opts),
     cleanSessions(opts),
     cleanCache(opts),
   ];

package/packages/utility/src/prefix-cache.ts

@@ -0,0 +1,263 @@
+import { createHmac, randomBytes } from "node:crypto";
+
+export type PrefixTransition =
+  | "first_request"
+  | "prefix_extended"
+  | "identical_retry"
+  | "envelope_changed"
+  | "history_rewritten"
+  | "payload_shape_changed";
+
+export interface PrefixCacheSnapshot {
+  epoch: number;
+  requests: number;
+  prefixExtensions: number;
+  identicalRetries: number;
+  boundaries: number;
+  lastTransition: PrefixTransition | "none";
+  requestFingerprint: string;
+  envelopeFingerprint: string;
+  sequenceField: string;
+  sequenceItems: number;
+  route: string;
+  usage: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    responses: number;
+  };
+}
+
+interface ObservedRequest {
+  envelopeFingerprint: string;
+  requestFingerprint: string;
+  sequenceField: string;
+  sequenceItemFingerprints: string[];
+}
+
+const EMPTY_SNAPSHOT: PrefixCacheSnapshot = {
+  epoch: 0,
+  requests: 0,
+  prefixExtensions: 0,
+  identicalRetries: 0,
+  boundaries: 0,
+  lastTransition: "none",
+  requestFingerprint: "none",
+  envelopeFingerprint: "none",
+  sequenceField: "none",
+  sequenceItems: 0,
+  route: "unknown",
+  usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, responses: 0 },
+};
+
+function canonicalize(value: unknown, seen = new WeakSet<object>()): unknown {
+  if (value === undefined) return { $type: "undefined" };
+  if (typeof value === "bigint") return { $type: "bigint", value: value.toString() };
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    return { $type: "number", value: String(value) };
+  }
+  if (typeof value !== "object" || value === null) return value;
+  if (seen.has(value)) return { $type: "cycle" };
+  seen.add(value);
+
+  if (Array.isArray(value)) {
+    const result = value.map((item) => canonicalize(item, seen));
+    seen.delete(value);
+    return result;
+  }
+
+  if (value instanceof Uint8Array) {
+    seen.delete(value);
+    return { $type: "bytes", length: value.byteLength };
+  }
+
+  const record = value as Record<string, unknown>;
+  const result: Record<string, unknown> = {};
+  for (const key of Object.keys(record).sort((a, b) => a < b ? -1 : a > b ? 1 : 0)) {
+    result[key] = canonicalize(record[key], seen);
+  }
+  seen.delete(value);
+  return result;
+}
+
+function canonicalJson(value: unknown): string {
+  return JSON.stringify(canonicalize(value));
+}
+
+function routeLabel(model: unknown): string {
+  if (!model || typeof model !== "object") return "unknown";
+  const value = model as Record<string, unknown>;
+  return [value.provider, value.id, value.api]
+    .filter((part): part is string => typeof part === "string" && part.length > 0)
+    .join("/") || "unknown";
+}
+
+function findSequence(payload: Record<string, unknown>): { field: string; items: unknown[] } {
+  for (const field of ["messages", "input", "contents"] as const) {
+    if (Array.isArray(payload[field])) return { field, items: payload[field] as unknown[] };
+  }
+  return { field: "none", items: [] };
+}
+
+function isPrefix(previous: string[], current: string[]): boolean {
+  return previous.length <= current.length && previous.every((item, index) => current[index] === item);
+}
+
+function usageNumber(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+/**
+ * Session-local, privacy-safe prefix observability.
+ *
+ * Prompt/tool bytes are only canonicalized transiently. The tracker retains
+ * keyed HMACs and counters, never raw provider payloads. Its random key is not
+ * persisted, so fingerprints cannot be correlated across process lifetimes or
+ * used as a precomputed dictionary oracle.
+ */
+export class PrefixCacheTracker {
+  private readonly key: Uint8Array;
+  private previous: ObservedRequest | null = null;
+  private seenResponses = new WeakSet<object>();
+  private snapshot: PrefixCacheSnapshot = structuredClone(EMPTY_SNAPSHOT);
+
+  constructor(key: Uint8Array = randomBytes(32)) {
+    this.key = key;
+  }
+
+  reset(): void {
+    this.previous = null;
+    this.seenResponses = new WeakSet<object>();
+    this.snapshot = structuredClone(EMPTY_SNAPSHOT);
+  }
+
+  private fingerprint(value: unknown): string {
+    return createHmac("sha256", this.key).update(canonicalJson(value)).digest("hex").slice(0, 16);
+  }
+
+  observeRequest(payload: unknown, model?: unknown): PrefixCacheSnapshot {
+    const object = payload && typeof payload === "object" && !Array.isArray(payload)
+      ? payload as Record<string, unknown>
+      : { payload };
+    const { field, items } = findSequence(object);
+    const route = routeLabel(model);
+    const envelope: Record<string, unknown> = { route };
+    for (const [key, value] of Object.entries(object)) {
+      if (key !== field) envelope[key] = value;
+    }
+
+    const current: ObservedRequest = {
+      envelopeFingerprint: this.fingerprint(envelope),
+      requestFingerprint: this.fingerprint(object),
+      sequenceField: field,
+      sequenceItemFingerprints: items.map((item) => this.fingerprint(item)),
+    };
+
+    let transition: PrefixTransition;
+    let epoch = this.snapshot.epoch;
+    if (!this.previous) {
+      transition = "first_request";
+      epoch = Math.max(1, epoch);
+    } else if (
+      current.envelopeFingerprint !== this.previous.envelopeFingerprint
+    ) {
+      transition = "envelope_changed";
+      epoch++;
+    } else if (current.sequenceField !== this.previous.sequenceField) {
+      transition = "payload_shape_changed";
+      epoch++;
+    } else if (current.requestFingerprint === this.previous.requestFingerprint) {
+      transition = "identical_retry";
+    } else if (isPrefix(this.previous.sequenceItemFingerprints, current.sequenceItemFingerprints)) {
+      transition = "prefix_extended";
+    } else {
+      transition = "history_rewritten";
+      epoch++;
+    }
+
+    this.snapshot = {
+      ...this.snapshot,
+      epoch,
+      requests: this.snapshot.requests + 1,
+      prefixExtensions: this.snapshot.prefixExtensions + (transition === "prefix_extended" ? 1 : 0),
+      identicalRetries: this.snapshot.identicalRetries + (transition === "identical_retry" ? 1 : 0),
+      boundaries: this.snapshot.boundaries + (
+        transition === "envelope_changed" || transition === "history_rewritten" || transition === "payload_shape_changed"
+          ? 1
+          : 0
+      ),
+      lastTransition: transition,
+      requestFingerprint: current.requestFingerprint,
+      envelopeFingerprint: current.envelopeFingerprint,
+      sequenceField: current.sequenceField,
+      sequenceItems: current.sequenceItemFingerprints.length,
+      route,
+    };
+    this.previous = current;
+    return this.getSnapshot();
+  }
+
+  observeMessages(messages: unknown[]): PrefixCacheSnapshot {
+    for (const message of messages) {
+      if (!message || typeof message !== "object") continue;
+      const value = message as Record<string, unknown>;
+      if (value.role !== "assistant" || !value.usage || typeof value.usage !== "object") continue;
+      if (value.stopReason === "error" || value.stopReason === "aborted") continue;
+
+      // agent_end can expose the whole active context repeatedly. Deduplicate
+      // exact message objects by identity; two genuinely distinct provider
+      // responses with identical content/usage must still both count.
+      if (this.seenResponses.has(message as object)) continue;
+      this.seenResponses.add(message as object);
+
+      const usage = value.usage as Record<string, unknown>;
+      this.snapshot.usage.input += usageNumber(usage.input);
+      this.snapshot.usage.output += usageNumber(usage.output);
+      this.snapshot.usage.cacheRead += usageNumber(usage.cacheRead);
+      this.snapshot.usage.cacheWrite += usageNumber(usage.cacheWrite);
+      this.snapshot.usage.responses++;
+    }
+    return this.getSnapshot();
+  }
+
+  markBoundary(transition: Extract<PrefixTransition, "history_rewritten" | "envelope_changed">): void {
+    // Lifecycle events can identify a boundary before the next payload arrives.
+    // Drop the comparison baseline so the next request starts a fresh observed
+    // epoch rather than being misclassified against pre-boundary history.
+    if (this.previous) {
+      this.snapshot.epoch++;
+      this.snapshot.boundaries++;
+    }
+    this.snapshot.lastTransition = transition;
+    this.previous = null;
+  }
+
+  getSnapshot(): PrefixCacheSnapshot {
+    return structuredClone(this.snapshot);
+  }
+}
+
+export function formatPrefixCacheStats(snapshot: PrefixCacheSnapshot): string {
+  const usage = snapshot.usage;
+  const totalPrompt = usage.input + usage.cacheRead + usage.cacheWrite;
+  const readRate = totalPrompt > 0 ? `${((usage.cacheRead / totalPrompt) * 100).toFixed(1)}%` : "n/a";
+  return [
+    "## Provider Prefix Cache",
+    "",
+    `- Epoch: ${snapshot.epoch || "not observed"}`,
+    `- Requests observed: ${snapshot.requests}`,
+    `- Prefix extensions: ${snapshot.prefixExtensions}`,
+    `- Explicit boundaries: ${snapshot.boundaries}`,
+    `- Last transition: ${snapshot.lastTransition}`,
+    `- Route: ${snapshot.route}`,
+    `- Request fingerprint: ${snapshot.requestFingerprint}`,
+    `- Envelope fingerprint: ${snapshot.envelopeFingerprint}`,
+    `- Provider cache read: ${usage.cacheRead} tokens`,
+    `- Provider cache write: ${usage.cacheWrite} tokens`,
+    `- Observed cache-read share: ${readRate}`,
+    "",
+    "Fingerprints are session-local keyed HMACs. Raw prompts, messages, tool arguments, and payloads are not retained or logged.",
+    "A prefix extension indicates structural eligibility only; provider cache retention and routing still determine actual hits.",
+  ].join("\n");
+}

package/packages/utility/src/types.ts

@@ -227,7 +227,7 @@ export interface EnvironmentInfo {
 /** Result of a cleanup operation */
 export interface CleanupResult {
   /** What was cleaned */
-  category: "db" | "temp" | "session" | "cache" | "log";
+  category: "db" | "temp" | "tool-results" | "session" | "cache" | "log";
   /** Items removed */
   removed: number;
   /** Bytes freed (approximate) */

package/packages/web-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/web-api",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "description": "Web search, read, and summarize tools with provider-based backend selection for Pi coding agent",
   "type": "module",
   "main": "src/index.ts",
@@ -31,7 +31,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@pi-unipi/core": "2.4.1",
+    "@pi-unipi/core": "2.6.0",
     "defuddle": "^0.18.1",
     "linkedom": "^0.18.12",
     "lodash": "^4.17.21",

package/packages/workflow/README.md

@@ -128,6 +128,14 @@ Skills define:
 
 The agent reads the skill, executes the steps, and produces artifacts in the `.unipi/` directory.
 
+## Workflow Sandbox
+
+Each workflow activates a command-specific sandbox for the duration of its agent run. The sandbox blocks disallowed tool calls by name (for example, `write`, `edit`, or `bash` in read-only workflows) without changing Pi's active tool list. Keeping the provider tool schemas and their order unchanged makes the workflow prefix cache-stable.
+
+Sandbox instructions are stored as hidden, append-only `unipi-workflow-sandbox-snapshot` messages rather than being injected into the system prompt. An active snapshot explicitly supersedes older snapshots. After the workflow completes at `agent_end`, the next agent start appends an inactive snapshot when needed so stale restrictions no longer apply. Sessions that have never activated a workflow do not receive a marker.
+
+The sandbox preserves the existing command-level semantics; skill instructions still define narrower write locations and setup-only shell usage where applicable.
+
 ## Directory Structure
 
 ```

package/packages/workflow/commands.ts

@@ -8,7 +8,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { readFileSync, readdirSync, existsSync, statSync } from "fs";
 import { join, basename } from "path";
-import { UNIPI_PREFIX, WORKFLOW_COMMANDS, getToolsForCommand, getSandboxLevel, type SandboxLevel, type UnipiWorkflowEvent } from "@pi-unipi/core";
+import { UNIPI_PREFIX, WORKFLOW_COMMANDS, type UnipiWorkflowEvent } from "@pi-unipi/core";
 
 type CompletionItem = { value: string; label: string; description: string };
 
@@ -16,14 +16,10 @@ type CompletionItem = { value: string; label: string; description: string };
 export interface WorkflowCommandOptions {
   /** Check if ralph module is detected */
   isRalphDetected: () => boolean;
-  /** Get current active tool names */
-  getActiveTools: () => string[];
-  /** Set active tools with sandbox level */
-  setActiveTools: (tools: string[], level: SandboxLevel) => void;
-  /** Save tools for later restore */
-  saveTools: (tools: string[]) => void;
-  /** Begin one workflow lifecycle; false means another workflow is active. */
-  startWorkflow: (event: UnipiWorkflowEvent) => boolean;
+  /** Begin one workflow lifecycle and activate its sandbox. */
+  activateSandbox: (event: UnipiWorkflowEvent) => boolean;
+  /** Roll back lifecycle and sandbox state after dispatch failure. */
+  abortWorkflow: () => void;
 }
 
 /** Command definition */
@@ -409,19 +405,12 @@ export function registerWorkflowCommands(
           fullCommand: `/${fullCommand}`,
           args: args?.trim() ?? "",
         };
-        if (!options.startWorkflow(workflowEvent)) {
+        if (!options.activateSandbox(workflowEvent)) {
           if (ctx.hasUI) ctx.ui.notify("Another UniPi workflow is still active", "warning");
           return;
         }
 
-        // Apply sandbox — save current tools, set command's tools
-        const currentTools = options.getActiveTools();
-        options.saveTools(currentTools);
-        const sandboxTools = getToolsForCommand(cmd.name, currentTools);
-        const sandboxLevel = getSandboxLevel(cmd.name);
-        options.setActiveTools([...sandboxTools], sandboxLevel);
-
-        // Load skill content from SKILL.md
+        // Load skill content from SKILL.md.
         let skillContent = "";
         try {
           const skillPath = join(
@@ -431,33 +420,34 @@ export function registerWorkflowCommands(
           );
           skillContent = readFileSync(skillPath, "utf-8");
         } catch {
-          // Skill file not found — continue without it
+          // Skill file not found — continue without it.
         }
 
-        // Build skill invocation message
         let message = `Execute the ${cmd.skillName} workflow.`;
 
-        // Add args if provided
         if (args?.trim()) {
           message += `\n\nArguments: ${args.trim()}`;
         }
 
-        // Add ralph hint if applicable
         if (cmd.ralphHint && options.isRalphDetected()) {
           message += `\n\n💡 ${cmd.ralphHint}`;
         }
 
-        // Inject skill content as context
         if (skillContent) {
           message += `\n\n<skill_content>\n${skillContent}\n</skill_content>`;
         }
 
-        // Send as user message to trigger skill processing
-        pi.sendUserMessage(message, { deliverAs: "followUp" });
+        // Any synchronous dispatch failure must not leave a phantom workflow
+        // lifecycle or sandbox behind.
+        try {
+          pi.sendUserMessage(message, { deliverAs: "followUp" });
+        } catch (error) {
+          options.abortWorkflow();
+          throw error;
+        }
 
         if (ctx.hasUI) {
           ctx.ui.notify(`Running /${fullCommand}`, "info");
-          // Update extension status with active command name
           const ralphStatus = options.isRalphDetected() ? "✓ rl" : "○ rl";
           ctx.ui.setStatus("unipi-workflow", `⚡ wf:${cmd.name} ${ralphStatus}`);
         }