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

package/lib/types/turn-usage.js

@@ -0,0 +1,229 @@
+import { lastAssistantStreamChunk } from '@qilin-agent/llm/assistant-stream';
+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 undefined;
+    }
+    return total;
+}
+function messageRoute(message) {
+    const { provider, model } = message.source;
+    return provider.length > 0 && model.length > 0 ? { provider, model } : undefined;
+}
+function streamUsage(stream) {
+    return lastAssistantStreamChunk(stream, 'usage')?.usage;
+}
+function normalizeUsage(usage, route) {
+    const { inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens, reasoningTokens, totalTokens, } = usage;
+    if (!isCount(inputTokens) || !isCount(outputTokens))
+        return undefined;
+    if (cacheReadTokens !== undefined && !isCount(cacheReadTokens))
+        return undefined;
+    if (cacheWriteTokens !== undefined && !isCount(cacheWriteTokens))
+        return undefined;
+    if (reasoningTokens !== undefined && (!isCount(reasoningTokens) || reasoningTokens > outputTokens)) {
+        return undefined;
+    }
+    const knownPrompt = safeSum([
+        inputTokens,
+        ...cacheReadTokens === undefined ? [] : [cacheReadTokens],
+        ...cacheWriteTokens === undefined ? [] : [cacheWriteTokens],
+    ]);
+    if (knownPrompt === undefined)
+        return undefined;
+    let exactTotal;
+    if (totalTokens !== undefined) {
+        if (!isCount(totalTokens))
+            return undefined;
+        const exactPrompt = totalTokens - outputTokens;
+        if (!isCount(exactPrompt) || exactPrompt < knownPrompt)
+            return undefined;
+        if (cacheReadTokens !== undefined && cacheWriteTokens !== undefined && exactPrompt !== knownPrompt) {
+            return undefined;
+        }
+        exactTotal = totalTokens;
+    }
+    else {
+        if (cacheReadTokens === undefined || cacheWriteTokens === undefined)
+            return undefined;
+        const derivedTotal = safeSum([knownPrompt, outputTokens]);
+        if (derivedTotal === undefined)
+            return undefined;
+        exactTotal = derivedTotal;
+    }
+    return {
+        inputTokens,
+        outputTokens,
+        totalTokens: exactTotal,
+        ...cacheReadTokens === undefined ? {} : { cacheReadTokens },
+        ...cacheWriteTokens === undefined ? {} : { cacheWriteTokens },
+        ...reasoningTokens === undefined ? {} : { reasoningTokens },
+        ...route === undefined ? {} : { route },
+    };
+}
+function aggregateAttempts(attempts) {
+    if (attempts.length === 0)
+        return undefined;
+    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 === undefined || outputTokens === undefined || totalTokens === undefined)
+        return undefined;
+    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) : undefined;
+    const cacheWriteTokens = cacheWrite.every(isCount) ? safeSum(cacheWrite) : undefined;
+    const reasoningTokens = reasoning.every(isCount) ? safeSum(reasoning) : undefined;
+    // A present cache bucket is bounded by exact prompt, and reasoning is bounded
+    // by output. Safe required aggregates therefore imply safe optional sums.
+    let routes;
+    const attributed = attempts.map(attempt => attempt.route);
+    if (attributed.every((route) => route !== undefined)) {
+        const unique = new Map();
+        for (const route of attributed)
+            unique.set(`${route.provider}\0${route.model}`, route);
+        routes = [...unique.values()];
+    }
+    return {
+        uncachedInputTokens: inputTokens,
+        outputTokens,
+        totalTokens,
+        ...cacheReadTokens === undefined ? {} : { cacheReadTokens },
+        ...cacheWriteTokens === undefined ? {} : { cacheWriteTokens },
+        ...reasoningTokens === undefined ? {} : { reasoningTokens },
+        ...routes === undefined ? {} : { 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.
+ */
+export 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 === undefined)
+            return false;
+        const normalized = normalizeUsage(state.sample, route);
+        if (normalized === undefined)
+            return false;
+        attempts.push(normalized);
+        return true;
+    };
+    for (const event of events) {
+        if (invalid)
+            break;
+        if (event.type === 'turn/start') {
+            if (turn !== undefined || state.kind !== 'idle')
+                invalid = true;
+            else
+                turn = event.data.turn;
+            continue;
+        }
+        if (turn === undefined) {
+            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 === undefined ? {} : { 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 !== undefined)
+                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' ? undefined : aggregateAttempts(attempts);
+}
+//# sourceMappingURL=turn-usage.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Public configuration and measurement vocabulary for replay token metering.
+ *
+ * @module @qilin-agent/token-meter/types
+ */
+import type { TokenUsage } from '@qilin-agent/llm';
+import type { SessionLogOffset, SessionSeq } from '@qilin-agent/session/types';
+export type { ContextBreakdownProjection, ContextPressureProjection, TokenUsageProjection } from './projection.ts';
+/** Token-meter plugin configuration; the fixed estimator has no settings. */
+export type TokenMeterConfig = Record<string, never>;
+/** The baseline from which a signed surface delta produces current pressure. */
+export type TokenMeasurementBaseline = {
+    readonly kind: 'none';
+    readonly tokens: 0;
+} | {
+    readonly kind: 'estimated';
+    readonly tokens: number;
+} | {
+    readonly kind: 'usage';
+    readonly tokens: number;
+    readonly usage: Readonly<TokenUsage>;
+};
+/** Detached immutable request-pressure and surface snapshot at one consumed log revision. */
+export interface TokenMeasurement {
+    /** Number of durable events consumed; equal to the next unread event seq. */
+    readonly logRevision: SessionLogOffset;
+    /** Provider or heuristic anchor used for this measurement. */
+    readonly baseline: TokenMeasurementBaseline;
+    /** Signed repricing of current surface content relative to the baseline anchor. */
+    readonly surfaceDeltaTokens: number;
+    /** Non-negative current request-and-response pressure. */
+    readonly totalTokens: number;
+    /** Total route-priced request tokens across the current surface; equals the sum of the node prices. */
+    readonly surfaceTokens: number;
+    /** Current surface nodes in positional head-to-tail order. */
+    readonly nodes: readonly TokenSurfaceNode[];
+}
+/** One token-priced node in the current ordered session surface. */
+export interface TokenSurfaceNode {
+    /** Durable sequence number of the surface event. */
+    readonly seq: SessionSeq;
+    /**
+     * Request-pressure tokens for the exact message projected by this node under
+     * the measured route: image occurrences carry the route's declared visual
+     * price when the routed adapter declares one, and the fixed heuristic
+     * otherwise. Trigger, retention, and range selection all read this price.
+     */
+    readonly tokens: number;
+    /**
+     * Fixed-heuristic tokens for the same message, independent of any route.
+     * The shadow-price protocol prices replacements with this value so the O(1)
+     * projection fold stays in agreement with its own appends.
+     */
+    readonly heuristicTokens: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,7 @@
+/**
+ * Public configuration and measurement vocabulary for replay token metering.
+ *
+ * @module @qilin-agent/token-meter/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/lib/types/usage-projection.d.ts

@@ -0,0 +1,223 @@
+/**
+ * Pure folds for durable provider-reported token usage and context occupancy.
+ */
+import { z } from 'zod';
+import { SessionSeq } from '@qilin-agent/session';
+import type { SessionEvent } from '@qilin-agent/session';
+import type { ContextPressureProjection, TokenUsageProjection } from './projection.ts';
+/**
+ * The token-usage unit's state schema — the one definition of the state
+ * shape; the state type is inferred from it.
+ */
+declare const tokenUsageStateSchema: z.ZodObject<{
+    totals: z.ZodObject<{
+        uncachedInputTokens: z.ZodNumber;
+        outputTokens: z.ZodNumber;
+        cacheReadTokens: z.ZodNumber;
+        cacheWriteTokens: z.ZodNumber;
+    }, z.core.$strict>;
+    last: z.ZodNullable<z.ZodObject<{
+        turn: z.ZodNumber;
+        step: z.ZodNumber;
+        buckets: z.ZodObject<{
+            uncachedInputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+            cacheReadTokens: z.ZodNumber;
+            cacheWriteTokens: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+type TokenUsageState = z.infer<typeof tokenUsageStateSchema>;
+declare module '@qilin-agent/session-projection/types' {
+    interface SessionProjectionStateMap {
+        tokenUsage: TokenUsageState;
+        contextPressure: ContextPressureState;
+    }
+}
+/** The context-pressure state schema and source of its inferred type. */
+declare const contextPressureStateSchema: z.ZodObject<{
+    contextWindow: z.ZodOptional<z.ZodNumber>;
+    pressureTokens: z.ZodOptional<z.ZodNumber>;
+    surfaceTokens: z.ZodNumber;
+    sampledSurfaceTokens: z.ZodOptional<z.ZodNumber>;
+    claim: z.ZodOptional<z.ZodObject<{
+        start: z.ZodPipe<z.ZodNumber, z.ZodTransform<SessionSeq, number>>;
+        end: z.ZodPipe<z.ZodNumber, z.ZodTransform<SessionSeq, number>>;
+        tokens: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
+type ContextPressureState = z.infer<typeof contextPressureStateSchema>;
+/**
+ * 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 declare const tokenUsageProjectionDefinition: {
+    key: "tokenUsage";
+    stateVersion: number;
+    stateSchema: z.ZodObject<{
+        totals: z.ZodObject<{
+            uncachedInputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+            cacheReadTokens: z.ZodNumber;
+            cacheWriteTokens: z.ZodNumber;
+        }, z.core.$strict>;
+        last: z.ZodNullable<z.ZodObject<{
+            turn: z.ZodNumber;
+            step: z.ZodNumber;
+            buckets: z.ZodObject<{
+                uncachedInputTokens: z.ZodNumber;
+                outputTokens: z.ZodNumber;
+                cacheReadTokens: z.ZodNumber;
+                cacheWriteTokens: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strip>>;
+    }, z.core.$strict>;
+    init: () => {
+        totals: TokenUsageProjection;
+        last: null;
+    };
+    apply: (state: NoInfer<{
+        totals: {
+            uncachedInputTokens: number;
+            outputTokens: number;
+            cacheReadTokens: number;
+            cacheWriteTokens: number;
+        };
+        last: {
+            turn: number;
+            step: number;
+            buckets: {
+                uncachedInputTokens: number;
+                outputTokens: number;
+                cacheReadTokens: number;
+                cacheWriteTokens: number;
+            };
+        } | null;
+    }>, event: SessionEvent) => {
+        totals: {
+            uncachedInputTokens: number;
+            outputTokens: number;
+            cacheReadTokens: number;
+            cacheWriteTokens: number;
+        };
+        last: {
+            turn: number;
+            step: number;
+            buckets: {
+                uncachedInputTokens: number;
+                outputTokens: number;
+                cacheReadTokens: number;
+                cacheWriteTokens: number;
+            };
+        } | null;
+    };
+    wire: {
+        viewSchema: z.ZodObject<{
+            uncachedInputTokens: z.ZodNumber;
+            outputTokens: z.ZodNumber;
+            cacheReadTokens: z.ZodNumber;
+            cacheWriteTokens: z.ZodNumber;
+        }, z.core.$strict>;
+        view: (state: NoInfer<{
+            totals: {
+                uncachedInputTokens: number;
+                outputTokens: number;
+                cacheReadTokens: number;
+                cacheWriteTokens: number;
+            };
+            last: {
+                turn: number;
+                step: number;
+                buckets: {
+                    uncachedInputTokens: number;
+                    outputTokens: number;
+                    cacheReadTokens: number;
+                    cacheWriteTokens: number;
+                };
+            } | null;
+        }>) => {
+            uncachedInputTokens: number;
+            outputTokens: number;
+            cacheReadTokens: number;
+            cacheWriteTokens: number;
+        };
+    };
+};
+/**
+ * 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 declare const contextPressureProjectionDefinition: {
+    key: "contextPressure";
+    stateVersion: number;
+    stateSchema: z.ZodObject<{
+        contextWindow: z.ZodOptional<z.ZodNumber>;
+        pressureTokens: z.ZodOptional<z.ZodNumber>;
+        surfaceTokens: z.ZodNumber;
+        sampledSurfaceTokens: z.ZodOptional<z.ZodNumber>;
+        claim: z.ZodOptional<z.ZodObject<{
+            start: z.ZodPipe<z.ZodNumber, z.ZodTransform<SessionSeq, number>>;
+            end: z.ZodPipe<z.ZodNumber, z.ZodTransform<SessionSeq, number>>;
+            tokens: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strict>;
+    init: () => {
+        surfaceTokens: number;
+    };
+    apply: (state: NoInfer<{
+        surfaceTokens: number;
+        contextWindow?: number | undefined;
+        pressureTokens?: number | undefined;
+        sampledSurfaceTokens?: number | undefined;
+        claim?: {
+            start: SessionSeq;
+            end: SessionSeq;
+            tokens: number;
+        } | undefined;
+    }>, event: SessionEvent) => {
+        surfaceTokens: number;
+        contextWindow?: number | undefined;
+        pressureTokens?: number | undefined;
+        sampledSurfaceTokens?: number | undefined;
+    };
+    wire: {
+        viewSchema: z.ZodType<ContextPressureProjection, unknown, z.core.$ZodTypeInternals<ContextPressureProjection, unknown>>;
+        view: ({ contextWindow, pressureTokens, surfaceTokens, sampledSurfaceTokens }: NoInfer<{
+            surfaceTokens: number;
+            contextWindow?: number | undefined;
+            pressureTokens?: number | undefined;
+            sampledSurfaceTokens?: number | undefined;
+            claim?: {
+                start: SessionSeq;
+                end: SessionSeq;
+                tokens: number;
+            } | undefined;
+        }>) => {
+            projectedTokens?: number;
+            pressureTokens?: number;
+            contextWindow?: number;
+        };
+    };
+};
+export {};
+//# sourceMappingURL=usage-projection.d.ts.map