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

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

@@ -0,0 +1,98 @@
+/**
+ * Heuristic composition of the current retained surface, independent of route
+ * image pricing and provider usage. Positional entries preserve system-prompt
+ * classification across replacements without retaining historical messages.
+ */
+import { z } from 'zod';
+import { SessionSeq } from '@qilin-agent/session';
+declare module '@qilin-agent/session-projection/types' {
+    interface SessionProjectionStateMap {
+        contextBreakdown: ContextBreakdownState;
+    }
+}
+/** Plain-JSON checkpoint: one compact entry per retained surface position. */
+declare const contextBreakdownStateSchema: z.ZodObject<{
+    nodes: z.ZodArray<z.ZodObject<{
+        seq: z.ZodPipe<z.ZodNumber, z.ZodTransform<SessionSeq, number>>;
+        heuristicTokens: z.ZodNumber;
+        system: z.ZodBoolean;
+    }, z.core.$strict>>;
+    breakdown: z.ZodObject<{
+        systemTokens: z.ZodNumber;
+        toolsTokens: z.ZodNumber;
+        messageTokens: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+type ContextBreakdownState = z.infer<typeof contextBreakdownStateSchema>;
+/**
+ * Context composition with the last nonempty surviving system in surface
+ * order classified as system tokens; all other visible prices are messages.
+ * Replacements use the measurement planner, not shadow-price claims. State
+ * and surface transitions cost O(current retained surface), not O(log length).
+ * Tools are priced from the latest request header. No route pricing applies.
+ */
+export declare const contextBreakdownProjectionDefinition: {
+    key: "contextBreakdown";
+    stateVersion: number;
+    stateSchema: z.ZodObject<{
+        nodes: z.ZodArray<z.ZodObject<{
+            seq: z.ZodPipe<z.ZodNumber, z.ZodTransform<SessionSeq, number>>;
+            heuristicTokens: z.ZodNumber;
+            system: z.ZodBoolean;
+        }, z.core.$strict>>;
+        breakdown: z.ZodObject<{
+            systemTokens: z.ZodNumber;
+            toolsTokens: z.ZodNumber;
+            messageTokens: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    init: () => ContextBreakdownState;
+    apply: (state: NoInfer<{
+        nodes: {
+            seq: SessionSeq;
+            heuristicTokens: number;
+            system: boolean;
+        }[];
+        breakdown: {
+            systemTokens: number;
+            toolsTokens: number;
+            messageTokens: number;
+        };
+    }>, event: import("@qilin-agent/session").SessionEvent) => {
+        nodes: {
+            seq: SessionSeq;
+            heuristicTokens: number;
+            system: boolean;
+        }[];
+        breakdown: {
+            systemTokens: number;
+            toolsTokens: number;
+            messageTokens: number;
+        };
+    };
+    wire: {
+        viewSchema: z.ZodObject<{
+            systemTokens: z.ZodNumber;
+            toolsTokens: z.ZodNumber;
+            messageTokens: z.ZodNumber;
+        }, z.core.$strict>;
+        view: (state: NoInfer<{
+            nodes: {
+                seq: SessionSeq;
+                heuristicTokens: number;
+                system: boolean;
+            }[];
+            breakdown: {
+                systemTokens: number;
+                toolsTokens: number;
+                messageTokens: number;
+            };
+        }>) => {
+            systemTokens: number;
+            toolsTokens: number;
+            messageTokens: number;
+        };
+    };
+};
+export {};
+//# sourceMappingURL=breakdown-projection.d.ts.map

package/lib/types/breakdown-projection.js

@@ -0,0 +1,68 @@
+/**
+ * Heuristic composition of the current retained surface, independent of route
+ * image pricing and provider usage. Positional entries preserve system-prompt
+ * classification across replacements without retaining historical messages.
+ */
+import { z } from 'zod';
+import { canonicalHeader, isSurfaceEvent, SessionSeq } from '@qilin-agent/session';
+import { estimateToolsTokens } from "./estimate.js";
+import { commitSurfaceTokens, planSurfaceTokens } from "./surface-fold.js";
+const tokenCount = z.number().int().nonnegative();
+const sessionSeq = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).transform(SessionSeq);
+const breakdownSchema = z.object({
+    systemTokens: tokenCount,
+    toolsTokens: tokenCount,
+    messageTokens: tokenCount,
+}).strict();
+/** Plain-JSON checkpoint: one compact entry per retained surface position. */
+const contextBreakdownStateSchema = z.object({
+    nodes: z.array(z.object({
+        seq: sessionSeq,
+        heuristicTokens: tokenCount,
+        system: z.boolean(),
+    }).strict()),
+    breakdown: breakdownSchema,
+}).strict();
+/**
+ * Context composition with the last nonempty surviving system in surface
+ * order classified as system tokens; all other visible prices are messages.
+ * Replacements use the measurement planner, not shadow-price claims. State
+ * and surface transitions cost O(current retained surface), not O(log length).
+ * Tools are priced from the latest request header. No route pricing applies.
+ */
+export const contextBreakdownProjectionDefinition = {
+    key: 'contextBreakdown',
+    stateVersion: 5,
+    stateSchema: contextBreakdownStateSchema,
+    init: () => ({
+        nodes: [],
+        breakdown: { systemTokens: 0, toolsTokens: 0, messageTokens: 0 },
+    }),
+    apply: (state, event) => {
+        if (event.type === 'request/header') {
+            const toolsTokens = estimateToolsTokens(canonicalHeader(event.data.header));
+            return toolsTokens === state.breakdown.toolsTokens
+                ? state
+                : { ...state, breakdown: { ...state.breakdown, toolsTokens } };
+        }
+        if (!isSurfaceEvent(event))
+            return state;
+        const plan = planSurfaceTokens(state.nodes, event);
+        const nodes = [...state.nodes];
+        commitSurfaceTokens(nodes, {
+            ...plan,
+            node: { seq: event.seq, heuristicTokens: plan.tokens, system: event.type === 'system/message' },
+        });
+        const systemTokens = nodes.findLast(node => node.system && node.heuristicTokens > 0)?.heuristicTokens ?? 0;
+        const messageTokens = state.breakdown.systemTokens + state.breakdown.messageTokens + plan.deltaTokens - systemTokens;
+        const breakdown = systemTokens === state.breakdown.systemTokens && messageTokens === state.breakdown.messageTokens
+            ? state.breakdown
+            : { systemTokens, toolsTokens: state.breakdown.toolsTokens, messageTokens };
+        return { nodes, breakdown };
+    },
+    wire: {
+        viewSchema: breakdownSchema,
+        view: state => state.breakdown,
+    },
+};
+//# sourceMappingURL=breakdown-projection.js.map

package/lib/types/client.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Client-namespace projection of token-meter's browser-safe contracts and folds.
+ *
+ * @module @qilin-agent/token-meter/client
+ */
+export type * from './projection.ts';
+export { deriveTurnTokenUsage } from './turn-usage.ts';
+export type { TurnTokenUsage, TurnTokenUsageRoute } from './turn-usage.ts';
+//# sourceMappingURL=client.d.ts.map

package/lib/types/client.js

@@ -0,0 +1,7 @@
+/**
+ * Client-namespace projection of token-meter's browser-safe contracts and folds.
+ *
+ * @module @qilin-agent/token-meter/client
+ */
+export { deriveTurnTokenUsage } from "./turn-usage.js";
+//# sourceMappingURL=client.js.map

package/lib/types/estimate.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Fixed-density heuristic token pricing shared by the meter service and the
+ * pure context-breakdown projection, so both surfaces price identical content
+ * to identical numbers.
+ *
+ * @module @qilin-agent/token-meter/estimate
+ */
+import type { ContentBlock, Message } from '@qilin-agent/llm';
+import type { EpochHeader } from '@qilin-agent/session';
+/** Role-field framing overhead added to every priced message. */
+export declare const ROLE_OVERHEAD = 4;
+/**
+ * Structural JSON price of one block outside the typed pricing arms: the
+ * fixed heuristic for merge-extended blocks and for image references, whose
+ * request price is route-owned rather than fixed. Image offload marks do not
+ * change this reference-only heuristic; route pricing owns their placeholders.
+ * @param block - block to price without mutation.
+ * @returns heuristic tokens for the block's JSON structure.
+ */
+export declare function estimateStructuralBlock(block: ContentBlock): number;
+/**
+ * Price content blocks recursively under the fixed density heuristic.
+ * @param blocks - content blocks to price without mutation.
+ * @returns heuristic tokens including per-block structural overhead.
+ */
+export declare function estimateContent(blocks: readonly ContentBlock[]): number;
+/**
+ * Price the rendered system prompt: the `system/message` surface node's text.
+ * Adapters serialize the prompt as a plain string — a system-role message or
+ * the request's system field — not as a typed content block, so the price is
+ * text density plus role framing with no per-block overhead.
+ * @param message - system-role message to price without mutation.
+ * @returns heuristic system-prompt tokens; 0 for empty content ("no system prompt").
+ */
+export declare function estimateSystemMessage(message: Message): number;
+/**
+ * Heuristically price one model-visible message.
+ * @param message - message to price without mutation.
+ * @returns content and role-framing tokens under the fixed heuristic; a
+ *   system-role message prices as {@link estimateSystemMessage}.
+ */
+export declare function estimateMessage(message: Message): number;
+/**
+ * Price the tool-schema part of a canonical request envelope — the envelope's
+ * only priced field, since the system prompt is a surface node.
+ * @param header - canonical envelope, or undefined before any request.
+ * @returns heuristic tool-schema tokens; 0 when absent or empty.
+ */
+export declare function estimateToolsTokens(header: EpochHeader | undefined): number;
+//# sourceMappingURL=estimate.d.ts.map

package/lib/types/estimate.js

@@ -0,0 +1,95 @@
+/**
+ * Fixed-density heuristic token pricing shared by the meter service and the
+ * pure context-breakdown projection, so both surfaces price identical content
+ * to identical numbers.
+ *
+ * @module @qilin-agent/token-meter/estimate
+ */
+/** Fixed text-density estimate used until exact tokenization is needed. */
+const CHARS_PER_TOKEN = 4;
+/** Per-block structural overhead for JSON framing and type tags. */
+const BLOCK_OVERHEAD = 4;
+/** Role-field framing overhead added to every priced message. */
+export const ROLE_OVERHEAD = 4;
+/**
+ * Structural JSON price of one block outside the typed pricing arms: the
+ * fixed heuristic for merge-extended blocks and for image references, whose
+ * request price is route-owned rather than fixed. Image offload marks do not
+ * change this reference-only heuristic; route pricing owns their placeholders.
+ * @param block - block to price without mutation.
+ * @returns heuristic tokens for the block's JSON structure.
+ */
+export function estimateStructuralBlock(block) {
+    if (block.type === 'image') {
+        const { offloaded: _offloaded, ...reference } = block;
+        return BLOCK_OVERHEAD + Math.ceil(JSON.stringify(reference).length / CHARS_PER_TOKEN);
+    }
+    return BLOCK_OVERHEAD + Math.ceil(JSON.stringify(block).length / CHARS_PER_TOKEN);
+}
+/**
+ * Price content blocks recursively under the fixed density heuristic.
+ * @param blocks - content blocks to price without mutation.
+ * @returns heuristic tokens including per-block structural overhead.
+ */
+export function estimateContent(blocks) {
+    let tokens = 0;
+    for (const block of blocks) {
+        switch (block.type) {
+            case 'text':
+            case 'reasoning':
+                tokens += Math.ceil(block.text.length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD;
+                break;
+            case 'tool-call':
+                tokens += Math.ceil(block.name.length / CHARS_PER_TOKEN)
+                    + Math.ceil(block.arguments.length / CHARS_PER_TOKEN)
+                    + BLOCK_OVERHEAD;
+                break;
+            default:
+                // ContentBlockMap is merge-extensible; unknown blocks (and image
+                // references, whose request price is route-owned) retain a
+                // conservative structural JSON price under the fixed heuristic.
+                tokens += estimateStructuralBlock(block);
+        }
+    }
+    return tokens;
+}
+/**
+ * Price the rendered system prompt: the `system/message` surface node's text.
+ * Adapters serialize the prompt as a plain string — a system-role message or
+ * the request's system field — not as a typed content block, so the price is
+ * text density plus role framing with no per-block overhead.
+ * @param message - system-role message to price without mutation.
+ * @returns heuristic system-prompt tokens; 0 for empty content ("no system prompt").
+ */
+export function estimateSystemMessage(message) {
+    if (message.content.length === 0)
+        return 0;
+    let characters = 0;
+    for (const block of message.content) {
+        characters += block.type === 'text' ? block.text.length : JSON.stringify(block).length;
+    }
+    return Math.ceil(characters / CHARS_PER_TOKEN) + ROLE_OVERHEAD;
+}
+/**
+ * Heuristically price one model-visible message.
+ * @param message - message to price without mutation.
+ * @returns content and role-framing tokens under the fixed heuristic; a
+ *   system-role message prices as {@link estimateSystemMessage}.
+ */
+export function estimateMessage(message) {
+    if (message.role === 'system')
+        return estimateSystemMessage(message);
+    return estimateContent(message.content) + ROLE_OVERHEAD;
+}
+/**
+ * Price the tool-schema part of a canonical request envelope — the envelope's
+ * only priced field, since the system prompt is a surface node.
+ * @param header - canonical envelope, or undefined before any request.
+ * @returns heuristic tool-schema tokens; 0 when absent or empty.
+ */
+export function estimateToolsTokens(header) {
+    if (header?.tools === undefined || header.tools.length === 0)
+        return 0;
+    return Math.ceil(JSON.stringify(header.tools).length / CHARS_PER_TOKEN) + BLOCK_OVERHEAD;
+}
+//# sourceMappingURL=estimate.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Single replay-aware token-meter service for request and surface pressure.
+ *
+ * @module @qilin-agent/token-meter
+ */
+import { Context, Service } from '@qilin-agent/kylin';
+import z from '@qilin-agent/schemastery';
+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' {
+    interface Context {
+        tokenMeter: TokenMeter;
+    }
+}
+/** Replay owner for one service-wide estimator and isolated per-session folds. */
+export declare class TokenMeter extends Service {
+    static Config: z<TokenMeterConfig>;
+    static inject: string[];
+    private readonly states;
+    constructor(ctx: Context, config?: TokenMeterConfig);
+    /**
+     * Measure current request pressure and surface through the durable tail.
+     *
+     * The effective envelope's routed provider/model selects the request-image
+     * pricing every node is priced under: a route whose adapter declares image
+     * pricing charges each retained image its visual tokens plus its
+     * model-visible text, while other routes keep the fixed heuristic. Provider
+     * usage is reused only when the latest successful call's canonical request
+     * envelope matches `requestHeader` and its total is no lower than that
+     * call's full route-priced anchor; otherwise the complete envelope and
+     * surface are repriced. The anchor includes all surface nodes immediately
+     * before the assistant message, including inputs admitted after step/start.
+     *
+     * `requestHeader` replaces the latest logged envelope for pressure and node
+     * pricing; the node set always describes the current session surface. Every
+     * call clones those positional nodes, so measurement is O(surface).
+     *
+     * @param session - session to replay through its current durable tail.
+     * @param requestHeader - optional effective request envelope replacing the latest logged header.
+     * @returns a detached deeply immutable pressure and surface measurement.
+     */
+    measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement;
+    /** Resolve the routed model's image pricing, when the llm service and route declare one. */
+    private _routeImagePricing;
+    /** Resolve request-time file projection when an LLM service is mounted. */
+    private _fileRequestText;
+    /**
+     * Heuristically price one model-visible message (instance face of the pure
+     * `estimateMessage` export from `estimate.ts`).
+     * @param message - message to price without mutation.
+     * @returns content and role-framing tokens under the fixed service heuristic.
+     */
+    estimateMessage(message: Message): number;
+    /** Catch one session's fold up to the current durable tail. */
+    private _sync;
+    /**
+     * Run every fallible step — surface plan and anchor validation — before
+     * mutating replay state, so a malformed event remains unread on every
+     * retry instead of half-applying.
+     */
+    private _foldEvent;
+    /**
+     * Reassemble provider output from the message's exact embedded stream.
+     */
+    private _estimateProviderAssistant;
+}
+export default TokenMeter;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,260 @@
+/**
+ * Single replay-aware token-meter service for request and surface pressure.
+ *
+ * @module @qilin-agent/token-meter
+ */
+import { Service } from '@qilin-agent/kylin';
+import z from '@qilin-agent/schemastery';
+import { assembleAssistantStream } from '@qilin-agent/llm';
+import { deepFreeze } from '@qilin-agent/util-values';
+import { canonicalHeader, headerEquals, isSurfaceEvent, SessionLogOffset, SessionSeq, } from '@qilin-agent/session';
+import { contextBreakdownProjectionDefinition } from "./breakdown-projection.js";
+import { contextPressureProjectionDefinition, tokenUsageProjectionDefinition } from "./usage-projection.js";
+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
+        + (usage.cacheReadTokens ?? 0)
+        + (usage.cacheWriteTokens ?? 0)
+        + usage.outputTokens;
+}
+/** Compare optional envelopes so a headerless estimate can track later surface deltas. */
+function optionalHeaderEquals(left, right) {
+    if (left === undefined || right === undefined)
+        return left === right;
+    return headerEquals(left, right);
+}
+/** Reject stale or misspelled keys before defaults can hide them. */
+function validateConfigKeys(config) {
+    for (const key of Object.keys(config)) {
+        throw new Error(`TokenMeterConfig: unknown key "${key}" (no settings are supported)`);
+    }
+}
+/** Replay owner for one service-wide estimator and isolated per-session folds. */
+export class TokenMeter extends Service {
+    // Schemastery preserves untrusted loader keys on an empty object schema;
+    // the public type excludes settings while validateConfigKeys rejects them.
+    static Config = z.object({});
+    static inject = ['sessionProjections'];
+    states = new WeakMap();
+    constructor(ctx, config = {}) {
+        super(ctx, 'tokenMeter');
+        validateConfigKeys(config);
+        ctx.sessionProjections.register(tokenUsageProjectionDefinition);
+        ctx.sessionProjections.register(contextPressureProjectionDefinition);
+        ctx.sessionProjections.register(contextBreakdownProjectionDefinition);
+        // Readers catch up independently, while eager observation bounds ordinary
+        // read latency without creating state for sessions no consumer has read.
+        ctx.on('session/event', (session) => {
+            if (this.states.has(session))
+                this._sync(session);
+        });
+    }
+    /**
+     * Measure current request pressure and surface through the durable tail.
+     *
+     * The effective envelope's routed provider/model selects the request-image
+     * pricing every node is priced under: a route whose adapter declares image
+     * pricing charges each retained image its visual tokens plus its
+     * model-visible text, while other routes keep the fixed heuristic. Provider
+     * usage is reused only when the latest successful call's canonical request
+     * envelope matches `requestHeader` and its total is no lower than that
+     * call's full route-priced anchor; otherwise the complete envelope and
+     * surface are repriced. The anchor includes all surface nodes immediately
+     * before the assistant message, including inputs admitted after step/start.
+     *
+     * `requestHeader` replaces the latest logged envelope for pressure and node
+     * pricing; the node set always describes the current session surface. Every
+     * call clones those positional nodes, so measurement is O(surface).
+     *
+     * @param session - session to replay through its current durable tail.
+     * @param requestHeader - optional effective request envelope replacing the latest logged header.
+     * @returns a detached deeply immutable pressure and surface measurement.
+     */
+    measure(session, requestHeader) {
+        const state = this._sync(session);
+        const header = requestHeader === undefined
+            ? state.header
+            : canonicalHeader(requestHeader);
+        const pricing = this._routeImagePricing(header);
+        const fileText = this._fileRequestText();
+        const surface = priceSurface(state.surface, pricing, fileText);
+        const anchor = state.anchor;
+        let baseline;
+        let surfaceDeltaTokens;
+        if (anchor !== undefined && optionalHeaderEquals(anchor.header, header)) {
+            // Matching headers share one route, so the anchored snapshot reprices
+            // under the same pricing as the current surface and the signed delta
+            // compares like with like.
+            const anchorSurfaceTokens = priceSurface(anchor.nodes, pricing, fileText).surfaceTokens
+                + anchor.assistantTokens;
+            const estimatedAnchorTokens = estimateToolsTokens(header) + anchorSurfaceTokens;
+            const usage = anchor.usage;
+            // Signed heuristic deltas remain conservative only from an anchor
+            // that is at least as large as the matching full heuristic price.
+            baseline = usage !== undefined && usageTokens(usage) >= estimatedAnchorTokens
+                ? { kind: 'usage', tokens: usageTokens(usage), usage }
+                : { kind: 'estimated', tokens: estimatedAnchorTokens };
+            surfaceDeltaTokens = surface.surfaceTokens - anchorSurfaceTokens;
+        }
+        else if (header === undefined && surface.surfaceTokens === 0) {
+            baseline = { kind: 'none', tokens: 0 };
+            surfaceDeltaTokens = 0;
+        }
+        else {
+            baseline = {
+                kind: 'estimated',
+                tokens: estimateToolsTokens(header) + surface.surfaceTokens,
+            };
+            surfaceDeltaTokens = 0;
+        }
+        return deepFreeze(structuredClone({
+            logRevision: state.consumedEvents,
+            baseline,
+            surfaceDeltaTokens,
+            totalTokens: Math.max(0, baseline.tokens + surfaceDeltaTokens),
+            surfaceTokens: surface.surfaceTokens,
+            nodes: surface.nodes,
+        }));
+    }
+    /** Resolve the routed model's image pricing, when the llm service and route declare one. */
+    _routeImagePricing(header) {
+        const config = header?.config;
+        if (config === undefined)
+            return undefined;
+        return this.ctx.get('llm')?.imageRequestPricing(config.provider, config.model);
+    }
+    /** Resolve request-time file projection when an LLM service is mounted. */
+    _fileRequestText() {
+        const llm = this.ctx.get('llm');
+        return llm === undefined ? undefined : ref => llm.fileRequestText(ref);
+    }
+    /**
+     * Heuristically price one model-visible message (instance face of the pure
+     * `estimateMessage` export from `estimate.ts`).
+     * @param message - message to price without mutation.
+     * @returns content and role-framing tokens under the fixed service heuristic.
+     */
+    estimateMessage(message) {
+        return estimateMessage(message);
+    }
+    /** Catch one session's fold up to the current durable tail. */
+    _sync(session) {
+        let state = this.states.get(session);
+        if (state === undefined) {
+            state = {
+                consumedEvents: SessionLogOffset(0),
+                header: undefined,
+                surface: [],
+                stepStart: undefined,
+                anchor: undefined,
+            };
+            this.states.set(session, state);
+        }
+        while (state.consumedEvents < session.seq) {
+            // Contiguous session seqs index the durable log; existing Session history read, migration deferred.
+            // oxlint-disable-next-line typescript/no-non-null-assertion, typescript/no-deprecated
+            const event = session.eventAt(SessionSeq(state.consumedEvents));
+            this._foldEvent(state, event);
+            state.consumedEvents = SessionLogOffset(state.consumedEvents + 1);
+        }
+        return state;
+    }
+    /**
+     * Run every fallible step — surface plan and anchor validation — before
+     * mutating replay state, so a malformed event remains unread on every
+     * retry instead of half-applying.
+     */
+    _foldEvent(state, event) {
+        let nextHeader = state.header;
+        let nextStepStart = state.stepStart;
+        let nextAnchor = state.anchor;
+        switch (event.type) {
+            case 'image/offload': {
+                const offloaded = new Map(event.data.targets.map(target => [target.seq, new Set(target.imageIndexes)]));
+                state.surface = state.surface.map((node) => {
+                    const indexes = offloaded.get(node.seq);
+                    if (indexes === undefined)
+                        return node;
+                    return {
+                        ...node,
+                        images: node.images.map((image, index) => (indexes.has(index) ? { ...image, offloaded: true } : image)),
+                    };
+                });
+                break;
+            }
+            case 'request/header':
+                nextHeader = canonicalHeader(event.data.header);
+                break;
+            case 'step/start':
+                if (state.stepStart !== undefined) {
+                    throw new Error(`token meter: step/start at seq ${event.seq} arrived before turn ${state.stepStart.turn}/step ${state.stepStart.step} ended`);
+                }
+                nextStepStart = { ...event.data };
+                break;
+            case 'step/end':
+                if (state.stepStart === undefined
+                    || state.stepStart.turn !== event.data.turn
+                    || state.stepStart.step !== event.data.step) {
+                    throw new Error(`token meter: step/end at seq ${event.seq} has no matching step/start event`);
+                }
+                nextStepStart = undefined;
+                break;
+            default:
+                break;
+        }
+        const plan = isSurfaceEvent(event)
+            ? planSurfaceTokens(state.surface, event)
+            : undefined;
+        if (event.type === 'assistant/message') {
+            const stepStart = state.stepStart;
+            if (stepStart === undefined
+                || stepStart.turn !== event.data.turn
+                || stepStart.step !== event.data.step) {
+                throw new Error(`token meter: assistant/message at seq ${event.seq} has no matching step/start event`);
+            }
+            // assistant/message is surface-mandatory at every append/seed boundary.
+            // oxlint-disable-next-line typescript/no-non-null-assertion
+            const eventTokens = plan.tokens;
+            // The loop admits prompts and user messages after step/start; retries may
+            // replace them before succeeding. Only the pre-assistant surface is priced
+            // by this call. Provider output stays separate from durable output rewrites.
+            if (event.data.usage !== undefined && nextHeader !== undefined) {
+                nextAnchor = {
+                    header: nextHeader,
+                    nodes: [...state.surface],
+                    assistantTokens: this._estimateProviderAssistant(event),
+                    usage: event.data.usage,
+                };
+            }
+            else {
+                nextAnchor = {
+                    header: nextHeader,
+                    nodes: [...state.surface],
+                    assistantTokens: eventTokens,
+                    usage: undefined,
+                };
+            }
+        }
+        state.header = nextHeader;
+        state.stepStart = nextStepStart;
+        if (plan !== undefined) {
+            commitSurfaceTokens(state.surface, plan);
+        }
+        state.anchor = nextAnchor;
+    }
+    /**
+     * Reassemble provider output from the message's exact embedded stream.
+     */
+    _estimateProviderAssistant(event) {
+        const providerContent = assembleAssistantStream(event.data.stream).blocks();
+        return providerContent.length === 0 ? 0 : estimateContent(providerContent) + ROLE_OVERHEAD;
+    }
+}
+export default TokenMeter;
+//# sourceMappingURL=index.js.map