@qilin-agent/token-meter 3.1.3 → 3.1.4

package/README.i18n.yaml

@@ -5,60 +5,60 @@
 /:
   en: 6eda56ef696001df
   zh: 13f961071e8609a7
-/qilin-token-meter:
-  en: 1db93ead2015348e
-  zh: d458c4979077cc4a
-/qilin-token-meter/summary:
+/qilin-agent-token-meter:
+  en: 8ae25b1d039ca515
+  zh: b278cba8dfc29d0e
+/qilin-agent-token-meter/summary:
   en: 106e3eda9a85bdd1
   zh: 051bc764bf7a1912
-/qilin-token-meter/table-of-contents:
+/qilin-agent-token-meter/table-of-contents:
   en: d152484eb41ac6b4
   zh: 09388d293f9be9cb
-/qilin-token-meter/use-this-package:
+/qilin-agent-token-meter/use-this-package:
   en: 5907ef1472773a47
   zh: 06f1e988290a32c6
-/qilin-token-meter/use-this-package/when-to-choose-it:
+/qilin-agent-token-meter/use-this-package/when-to-choose-it:
   en: e8c4cd1e945f86ba
   zh: 133c1f1a85179d30
-/qilin-token-meter/use-this-package/measuring-pressure:
+/qilin-agent-token-meter/use-this-package/measuring-pressure:
   en: 58de3b364ab5af6b
   zh: c5440af43d321e56
-/qilin-token-meter/use-this-package/session-projections:
+/qilin-agent-token-meter/use-this-package/session-projections:
   en: 0a4c3ae2763be227
   zh: 0e2c5a77f9b4b94f
-/qilin-token-meter/use-this-package/composition:
+/qilin-agent-token-meter/use-this-package/composition:
   en: 27b823c34f4fd96c
   zh: 904373f93056da3e
-/qilin-token-meter/use-this-package/reading-the-numbers:
+/qilin-agent-token-meter/use-this-package/reading-the-numbers:
   en: 7950203e0c146123
   zh: 4fe421b2268f12a9
-/qilin-token-meter/understand-the-implementation:
+/qilin-agent-token-meter/understand-the-implementation:
   en: 9630d7e26193a512
   zh: 94222c2a487c4b8c
-/qilin-token-meter/understand-the-implementation/design-philosophy:
+/qilin-agent-token-meter/understand-the-implementation/design-philosophy:
   en: 921a2c40433abc06
   zh: 5172de58e8724be8
-/qilin-token-meter/understand-the-implementation/source-map:
+/qilin-agent-token-meter/understand-the-implementation/source-map:
   en: 0bea6321416c49d4
   zh: 5446b39910df9829
-/qilin-token-meter/understand-the-implementation/fold-flow:
+/qilin-agent-token-meter/understand-the-implementation/fold-flow:
   en: c97959d84cf8a1a4
   zh: f17570caa42a1a8e
-/qilin-token-meter/understand-the-implementation/projection-semantics:
+/qilin-agent-token-meter/understand-the-implementation/projection-semantics:
   en: 0269213216881c60
   zh: 5c1c4c46c0e6d109
-/qilin-token-meter/further-exploration:
+/qilin-agent-token-meter/further-exploration:
   en: 0e57783e04ab4bae
   zh: df3e56f0117e125e
-/qilin-token-meter/model-experience:
+/qilin-agent-token-meter/model-experience:
   en: 17231a6190c084ce
   zh: 7485c8e03f5a6726
-/qilin-token-meter/model-experience/kv-cache-effect:
+/qilin-agent-token-meter/model-experience/kv-cache-effect:
   en: 40294c1c31b74824
   zh: c2284876b56d2dbc
-/qilin-token-meter/known-limitations-and-deferred-work:
+/qilin-agent-token-meter/known-limitations-and-deferred-work:
   en: a8c57e6f8c5009a2
   zh: 5975018d14bfbdbb
-/qilin-token-meter/known-limitations-and-deferred-work/dev-note:
+/qilin-agent-token-meter/known-limitations-and-deferred-work/dev-note:
   en: 86d686346e2ee1d8
   zh: d660b9884e4764a4

package/lib/index.js

