@tt-a1i/openpi 0.4.0 → 0.6.0

package/extensions/model-info/cache-diagnostics.ts

@@ -0,0 +1,220 @@
+import { createHash } from "node:crypto";
+import type { Usage } from "@earendil-works/pi-ai";
+
+export const CACHE_DIAGNOSTICS_CHANNEL = "model-info:cache-diagnostics";
+
+export const CACHE_WARM_MINIMUM_TOKENS = 2_048;
+
+export type CacheSemantics =
+  | "explicit-prefix"
+  | "implicit-best-effort"
+  | "unknown";
+
+export type CacheObservationKind =
+  | "first-turn"
+  | "cold"
+  | "warm"
+  | "partial-hit"
+  | "miss-after-warm-prefix"
+  | "unknown";
+
+export type CacheCorrelation =
+  | "model-change"
+  | "thinking-change"
+  | "tool-surface-change"
+  | "system-prompt-change"
+  | "compaction"
+  | "branch-change";
+
+export interface CacheTurnIdentity {
+  provider: string;
+  modelId: string;
+  thinking: string;
+  toolSurfaceFingerprint: string;
+  systemPromptFingerprint: string;
+}
+
+export interface CacheTurnObservation {
+  turnIndex: number;
+  provider: string;
+  semantics: CacheSemantics;
+  kind: CacheObservationKind;
+  usage: {
+    input: number;
+    cacheRead: number;
+    cacheWrite: number;
+    promptTokens: number;
+  };
+  previousCacheRead: number | null;
+  reprocessedTokens: number | null;
+  correlations: CacheCorrelation[];
+  evidence: "observation";
+  verifiedCause: null;
+  explanation: string;
+}
+
+type TurnSample = {
+  identity: CacheTurnIdentity;
+  usage: CacheTurnObservation["usage"];
+};
+
+const IMPLICIT_CACHE_PROVIDERS = new Set([
+  "azure-openai-responses",
+  "google",
+  "google-antigravity",
+  "google-gemini-cli",
+  "openai",
+  "openai-codex",
+  "openai-responses",
+]);
+
+export function cacheSemanticsForProvider(provider: string): CacheSemantics {
+  const normalized = provider.trim().toLowerCase();
+  if (normalized === "anthropic") return "explicit-prefix";
+  if (IMPLICIT_CACHE_PROVIDERS.has(normalized)) return "implicit-best-effort";
+  return "unknown";
+}
+
+export function fingerprintCacheSurface(value: unknown) {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+
+function finiteUsage(value: number) {
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+function promptUsage(usage: Usage): CacheTurnObservation["usage"] {
+  const input = finiteUsage(usage.input);
+  const cacheRead = finiteUsage(usage.cacheRead);
+  const cacheWrite = finiteUsage(usage.cacheWrite);
+  return {
+    input,
+    cacheRead,
+    cacheWrite,
+    promptTokens: input + cacheRead + cacheWrite,
+  };
+}
+
+function identityCorrelations(
+  previous: CacheTurnIdentity,
+  current: CacheTurnIdentity,
+) {
+  const correlations: CacheCorrelation[] = [];
+  if (
+    previous.provider !== current.provider ||
+    previous.modelId !== current.modelId
+  ) {
+    correlations.push("model-change");
+  }
+  if (previous.thinking !== current.thinking) {
+    correlations.push("thinking-change");
+  }
+  if (previous.toolSurfaceFingerprint !== current.toolSurfaceFingerprint) {
+    correlations.push("tool-surface-change");
+  }
+  if (previous.systemPromptFingerprint !== current.systemPromptFingerprint) {
+    correlations.push("system-prompt-change");
+  }
+  return correlations;
+}
+
+function classify(
+  semantics: CacheSemantics,
+  current: CacheTurnObservation["usage"],
+  previous: TurnSample | undefined,
+): Pick<CacheTurnObservation, "kind" | "reprocessedTokens" | "explanation"> {
+  if (!previous) {
+    return {
+      kind: "first-turn",
+      reprocessedTokens: null,
+      explanation:
+        "No prior turn exists, so cache continuity cannot be inferred.",
+    };
+  }
+
+  const previousWarm = previous.usage.cacheRead >= CACHE_WARM_MINIMUM_TOKENS;
+  if (current.cacheRead > 0) {
+    return {
+      kind:
+        current.cacheRead < previous.usage.cacheRead ? "partial-hit" : "warm",
+      reprocessedTokens: null,
+      explanation:
+        current.cacheRead < previous.usage.cacheRead
+          ? "The provider reported a smaller cache read than on the prior turn."
+          : "The provider reported cached prompt tokens on this turn.",
+    };
+  }
+  if (!previousWarm) {
+    return {
+      kind: "cold",
+      reprocessedTokens: null,
+      explanation:
+        "The prior turn had no sufficiently warm prefix, so this cold turn is not an invalidation signal.",
+    };
+  }
+  if (semantics !== "explicit-prefix") {
+    return {
+      kind: "unknown",
+      reprocessedTokens: null,
+      explanation:
+        semantics === "implicit-best-effort"
+          ? "A warm-to-cold transition was observed, but this provider exposes only best-effort cache usage."
+          : "A warm-to-cold transition was observed, but the provider cache contract is unknown.",
+    };
+  }
+  return {
+    kind: "miss-after-warm-prefix",
+    reprocessedTokens: current.input,
+    explanation:
+      "An explicit-prefix provider reported a warm prior turn and zero cache read now; local boundaries are correlations, not verified causes.",
+  };
+}
+
+export function createCacheDiagnosticsTracker() {
+  let previous: TurnSample | undefined;
+  let pendingCorrelations = new Set<CacheCorrelation>();
+
+  const reset = () => {
+    previous = undefined;
+    pendingCorrelations = new Set();
+  };
+
+  const mark = (correlation: CacheCorrelation) => {
+    pendingCorrelations.add(correlation);
+  };
+
+  const observe = (options: {
+    turnIndex: number;
+    identity: CacheTurnIdentity;
+    usage: Usage;
+  }) => {
+    const usage = promptUsage(options.usage);
+    const semantics = cacheSemanticsForProvider(options.identity.provider);
+    const classification = classify(semantics, usage, previous);
+    const correlations = previous
+      ? identityCorrelations(previous.identity, options.identity)
+      : [];
+    for (const pending of pendingCorrelations) correlations.push(pending);
+    const uniqueCorrelations = [...new Set(correlations)];
+
+    const observation: CacheTurnObservation = {
+      turnIndex: options.turnIndex,
+      provider: options.identity.provider,
+      semantics,
+      kind: classification.kind,
+      usage,
+      previousCacheRead: previous?.usage.cacheRead ?? null,
+      reprocessedTokens: classification.reprocessedTokens,
+      correlations: uniqueCorrelations,
+      evidence: "observation",
+      verifiedCause: null,
+      explanation: classification.explanation,
+    };
+
+    previous = { identity: options.identity, usage };
+    pendingCorrelations.clear();
+    return observation;
+  };
+
+  return { mark, observe, reset };
+}

package/extensions/model-info/index.ts

@@ -7,37 +7,17 @@ import {
   MODEL_INFO_CHANNEL,
   REFRESH_CHANNEL,
 } from "../shared/dashboard-state.ts";
+import { createSessionMetricsTracker } from "./session-metrics.ts";
+import {
+  CACHE_DIAGNOSTICS_CHANNEL,
+  createCacheDiagnosticsTracker,
+  fingerprintCacheSurface,
+  type CacheTurnIdentity,
+} from "./cache-diagnostics.ts";
 
 const CHARS_PER_ESTIMATED_TOKEN = 4;
 const LIVE_UPDATE_INTERVAL_MS = 200;
 
-function getSessionMetrics(ctx: ExtensionContext) {
-  let cost = 0;
-  let cacheRead = 0;
-  let promptTokens = 0;
-
-  for (const entry of ctx.sessionManager.getBranch()) {
-    let usage;
-    if (entry.type === "message") {
-      const message = entry.message;
-      if (message.role === "assistant" || message.role === "toolResult") {
-        usage = message.usage;
-      }
-    } else if (entry.type === "compaction" || entry.type === "branch_summary") {
-      usage = entry.usage;
-    }
-    if (!usage) continue;
-    cost += usage.cost.total;
-    cacheRead += usage.cacheRead;
-    promptTokens += usage.input + usage.cacheRead + usage.cacheWrite;
-  }
-
-  return {
-    cost,
-    cachePercent: promptTokens > 0 ? (cacheRead / promptTokens) * 100 : null,
-  };
-}
-
 function estimateContentTokens(characters: number) {
   return Math.ceil(characters / CHARS_PER_ESTIMATED_TOKEN);
 }
@@ -54,6 +34,9 @@ export default function modelInfo(pi: ExtensionAPI) {
   let runContentStreamMs = 0;
   let lastLiveUpdate = 0;
   let currentContext: ExtensionContext | undefined;
+  const sessionMetrics = createSessionMetricsTracker();
+  const cacheDiagnostics = createCacheDiagnosticsTracker();
+  let cacheIdentity: CacheTurnIdentity | undefined;
 
   const publish = () => pi.events.emit(MODEL_INFO_CHANNEL, { ...state });
 
@@ -61,7 +44,6 @@ export default function modelInfo(pi: ExtensionAPI) {
     currentContext = ctx;
     const model = ctx.model;
     const usage = ctx.getContextUsage();
-    const metrics = getSessionMetrics(ctx);
 
     state = {
       ...state,
@@ -72,12 +54,14 @@ export default function modelInfo(pi: ExtensionAPI) {
       contextTokens: usage?.tokens ?? null,
       contextWindow: usage?.contextWindow ?? model?.contextWindow ?? 0,
       contextPercent: usage?.percent ?? null,
-      cachePercent: metrics.cachePercent,
-      cost: metrics.cost,
     };
     publish();
   }
 
+  function syncSessionMetrics(ctx: ExtensionContext) {
+    state = { ...state, ...sessionMetrics.sync(ctx.sessionManager) };
+  }
+
   function resetMessageTracking() {
     contentStreamStart = null;
     lastContentDeltaAt = null;
@@ -97,10 +81,15 @@ export default function modelInfo(pi: ExtensionAPI) {
     runContentTokens = 0;
     runContentStreamMs = 0;
     state = { ...state, tokensPerSecond: null, generating: false };
+    sessionMetrics.reset();
+    cacheDiagnostics.reset();
+    cacheIdentity = undefined;
+    syncSessionMetrics(ctx);
     refresh(ctx);
   });
 
   pi.on("model_select", (event, ctx) => {
+    cacheDiagnostics.mark("model-change");
     state = {
       ...state,
       provider: event.model.provider,
@@ -113,6 +102,7 @@ export default function modelInfo(pi: ExtensionAPI) {
   });
 
   pi.on("thinking_level_select", (event) => {
+    cacheDiagnostics.mark("thinking-change");
     state = { ...state, thinking: event.level };
     publish();
   });
@@ -125,6 +115,17 @@ export default function modelInfo(pi: ExtensionAPI) {
     refresh(ctx);
   });
 
+  pi.on("before_agent_start", (event, ctx) => {
+    const selectedTools = event.systemPromptOptions.selectedTools ?? [];
+    cacheIdentity = {
+      provider: ctx.model?.provider ?? "",
+      modelId: ctx.model?.id ?? "no-model",
+      thinking: ctx.model?.reasoning ? pi.getThinkingLevel() : "off",
+      toolSurfaceFingerprint: fingerprintCacheSurface(selectedTools),
+      systemPromptFingerprint: fingerprintCacheSurface(event.systemPrompt),
+    };
+  });
+
   pi.on("message_start", (event) => {
     if (event.message.role === "assistant") resetMessageTracking();
   });
@@ -213,14 +214,42 @@ export default function modelInfo(pi: ExtensionAPI) {
     refresh(ctx);
   });
 
-  pi.on("turn_end", (_event, ctx) => refresh(ctx));
+  pi.on("turn_end", (event, ctx) => {
+    syncSessionMetrics(ctx);
+    refresh(ctx);
+    // Failed/cancelled responses may carry placeholder zero usage. They do
+    // not establish a cache observation or replace the last valid baseline.
+    if (
+      event.message?.role === "assistant" &&
+      event.message.stopReason !== "error" &&
+      event.message.stopReason !== "aborted" &&
+      cacheIdentity
+    ) {
+      pi.events.emit(
+        CACHE_DIAGNOSTICS_CHANNEL,
+        cacheDiagnostics.observe({
+          turnIndex: event.turnIndex,
+          identity: cacheIdentity,
+          usage: event.message.usage,
+        }),
+      );
+    }
+  });
 
   // Compaction and branch moves rewrite history, so the cached percentage is
   // stale the moment they land. Pi reports unknown occupancy until the next
   // assistant reply, which is the honest state to show.
-  pi.on("session_compact", (_event, ctx) => refresh(ctx));
+  pi.on("session_compact", (_event, ctx) => {
+    cacheDiagnostics.mark("compaction");
+    syncSessionMetrics(ctx);
+    refresh(ctx);
+  });
 
-  pi.on("session_tree", (_event, ctx) => refresh(ctx));
+  pi.on("session_tree", (_event, ctx) => {
+    cacheDiagnostics.mark("branch-change");
+    syncSessionMetrics(ctx);
+    refresh(ctx);
+  });
 
   pi.on("agent_settled", (_event, ctx) => {
     state = { ...state, generating: false };
@@ -230,5 +259,8 @@ export default function modelInfo(pi: ExtensionAPI) {
   pi.on("session_shutdown", () => {
     stopRefreshListener();
     currentContext = undefined;
+    sessionMetrics.reset();
+    cacheDiagnostics.reset();
+    cacheIdentity = undefined;
   });
 }

package/extensions/model-info/session-metrics.ts

@@ -0,0 +1,96 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { Usage } from "@earendil-works/pi-ai";
+
+type SessionMetricsManager = {
+  getSessionId(): string;
+  getLeafId(): string | null;
+  getEntry(id: string): SessionEntry | undefined;
+};
+
+type PrefixMetrics = Readonly<{
+  cost: number;
+  cacheRead: number;
+  promptTokens: number;
+}>;
+
+const EMPTY_PREFIX: PrefixMetrics = Object.freeze({
+  cost: 0,
+  cacheRead: 0,
+  promptTokens: 0,
+});
+
+function getUsage(entry: SessionEntry): Usage | undefined {
+  if (entry.type === "message") {
+    return entry.message.role === "assistant" ||
+      entry.message.role === "toolResult"
+      ? entry.message.usage
+      : undefined;
+  }
+  return entry.type === "compaction" || entry.type === "branch_summary"
+    ? entry.usage
+    : undefined;
+}
+
+function addUsage(prefix: PrefixMetrics, entry: SessionEntry): PrefixMetrics {
+  const usage = getUsage(entry);
+  if (!usage) return prefix;
+  return Object.freeze({
+    cost: prefix.cost + usage.cost.total,
+    cacheRead: prefix.cacheRead + usage.cacheRead,
+    promptTokens:
+      prefix.promptTokens + usage.input + usage.cacheRead + usage.cacheWrite,
+  });
+}
+
+function toMetrics(prefix: PrefixMetrics) {
+  return {
+    cost: prefix.cost,
+    cachePercent:
+      prefix.promptTokens > 0
+        ? (prefix.cacheRead / prefix.promptTokens) * 100
+        : null,
+  };
+}
+
+export function createSessionMetricsTracker() {
+  let sessionId: string | undefined;
+  let prefixes = new Map<string, PrefixMetrics>();
+
+  const reset = () => {
+    sessionId = undefined;
+    prefixes = new Map();
+  };
+
+  const sync = (manager: SessionMetricsManager) => {
+    const nextSessionId = manager.getSessionId();
+    if (sessionId !== nextSessionId) reset();
+    sessionId = nextSessionId;
+
+    const leafId = manager.getLeafId();
+    if (!leafId) return toMetrics(EMPTY_PREFIX);
+
+    const cachedLeaf = prefixes.get(leafId);
+    if (cachedLeaf) return toMetrics(cachedLeaf);
+
+    const suffix: SessionEntry[] = [];
+    let currentId: string | null = leafId;
+    while (currentId && !prefixes.has(currentId)) {
+      const entry = manager.getEntry(currentId);
+      if (!entry) break;
+      suffix.push(entry);
+      currentId = entry.parentId;
+    }
+
+    let prefix = currentId
+      ? (prefixes.get(currentId) ?? EMPTY_PREFIX)
+      : EMPTY_PREFIX;
+    for (const entry of suffix.reverse()) {
+      prefix = addUsage(prefix, entry);
+      prefixes.set(entry.id, prefix);
+    }
+
+    return toMetrics(prefixes.get(leafId) ?? EMPTY_PREFIX);
+  };
+
+  return { sync, reset };
+}

package/extensions/plan-mode/bash-policy.ts

@@ -11,11 +11,13 @@
  *
  * THREAT MODEL. The adversary is a model that would start changing things
  * before the user approved a plan — including one steered by injected text it
- * read while investigating. It is NOT a hostile repository: `git diff` honors
- * `diff.external` from the repo's own config, so a checkout whose `.git/config`
- * is attacker-controlled can run a program through a command this module
- * allows. Nothing here can prevent that, and nothing above it tries to: pi
- * already runs the project's own tooling under the user's trust decision.
+ * read while investigating. Repository-configured diff drivers are also in
+ * scope for commands that render patches: raw `git diff`, `git show`,
+ * `git whatchanged`, and diff-generating `git log` forms are refused here. Plan
+ * Mode exposes the structured git-read tools instead; they force
+ * `--no-ext-diff --no-textconv --no-color` in argv. This is not a claim that
+ * every hostile Git configuration is inert: the remaining Git investigation
+ * commands still run under Pi's existing project trust boundary.
  *
  * EVERY LIST BELOW IS AN ALLOWLIST, deliberately. An earlier version scanned
  * for known-dangerous flags instead, and review found four separate escapes in
@@ -50,9 +52,7 @@ const UNQUOTED_GLOB_CHARACTERS = new Set(["*", "?", "[", "]"]);
  */
 const GIT_SUBCOMMANDS = new Set([
   "log",
-  "diff",
   "status",
-  "show",
   "blame",
   "shortlog",
   "describe",
@@ -63,10 +63,11 @@ const GIT_SUBCOMMANDS = new Set([
   "cat-file",
   "merge-base",
   "name-rev",
-  "whatchanged",
   "grep",
 ]);
 
+const GIT_DIFF_SUBCOMMANDS = new Set(["diff", "show", "whatchanged"]);
+
 /**
  * Flags accepted after a git subcommand. The admission rule for this list is
  * narrow: a flag qualifies only if it shapes OUTPUT or SELECTS commits, and
@@ -159,6 +160,27 @@ const GIT_FLAGS = new Set([
   "--count",
 ]);
 
+/**
+ * Options that make `git log` enter the diff machinery. Git enables textconv
+ * by default for porcelain log/diff output, so these must use the structured
+ * git tools even though plain history browsing remains safe and useful.
+ */
+const GIT_LOG_DIFF_FLAGS = new Set([
+  "-p",
+  "--patch",
+  "--stat",
+  "--shortstat",
+  "--numstat",
+  "--summary",
+  "--raw",
+  "--name-only",
+  "--name-status",
+  "--word-diff",
+  "-U",
+  "--unified",
+  "-L",
+]);
+
 /** gh subcommands paired with the verbs under each that only read. */
 const GH_SUBCOMMANDS = new Map<string, ReadonlySet<string>>([
   ["pr", new Set(["view", "list", "diff", "checks", "status"])],
@@ -377,6 +399,16 @@ function flagName(word: string) {
   return eq === -1 ? word : word.slice(0, eq);
 }
 
+function firstMatchedFlag(
+  words: readonly string[],
+  flags: ReadonlySet<string>,
+) {
+  for (const word of words) {
+    if (word === "--") break;
+    if (flags.has(flagName(word))) return word;
+  }
+}
+
 /**
  * Check the argument tail. Words after `--` are pathspecs by definition and
  * need no check; before it, a word either is an allowlisted flag or is not a
@@ -439,11 +471,24 @@ export function planBashDecision(command: unknown): BashPlanDecision {
    */
   if (program === "git") {
     const [subcommand, ...args] = rest;
+    if (subcommand && GIT_DIFF_SUBCOMMANDS.has(subcommand)) {
+      return refuse(
+        `plan mode does not run raw "git ${subcommand}" because repository diff drivers may execute external programs — use git_diff or git_show instead (and git_log to find commits)`,
+      );
+    }
     if (!subcommand || !GIT_SUBCOMMANDS.has(subcommand)) {
       return refuse(
-        `plan mode allows only a read-only git subcommand immediately after "git" (log, diff, status, show, blame, …), not "${subcommand ?? "(none)"}"`,
+        `plan mode allows only a read-only git subcommand immediately after "git" (log, status, blame, …), not "${subcommand ?? "(none)"}"`,
       );
     }
+    if (subcommand === "log") {
+      const diffFlag = firstMatchedFlag(args, GIT_LOG_DIFF_FLAGS);
+      if (diffFlag) {
+        return refuse(
+          `plan mode does not run raw "git log ${diffFlag}" because diff-generating log options may execute repository diff drivers — use git_log to find commits, then git_show or git_diff to inspect changes`,
+        );
+      }
+    }
     return scanArguments(args, GIT_FLAGS, "git");
   }