/** * Pure folds for durable provider-reported token usage and context occupancy. */ import { z } from 'zod' import { lastAssistantStreamChunk, type TokenUsage } from '@deepseek-ai/dsh-llm' import type {} from '@deepseek-ai/dsh-llm-retry/types' import { SessionSeq } from '@deepseek-ai/dsh-session' import type { SessionEvent } from '@deepseek-ai/dsh-session' import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection' import type { ContextPressureProjection, TokenUsageProjection } from './projection.ts' import { foldSurfaceProjection } from './surface-projection.ts' const zeroBuckets = (): TokenUsageProjection => ({ uncachedInputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, }) const bucketsFrom = (usage: TokenUsage): TokenUsageProjection => ({ uncachedInputTokens: usage.inputTokens, outputTokens: usage.outputTokens, cacheReadTokens: usage.cacheReadTokens ?? 0, cacheWriteTokens: usage.cacheWriteTokens ?? 0, }) const bucketsEqual = (left: TokenUsageProjection, right: TokenUsageProjection): boolean => left.uncachedInputTokens === right.uncachedInputTokens && left.outputTokens === right.outputTokens && left.cacheReadTokens === right.cacheReadTokens && left.cacheWriteTokens === right.cacheWriteTokens const addReplacing = ( totals: TokenUsageProjection, previous: TokenUsageProjection | undefined, next: TokenUsageProjection, ): TokenUsageProjection => ({ 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() type TokenUsageState = z.infer const pressureSchema: z.ZodType = 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: TokenUsage): number => usage.inputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0) /** The usage one durable Assistant settlement reports for its attempt, if any. */ function usageOf(event: SessionEvent): TokenUsage | undefined { 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 } declare module '@deepseek-ai/dsh-session-projection/types' { interface SessionProjectionStateMap { tokenUsage: TokenUsageState contextPressure: ContextPressureState } } /** 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() type ContextPressureState = z.infer /** * 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: TokenUsage = 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 }, } satisfies ProjectionDefinition<'tokenUsage', TokenUsageState> /** * 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) }, }), }, } satisfies ProjectionDefinition<'contextPressure', ContextPressureState>