@@ -4,6 +4,7 @@ import { assembleAssistantStream, lastAssistantStreamChunk } from "@qilin-agent/
 import { deepFreeze } from "@qilin-agent/util-values";
 import { SessionLogOffset, SessionSeq, canonicalHeader, deriveEventMessage, headerEquals, isSurfaceEvent } from "@qilin-agent/session";
 import { z as z$1 } from "zod";
+import { lastAssistantStreamChunk as lastAssistantStreamChunk$1 } from "@qilin-agent/llm/assistant-stream";
 //#region lib/types/estimate.js
 /**
 * Fixed-density heuristic token pricing shared by the meter service and the
@@ -583,6 +584,220 @@ function priceSurface(nodes, pricing, fileText) {
 	};
 }
 //#endregion
+//#region lib/types/turn-usage.js
+function isCount(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function safeSum(values) {
+	let total = 0;
+	for (const value of values) {
+		total += value;
+		if (!Number.isSafeInteger(total)) return void 0;
+	}
+	return total;
+}
+function messageRoute(message) {
+	const { provider, model } = message.source;
+	return provider.length > 0 && model.length > 0 ? {
+		provider,
+		model
+	} : void 0;
+}
+function streamUsage(stream) {
+	return lastAssistantStreamChunk$1(stream, "usage")?.usage;
+}
+function normalizeUsage(usage, route) {
+	const { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, reasoningTokens, totalTokens } = usage;
+	if (!isCount(inputTokens) || !isCount(outputTokens)) return void 0;
+	if (cacheReadTokens !== void 0 && !isCount(cacheReadTokens)) return void 0;
+	if (cacheWriteTokens !== void 0 && !isCount(cacheWriteTokens)) return void 0;
+	if (reasoningTokens !== void 0 && (!isCount(reasoningTokens) || reasoningTokens > outputTokens)) return;
+	const knownPrompt = safeSum([
+		inputTokens,
+		...cacheReadTokens === void 0 ? [] : [cacheReadTokens],
+		...cacheWriteTokens === void 0 ? [] : [cacheWriteTokens]
+	]);
+	if (knownPrompt === void 0) return void 0;
+	let exactTotal;
+	if (totalTokens !== void 0) {
+		if (!isCount(totalTokens)) return void 0;
+		const exactPrompt = totalTokens - outputTokens;
+		if (!isCount(exactPrompt) || exactPrompt < knownPrompt) return void 0;
+		if (cacheReadTokens !== void 0 && cacheWriteTokens !== void 0 && exactPrompt !== knownPrompt) return;
+		exactTotal = totalTokens;
+	} else {
+		if (cacheReadTokens === void 0 || cacheWriteTokens === void 0) return void 0;
+		const derivedTotal = safeSum([knownPrompt, outputTokens]);
+		if (derivedTotal === void 0) return void 0;
+		exactTotal = derivedTotal;
+	}
+	return {
+		inputTokens,
+		outputTokens,
+		totalTokens: exactTotal,
+		...cacheReadTokens === void 0 ? {} : { cacheReadTokens },
+		...cacheWriteTokens === void 0 ? {} : { cacheWriteTokens },
+		...reasoningTokens === void 0 ? {} : { reasoningTokens },
+		...route === void 0 ? {} : { route }
+	};
+}
+function aggregateAttempts(attempts) {
+	if (attempts.length === 0) return void 0;
+	const inputTokens = safeSum(attempts.map((attempt) => attempt.inputTokens));
+	const outputTokens = safeSum(attempts.map((attempt) => attempt.outputTokens));
+	const totalTokens = safeSum(attempts.map((attempt) => attempt.totalTokens));
+	if (inputTokens === void 0 || outputTokens === void 0 || totalTokens === void 0) return void 0;
+	const cacheRead = attempts.map((attempt) => attempt.cacheReadTokens);
+	const cacheWrite = attempts.map((attempt) => attempt.cacheWriteTokens);
+	const reasoning = attempts.map((attempt) => attempt.reasoningTokens);
+	const cacheReadTokens = cacheRead.every(isCount) ? safeSum(cacheRead) : void 0;
+	const cacheWriteTokens = cacheWrite.every(isCount) ? safeSum(cacheWrite) : void 0;
+	const reasoningTokens = reasoning.every(isCount) ? safeSum(reasoning) : void 0;
+	let routes;
+	const attributed = attempts.map((attempt) => attempt.route);
+	if (attributed.every((route) => route !== void 0)) {
+		const unique = /* @__PURE__ */ new Map();
+		for (const route of attributed) unique.set(`${route.provider}\0${route.model}`, route);
+		routes = [...unique.values()];
+	}
+	return {
+		uncachedInputTokens: inputTokens,
+		outputTokens,
+		totalTokens,
+		...cacheReadTokens === void 0 ? {} : { cacheReadTokens },
+		...cacheWriteTokens === void 0 ? {} : { cacheWriteTokens },
+		...reasoningTokens === void 0 ? {} : { reasoningTokens },
+		...routes === void 0 ? {} : { routes }
+	};
+}
+function sameAttempt(state, turn, step) {
+	return state.turn === turn && state.step === step;
+}
+/**
+* Fold one complete Turn's durable attempt lifecycle into exact token accounting.
+*
+* No attempt is inferred from a usage sample. Any missing lifecycle boundary,
+* incomplete attempt usage, unsafe count, or contradictory exact total makes
+* the whole disclosure unavailable.
+* @param events - Turn-local durable events from `turn/start` through `turn/end`.
+* @returns exact aggregate usage, or undefined when it cannot be proven.
+*/
+function deriveTurnTokenUsage(events) {
+	let state = { kind: "idle" };
+	const attempts = [];
+	let turn;
+	let sawEnd = false;
+	let invalid = false;
+	const closeOpen = (route) => {
+		if (state.kind !== "open" || state.sample === void 0) return false;
+		const normalized = normalizeUsage(state.sample, route);
+		if (normalized === void 0) return false;
+		attempts.push(normalized);
+		return true;
+	};
+	for (const event of events) {
+		if (invalid) break;
+		if (event.type === "turn/start") {
+			if (turn !== void 0 || state.kind !== "idle") invalid = true;
+			else turn = event.data.turn;
+			continue;
+		}
+		if (turn === void 0) {
+			invalid = true;
+			break;
+		}
+		if (event.type === "turn/end") {
+			if (event.data.turn !== turn || state.kind !== "idle" || sawEnd) invalid = true;
+			else sawEnd = true;
+			continue;
+		}
+		if (sawEnd) {
+			invalid = true;
+			break;
+		}
+		if (event.type === "step/start") {
+			if (event.data.turn !== turn || state.kind !== "idle") invalid = true;
+			else state = {
+				kind: "open",
+				turn,
+				step: event.data.step
+			};
+			continue;
+		}
+		if (event.type === "llm/retry-started") {
+			if (event.data.turn !== turn || state.kind !== "settled" || state.by !== "retry" || !sameAttempt(state, event.data.turn, event.data.step)) invalid = true;
+			else state = {
+				kind: "open",
+				turn,
+				step: event.data.step
+			};
+			continue;
+		}
+		if (event.type === "assistant/attempt") {
+			if (event.data.turn !== turn || state.kind !== "open" || !sameAttempt(state, event.data.turn, event.data.step)) {
+				invalid = true;
+				continue;
+			}
+			const sample = streamUsage(event.data.stream) ?? state.sample;
+			state = {
+				kind: "open",
+				turn,
+				step: event.data.step,
+				...sample === void 0 ? {} : { sample }
+			};
+			if (!closeOpen()) invalid = true;
+			else state = {
+				kind: "finishClosed",
+				turn,
+				step: event.data.step
+			};
+			continue;
+		}
+		if (event.type === "assistant/message") {
+			if (event.data.turn !== turn || state.kind !== "open" || !sameAttempt(state, event.data.turn, event.data.step)) {
+				invalid = true;
+				continue;
+			}
+			const sample = event.data.usage ?? streamUsage(event.data.stream);
+			if (sample !== void 0) state = {
+				...state,
+				sample
+			};
+			if (!closeOpen(messageRoute(event.data.message))) invalid = true;
+			else state = {
+				kind: "settled",
+				turn,
+				step: event.data.step,
+				by: "message"
+			};
+			continue;
+		}
+		if (event.type === "llm/retry") {
+			if (event.data.turn !== turn || state.kind === "idle" || !sameAttempt(state, event.data.turn, event.data.step)) {
+				invalid = true;
+				continue;
+			}
+			if (state.kind === "settled" || state.kind === "open" && !closeOpen()) invalid = true;
+			if (!invalid) state = {
+				kind: "settled",
+				turn,
+				step: event.data.step,
+				by: "retry"
+			};
+			continue;
+		}
+		if (event.type === "step/end") {
+			if (event.data.turn !== turn || state.kind === "idle" || !sameAttempt(state, event.data.turn, event.data.step)) {
+				invalid = true;
+				continue;
+			}
+			if (state.kind === "open" && !closeOpen()) invalid = true;
+			if (!invalid) state = { kind: "idle" };
+		}
+	}
+	return invalid || !sawEnd || state.kind !== "idle" ? void 0 : aggregateAttempts(attempts);
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Single replay-aware token-meter service for request and surface pressure.
@@ -792,4 +1007,4 @@ var TokenMeter = class extends Service {
 	}
 };
 //#endregion
