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

package/lib/types/projection.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Pure client-safe token-projection vocabulary.
+ *
+ * @module @qilin-agent/token-meter/projection
+ */
+/**
+ * Durable cumulative provider usage for a complete session log.
+ *
+ * The four buckets are disjoint. In particular, reasoning tokens are already
+ * included in `outputTokens` and are not accumulated again.
+ */
+export interface TokenUsageProjection {
+    uncachedInputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+/**
+ * Approximate context occupancy for a status display.
+ *
+ * The fields, when present, are deliberately NOT one atomic request
+ * observation: each is a last-wins record of a different moment. Switching
+ * models can therefore pair a fresh capacity with the previous route's
+ * pressure until the next request reports usage. This is an intentional trade
+ * — the value is a user-facing reference, not a billing or gating input. See
+ * the token-meter README for the full rationale.
+ */
+export interface ContextPressureProjection {
+    /**
+     * Provider-reported prompt size of the most recent request: uncached input
+     * plus cache reads and writes. Response output is excluded, so this does not
+     * grow as the current turn streams. Absent until a provider reports usage.
+     */
+    pressureTokens?: number;
+    /**
+     * What the NEXT request's prompt would cost: {@link pressureTokens} plus the
+     * heuristic repricing of everything the surface gained or lost since that
+     * sample. Only the delta is estimated, so the figure stays anchored to the
+     * provider while still reacting the moment a compaction shadows a span —
+     * which `pressureTokens` alone cannot do, since compaction reports no usage
+     * of its own. Absent until a provider reports usage.
+     */
+    projectedTokens?: number;
+    /** Newest recorded route capacity; absent when no adapter advertised one. */
+    contextWindow?: number;
+}
+/**
+ * Heuristic composition of the next request's context: what the prompt is
+ * made of, not what it costs. All three figures use the meter's fixed
+ * density estimate, so they will not sum to the provider-anchored
+ * `projectedTokens`: the estimator systematically underprices CJK text and
+ * JSON schemas, which is exactly the error the anchoring in
+ * {@link ContextPressureProjection.projectedTokens} keeps out of the occupancy
+ * figure. Present these as approximations of composition, never as a total.
+ */
+export interface ContextBreakdownProjection {
+    /** Heuristic tokens of the last nonempty surviving system prompt in surface order; 0 when none exists. */
+    systemTokens: number;
+    /** Heuristic tokens of the newest request envelope's tool schemas; 0 before any request. */
+    toolsTokens: number;
+    /** Heuristic tokens of every other visible surface node, including superseded system prompts. */
+    messageTokens: number;
+}
+declare module '@qilin-agent/session-projection/types' {
+    interface SessionProjectionMap {
+        /** Provider-reported usage accumulated across the complete durable log. */
+        tokenUsage: TokenUsageProjection;
+        /** Newest request pressure paired with the newest known route capacity. */
+        contextPressure: ContextPressureProjection;
+        /** Heuristic system/tools/message composition of the next request. */
+        contextBreakdown: ContextBreakdownProjection;
+    }
+}
+//# sourceMappingURL=projection.d.ts.map

package/lib/types/projection.js

@@ -0,0 +1,7 @@
+/**
+ * Pure client-safe token-projection vocabulary.
+ *
+ * @module @qilin-agent/token-meter/projection
+ */
+export {};
+//# sourceMappingURL=projection.js.map

package/lib/types/route-pricing.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Request-projected surface pricing: replaces attachment-block heuristics with
+ * the image and file representations sent to the routed model.
+ *
+ * @module @qilin-agent/token-meter/route-pricing
+ */
+import type { ContentBlock, LlmImageRequestPricing } from '@qilin-agent/llm';
+import type { MeterSurfaceNode } from './surface-fold.ts';
+import type { TokenSurfaceNode } from './types.ts';
+type FileAttachmentRef = Extract<ContentBlock, {
+    type: 'file';
+}>['attachment'];
+/** One surface priced for a request route: public nodes plus their total. */
+export interface PricedSurface {
+    /** Positional nodes carrying both the route price and the fixed-heuristic price. */
+    readonly nodes: TokenSurfaceNode[];
+    /** Sum of the route prices across the surface. */
+    readonly surfaceTokens: number;
+}
+/**
+ * Price one ordered surface under its model-request attachment projection.
+ * @param nodes - the fold's current or snapshotted surface, in model-visible order.
+ * @param pricing - the routed model's image pricing, or undefined to keep the fixed heuristic.
+ * @param fileText - exact file handle projection used by the mounted LLM service.
+ * @returns detached public nodes and their route-priced total.
+ * @throws when the pricing answers a different occurrence count than it was
+ *   asked — misalignment would silently misprice nodes, so it must fail loud.
+ */
+export declare function priceSurface(nodes: readonly MeterSurfaceNode[], pricing: LlmImageRequestPricing | undefined, fileText?: (ref: FileAttachmentRef) => string): PricedSurface;
+export {};
+//# sourceMappingURL=route-pricing.d.ts.map

package/lib/types/route-pricing.js

@@ -0,0 +1,56 @@
+/**
+ * Request-projected surface pricing: replaces attachment-block heuristics with
+ * the image and file representations sent to the routed model.
+ *
+ * @module @qilin-agent/token-meter/route-pricing
+ */
+import { estimateContent } from "./estimate.js";
+/**
+ * Price one ordered surface under its model-request attachment projection.
+ * @param nodes - the fold's current or snapshotted surface, in model-visible order.
+ * @param pricing - the routed model's image pricing, or undefined to keep the fixed heuristic.
+ * @param fileText - exact file handle projection used by the mounted LLM service.
+ * @returns detached public nodes and their route-priced total.
+ * @throws when the pricing answers a different occurrence count than it was
+ *   asked — misalignment would silently misprice nodes, so it must fail loud.
+ */
+export function priceSurface(nodes, pricing, fileText) {
+    const images = pricing === undefined ? [] : nodes.flatMap(node => node.images);
+    const hasFiles = fileText !== undefined && nodes.some(node => node.files.length > 0);
+    if ((pricing === undefined || images.length === 0) && !hasFiles) {
+        let surfaceTokens = 0;
+        const publicNodes = nodes.map((node) => {
+            surfaceTokens += node.heuristicTokens;
+            return { seq: node.seq, tokens: node.heuristicTokens, heuristicTokens: node.heuristicTokens };
+        });
+        return { nodes: publicNodes, surfaceTokens };
+    }
+    const prices = pricing === undefined ? [] : pricing.priceImages(images);
+    if (pricing !== undefined && prices.length !== images.length) {
+        throw new Error(`token meter: route image pricing answered ${prices.length} prices for ${images.length} occurrences`);
+    }
+    let cursor = 0;
+    let surfaceTokens = 0;
+    const publicNodes = nodes.map((node) => {
+        let tokens = node.heuristicTokens;
+        if (fileText !== undefined && node.files.length > 0) {
+            tokens -= node.fileStructuralTokens;
+            for (const file of node.files) {
+                tokens += estimateContent([{ type: 'text', text: fileText(file) }]);
+            }
+        }
+        if (pricing !== undefined && node.images.length > 0) {
+            tokens -= node.imageStructuralTokens;
+            for (let occurrence = 0; occurrence < node.images.length; occurrence += 1) {
+                // oxlint-disable-next-line typescript/no-non-null-assertion -- length equality is asserted above
+                const price = prices[cursor];
+                cursor += 1;
+                tokens += price.visualTokens + estimateContent([{ type: 'text', text: price.text }]);
+            }
+        }
+        surfaceTokens += tokens;
+        return { seq: node.seq, tokens, heuristicTokens: node.heuristicTokens };
+    });
+    return { nodes: publicNodes, surfaceTokens };
+}
+//# sourceMappingURL=route-pricing.js.map

package/lib/types/surface-fold.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Positional pricing shared by measurement and the context-breakdown fold:
+ * measurement retains attachment details for route pricing; breakdown keeps
+ * only retained node identities, heuristic prices, and system classification.
+ * The occupancy projection uses the scalar shadow-price protocol instead.
+ *
+ * The fold is a plan/commit pair: {@link planSurfaceTokens} runs every
+ * fallible step read-only and {@link commitSurfaceTokens} mutates in place,
+ * so a throw leaves the caller's state untouched and the same malformed
+ * event fails identically on every retry.
+ * Nodes also carry durable attachment occurrences and their structural prices,
+ * so `measure()` can price the request representation sent to the model.
+ *
+ * @module @qilin-agent/token-meter/surface-fold
+ */
+import type { SessionSeq, SurfaceEvent } from '@qilin-agent/session';
+import type { ContentBlock, ImageBlock } from '@qilin-agent/llm';
+type FileAttachmentRef = Extract<ContentBlock, {
+    type: 'file';
+}>['attachment'];
+/** One priced surface node with the image occurrences route pricing replaces. */
+export interface MeterSurfaceNode {
+    /** Durable sequence number of the surface event. */
+    readonly seq: SessionSeq;
+    /** Fixed-heuristic price of the node's exact message. */
+    readonly heuristicTokens: number;
+    /** Structural JSON price replaced when the routed request projects images. */
+    readonly imageStructuralTokens: number;
+    /** Structural JSON price replaced when request assembly projects files to text. */
+    readonly fileStructuralTokens: number;
+    /** Durable image blocks in message order, `offloaded` marks included; empty for image-free nodes. */
+    readonly images: readonly ImageBlock[];
+    /** Durable file occurrences in message order; empty for file-free nodes. */
+    readonly files: readonly FileAttachmentRef[];
+}
+/** One validated surface transition that has not mutated the priced surface yet. */
+export interface SurfaceTokenPlan<Node = MeterSurfaceNode> {
+    /** Heuristic price of the event's own message; 0 when it derives none. */
+    readonly tokens: number;
+    /** Signed change in the surface total: `tokens` minus anything shadowed. */
+    readonly deltaTokens: number;
+    /** The priced node the commit inserts for this event. */
+    readonly node: Node;
+    /** Commit position: `append`, or the inclusive replaced index range. */
+    readonly target: 'append' | {
+        readonly startIdx: number;
+        readonly endIdx: number;
+    };
+}
+/**
+ * Validate and price one surface event without mutating the surface.
+ * @param nodes - the priced surface preceding this event, in model-visible order.
+ * @param event - the surface event to place.
+ * @returns the plan for {@link commitSurfaceTokens}.
+ * @throws when a replacement names a range absent from `nodes` — committed
+ *   logs are surface-validated at append time, so an unresolvable range is log
+ *   corruption and must fail loud rather than skip the event.
+ */
+export declare function planSurfaceTokens(nodes: readonly Pick<MeterSurfaceNode, 'seq' | 'heuristicTokens'>[], event: SurfaceEvent): SurfaceTokenPlan;
+/**
+ * Apply one validated plan to the priced surface in place; infallible, so it
+ * cannot leave a half-applied surface behind.
+ * @param nodes - the exact priced surface the plan was built against.
+ * @param plan - the transition returned by {@link planSurfaceTokens}.
+ */
+export declare function commitSurfaceTokens<Node>(nodes: Node[], plan: SurfaceTokenPlan<Node>): void;
+export {};
+//# sourceMappingURL=surface-fold.d.ts.map

package/lib/types/surface-fold.js

@@ -0,0 +1,98 @@
+/**
+ * Positional pricing shared by measurement and the context-breakdown fold:
+ * measurement retains attachment details for route pricing; breakdown keeps
+ * only retained node identities, heuristic prices, and system classification.
+ * The occupancy projection uses the scalar shadow-price protocol instead.
+ *
+ * The fold is a plan/commit pair: {@link planSurfaceTokens} runs every
+ * fallible step read-only and {@link commitSurfaceTokens} mutates in place,
+ * so a throw leaves the caller's state untouched and the same malformed
+ * event fails identically on every retry.
+ * Nodes also carry durable attachment occurrences and their structural prices,
+ * so `measure()` can price the request representation sent to the model.
+ *
+ * @module @qilin-agent/token-meter/surface-fold
+ */
+import { deriveEventMessage } from '@qilin-agent/session';
+import { estimateMessage, estimateStructuralBlock } from "./estimate.js";
+/** Collect projected attachment occurrences and their structural prices. */
+function collectProjectedAttachments(blocks, images, files) {
+    let imageTokens = 0;
+    let fileTokens = 0;
+    for (const block of blocks) {
+        if (block.type === 'image') {
+            images.push(block);
+            imageTokens += estimateStructuralBlock(block);
+        }
+        else if (block.type === 'file') {
+            files.push(block.attachment);
+            fileTokens += estimateStructuralBlock(block);
+        }
+    }
+    return { imageTokens, fileTokens };
+}
+/** Build one priced node from a surface event's derived message. */
+function analyzeNode(seq, message) {
+    if (message === null) {
+        return {
+            seq,
+            heuristicTokens: 0,
+            imageStructuralTokens: 0,
+            fileStructuralTokens: 0,
+            images: [],
+            files: [],
+        };
+    }
+    const heuristicTokens = estimateMessage(message);
+    const images = [];
+    const files = [];
+    const structural = collectProjectedAttachments(message.content, images, files);
+    return {
+        seq,
+        heuristicTokens,
+        imageStructuralTokens: structural.imageTokens,
+        fileStructuralTokens: structural.fileTokens,
+        images,
+        files,
+    };
+}
+/**
+ * Validate and price one surface event without mutating the surface.
+ * @param nodes - the priced surface preceding this event, in model-visible order.
+ * @param event - the surface event to place.
+ * @returns the plan for {@link commitSurfaceTokens}.
+ * @throws when a replacement names a range absent from `nodes` — committed
+ *   logs are surface-validated at append time, so an unresolvable range is log
+ *   corruption and must fail loud rather than skip the event.
+ */
+export function planSurfaceTokens(nodes, event) {
+    const node = analyzeNode(event.seq, deriveEventMessage(event));
+    const tokens = node.heuristicTokens;
+    const op = event.surfaceOp;
+    if (op === 'append') {
+        return { tokens, deltaTokens: tokens, node, target: 'append' };
+    }
+    const startIdx = nodes.findIndex(candidate => candidate.seq === op.startSeq);
+    const endIdx = nodes.findIndex(candidate => candidate.seq === op.endSeq);
+    if (startIdx === -1 || endIdx === -1 || startIdx > endIdx) {
+        throw new Error(`token surface: replace at seq ${event.seq} has invalid current range ${op.startSeq}-${op.endSeq}`);
+    }
+    const removed = nodes
+        .slice(startIdx, endIdx + 1)
+        .reduce((total, candidate) => total + candidate.heuristicTokens, 0);
+    return { tokens, deltaTokens: tokens - removed, node, target: { startIdx, endIdx } };
+}
+/**
+ * Apply one validated plan to the priced surface in place; infallible, so it
+ * cannot leave a half-applied surface behind.
+ * @param nodes - the exact priced surface the plan was built against.
+ * @param plan - the transition returned by {@link planSurfaceTokens}.
+ */
+export function commitSurfaceTokens(nodes, plan) {
+    if (plan.target === 'append') {
+        nodes.push(plan.node);
+        return;
+    }
+    nodes.splice(plan.target.startIdx, plan.target.endIdx - plan.target.startIdx + 1, plan.node);
+}
+//# sourceMappingURL=surface-fold.js.map

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

@@ -0,0 +1,58 @@
+/**
+ * The context-pressure projection's O(1) surface-token fold.
+ *
+ * Its checkpoint keeps scalar totals rather than the retained surface used
+ * by context breakdown. Replacements ride the compact
+ * seam's shadow-price protocol: the metering event immediately before a
+ * surface `replace` (`compaction/summary` or `compaction/prune`) states the
+ * heuristic price of the exact replaced range, so the fold keeps a running
+ * total plus at most one pending claim and never retains per-node prices.
+ * The counts are exact by construction: producers derive them from the same
+ * fixed estimator this module prices appends with. A replacement without an
+ * armed claim folds with zero delta because bounded state cannot reconstruct
+ * the replaced range; this preserves replay at the cost of possible drift.
+ *
+ * @module @qilin-agent/token-meter/surface-projection
+ */
+import { SessionSeq } from '@qilin-agent/session';
+import type { SessionEvent } from '@qilin-agent/session';
+/**
+ * One armed shadow price: the heuristic tokens of the surface range the
+ * IMMEDIATELY following event replaces. Plain JSON — it is part of the
+ * persisted unit state while armed.
+ */
+export interface ShadowPriceClaim {
+    /** Declared inclusive first surface-node seq of the priced range. */
+    start: SessionSeq;
+    /** Declared inclusive last surface-node seq of the priced range. */
+    end: SessionSeq;
+    /** Heuristic tokens of the priced range under the fixed estimator. */
+    tokens: number;
+}
+/** One event's effect on a running surface-token total. */
+export interface SurfaceTokensFold {
+    /** Signed change in the surface total; 0 for events off the surface. */
+    readonly deltaTokens: number;
+    /** Claim to carry into the next event; undefined when none survives. */
+    readonly claim: ShadowPriceClaim | undefined;
+}
+/**
+ * Fold one committed event onto a running surface-token total.
+ *
+ * A shadow-price event arms a claim; any other event expires it, and a
+ * surface `replace` consumes the claim naming its exact range — the
+ * producers append the metering event and the replacement synchronously
+ * adjacent, so a surviving claim always prices the very next event.
+ * A replace with no claim folds with zero delta because the bounded state
+ * cannot reconstruct the replaced range. An armed claim for another range
+ * still fails because the adjacent events contradict each other.
+ * @param claim - the claim armed by the immediately preceding event, if any.
+ * @param event - the next committed session event.
+ * @returns the signed token delta and the claim state after this event.
+ * @throws when a replacement arrives with an armed claim for a different
+ *   range — the metering event was adjacent, so this is a live producer's
+ *   shadow-price contract violation, not historical data, and must fail
+ *   loud rather than let the total drift.
+ */
+export declare function foldSurfaceProjection(claim: ShadowPriceClaim | undefined, event: SessionEvent): SurfaceTokensFold;
+//# sourceMappingURL=surface-projection.d.ts.map

package/lib/types/surface-projection.js

@@ -0,0 +1,68 @@
+/**
+ * The context-pressure projection's O(1) surface-token fold.
+ *
+ * Its checkpoint keeps scalar totals rather than the retained surface used
+ * by context breakdown. Replacements ride the compact
+ * seam's shadow-price protocol: the metering event immediately before a
+ * surface `replace` (`compaction/summary` or `compaction/prune`) states the
+ * heuristic price of the exact replaced range, so the fold keeps a running
+ * total plus at most one pending claim and never retains per-node prices.
+ * The counts are exact by construction: producers derive them from the same
+ * fixed estimator this module prices appends with. A replacement without an
+ * armed claim folds with zero delta because bounded state cannot reconstruct
+ * the replaced range; this preserves replay at the cost of possible drift.
+ *
+ * @module @qilin-agent/token-meter/surface-projection
+ */
+import { deriveEventMessage, isSurfaceEvent, SessionSeq } from '@qilin-agent/session';
+import { estimateMessage } from "./estimate.js";
+/**
+ * Fold one committed event onto a running surface-token total.
+ *
+ * A shadow-price event arms a claim; any other event expires it, and a
+ * surface `replace` consumes the claim naming its exact range — the
+ * producers append the metering event and the replacement synchronously
+ * adjacent, so a surviving claim always prices the very next event.
+ * A replace with no claim folds with zero delta because the bounded state
+ * cannot reconstruct the replaced range. An armed claim for another range
+ * still fails because the adjacent events contradict each other.
+ * @param claim - the claim armed by the immediately preceding event, if any.
+ * @param event - the next committed session event.
+ * @returns the signed token delta and the claim state after this event.
+ * @throws when a replacement arrives with an armed claim for a different
+ *   range — the metering event was adjacent, so this is a live producer's
+ *   shadow-price contract violation, not historical data, and must fail
+ *   loud rather than let the total drift.
+ */
+export function foldSurfaceProjection(claim, event) {
+    if (event.type === 'compaction/summary' || event.type === 'compaction/prune') {
+        const { shadowedRange, shadowedTokenCount } = event.data;
+        return {
+            deltaTokens: 0,
+            claim: {
+                start: SessionSeq(shadowedRange.start),
+                end: SessionSeq(shadowedRange.end),
+                tokens: shadowedTokenCount,
+            },
+        };
+    }
+    if (!isSurfaceEvent(event))
+        return { deltaTokens: 0, claim: undefined };
+    const message = deriveEventMessage(event);
+    const tokens = message === null ? 0 : estimateMessage(message);
+    const op = event.surfaceOp;
+    if (op === 'append')
+        return { deltaTokens: tokens, claim: undefined };
+    // Sessions recorded before the shadow-price protocol log replacements with
+    // no adjacent metering event; the bounded state cannot reconstruct the
+    // replaced range's price, so fold those neutrally — historical replay
+    // degrades to drift instead of failing.
+    if (claim === undefined)
+        return { deltaTokens: 0, claim: undefined };
+    if (claim.start !== op.startSeq || claim.end !== op.endSeq) {
+        throw new Error(`token surface: replace at seq ${event.seq} over range ${op.startSeq}-${op.endSeq} has no adjacent shadow price`
+            + ` (armed claim covers ${claim.start}-${claim.end})`);
+    }
+    return { deltaTokens: tokens - claim.tokens, claim: undefined };
+}
+//# sourceMappingURL=surface-projection.js.map

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

@@ -0,0 +1,33 @@
+import type { SessionEvent } from '@qilin-agent/session/types';
+/** One provider/model route that contributed a billed request attempt. */
+export interface TurnTokenUsageRoute {
+    readonly provider: string;
+    readonly model: string;
+}
+/** Exact provider-reported token accounting for every attempt in one completed Turn. */
+export interface TurnTokenUsage {
+    /** Sum of uncached prompt input across all attempts. */
+    readonly uncachedInputTokens: number;
+    readonly outputTokens: number;
+    /** Exact aggregate prompt plus output total across all attempts. */
+    readonly totalTokens: number;
+    /** Present only when every attempt reported the bucket. */
+    readonly cacheReadTokens?: number;
+    /** Present only when every attempt reported the bucket. */
+    readonly cacheWriteTokens?: number;
+    /** Output subset, present only when every attempt reported it. */
+    readonly reasoningTokens?: number;
+    /** Present only when every billed attempt has provider/model attribution. */
+    readonly routes?: readonly TurnTokenUsageRoute[];
+}
+/**
+ * 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 declare function deriveTurnTokenUsage(events: readonly SessionEvent[]): TurnTokenUsage | undefined;
+//# sourceMappingURL=turn-usage.d.ts.map