@kenkaiiii/ggcoder 5.68.0 → 5.69.0

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

@@ -0,0 +1,68 @@
+import type { CacheRetention, PreparedContext, Usage } from "@kenkaiiii/gg-ai";
+import { type CacheTouch } from "./cache-expiry.js";
+export interface CacheRequestObservation {
+    provider: string;
+    model: string;
+    at: number;
+    cacheRetention: CacheRetention;
+    /** Request-shaping settings only; digested in memory, never logged. */
+    settings: unknown;
+    /** Route/account identity, digested in memory. Never pass credentials. */
+    route: unknown;
+}
+type HistoryEdit = "tool_prune" | "compaction";
+export interface CacheContextReport {
+    stage: "prepared_context";
+    request: number;
+    changes: string[];
+    messageCount: number;
+    previousMessageCount: number;
+    /** Logical-message prefix, NOT a provider token offset or exact HTTP-body comparison. */
+    unchangedMessages: number;
+    imagesBefore: number;
+    imagesAfter: number;
+    imagesDropped: number;
+    pruneFreedTokensEstimate: number;
+    sincePreviousRequestMs: number | null;
+    requestedTtlExceeded: boolean;
+    /** Possible signed-thinking prefix mismatch; not a server-confirmed rejection. */
+    thinkingPrefixRiskBlocks: number;
+    /** Existing Anthropic encoding removes these signed blocks from settled turns. */
+    settledThinkingBlocks: number;
+    fingerprintMs: number;
+}
+export interface CacheUsageReport extends CacheContextReport {
+    promptTokens: number;
+    cacheRead: number;
+    cacheWrite: number;
+    comparison: "first_request" | "compaction" | "route_changed" | "cache_unreported" | "comparable";
+    /** Upper-bound proxy for repeated input not read from cache, not proven avoidable waste. */
+    reprocessedPromptTokensEstimate: number | null;
+    costStatus: "unavailable";
+    ttftMs: number | null;
+    providerDurationMs: number;
+}
+/** One per session. Retains only one completed snapshot and one in-flight snapshot, no payloads.
+ * Failed/retried attempts never replace the last successful usage baseline. */
+export declare class CacheDiagnostics {
+    private completed;
+    private pending;
+    private edits;
+    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;
+    prepare(context: PreparedContext, input: CacheRequestObservation): CacheContextReport;
+    complete(usage: Usage, timing: {
+        ttftMs?: number;
+        providerDurationMs: number;
+    }): CacheUsageReport | undefined;
+}
+export {};

package/dist/core/cache-diagnostics.js