-export { TokenMeter, TokenMeter as default };
+export { TokenMeter, TokenMeter as default, deriveTurnTokenUsage };

package/lib/types/index.d.ts

@@ -9,6 +9,7 @@ import type { Message } from '@qilin-agent/llm';
 import type { EpochHeader, Session } from '@qilin-agent/session';
 import type { TokenMeasurement, TokenMeterConfig } from './types.ts';
 export type * from './types.ts';
+export { deriveTurnTokenUsage } from './turn-usage.ts';
 export type * from './usage-projection.ts';
 export type * from './breakdown-projection.ts';
 declare module '@qilin-agent/kylin' {

package/lib/types/index.js

@@ -13,6 +13,9 @@ import { contextPressureProjectionDefinition, tokenUsageProjectionDefinition } f
 import { estimateContent, estimateMessage, estimateToolsTokens, ROLE_OVERHEAD } from "./estimate.js";
 import { commitSurfaceTokens, planSurfaceTokens } from "./surface-fold.js";
 import { priceSurface } from "./route-pricing.js";
+// The exact per-Turn fold, for consumers that account for a Turn outside the
+// browser transcript; a deployment's usage reporter is the current one.
+export { deriveTurnTokenUsage } from "./turn-usage.js";
 /** Sum disjoint provider usage buckets without double-counting reasoning output. */
 function usageTokens(usage) {
     return usage.inputTokens

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@qilin-agent/token-meter",
   "description": "Replay-aware token measurement service (ctx.tokenMeter) for the QiLin",
-  "version": "3.1.3",
+  "version": "3.1.4",
   "publishConfig": {
     "access": "public"
   },
@@ -39,26 +39,26 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@qilin-agent/kylin": "~4.0.3",
-    "@qilin-agent/llm-retry": "3.1.3",
-    "@qilin-agent/compaction": "3.1.3",
-    "@qilin-agent/llm": "3.1.3",
-    "@qilin-agent/session": "3.1.3",
-    "@qilin-agent/compaction-image-offload": "3.1.3",
-    "@qilin-agent/session-projection": "3.1.3"
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/compaction": "3.1.4",
+    "@qilin-agent/llm-retry": "3.1.4",
+    "@qilin-agent/session-projection": "3.1.4",
+    "@qilin-agent/session": "3.1.4",
+    "@qilin-agent/compaction-image-offload": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3"
   },
   "dependencies": {
     "zod": "^4.4.3",
-    "@qilin-agent/schemastery": "~3.18.3",
-    "@qilin-agent/util-values": "3.1.3"
+    "@qilin-agent/util-values": "3.1.4",
+    "@qilin-agent/schemastery": "~3.18.3"
   },
   "devDependencies": {
-    "@qilin-agent/compaction": "3.1.3",
+    "@qilin-agent/compaction": "3.1.4",
+    "@qilin-agent/llm": "3.1.4",
     "@qilin-agent/kylin": "~4.0.3",
-    "@qilin-agent/llm-retry": "3.1.3",
-    "@qilin-agent/llm": "3.1.3",
-    "@qilin-agent/session": "3.1.3",
-    "@qilin-agent/compaction-image-offload": "3.1.3",
-    "@qilin-agent/session-projection": "3.1.3"
+    "@qilin-agent/llm-retry": "3.1.4",
+    "@qilin-agent/session": "3.1.4",
+    "@qilin-agent/session-projection": "3.1.4",
+    "@qilin-agent/compaction-image-offload": "3.1.4"
   }
 }