@kenkaiiii/ggcoder 5.68.1 → 5.69.0

package/dist/core/cache-diagnostics.d.ts

@@ -1,4 +1,5 @@
 import type { CacheRetention, PreparedContext, Usage } from "@kenkaiiii/gg-ai";
+import { type CacheTouch } from "./cache-expiry.js";
 export interface CacheRequestObservation {
     provider: string;
     model: string;
@@ -50,6 +51,11 @@ export declare class CacheDiagnostics {
     private freedTokens;
     private requests;
     private reportedCache;
+    private lastTouch;
+    /** Last successful cache-using request (real turn or prewarm), or null. */
+    lastCacheTouch(): CacheTouch | null;
+    /** Record a successful cache-using request that bypassed prepare/complete (prewarm). */
+    noteCacheTouch(touch: CacheTouch): void;
     reset(): void;
     discardAttempt(): void;
     noteEdit(edit: HistoryEdit, freedTokens?: number): void;

package/dist/core/cache-diagnostics.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { resolveCacheTtl } from "./cache-expiry.js";
 /** Digests never leave this instance. Canonical object keys avoid spurious edits on resume. */
 function digest(value) {
     const json = JSON.stringify(value, (_key, item) => item !== null && typeof item === "object" && !Array.isArray(item)
@@ -8,6 +9,13 @@ function digest(value) {
         .update(json ?? "null")
         .digest("hex");
 }
+/** Route fields the session passes as `route`; read structurally, never digested. */
+function routeField(route, key) {
+    if (!route || typeof route !== "object")
+        return undefined;
+    const value = route[key];
+    return typeof value === "string" && value ? value : undefined;
+}
 function signedThinkingCount(message) {
     if (message.role !== "assistant" || !Array.isArray(message.content))
         return 0;
@@ -28,7 +36,17 @@ export class CacheDiagnostics {
     freedTokens = 0;
     requests = 0;
     reportedCache = false;
+    lastTouch = null;
+    /** Last successful cache-using request (real turn or prewarm), or null. */
+    lastCacheTouch() {
+        return this.lastTouch;
+    }
+    /** Record a successful cache-using request that bypassed prepare/complete (prewarm). */
+    noteCacheTouch(touch) {
+        this.lastTouch = { ...touch };
+    }
     reset() {
+        this.lastTouch = null;
         this.completed = undefined;
         this.pending = undefined;
         this.edits.clear();
@@ -56,6 +74,16 @@ export class CacheDiagnostics {
             route: digest({ provider: input.provider, model: input.model, route: input.route }),
             imagesDropped: context.imagesBefore - context.imagesAfter,
             at: input.at,
+            touch: (() => {
+                const policy = resolveCacheTtl({
+                    provider: input.provider,
+                    model: input.model,
+                    cacheRetention: input.cacheRetention,
+                    baseUrl: routeField(input.route, "baseUrl"),
+                    accountId: routeField(input.route, "accountId"),
+                });
+                return policy ? { provider: input.provider, model: input.model, policy } : null;
+            })(),
         };
         let unchanged = 0;
         if (previous) {
@@ -143,6 +171,9 @@ export class CacheDiagnostics {
             ? Math.max(0, Math.min(promptTokens(previous.usage), promptTokens(usage)) - cacheRead)
             : null;
         this.completed = { ...snapshot, usage: { ...usage } };
+        // The provider refreshes the cached prefix when the request is processed, so
+        // the TTL clock restarts at the request's start time.
+        this.lastTouch = snapshot.touch ? { ...snapshot.touch, at: snapshot.at } : null;
         this.pending = undefined;
         this.edits.clear();
         this.freedTokens = 0;

package/dist/core/cache-diagnostics.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache-diagnostics.js","sourceRoot":"","sources":["../../src/core/cache-diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,+FAA+F;AAC/F,SAAS,MAAM,CAAC,KAAc;IAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,IAAa,EAAE,EAAE,CACzD,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAC/D,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3F,CAAC,CAAC,IAAI,CACT,CAAC;IACF,OAAO,UAAU,CAAC,QAAQ,CAAC;SACxB,MAAM,CAAC,IAAI,IAAI,MAAM,CAAC;SACtB,MAAM,CAAC,KAAK,CAAC,CAAC;AACnB,CAAC;AAyDD,SAAS,mBAAmB,CAAC,OAAgB;IAC3C,IAAI,OAAO,CAAC,IAAI,KAAK,WAAW,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,CAAC,CAAC;IAC9E,OAAO,OAAO,CAAC,OAAO,CAAC,MAAM,CAC3B,CAAC,IAAI,EAAE,EAAE,CACP,CAAC,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7D,CAAC,IAAI,CAAC,IAAI,KAAK,KAAK;YAClB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,mBAAmB;gBACrC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,CACnF,CAAC,MAAM,CAAC;AACX,CAAC;AAED,SAAS,YAAY,CAAC,KAAY;IAChC,OAAO,KAAK,CAAC,WAAW,GAAG,CAAC,KAAK,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC;AAC9E,CAAC;AAED;+EAC+E;AAC/E,MAAM,OAAO,gBAAgB;IACnB,SAAS,CAA8B;IACvC,OAAO,CAAwE;IAC/E,KAAK,GAAG,IAAI,GAAG,EAAe,CAAC;IAC/B,WAAW,GAAG,CAAC,CAAC;IAChB,QAAQ,GAAG,CAAC,CAAC;IACb,aAAa,GAAG,KAAK,CAAC;IAE9B,KAAK;QACH,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QACzB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;QACrB,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;QAClB,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;IAC7B,CAAC;IAED,cAAc;QACZ,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;IAC3B,CAAC;IAED,QAAQ,CAAC,IAAiB,EAAE,WAAW,GAAG,CAAC;QACzC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACrB,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,CAAC,OAAwB,EAAE,KAA8B;QAC9D,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;QAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,MAAM,QAAQ,GAAoB;YAChC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACzC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CACzD;YACD,QAAQ,EAAE,MAAM,CAAC;gBACf,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,cAAc,EAAE,KAAK,CAAC,cAAc;aACrC,CAAC;YACF,KAAK,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;YACnF,aAAa,EAAE,OAAO,CAAC,YAAY,GAAG,OAAO,CAAC,WAAW;YACzD,EAAE,EAAE,KAAK,CAAC,EAAE;SACb,CAAC;QACF,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,IAAI,QAAQ,EAAE,CAAC;YACb,OACE,SAAS,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM;gBACpC,SAAS,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM;gBACpC,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAC,QAAQ,CAAC,SAAS,CAAC;gBAE7D,SAAS,EAAE,CAAC;QAChB,CAAC;QACD,MAAM,OAAO,GAAa,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,QAAQ,EAAE,KAAK,KAAK,SAAS,IAAI,QAAQ,CAAC,KAAK,KAAK,QAAQ,CAAC,KAAK;YACpE,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QACjC,MAAM,eAAe,GAAG,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,QAAQ,KAAK,QAAQ,CAAC,QAAQ,CAAC;QAC1F,IAAI,eAAe;YAAE,OAAO,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;QACtD,MAAM,cAAc,GAAG,QAAQ,KAAK,SAAS,IAAI,SAAS,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC;QACtF,IAAI,cAAc;YAAE,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,QAAQ,CAAC,aAAa,KAAK,CAAC,QAAQ,EAAE,aAAa,IAAI,CAAC,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAE5F,wFAAwF;QACxF,oFAAoF;QACpF,IAAI,SAAS,GAAG,OAAO,CAAC,qBAAqB,IAAI,MAAM,CAAC,iBAAiB,CAAC;QAC1E,IAAI,cAAc;YAAE,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QAC/D,IAAI,eAAe;YAAE,SAAS,GAAG,CAAC,CAAC,CAAC;QACpC,IAAI,QAAQ,GAAG,CAAC,CAAC,CAAC;QAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE;YAC1C,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM;gBAAE,QAAQ,GAAG,KAAK,CAAC;QAChD,CAAC,CAAC,CAAC;QACH,IAAI,wBAAwB,GAAG,CAAC,CAAC;QACjC,IAAI,qBAAqB,GAAG,CAAC,CAAC;QAC9B,IAAI,KAAK,CAAC,QAAQ,KAAK,WAAW,EAAE,CAAC;YACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE;gBAC1C,MAAM,KAAK,GAAG,mBAAmB,CAAC,OAAO,CAAC,CAAC;gBAC3C,IAAI,KAAK,IAAI,SAAS;oBAAE,wBAAwB,IAAI,KAAK,CAAC;gBAC1D,IAAI,KAAK,GAAG,QAAQ;oBAAE,qBAAqB,IAAI,KAAK,CAAC;YACvD,CAAC,CAAC,CAAC;QACL,CAAC;QACD,MAAM,sBAAsB,GAAG,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,GAAG,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACrF,MAAM,MAAM,GAAuB;YACjC,KAAK,EAAE,kBAAkB;YACzB,OAAO,EAAE,EAAE,IAAI,CAAC,QAAQ;YACxB,OAAO,EAAE,OAAO,CAAC,IAAI,EAAE;YACvB,YAAY,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM;YACtC,oBAAoB,EAAE,QAAQ,EAAE,QAAQ,CAAC,MAAM,IAAI,CAAC;YACpD,iBAAiB,EAAE,SAAS;YAC5B,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,aAAa,EAAE,QAAQ,CAAC,aAAa;YACrC,wBAAwB,EAAE,IAAI,CAAC,WAAW;YAC1C,sBAAsB;YACtB,oBAAoB,EAClB,KAAK,CAAC,cAAc,KAAK,MAAM;gBAC/B,sBAAsB,KAAK,IAAI;gBAC/B,sBAAsB,GAAG,CAAC,KAAK,CAAC,cAAc,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;YAClF,wBAAwB;YACxB,qBAAqB;YACrB,aAAa,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG;SACrE,CAAC;QACF,IAAI,CAAC,OAAO,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;QACpC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,QAAQ,CACN,KAAY,EACZ,MAAuD;QAEvD,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,SAAS,CAAC;QACpC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAChC,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,CAAC,CAAC;QACvC,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,CAAC,CAAC;QACzC,MAAM,YAAY,GAAG,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,KAAK,KAAK,QAAQ,CAAC,KAAK,CAAC;QACjF,MAAM,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,CAAC,IAAI,CAAC,CAAC,YAAY,IAAI,IAAI,CAAC,aAAa,CAAC,CAAC;QACrF,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,KAAK;YACjC,CAAC,CAAC,eAAe;YACjB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC;gBAC5B,CAAC,CAAC,YAAY;gBACd,CAAC,CAAC,YAAY;oBACZ,CAAC,CAAC,eAAe;oBACjB,CAAC,CAAC,CAAC,QAAQ;wBACT,CAAC,CAAC,kBAAkB;wBACpB,CAAC,CAAC,YAAY,CAAC;QACvB,MAAM,WAAW,GACf,UAAU,KAAK,YAAY,IAAI,QAAQ,EAAE,KAAK;YAC5C,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,GAAG,SAAS,CAAC;YACtF,CAAC,CAAC,IAAI,CAAC;QACX,IAAI,CAAC,SAAS,GAAG,EAAE,GAAG,QAAQ,EAAE,KAAK,EAAE,EAAE,GAAG,KAAK,EAAE,EAAE,CAAC;QACtD,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC;QACzB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACnB,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;QACrB,IAAI,CAAC,aAAa,GAAG,QAAQ,CAAC;QAC9B,OAAO;YACL,GAAG,MAAM;YACT,YAAY,EAAE,YAAY,CAAC,KAAK,CAAC;YACjC,SAAS;YACT,UAAU;YACV,UAAU;YACV,+BAA+B,EAAE,WAAW;YAC5C,oFAAoF;YACpF,sFAAsF;YACtF,UAAU,EAAE,aAAa;YACzB,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,IAAI;YAC7B,kBAAkB,EAAE,MAAM,CAAC,kBAAkB;SAC9C,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"cache-diagnostics.js","sourceRoot":"","sources":["../../src/core/cache-diagnostics.ts"],"names":[],"mappings":"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"}

package/dist/core/cache-expiry.d.ts

@@ -0,0 +1,87 @@
+import type { CacheRetention } from "@kenkaiiii/gg-ai";
+/**
+ * Cold-prompt-cache detection (mirrors langchain-ai/deepagents#6477's
+ * `cold_cache.py`): providers keep the conversation prefix cached only for a
+ * TTL, so after a break the next message re-reads the whole context uncached.
+ *
+ * Every TTL below is derived from what gg-ai actually puts on the wire — never
+ * from a provider's marketing maximum we did not request. A provider/route we
+ * cannot pin to a request-side TTL returns `null` (no warning) rather than a
+ * guess.
+ */
+export interface CacheTtlPolicy {
+    ttlMs: number;
+    /**
+     * `expired`: the TTL is a documented/requested *maximum* — past it the entry
+     * is gone. `may_be_cold`: the TTL is a guaranteed *minimum* (GPT-5.6+ `30m`),
+     * so past it the prefix may still be warm.
+     */
+    confidence: "expired" | "may_be_cold";
+    /** Where the number comes from, for logs/diagnostics. */
+    source: string;
+}
+export interface CacheTtlInput {
+    provider: string;
+    model: string;
+    cacheRetention: CacheRetention;
+    baseUrl?: string;
+    /** OpenAI OAuth (ChatGPT/Codex) routes carry an account id. */
+    accountId?: string;
+}
+/** Resolve the cache TTL our provider code requests for this route. */
+export declare function resolveCacheTtl(input: CacheTtlInput): CacheTtlPolicy | null;
+/**
+ * Prefix size below which the notice is not worth an interruption. At 40k
+ * tokens a cold Anthropic re-read (1.25x write vs 0.1x cached read) costs ~12x
+ * the warm request, roughly a dime on Sonnet-class pricing; below that the delta
+ * is pennies — and compacting first itself re-reads the whole context once, so
+ * on small chats "Compact first" saves nothing.
+ */
+export declare const CACHE_EXPIRY_NOTICE_MIN_TOKENS = 40000;
+export interface CacheTouch {
+    at: number;
+    provider: string;
+    model: string;
+    policy: CacheTtlPolicy;
+}
+export interface CacheExpiryStatus {
+    /** Owning session, so clients can key "dismissed once per expiry per chat". */
+    sessionId?: string;
+    provider: string;
+    ttlMs: number;
+    confidence: CacheTtlPolicy["confidence"];
+    ttlSource: string;
+    /** Last successful cache-using request (real turn or prewarm), epoch ms. */
+    lastRequestAt: number | null;
+    /** When the cached prefix lapses/lapsed, epoch ms; null when age is unknown. */
+    expiresAt: number | null;
+    expired: boolean;
+    /**
+     * `idle`: TTL passed. `age_unknown`: resumed/reset session with no request in
+     * this process. `identity_changed`: provider/model switched since the last
+     * request, so the old prefix cannot be reused.
+     */
+    reason: "idle" | "age_unknown" | "identity_changed" | null;
+    /** Tokens the next request would re-read (the current context). */
+    prefixTokens: number;
+    minTokens: number;
+    /** expired AND prefixTokens >= minTokens: worth showing the notice. */
+    notable: boolean;
+    /** No authoritative pricing exists in GG (turn metric cost is "unavailable"). */
+    estimatedExtraCostUsd: null;
+}
+export interface AssessCacheExpiryInput {
+    /** Policy for the route the NEXT request will take. */
+    current: {
+        provider: string;
+        model: string;
+        policy: CacheTtlPolicy | null;
+    };
+    lastTouch: CacheTouch | null;
+    now: number;
+    prefixTokens: number;
+    /** False for an empty chat — nothing to re-read. */
+    hasHistory: boolean;
+    minTokens?: number;
+}
+export declare function assessCacheExpiry(input: AssessCacheExpiryInput): CacheExpiryStatus | null;

package/dist/core/cache-expiry.js

@@ -0,0 +1,111 @@
+const MINUTE = 60_000;
+/** Resolve the cache TTL our provider code requests for this route. */
+export function resolveCacheTtl(input) {
+    if (input.cacheRetention === "none")
+        return null;
+    if (input.provider === "anthropic") {
+        // gg-ai/src/providers/transform.ts `toAnthropicCacheControl`: "long" sends
+        // `ttl: "1h"` only on the first-party endpoint; everything else sends a bare
+        // `{type: "ephemeral"}`, which is Anthropic's 5-minute default.
+        const firstParty = !input.baseUrl || input.baseUrl.includes("api.anthropic.com");
+        if (input.cacheRetention === "long" && firstParty) {
+            return {
+                ttlMs: 60 * MINUTE,
+                confidence: "expired",
+                source: "anthropic cache_control ttl=1h (transform.ts toAnthropicCacheControl)",
+            };
+        }
+        return {
+            ttlMs: 5 * MINUTE,
+            confidence: "expired",
+            source: "anthropic cache_control ephemeral default 5m (transform.ts toAnthropicCacheControl)",
+        };
+    }
+    if (input.provider === "openai") {
+        if (input.accountId) {
+            // gg-ai/src/providers/openai-codex.ts: the Codex backend rejects
+            // prompt_cache_retention; "Cache TTL on Codex is controlled server-side
+            // (~5-10 min in-memory)". Use the upper bound so we only warn once the
+            // entry is surely gone.
+            return {
+                ttlMs: 10 * MINUTE,
+                confidence: "expired",
+                source: "codex server-side in-memory cache ~5-10m (openai-codex.ts)",
+            };
+        }
+        if (input.model.startsWith("gpt-5.6") || input.model.startsWith("gpt-6")) {
+            // gg-ai/src/providers/openai.ts sends prompt_cache_options.ttl = "30m";
+            // OpenAI documents 30 minutes as a guaranteed minimum.
+            return {
+                ttlMs: 30 * MINUTE,
+                confidence: "may_be_cold",
+                source: "openai prompt_cache_options ttl=30m (openai.ts)",
+            };
+        }
+        if (input.cacheRetention === "long") {
+            // gg-ai/src/providers/openai.ts sends prompt_cache_retention = "24h".
+            return {
+                ttlMs: 24 * 60 * MINUTE,
+                confidence: "expired",
+                source: "openai prompt_cache_retention=24h (openai.ts)",
+            };
+        }
+        // No retention param sent → OpenAI's default in-memory retention, which
+        // its prompt-caching guide documents as up to one hour (a maximum).
+        return {
+            ttlMs: 60 * MINUTE,
+            confidence: "expired",
+            source: "openai default in_memory retention, max 1h (no param sent by openai.ts)",
+        };
+    }
+    // Other providers (Gemini, GLM, Moonshot, OpenRouter, local, …): we request
+    // no TTL and have no documented window to anchor a warning on.
+    return null;
+}
+/**
+ * Prefix size below which the notice is not worth an interruption. At 40k
+ * tokens a cold Anthropic re-read (1.25x write vs 0.1x cached read) costs ~12x
+ * the warm request, roughly a dime on Sonnet-class pricing; below that the delta
+ * is pennies — and compacting first itself re-reads the whole context once, so
+ * on small chats "Compact first" saves nothing.
+ */
+export const CACHE_EXPIRY_NOTICE_MIN_TOKENS = 40_000;
+export function assessCacheExpiry(input) {
+    const { current, lastTouch, now } = input;
+    if (!input.hasHistory || !current.policy)
+        return null;
+    const minTokens = input.minTokens ?? CACHE_EXPIRY_NOTICE_MIN_TOKENS;
+    const prefixTokens = Math.max(0, Math.round(input.prefixTokens));
+    let reason = null;
+    let expiresAt = null;
+    // The entry lives by the TTL it was WRITTEN with, not the current setting.
+    let policy = current.policy;
+    if (!lastTouch) {
+        reason = "age_unknown";
+    }
+    else if (lastTouch.provider !== current.provider || lastTouch.model !== current.model) {
+        reason = "identity_changed";
+    }
+    else {
+        policy = lastTouch.policy;
+        expiresAt = lastTouch.at + policy.ttlMs;
+        if (now >= expiresAt)
+            reason = "idle";
+    }
+    const expired = reason !== null;
+    return {
+        provider: current.provider,
+        ttlMs: policy.ttlMs,
+        confidence: policy.confidence,
+        ttlSource: policy.source,
+        lastRequestAt: lastTouch?.at ?? null,
+        expiresAt,
+        expired,
+        reason,
+        prefixTokens,
+        minTokens,
+        notable: expired && prefixTokens >= minTokens,
+        estimatedExtraCostUsd: null,
+    };
+}
+//# sourceMappingURL=cache-expiry.js.map

package/dist/core/cache-expiry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-expiry.js","sourceRoot":"","sources":["../../src/core/cache-expiry.ts"],"names":[],"mappings":"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"}

package/dist/core/destructive-git-guard.d.ts

@@ -39,6 +39,33 @@ export interface DestructiveGitMatch {
     /** branch -D targets; stash drop target. */
     refs: string[];
 }
+/** Basename of a command word, `.exe` stripped (`/usr/bin/git`, `git.exe`). */
+export declare function commandName(word: string): string;
+/**
+ * Expand the home and working-directory forms a model writes in paths:
+ * `~`, `$HOME`/`${HOME}` (any case, which also covers PowerShell `$home`),
+ * `$env:USERPROFILE`/`$env:HOME`, cmd `%USERPROFILE%`, and `$PWD`/`${PWD}`. Other variables stay
+ * literal, so they resolve to a harmless relative path.
+ */
+export declare function expandShellPath(p: string, cwd: string): string;
+/** One simple command found in a shell string, after unwrapping. */
+export interface ShellInvocation {
+    /** {@link commandName} of the command word. */
+    name: string;
+    args: readonly string[];
+    /** Directory it would run in after any earlier `cd` in the same script. */
+    cwd: string;
+    /** Run by `xargs`, which appends operands read from stdin. */
+    viaXargs: boolean;
+}
+/**
+ * Every simple command in `command` whose name satisfies `wanted`, in source
+ * order, after splitting on `&&`/`;`/`||`/pipes, entering subshells,
+ * substitutions and `if`/`for`/`while` bodies, unwrapping `bash -c`/`eval`/
+ * `pwsh -c` scripts and exec wrappers (`sudo`, `env`, `timeout`, `xargs`, …),
+ * and following `cd`. Pure: nothing is executed.
+ */
+export declare function walkShell(command: string, cwd: string, wanted: (name: string) => boolean): ShellInvocation[];
 /**
  * Parse `command` and return every git invocation in it that can destroy
  * work, with the directory each would run in. Pure apart from `existsSync`

package/dist/core/destructive-git-guard.js

@@ -1,7 +1,7 @@
-import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { BackgroundGitError, runBackgroundGit } from "../utils/git.js";
 import { log } from "./logger.js";
 const MAX_DEPTH = 6;
 const GIT_TIMEOUT_MS = 3_000;
@@ -326,22 +326,34 @@ const SHELL_KEYWORDS = new Set([
     "function",
 ]);
 /** Basename of a command word, `.exe` stripped (`/usr/bin/git`, `git.exe`). */
-function commandName(word) {
+export function commandName(word) {
     return (word.split(/[\\/]/).pop() ?? word).replace(/\.exe$/i, "");
 }
-function expandHome(p) {
-    return p.replace(/^~(?=[\\/]|$)/, os.homedir());
+/**
+ * Expand the home and working-directory forms a model writes in paths:
+ * `~`, `$HOME`/`${HOME}` (any case, which also covers PowerShell `$home`),
+ * `$env:USERPROFILE`/`$env:HOME`, cmd `%USERPROFILE%`, and `$PWD`/`${PWD}`. Other variables stay
+ * literal, so they resolve to a harmless relative path.
+ */
+export function expandShellPath(p, cwd) {
+    return p
+        .replace(/^(?:~|\$\{?home\}?|\$env:(?:userprofile|home)|%userprofile%)(?=[\\/]|$)/i, os.homedir())
+        .replace(/^\$\{?PWD\}?(?=[\\/]|$)/, cwd);
+}
+function isPowerShell(name) {
+    const lower = name.toLowerCase();
+    return lower === "powershell" || lower === "pwsh";
 }
-function analyzeScript(script, ctx, out) {
+function walkScript(script, ctx) {
     const commands = [];
     scanShell(script, ctx.depth, commands);
     // `cd` persists for later commands in the same script (approximation: a
     // subshell's cd leaks too, which only ever widens what gets checked).
-    const local = { cwd: ctx.cwd, depth: ctx.depth };
+    const local = { ...ctx };
     for (const words of commands)
-        analyzeWords(words, local, out);
+        walkWords(words, local);
 }
-function analyzeWords(input, ctx, out) {
+function walkWords(input, ctx) {
     let words = input;
     while (words.length > 0 &&
         (SHELL_KEYWORDS.has(words[0] ?? "") || /^[A-Za-z_][A-Za-z0-9_]*=/.test(words[0] ?? ""))) {
@@ -354,31 +366,38 @@ function analyzeWords(input, ctx, out) {
     const args = words.slice(1);
     if (name === "cd" || name === "pushd") {
         const target = args.find((a) => !a.startsWith("-"));
-        if (target === undefined)
+        // `cd -` goes somewhere we cannot know; keep the current guess.
+        if (target === undefined && !args.includes("-"))
             ctx.cwd = os.homedir();
-        else
-            ctx.cwd = path.resolve(ctx.cwd, expandHome(target));
+        else if (target !== undefined)
+            ctx.cwd = path.resolve(ctx.cwd, expandShellPath(target, ctx.cwd));
         return;
     }
-    if (name === "git") {
-        const match = analyzeGit(args, ctx.cwd);
-        if (match)
-            out.push(match);
+    if (ctx.wanted(name)) {
+        ctx.out.push({ name, args, cwd: ctx.cwd, viaXargs: ctx.viaXargs });
         return;
     }
     if (ctx.depth >= MAX_DEPTH)
         return;
-    const deeper = { cwd: ctx.cwd, depth: ctx.depth + 1 };
+    const deeper = { ...ctx, depth: ctx.depth + 1 };
     if (SHELLS.has(name)) {
         // `bash -c 'script'`, also clustered (`-lc`, `-ec`).
         const flagIndex = args.findIndex((a) => /^-[A-Za-z]*c[A-Za-z]*$/.test(a));
         const script = flagIndex === -1 ? undefined : args[flagIndex + 1];
         if (script !== undefined)
-            analyzeScript(script, deeper, out);
+            walkScript(script, deeper);
+        return;
+    }
+    if (isPowerShell(name)) {
+        // `pwsh -c '…'` / `powershell -Command "…"` (any unambiguous prefix).
+        const flagIndex = args.findIndex((a) => /^-c(?:o(?:m(?:m(?:a(?:n(?:d)?)?)?)?)?)?$/i.test(a));
+        const script = flagIndex === -1 ? undefined : args.slice(flagIndex + 1).join(" ");
+        if (script)
+            walkScript(script, deeper);
         return;
     }
     if (name === "eval") {
-        analyzeScript(args.join(" "), deeper, out);
+        walkScript(args.join(" "), deeper);
         return;
     }
     if (EXEC_WRAPPERS.has(name)) {
@@ -387,15 +406,13 @@ function analyzeWords(input, ctx, out) {
         // analyse, stopping at a command that merely displays its operands.
         for (let index = 0; index < args.length; index += 1) {
             const candidate = commandName(args[index] ?? "");
-            if (candidate === "git" ||
+            if (ctx.wanted(candidate) ||
                 candidate === "cd" ||
                 candidate === "eval" ||
                 SHELLS.has(candidate) ||
+                isPowerShell(candidate) ||
                 EXEC_WRAPPERS.has(candidate)) {
-                // xargs appends operands read from stdin; stand in "." (whole tree)
-                // so `… | xargs git checkout --` is checked rather than parsed as empty.
-                const child = args.slice(index);
-                analyzeWords(name === "xargs" ? [...child, "."] : child, deeper, out);
+                walkWords(args.slice(index), { ...deeper, viaXargs: ctx.viaXargs || name === "xargs" });
                 return;
             }
             if (NON_EXEC_COMMANDS.has(candidate))
@@ -403,6 +420,18 @@ function analyzeWords(input, ctx, out) {
         }
     }
 }
+/**
+ * Every simple command in `command` whose name satisfies `wanted`, in source
+ * order, after splitting on `&&`/`;`/`||`/pipes, entering subshells,
+ * substitutions and `if`/`for`/`while` bodies, unwrapping `bash -c`/`eval`/
+ * `pwsh -c` scripts and exec wrappers (`sudo`, `env`, `timeout`, `xargs`, …),
+ * and following `cd`. Pure: nothing is executed.
+ */
+export function walkShell(command, cwd, wanted) {
+    const out = [];
+    walkScript(command, { cwd, depth: 0, viaXargs: false, wanted, out });
+    return out;
+}
 // ── git classification ─────────────────────────────────────
 /** True for a short-option cluster (`-fdx`) containing `letter`. */
 function hasShort(tokens, letter) {
@@ -474,18 +503,18 @@ function analyzeGit(args, cwd) {
     while (i < args.length) {
         const arg = args[i] ?? "";
         if (arg === "-C") {
-            dir = path.resolve(dir, expandHome(args[i + 1] ?? "."));
+            dir = path.resolve(dir, expandShellPath(args[i + 1] ?? ".", dir));
             i += 2;
             continue;
         }
         if (arg === "--git-dir" || arg === "--work-tree") {
-            gitArgs.push(`${arg}=${path.resolve(dir, expandHome(args[i + 1] ?? "."))}`);
+            gitArgs.push(`${arg}=${path.resolve(dir, expandShellPath(args[i + 1] ?? ".", dir))}`);
             i += 2;
             continue;
         }
         const assigned = /^(--git-dir|--work-tree)=(.*)$/.exec(arg);
         if (assigned) {
-            gitArgs.push(`${assigned[1]}=${path.resolve(dir, expandHome(assigned[2] ?? "."))}`);
+            gitArgs.push(`${assigned[1]}=${path.resolve(dir, expandShellPath(assigned[2] ?? ".", dir))}`);
             i += 1;
             continue;
         }
@@ -615,39 +644,52 @@ function truncate(text, max = 120) {
  */
 export function findDestructiveGitCommands(command, cwd) {
     const out = [];
-    analyzeScript(command, { cwd, depth: 0 }, out);
+    for (const call of walkShell(command, cwd, (name) => name === "git")) {
+        // xargs appends operands read from stdin; stand in "." (whole tree)
+        // so `… | xargs git checkout --` is checked rather than parsed as empty.
+        const match = analyzeGit(call.viaXargs ? [...call.args, "."] : call.args, call.cwd);
+        if (!match)
+            continue;
+        // A pathspec still holding a variable (`for f in …; do git checkout -- $f`)
+        // could name anything once expanded: check the whole tree instead of a
+        // literal `$f` that matches no file.
+        if (match.pathspecs.some((spec) => spec.includes("$")))
+            match.pathspecs = [];
+        out.push(match);
+    }
     return out;
 }
 class GuardError extends Error {
 }
-function runGit(dir, args) {
-    return new Promise((resolve, reject) => {
-        execFile("git", [...args], {
+/**
+ * Run an inspection git command against the target repo with repo-config
+ * execution sinks (fsmonitor, hooks, filters, …) disabled — see
+ * runBackgroundGit. `gitArgs` are the command's own `--git-dir`/`--work-tree`.
+ */
+async function runGit(dir, gitArgs, args) {
+    try {
+        const { stdout } = await runBackgroundGit(args, {
             cwd: dir,
-            timeout: GIT_TIMEOUT_MS,
+            globalArgs: gitArgs,
+            timeoutMs: GIT_TIMEOUT_MS,
             maxBuffer: 8 * 1024 * 1024,
-            windowsHide: true,
-            env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", LC_ALL: "C", GIT_TERMINAL_PROMPT: "0" },
-        }, (error, stdout) => {
-            if (!error) {
-                resolve({ code: 0, stdout });
-                return;
-            }
-            // A numeric code is git's exit status; a string (ENOENT) or a kill
-            // (timeout) means the guard itself could not inspect the repo.
-            const code = error.code;
-            if (typeof code === "number" && !error.killed) {
-                resolve({ code, stdout });
-                return;
-            }
-            reject(new GuardError(`git ${args.join(" ")} failed: ${error.message}`));
+            env: { LC_ALL: "C" },
         });
-    });
+        return { code: 0, stdout };
+    }
+    catch (error) {
+        // A numeric code is git's exit status; a string (ENOENT) or a kill
+        // (timeout) means the guard itself could not inspect the repo.
+        if (error instanceof BackgroundGitError && typeof error.code === "number" && !error.killed) {
+            return { code: error.code, stdout: error.stdout };
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new GuardError(`git ${args.join(" ")} failed: ${message}`);
+    }
 }
 /** `git status --porcelain=v1 -z`, parsed. Null when `dir` is not a repo. */
 async function gitStatus(match, extra) {
-    const result = await runGit(match.dir, [
-        ...match.gitArgs,
+    const result = await runGit(match.dir, match.gitArgs, [
         "status",
         "--porcelain=v1",
         "-z",
@@ -711,8 +753,7 @@ async function evaluate(match) {
         case "checkout-paths":
         case "restore-worktree": {
             if (match.maybeRef !== undefined) {
-                const ref = await runGit(match.dir, [
-                    ...match.gitArgs,
+                const ref = await runGit(match.dir, match.gitArgs, [
                     "rev-parse",
                     "--verify",
                     "--quiet",
@@ -756,7 +797,7 @@ async function evaluate(match) {
         }
         case "stash-drop":
         case "stash-clear": {
-            const list = await runGit(match.dir, [...match.gitArgs, "stash", "list"]);
+            const list = await runGit(match.dir, match.gitArgs, ["stash", "list"]);
             const entries = list.code === 0 ? list.stdout.split("\n").filter((l) => l.length > 0) : [];
             if (entries.length === 0)
                 return null;
@@ -772,8 +813,7 @@ async function evaluate(match) {
             const losses = [];
             for (const branch of match.refs) {
                 const ref = `refs/heads/${branch}`;
-                const result = await runGit(match.dir, [
-                    ...match.gitArgs,
+                const result = await runGit(match.dir, match.gitArgs, [
                     "rev-list",
                     "--count",
                     ref,