@zhin.js/gateway 1.2.0 → 1.4.0

package/lib/usage/prompt-cache.js

@@ -0,0 +1,113 @@
+/** Defaults: at least 20 consecutive zero-cache calls across at least 3 sessions. */
+export const PROMPT_CACHE_HINT_MIN_CALLS = 20;
+export const PROMPT_CACHE_HINT_MIN_SESSIONS = 3;
+/** Share of adjacent same-session requests with an identical prefix needed as evidence. */
+export const PROMPT_CACHE_HINT_MIN_SAME_PREFIX = 0.5;
+function emptyStreak(label) {
+    return { ...(label ? { label } : {}), providerIds: new Set(), calls: 0, reportedZero: 0, sessions: new Set(), compared: 0, same: 0, lastPrefix: new Map() };
+}
+function num(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+/**
+ * Feed trace records in chronological order ({@link visit}), then read {@link hints}.
+ * Sub-agent turns are included with their own session keys.
+ */
+export class PromptCacheProbe {
+    #streaks = new Map();
+    #resolved = new Map();
+    #options;
+    constructor(options = {}) {
+        this.#options = options;
+    }
+    visit(trace) {
+        if (!trace || typeof trace !== 'object')
+            return;
+        const session = typeof trace.session_key === 'string' ? trace.session_key : '';
+        const calls = Array.isArray(trace.model_calls) ? trace.model_calls : [];
+        for (const raw of calls)
+            this.#call(raw, session);
+        const children = Array.isArray(trace.subagents) ? trace.subagents : [];
+        for (const child of children)
+            this.visit(child);
+    }
+    hints() {
+        const minCalls = this.#options.minCalls ?? PROMPT_CACHE_HINT_MIN_CALLS;
+        const minSessions = this.#options.minSessions ?? PROMPT_CACHE_HINT_MIN_SESSIONS;
+        const minRatio = this.#options.minSamePrefixRatio ?? PROMPT_CACHE_HINT_MIN_SAME_PREFIX;
+        const out = [];
+        for (const [provider, streak] of this.#streaks) {
+            if (streak.calls < minCalls || streak.sessions.size < minSessions || streak.compared === 0)
+                continue;
+            const ratio = streak.same / streak.compared;
+            if (ratio < minRatio)
+                continue;
+            const name = streak.label ?? provider;
+            const percent = Math.round(ratio * 100);
+            out.push(Object.freeze({
+                provider,
+                ...(streak.label ? { label: streak.label } : {}),
+                providerIds: Object.freeze([...streak.providerIds].sort()),
+                zeroCacheCalls: streak.calls,
+                sessions: streak.sessions.size,
+                reportedZeroCalls: streak.reportedZero,
+                comparedPairs: streak.compared,
+                samePrefixPairs: streak.same,
+                samePrefixRatio: ratio,
+                message: `${name}：最近连续 ${streak.calls} 次请求（${streak.sessions.size} 个会话）没有命中提示缓存，`
+                    + `而相邻请求有 ${percent}%（${streak.same}/${streak.compared}）前缀相同——该服务可能不支持或未透传 prompt 缓存。`,
+            }));
+        }
+        return out.sort((a, b) => b.zeroCacheCalls - a.zeroCacheCalls);
+    }
+    #resolve(recorded) {
+        const resolveProvider = this.#options.resolveProvider;
+        if (!resolveProvider)
+            return undefined;
+        if (!this.#resolved.has(recorded)) {
+            let value;
+            try {
+                value = resolveProvider(recorded);
+            }
+            catch {
+                value = undefined;
+            }
+            this.#resolved.set(recorded, value);
+        }
+        return this.#resolved.get(recorded);
+    }
+    #call(call, session) {
+        const prompt = num(call.prompt_tokens);
+        if (prompt === undefined || prompt === 0)
+            return;
+        const recorded = typeof call.provider === 'string' && call.provider ? call.provider : 'unknown';
+        const service = this.#resolve(recorded);
+        const key = service?.key ?? recorded;
+        const cacheRead = num(call.cache_read_tokens);
+        if (cacheRead !== undefined && cacheRead > 0) {
+            // A cache hit ends the run: this provider does cache.
+            this.#streaks.set(key, emptyStreak(service?.label));
+            return;
+        }
+        let streak = this.#streaks.get(key);
+        if (!streak) {
+            streak = emptyStreak(service?.label);
+            this.#streaks.set(key, streak);
+        }
+        streak.providerIds.add(recorded);
+        streak.calls += 1;
+        if (cacheRead === 0)
+            streak.reportedZero += 1;
+        streak.sessions.add(session);
+        const prefix = typeof call.prefix_hash === 'string' && call.prefix_hash ? call.prefix_hash : undefined;
+        if (prefix) {
+            const previous = streak.lastPrefix.get(session);
+            if (previous !== undefined) {
+                streak.compared += 1;
+                if (previous === prefix)
+                    streak.same += 1;
+            }
+            streak.lastPrefix.set(session, prefix);
+        }
+    }
+}

package/lib/usage.d.ts

@@ -1,2 +1,3 @@
 /** `@zhin.js/gateway/usage` — usage statistics aggregation. */
 export * from './usage/aggregate.js';
+export * from './usage/prompt-cache.js';

package/lib/usage.js

@@ -1,2 +1,3 @@
 /** `@zhin.js/gateway/usage` — usage statistics aggregation. */
 export * from './usage/aggregate.js';
+export * from './usage/prompt-cache.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/gateway",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Zhin.js management gateway: Console access control, terminal, project configuration and instance supervision (ADR 0054)",
   "type": "module",
   "main": "./lib/index.js",
@@ -72,13 +72,13 @@
     "fs-extra": "^11.4.0",
     "tsx": "^4.23.1",
     "yaml": "^2.9.0",
-    "@zhin.js/console-protocol": "1.2.2",
-    "@zhin.js/database": "1.2.0",
-    "@zhin.js/host-http": "1.2.2",
-    "@zhin.js/logger": "1.1.3",
-    "@zhin.js/plugin-runtime": "1.2.1",
-    "@zhin.js/runtime": "1.2.2",
-    "@zhin.js/scaffold-wizard": "1.1.21"
+    "@zhin.js/console-protocol": "1.4.0",
+    "@zhin.js/database": "1.2.1",
+    "@zhin.js/host-http": "1.4.0",
+    "@zhin.js/logger": "1.2.0",
+    "@zhin.js/plugin-runtime": "1.3.0",
+    "@zhin.js/runtime": "1.4.0",
+    "@zhin.js/scaffold-wizard": "1.3.0"
   },
   "optionalDependencies": {
     "node-pty": "^1.0.0",