@qilin-agent/token-meter 0.0.0-stage → 3.1.3

package/lib/types/usage-projection.js

@@ -0,0 +1,189 @@
+/**
+ * Pure folds for durable provider-reported token usage and context occupancy.
+ */
+import { z } from 'zod';
+import { lastAssistantStreamChunk } from '@qilin-agent/llm';
+import { SessionSeq } from '@qilin-agent/session';
+import { foldSurfaceProjection } from "./surface-projection.js";
+const zeroBuckets = () => ({
+    uncachedInputTokens: 0,
+    outputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+});
+const bucketsFrom = (usage) => ({
+    uncachedInputTokens: usage.inputTokens,
+    outputTokens: usage.outputTokens,
+    cacheReadTokens: usage.cacheReadTokens ?? 0,
+    cacheWriteTokens: usage.cacheWriteTokens ?? 0,
+});
+const bucketsEqual = (left, right) => left.uncachedInputTokens === right.uncachedInputTokens
+    && left.outputTokens === right.outputTokens
+    && left.cacheReadTokens === right.cacheReadTokens
+    && left.cacheWriteTokens === right.cacheWriteTokens;
+const addReplacing = (totals, previous, next) => ({
+    uncachedInputTokens: totals.uncachedInputTokens - (previous?.uncachedInputTokens ?? 0) + next.uncachedInputTokens,
+    outputTokens: totals.outputTokens - (previous?.outputTokens ?? 0) + next.outputTokens,
+    cacheReadTokens: totals.cacheReadTokens - (previous?.cacheReadTokens ?? 0) + next.cacheReadTokens,
+    cacheWriteTokens: totals.cacheWriteTokens - (previous?.cacheWriteTokens ?? 0) + next.cacheWriteTokens,
+});
+const projectionSchema = z.object({
+    uncachedInputTokens: z.number().int().nonnegative(),
+    outputTokens: z.number().int().nonnegative(),
+    cacheReadTokens: z.number().int().nonnegative(),
+    cacheWriteTokens: z.number().int().nonnegative(),
+}).strict();
+/**
+ * The token-usage unit's state schema — the one definition of the state
+ * shape; the state type is inferred from it.
+ */
+const tokenUsageStateSchema = z.object({
+    totals: projectionSchema,
+    last: z.object({
+        turn: z.number().int().nonnegative(),
+        step: z.number().int().nonnegative(),
+        buckets: projectionSchema,
+    }).nullable(),
+}).strict();
+const pressureSchema = z.object({
+    pressureTokens: z.number().int().nonnegative().optional(),
+    projectedTokens: z.number().int().nonnegative().optional(),
+    contextWindow: z.number().int().positive().optional(),
+}).strict().transform(({ pressureTokens, projectedTokens, contextWindow }) => ({
+    ...pressureTokens === undefined ? {} : { pressureTokens },
+    ...projectedTokens === undefined ? {} : { projectedTokens },
+    ...contextWindow === undefined ? {} : { contextWindow },
+}));
+/** Prompt-side pressure of one request: input plus cache traffic, no output. */
+const pressureFrom = (usage) => usage.inputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0);
+/** The usage one durable Assistant settlement reports for its attempt, if any. */
+function usageOf(event) {
+    if (event.type === 'assistant/message' && event.data.usage !== undefined)
+        return event.data.usage;
+    if (event.type !== 'assistant/message' && event.type !== 'assistant/attempt')
+        return undefined;
+    return lastAssistantStreamChunk(event.data.stream, 'usage')?.usage;
+}
+/** The context-pressure state schema and source of its inferred type. */
+const contextPressureStateSchema = z.object({
+    contextWindow: z.number().int().positive().optional(),
+    pressureTokens: z.number().int().nonnegative().optional(),
+    surfaceTokens: z.number().int().nonnegative(),
+    sampledSurfaceTokens: z.number().int().nonnegative().optional(),
+    claim: z.object({
+        start: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionSeq),
+        end: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionSeq),
+        tokens: z.number().int().nonnegative(),
+    }).optional(),
+}).strict();
+/**
+ * Token-meter's session projection unit.
+ *
+ * Each v2 Assistant settlement contributes the last usage sample embedded in
+ * its stream. `llm/retry-started` closes the replacement slot so the retried
+ * attempt adds to the total.
+ */
+export const tokenUsageProjectionDefinition = {
+    key: 'tokenUsage',
+    stateVersion: 2,
+    stateSchema: tokenUsageStateSchema,
+    init: () => ({ totals: zeroBuckets(), last: null }),
+    apply: (state, event) => {
+        if (event.type === 'llm/retry-started') {
+            return state.last?.turn === event.data.turn && state.last.step === event.data.step
+                ? { ...state, last: null }
+                : state;
+        }
+        if (event.type !== 'assistant/message' && event.type !== 'assistant/attempt') {
+            return state;
+        }
+        const sample = usageOf(event);
+        if (sample === undefined)
+            return state;
+        const { turn, step } = event.data;
+        const usage = sample;
+        const buckets = bucketsFrom(usage);
+        const previous = state.last !== null
+            && state.last.turn === turn
+            && state.last.step === step
+            ? state.last.buckets
+            : undefined;
+        if (previous !== undefined && bucketsEqual(previous, buckets))
+            return state;
+        return {
+            totals: addReplacing(state.totals, previous, buckets),
+            last: { turn, step, buckets },
+        };
+    },
+    wire: { viewSchema: projectionSchema, view: state => state.totals },
+};
+/**
+ * Token-meter's context-occupancy projection unit.
+ *
+ * Independent last-wins slots: the newest usage sample supplies the provider
+ * numerator, the newest `request/context` record the denominator. Both are
+ * whole values, so replay order alone decides the result and no cross-field
+ * consistency is claimed — the pair is explicitly not one atomic request
+ * observation (see {@link ContextPressureProjection}).
+ *
+ * `pressureTokens` is prompt-side only, so it holds still while a turn streams
+ * and steps forward once the next request reports its usage. Because nothing
+ * but a request reports usage, it also cannot see a compaction: the fold
+ * therefore carries a running surface total alongside it and publishes
+ * `projectedTokens` — the sample plus the surface's signed movement since it
+ * was taken — so occupancy answers for the next request rather than the last
+ * one. The total rides {@link foldSurfaceProjection}, so the state stays O(1)
+ * and a replacement shrinks it by its logged shadow price. A replacement
+ * without a claim preserves the previous total. A usage sample is stamped
+ * BEFORE the same event joins the surface, so an `assistant/message` anchors
+ * against the surface its own request saw.
+ */
+export const contextPressureProjectionDefinition = {
+    key: 'contextPressure',
+    stateVersion: 5,
+    stateSchema: contextPressureStateSchema,
+    init: () => ({ surfaceTokens: 0 }),
+    apply: (state, event) => {
+        const fold = foldSurfaceProjection(state.claim, event);
+        let next = state;
+        if (event.type === 'request/context') {
+            const contextWindow = event.data.contextWindow;
+            if (contextWindow !== state.contextWindow) {
+                if (contextWindow !== undefined) {
+                    next = { ...next, contextWindow };
+                }
+                else {
+                    const { contextWindow: _removed, ...withoutContextWindow } = next;
+                    next = withoutContextWindow;
+                }
+            }
+        }
+        const usage = usageOf(event);
+        if (usage !== undefined) {
+            const pressureTokens = pressureFrom(usage);
+            if (pressureTokens !== next.pressureTokens || next.sampledSurfaceTokens !== next.surfaceTokens) {
+                next = { ...next, pressureTokens, sampledSurfaceTokens: next.surfaceTokens };
+            }
+        }
+        if (fold.deltaTokens !== 0) {
+            next = { ...next, surfaceTokens: next.surfaceTokens + fold.deltaTokens };
+        }
+        // A defined fold.claim is always freshly built, so presence decides claim
+        // bookkeeping: no claim before or after this event leaves `next` as is.
+        if (state.claim === undefined && fold.claim === undefined)
+            return next;
+        const { claim: _expired, ...withoutClaim } = next;
+        return fold.claim === undefined ? withoutClaim : { ...withoutClaim, claim: fold.claim };
+    },
+    wire: {
+        viewSchema: pressureSchema,
+        view: ({ contextWindow, pressureTokens, surfaceTokens, sampledSurfaceTokens }) => ({
+            ...contextWindow === undefined ? {} : { contextWindow },
+            ...pressureTokens === undefined ? {} : { pressureTokens },
+            ...pressureTokens === undefined || sampledSurfaceTokens === undefined
+                ? {}
+                : { projectedTokens: Math.max(0, pressureTokens + surfaceTokens - sampledSurfaceTokens) },
+        }),
+    },
+};
+//# sourceMappingURL=usage-projection.js.map

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@qilin-agent/token-meter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Replay-aware token measurement service (ctx.tokenMeter) for the QiLin",
+  "version": "3.1.3",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/llm/token-meter"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client.d.ts",
+      "default": "./lib/types/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json",
+    "./estimate": {
+      "types": "./lib/types/estimate.d.ts",
+      "default": "./lib/types/estimate.js"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "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"
+  },
+  "dependencies": {
+    "zod": "^4.4.3",
+    "@qilin-agent/schemastery": "~3.18.3",
+    "@qilin-agent/util-values": "3.1.3"
+  },
+  "devDependencies": {
+    "@qilin-agent/compaction": "3.1.3",
+    "@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"
+  }
 }