@@ -0,0 +1,196 @@
+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)
+        ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
+        : item);
+    return createHash("sha256")
+        .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;
+    return message.content.filter((part) => (part.type === "thinking" && Boolean(part.signature?.trim())) ||
+        (part.type === "raw" &&
+            (part.data.type === "redacted_thinking" ||
+                (part.data.type === "thinking" && typeof part.data.signature === "string")))).length;
+}
+function promptTokens(usage) {
+    return usage.inputTokens + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
+}
+/** One per session. Retains only one completed snapshot and one in-flight snapshot, no payloads.
+ * Failed/retried attempts never replace the last successful usage baseline. */
+export class CacheDiagnostics {
+    completed;
+    pending;
+    edits = new Set();
+    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();
+        this.freedTokens = 0;
+        this.requests = 0;
+        this.reportedCache = false;
+    }
+    discardAttempt() {
+        this.pending = undefined;
+    }
+    noteEdit(edit, freedTokens = 0) {
+        this.edits.add(edit);
+        this.freedTokens += Math.max(0, freedTokens);
+    }
+    prepare(context, input) {
+        const started = performance.now();
+        const previous = this.completed;
+        const snapshot = {
+            messages: context.messages.map((message) => digest({ role: message.role, content: message.content })),
+            settings: digest({
+                tools: context.tools,
+                settings: input.settings,
+                cacheRetention: input.cacheRetention,
+            }),
+            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) {
+            while (unchanged < previous.messages.length &&
+                unchanged < snapshot.messages.length &&
+                previous.messages[unchanged] === snapshot.messages[unchanged])
+                unchanged++;
+        }
+        const changes = [...this.edits];
+        if (previous?.route !== undefined && previous.route !== snapshot.route)
+            changes.push("route_or_model");
+        const settingsChanged = previous !== undefined && previous.settings !== snapshot.settings;
+        if (settingsChanged)
+            changes.push("request_settings");
+        const historyChanged = previous !== undefined && unchanged < previous.messages.length;
+        if (historyChanged)
+            changes.push("history");
+        if (snapshot.imagesDropped !== (previous?.imagesDropped ?? 0))
+            changes.push("image_budget");
+        // The input is already clamped. On resume there is no previous snapshot, but removal of
+        // earlier images can still invalidate signed reasoning from the saved conversation.
+        let firstEdit = context.firstImageDropMessage ?? Number.POSITIVE_INFINITY;
+        if (historyChanged)
+            firstEdit = Math.min(firstEdit, unchanged);
+        if (settingsChanged)
+            firstEdit = -1;
+        let lastUser = -1;
+        context.messages.forEach((message, index) => {
+            if (message.role === "user")
+                lastUser = index;
+        });
+        let thinkingPrefixRiskBlocks = 0;
+        let settledThinkingBlocks = 0;
+        if (input.provider === "anthropic") {
+            context.messages.forEach((message, index) => {
+                const count = signedThinkingCount(message);
+                if (index >= firstEdit)
+                    thinkingPrefixRiskBlocks += count;
+                if (index < lastUser)
+                    settledThinkingBlocks += count;
+            });
+        }
+        const sincePreviousRequestMs = previous ? Math.max(0, input.at - previous.at) : null;
+        const report = {
+            stage: "prepared_context",
+            request: ++this.requests,
+            changes: changes.sort(),
+            messageCount: snapshot.messages.length,
+            previousMessageCount: previous?.messages.length ?? 0,
+            unchangedMessages: unchanged,
+            imagesBefore: context.imagesBefore,
+            imagesAfter: context.imagesAfter,
+            imagesDropped: snapshot.imagesDropped,
+            pruneFreedTokensEstimate: this.freedTokens,
+            sincePreviousRequestMs,
+            requestedTtlExceeded: input.cacheRetention !== "none" &&
+                sincePreviousRequestMs !== null &&
+                sincePreviousRequestMs > (input.cacheRetention === "long" ? 3_600_000 : 300_000),
+            thinkingPrefixRiskBlocks,
+            settledThinkingBlocks,
+            fingerprintMs: Math.round((performance.now() - started) * 100) / 100,
+        };
+        this.pending = { snapshot, report };
+        return report;
+    }
+    complete(usage, timing) {
+        if (!this.pending)
+            return undefined;
+        const { snapshot, report } = this.pending;
+        const previous = this.completed;
+        const cacheRead = usage.cacheRead ?? 0;
+        const cacheWrite = usage.cacheWrite ?? 0;
+        const routeChanged = previous !== undefined && previous.route !== snapshot.route;
+        const hasCache = cacheRead + cacheWrite > 0 || (!routeChanged && this.reportedCache);
+        const comparison = !previous?.usage
+            ? "first_request"
+            : this.edits.has("compaction")
+                ? "compaction"
+                : routeChanged
+                    ? "route_changed"
+                    : !hasCache
+                        ? "cache_unreported"
+                        : "comparable";
+        const reprocessed = comparison === "comparable" && previous?.usage
+            ? 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;
+        this.reportedCache = hasCache;
+        return {
+            ...report,
+            promptTokens: promptTokens(usage),
+            cacheRead,
+            cacheWrite,
+            comparison,
+            reprocessedPromptTokensEstimate: reprocessed,
+            // GG's turn metrics currently have no authoritative effective-dated pricing. Do not
+            // turn a cache-write count (which includes new content) into fabricated dollar waste.
+            costStatus: "unavailable",
+            ttftMs: timing.ttftMs ?? null,
+            providerDurationMs: timing.providerDurationMs,
+        };
+    }
+}
+//# sourceMappingURL=cache-diagnostics.js.map

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

@@ -0,0 +1 @@
+{"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`