@modelprofile.com/flexharness 10.10.0 → 10.12.0

package/ts/errors.ts

@@ -118,6 +118,14 @@ export class FlexHarnessAbortError extends FlexHarnessError {
   }
 }
 
+/** The conversational run exhausted its model steps before producing a final answer. */
+export class FlexHarnessStepLimitError extends FlexHarnessError {
+  constructor(public readonly steps: number) {
+    super('FLEX_STEP_LIMIT', `The run exhausted its ${steps} model steps before completing its answer.`);
+    this.name = 'FlexHarnessStepLimitError';
+  }
+}
+
 export class FlexHarnessCallbackOverflowError extends FlexHarnessError {
   constructor(message: string) {
     super('FLEX_CALLBACK_OVERFLOW', message);

package/ts/interfaces.ts

@@ -62,6 +62,34 @@ export interface IFlexUsage {
   cacheWriteTokens: number;
 }
 
+/** Durable fixed-size model-call accounting, independent of transcript visibility. */
+export interface IFlexSessionMetricsState {
+  reportedLifetimeUsedTokens: number;
+  reportedLifetimeUsedTokensExact: boolean;
+  lifetimeUsageComplete: boolean;
+  pendingGenerationId?: string;
+  pendingCompactionId?: string;
+  lastObservedInputTokens?: number;
+  lastObservedInputTokensAt?: string;
+}
+
+/** No member estimates current context size or includes child-session / tool-owned model calls. */
+export interface IFlexSessionMetrics {
+  /** Sum of durably settled per-call reports; a lower bound when incomplete. */
+  reportedLifetimeUsedTokens: number;
+  /** False if invalid reports or safe-integer overflow prevented an exact reported sum. */
+  reportedLifetimeUsedTokensExact: boolean;
+  lifetimeUsageComplete: boolean;
+  /** Present only when lifetimeUsageComplete is true. */
+  lifetimeUsedTokens?: number;
+  inFlight: boolean;
+  /** Input of the last durably settled generation call, not its compaction summary call. */
+  lastObservedInputTokens?: number;
+  lastObservedInputTokensAt?: string;
+  /** Always historical: output, steering, compaction and reversion can change context. */
+  lastObservedInputTokensFreshness?: 'historical';
+}
+
 export interface IFlexModelIdentity {
   provider: string;
   model: string;
@@ -775,6 +803,8 @@ export interface IFlexProjectionSnapshotV2 {
 
 export interface IFlexProjectionSnapshotV3 {
   schemaVersion: 3;
+  /** Optional for existing schema-3 stores. Absence means lifetime usage is unknown. */
+  metrics?: IFlexSessionMetricsState;
   revision: number;
   messages: IFlexMessage[];
   stagedTerminals: IFlexTerminalProjection[];
@@ -1390,6 +1420,7 @@ export interface IFlexHarnessOptions<TScope> {
   subagents?: IFlexSubagentDefinition[];
   builtInTools?: IFlexBuiltInToolsOptions;
   slashCommands?: readonly TFlexSlashCommandRegistration<TScope>[];
+  /** Maximum child depth (root is 0). Defaults to 6; configurable from 1 through 8. */
   maxSubagentDepth?: number;
   maxSubagentCallsPerRun?: number;
 }

package/ts/plugins.ts

@@ -44,6 +44,7 @@ export {
 };
 export type {
   IAgentAppliedInput,
+  ISmartAiCacheDispatch,
   IAgentEventArchiveV2,
   IAgentContextCompactionOptions,
   IAgentEventSnapshotV2,
@@ -77,7 +78,7 @@ export type {
   TAgentToolExecutionReconciliationOptions,
 } from '@modelprofile.com/flexharness-agent';
 
-import { isModelLimitError, isModelLimitInfo } from '@modelprofile.com/flexharness-models';
+import { getSmartAiCacheWaitMs, isModelLimitError, isModelLimitInfo } from '@modelprofile.com/flexharness-models';
 
-export { isModelLimitError, isModelLimitInfo };
+export { getSmartAiCacheWaitMs, isModelLimitError, isModelLimitInfo };
 export type { IModelLimitInfo } from '@modelprofile.com/flexharness-models';

package/ts/readme.md

@@ -62,7 +62,7 @@ or provider SDKs.
 | `/chat` | Portable streaming `ChatSession`, history and usage | None |
 | `/chat/cli` | Ink/React terminal chat | `ink ink-text-input react`; TypeScript: `@types/react` |
 | `/chat/web` | Lit `flexchat-window`, `flexchat-message`, `flexchat-input` | `lit` |
-| `/chat/harness` | `FlexHarnessTranscript` and intents for the `@design.estate/dees-catalog` harness components, browser-safe | `@design.estate/dees-catalog` `^17.0.0 \|\| ^19.5.0` (types only) |
+| `/chat/harness` | `FlexHarnessTranscript` and intents for the `@design.estate/dees-catalog` harness components, browser-safe | `@design.estate/dees-catalog` `^17.0.0 \|\| ^19.5.0 \|\| ^20.0.0 \|\| ^21.0.0` (types only) |
 | `/kvm` | Browser control, terminal framing and OCR observation | `puppeteer` |
 | `/documents` | PDF and image documents, `extractTextFromPdf` | `@push.rocks/smartpdf`; for image documents `sharp` |
 | `/mcp` | MCP clients and AI SDK tool conversion | `@modelcontextprotocol/sdk` |
@@ -92,6 +92,41 @@ a model backed by its own server transport, or supply `run` in
 `IChatSessionOptions`. The web element accepts an `IChatSession` and maintains its
 own subscription. Full Node `AgentSession` remains at the agent package root.
 
+## Durable session token metrics
+
+Read `await harness.getSessionMetrics(scopeId, sessionId)` for bounded, durable
+accounting independent of transcript visibility. It reads fixed-size projection
+state rather than summing assistant messages or scanning event/archive/child history.
+A warm read joins outstanding projection writes and surfaces accounting failures.
+
+| Field | Meaning |
+| --- | --- |
+| `reportedLifetimeUsedTokens` | Sum of durably settled per-call reports. Incomplete accounting makes this a lower bound. |
+| `reportedLifetimeUsedTokensExact` | Whether the sum of those reports is exact; invalid reports and safe-integer overflow make it inexact. |
+| `lifetimeUsageComplete` | Every owned call is accounted for and no accounting operation remains in flight. |
+| `lifetimeUsedTokens` | Present only when the lifetime total is complete. Zero is a valid total. |
+| `inFlight` | A generation or actual compactor invocation has not settled its accounting yet. |
+| `lastObservedInputTokens`, `lastObservedInputTokensAt` | Input count and observation time of the last settled generation call with complete input/output totals. |
+| `lastObservedInputTokensFreshness` | Always `historical`. This is **not** current context size: output, steering, compaction and reversion can change context. |
+
+Accounting covers this session's generation calls and reported compaction calls,
+including failure, cancellation and retries. Child sessions own their own spend;
+tool-owned model calls are not included. Do not sum cumulative assistant-message
+usage to reconstruct lifetime spend. Missing/partial reports remain incomplete;
+unsafe totals saturate at `Number.MAX_SAFE_INTEGER` without claiming exactness.
+A compactor that reports no calls cannot prove zero spend.
+
+New sessions start complete at zero. Existing/imported sessions with unknown prior
+spend start incomplete. Write-ahead operation markers make interrupted recovery
+conservative: unresolved operations are cleared without certifying their unknown
+spend. Undo, redo, compaction and transcript archiving never subtract lifetime
+spend. Importing visible history does not reconstruct historical billing.
+
+Conversational runs that exhaust `maxSteps` with tool work or unseen input remaining
+fail with `FlexHarnessStepLimitError` (`FLEX_STEP_LIMIT`), rather than being marked
+completed with an empty answer. Standalone Agent callers retain tool-only results
+and can inspect `terminationReason: 'model' | 'step-limit'`.
+
 ## Provider subpaths
 
 Install `@modelprofile.com/flexharness-providers` once. Its root exports all provider
@@ -260,7 +295,7 @@ const harness = new FlexHarness<IProjectScope>({
       maxSteps: 8,
     },
   ],
-  maxSubagentDepth: 1,
+  maxSubagentDepth: 6,
   maxSubagentCallsPerRun: 32,
   externalErrorProjector: (_error, context) => ({
     name: 'ModelOperationError',
@@ -414,12 +449,10 @@ Normal Flex session cleanup always waits in-flight local project operations, the
 
 ## Subagents
 
-`subagents` enables the harness-owned `delegate` and `delegate_result` tools when at least one definition exists and the session depth is below `maxSubagentDepth`. A tool provider cannot replace either enabled built-in. Delegation is asynchronous by default: `delegate` returns `{ taskId, status: 'running', runId }` after durable child admission, so the parent can continue independent work. `delegate_result({ taskId, waitMs? })` reads live status and, once settled, bounded final text and model identity; its optional wait is limited to 240 seconds and observes parent cancellation. Set `foreground: true` to await the final answer in `delegate` itself. Children remain owned by the parent turn: Stop cancels its exact child runs, and the parent joins them before releasing authority and finalizing. A child result enters the parent's next model context as untrusted task data. When the parent's model ends its turn while background children still run, the turn waits for the next child to settle and takes its result in with another step (while steps remain), so a delegated result is never lost because the parent finished first.
+`subagents` enables the harness-owned `delegate`, `delegate_result`, and `delegate_send` tools when at least one definition exists and the session depth is below `maxSubagentDepth`. A tool provider cannot replace any enabled built-in; global and agent tool allowlists still intersect to control model-facing exposure. Delegation is asynchronous by default: `delegate` returns `{ taskId, status: 'running', runId }` after durable child admission, so the parent can continue independent work. `delegate_result({ taskId, waitMs? })` reads live status and, once settled, bounded final text and model identity; its optional wait is limited to 240 seconds and observes parent cancellation. Set `foreground: true` to await the final answer in `delegate` itself. Children remain owned by the parent turn: Stop cancels its exact child runs, and the parent joins them before releasing authority and finalizing. A child result enters the parent's next model context as untrusted task data. When the parent's model ends its turn while background children still run, the turn waits for the next child to settle and takes its result in with another step (while steps remain), so a delegated result is never lost because the parent finished first.
 
 The model calls it with this exact input shape:
 
-When upgrading from 9.x, callers that require the previous synchronous delegate result must pass `foreground: true`. Tool providers must also leave the newly reserved `delegate_result` name available when subagents are enabled.
-
 ```typescript
 interface IDelegateInput {
   description: string;
@@ -430,9 +463,24 @@ interface IDelegateInput {
 }
 ```
 
+When upgrading from 9.x, callers that require the previous synchronous delegate result must pass `foreground: true`. Tool providers must also leave the reserved `delegate_result` and `delegate_send` names available when subagents are enabled.
+
+`delegate_send({ taskId, prompt })` sends follow-up instructions to a running direct child owned by this exact parent turn. Both fields are required and extra fields are rejected; `taskId` is non-empty and at most 512 UTF-8 bytes, and `prompt` is non-empty and at most 64 KiB. It returns `{ steerId, queueId, runId }` on admission, with a stable steer identity derived from the parent run and tool call. The child takes the input at its next inference boundary, without interrupting a running tool or permission wait. A child waiting to finish while its own descendants run can take the follow-up and continue inference; those descendants keep running. Use `delegate_result` to inspect progress and collect the final answer.
+
+Controllers can use the same admission path explicitly:
+
+```typescript
+await harness.sendSubagentInput(scopeId, parentSessionId, parentRunId, taskId, {
+  steerId: 'follow-up-1',
+  prompt: 'Prefer primary sources and include the publication date.',
+});
+```
+
+Sending requires the exact active parent run, its currently delegated direct child, matching captured configuration and parent/child generations, and live writable ancestors. It does not authorize a root to skip levels, or infer ownership from immutable creation-origin metadata: a resumed child belongs to the current delegate invocation. Foreign, unowned, stale, cancelled, settled, or ending runs reject; sending never starts an idle generation, restarts a child, or resumes one. General public `steerPrompt()` still forbids child sessions. Child sends share root steering's duplicate rejection, pending count/byte bounds, accepted/applied events, durable user-message application, and terminal unapplied-input accounting.
+
 Before creating or resuming a child, FlexHarness requests permission on the parent run with `kind: 'subagent.start'`, the parent `toolCallId`, and separately bounded harness-owned agent/task metadata. Its metadata includes `childSessionId`, the exact ID reserved for this call: FlexHarness derives it deterministically when `taskId` is omitted and copies the supplied candidate when `taskId` is present. A resume also retains that candidate as `taskId`. This block is not truncated by `toolOutputLimits`. The reserved ID binds permission handling before child creation but does not prove that the child exists or is owned: applications must treat the later delegated admission context as authoritative. The controller answers through the normal permission APIs. This request has no `rememberKey`, so `always` is invalid; controllers use `once` or `reject`.
 
-Each new invocation creates a durable child `IFlexSession` with immutable `parentSessionId`, origin `parentRunId`, origin `parentToolCallId`, `agent`, and `depth`. New public roots persist `depth: 0`; legacy schema-1 roots may omit it. These fields are harness-owned; public `createSession()` remains limited to `sessionId`, `sessionGenerationId`, and `title`. Child sessions reject direct `prompt()`, `startPrompt()`, `enqueuePrompt()`, and `schedulePrompt()` calls and run only through the `delegate` tool. The model and tool resolver contexts receive optional immutable `parentSessionId` and `agent` values so integrations can apply agent-specific model and tool policy. Child prompts use the definition's `modelHint`, `system`, and `maxSteps`.
+Each new invocation creates a durable child `IFlexSession` with immutable `parentSessionId`, origin `parentRunId`, origin `parentToolCallId`, `agent`, and `depth`. New public roots persist `depth: 0`; legacy schema-1 roots may omit it. These fields are harness-owned; public `createSession()` accepts `sessionId`, `sessionGenerationId`, `configurationRef`, and `title`. A child inherits its parent's `configurationRef` and cannot resume under a different reference. Child sessions reject direct `prompt()`, `startPrompt()`, `enqueuePrompt()`, and `schedulePrompt()` calls and run only through the `delegate` tool. The model and tool resolver contexts receive optional immutable `parentSessionId` and `agent` values so integrations can apply agent-specific model and tool policy. Child prompts use the definition's `modelHint`, `system`, and `maxSteps`.
 
 The parent tool part receives `childSessionId` as soon as the child is acquired, so a host can offer an authorized live transcript. A foreground call also adds the resolved child model to its part and returns bounded JSON:
 
@@ -485,7 +533,7 @@ Acquisition completes before generation-side branch reversion, context compactio
 
 For a normally acquired lease, FlexHarness gives `close()` an awaited attempt after AgentSession generation and before canonical accepted, rejected, or interrupted finalization and the terminal `prompt.finished` event. If an abort detaches an acquisition that ignores its signal, the run may settle before acquisition returns; FlexHarness retains that owner and closes any late lease. `close()` must be idempotent and safe to retry after rejection. A close failure prevents successful child acceptance and remains owned by the exact child session generation for retry by later exact-session deletion, scope retirement, or disposal. Retirement and disposal truthfully wait for late acquisition and lease cleanup.
 
-Limits are validated and frozen at construction: at most 32 unique definitions; names are non-empty and at most 128 UTF-8 bytes; descriptions 2048 bytes; optional model hints 512 bytes; optional system prompts 64 KiB; and optional `maxSteps` a positive safe integer. `maxSubagentDepth` defaults to 1 and must be a positive safe integer at most 8. `maxSubagentCallsPerRun` defaults to 32 and must be a positive safe integer at most 128. A call slot is consumed synchronously at the start of every schema-valid delegate execution, before semantic bounds, subagent type/depth validation, permission, or child work. Inputs rejected by the tool schema never start delegate execution and do not consume a slot. After successful semantic validation, the child ID candidate is reserved for the rest of the parent run, including after permission rejection or later failure. Permission rejection creates no child session. Omitting `taskId` reserves a deterministic new child ID; supplying `taskId` reserves that unverified candidate and attempts resume after permission only if it identifies a resumable child. Delegate descriptions are non-empty and at most 256 UTF-8 bytes, prompts non-empty and at most 64 KiB, subagent types at most 128 bytes, and task IDs at most 512 bytes.
+Limits are validated and frozen at construction: at most 32 unique definitions; names are non-empty and at most 128 UTF-8 bytes; descriptions 2048 bytes; optional model hints 512 bytes; optional system prompts 64 KiB; and optional `maxSteps` a positive safe integer. `maxSubagentDepth` defaults to 6 and must be a positive safe integer at most 8. The root is depth 0, so the default permits six child levels (depths 1 through 6); delegation tools are absent at the configured maximum. `maxSubagentCallsPerRun` defaults to 32 and must be a positive safe integer at most 128. A call slot is consumed synchronously at the start of every schema-valid delegate execution, before semantic bounds, subagent type/depth validation, permission, or child work. Inputs rejected by the tool schema never start delegate execution and do not consume a slot. After successful semantic validation, the child ID candidate is reserved for the rest of the parent run, including after permission rejection or later failure. Permission rejection creates no child session. Omitting `taskId` reserves a deterministic new child ID; supplying `taskId` reserves that unverified candidate and attempts resume after permission only if it identifies a resumable child. Delegate descriptions are non-empty and at most 256 UTF-8 bytes, prompts non-empty and at most 64 KiB, subagent types at most 128 bytes, and task IDs at most 512 bytes.
 
 Scope snapshots remain schema 1 and legacy child tombstones without `subagent` provenance continue to load. New child tombstones write the atomic provenance block and reject partial, parent-generation-mismatched, depth-mismatched, or duplicate-origin records. FlexHarness versions before this provenance addition reject that new optional key under their strict reader, so downgrading or mixing old readers with newly written scope snapshots is unsupported.
 
@@ -645,7 +693,7 @@ console.log(result.unappliedSteerIds); // [] once the run took the steer in
 
 The run takes a steer in at its next step boundary: after the tool results of its current model step are recorded and before its next model call. A running tool call or a pending permission is never interrupted; the steer waits for the boundary that follows it. A steer taken in is a user message of the run (`steerId` set) that the model sees in its next call and every later turn. If the run had already answered, the assistant message that answered is completed and the run answers on in a new assistant message after the steer; a steer taken in before the run answered anything is placed before its still empty assistant message. `IFlexPromptResult.userMessage` stays the prompt and `assistantMessage` is the run's last assistant message. Undo and redo treat the run's messages as one turn.
 
-`steerPrompt()` resolves with `{ steerId, queueId, runId }` once the run accepted the steer and `prompt.steer.accepted` was emitted; `prompt.steer.applied` carries the `messageId` of the user message the steer became. Every accepted steer ends in exactly one of two ways: it is in the model context of later turns, or it is listed in `unappliedSteerIds`, in arrival order, on `IFlexPromptResult` and `run.finished`, and on the finished queue entry when that list is not empty. A steer is listed when the run did not take it in before it ended, because its last model step was already running or because it was stopped or failed, and also when the run itself does not stay in context. `keptInContext` on `run.finished` and on the finished queue entry says whether it does: it is `false` for a failed run and for a run stopped before any model output, and such a run lists every steer it accepted, including the ones it took in and reported with `prompt.steer.applied`. Send its prompt and its unapplied steers again to have them answered. The run stops taking steers atomically when its generation ends or `abort()`/`cancelPrompt()` stops it. A steer for a prompt without a running run, or whose run is ending, is refused with `FlexHarnessSteerRejectedError` reason `not-running`; the caller sends it as the next turn instead. Reusing a `steerId` within a run is refused with reason `duplicate`, an unknown `queueId` throws `FlexHarnessNotFoundError`, and subagent sessions are not steerable. A run holds at most `maxOutstandingPromptsPerSession` pending steers, and their bytes count against the session's outstanding prompt byte limit until the run takes them in or ends, so `startPrompt()` and `enqueuePrompt()` are refused with `FlexHarnessQueueFullError` while pending steers fill it. They are process-local like queue entries: a process restart ends the run and drops its pending steers, while steers it took in are durable parts of the turn.
+`steerPrompt()` resolves with `{ steerId, queueId, runId }` once the run accepted the steer and `prompt.steer.accepted` was emitted; `prompt.steer.applied` carries the `messageId` of the user message the steer became. Every accepted steer ends in exactly one of two ways: it is in the model context of later turns, or it is listed in `unappliedSteerIds`, in arrival order, on `IFlexPromptResult` and `run.finished`, and on the finished queue entry when that list is not empty. A steer is listed when the run did not take it in before it ended, because its last model step was already running or because it was stopped or failed, and also when the run itself does not stay in context. `keptInContext` on `run.finished` and on the finished queue entry says whether it does: it is `false` for a failed run and for a run stopped before any model output, and such a run lists every steer it accepted, including the ones it took in and reported with `prompt.steer.applied`. Send its prompt and its unapplied steers again to have them answered. The run stops taking steers atomically when its generation ends or `abort()`/`cancelPrompt()` stops it. A steer for a prompt without a running run, or whose run is ending, is refused with `FlexHarnessSteerRejectedError` reason `not-running`; the caller sends it as the next turn instead. Reusing a `steerId` within a run is refused with reason `duplicate`, an unknown `queueId` throws `FlexHarnessNotFoundError`, and child sessions reject this general API (their exact parent run uses `sendSubagentInput()` or `delegate_send` instead). A run holds at most `maxOutstandingPromptsPerSession` pending steers, and their bytes count against the session's outstanding prompt byte limit until the run takes them in or ends, so `startPrompt()` and `enqueuePrompt()` are refused with `FlexHarnessQueueFullError` while pending steers fill it. They are process-local like queue entries: a process restart ends the run and drops its pending steers, while steers it took in are durable parts of the turn.
 
 ## Slash Commands
 
@@ -1089,6 +1137,8 @@ Each domain serializes its own mutations. A successful run first persists a hidd
 
 Projection stores accept schema version 1, 2, or 3 from `load()`, but every `save()` receives the current schema-3 shape. Schema 3 records explicit reversion protocol, transcript/workspace provenance, and V2 disposition. A terminal V2 segment must be conclusively `revertible`, `no-change`, or `nonrevertible`; a pending V2 capture remains owned by its capture WAL and is never treated as transcript history.
 
+Current schema-3 projections also persist optional `metrics` state. Older strict readers that do not recognize this key cannot reopen a projection after metrics have been written; downgrade or mixed-version access to that session is unsupported.
+
 A loaded schema-1 projection has no reversion state. Schema-2 `workspaceCaptured` segments migrate as protocol-1 workspace/revertible history without discarding references; transcript-only segments migrate as protocol-1 transcript provenance. Under `workspace-required`, that legacy transcript history is a barrier. The next projection mutation writes schema 3. Custom stores must preserve strict compare-and-swap revisions across schema-1 and schema-2 read-upgrade-write cycles, including uncertain-save reconciliation.
 
 ## Migrating From 2.x

package/ts/utils.json.ts

@@ -1506,6 +1506,35 @@ function validateAffectedWorkspaces(value: unknown, path: string): void {
   }
 }
 
+function assertSessionMetrics(value: unknown): void {
+  const path = '$snapshot.metrics';
+  const metrics = requireRecord(value, path);
+  requireOnlyKeys(metrics, [
+    'reportedLifetimeUsedTokens', 'reportedLifetimeUsedTokensExact', 'lifetimeUsageComplete',
+    'pendingGenerationId', 'pendingCompactionId', 'lastObservedInputTokens', 'lastObservedInputTokensAt',
+  ], path);
+  requireNonNegativeInteger(metrics.reportedLifetimeUsedTokens, `${path}.reportedLifetimeUsedTokens`);
+  for (const key of ['reportedLifetimeUsedTokensExact', 'lifetimeUsageComplete']) {
+    if (typeof metrics[key] !== 'boolean') throw new FlexHarnessStoreFormatError(`${path}.${key} must be boolean.`);
+  }
+  if (!metrics.reportedLifetimeUsedTokensExact && metrics.lifetimeUsageComplete) {
+    throw new FlexHarnessStoreFormatError(`${path} cannot certify an inexact total.`);
+  }
+  for (const key of ['pendingGenerationId', 'pendingCompactionId']) {
+    if (Object.hasOwn(metrics, key)) requireBoundedString(metrics[key], `${path}.${key}`, 512);
+  }
+  const hasInput = Object.hasOwn(metrics, 'lastObservedInputTokens');
+  const hasTime = Object.hasOwn(metrics, 'lastObservedInputTokensAt');
+  if (hasInput !== hasTime) throw new FlexHarnessStoreFormatError(`${path} has a partial input observation.`);
+  if (hasInput) {
+    requireNonNegativeInteger(metrics.lastObservedInputTokens, `${path}.lastObservedInputTokens`);
+    const timestamp = requireString(metrics.lastObservedInputTokensAt, `${path}.lastObservedInputTokensAt`);
+    if (!Number.isFinite(Date.parse(timestamp)) || new Date(timestamp).toISOString() !== timestamp) {
+      throw new FlexHarnessStoreFormatError(`${path}.lastObservedInputTokensAt must be an ISO timestamp.`);
+    }
+  }
+}
+
 export function assertFlexProjectionSnapshotV3(
   value: unknown,
 ): asserts value is IFlexProjectionSnapshotV3 {
@@ -1514,6 +1543,7 @@ export function assertFlexProjectionSnapshotV3(
   requireOnlyKeys(snapshot, [
     'schemaVersion',
     'revision',
+    'metrics',
     'messages',
     'stagedTerminals',
     'reversionSegments',
@@ -1522,6 +1552,7 @@ export function assertFlexProjectionSnapshotV3(
     'pendingReversion',
     'pendingReversionReleases',
   ], '$snapshot');
+  if (Object.hasOwn(snapshot, 'metrics')) assertSessionMetrics(snapshot.metrics);
   if (snapshot.schemaVersion !== 3) {
     throw new FlexHarnessStoreFormatError('Projection snapshot schemaVersion must be 3.');
   }
@@ -1673,8 +1704,9 @@ export function assertFlexProjectionSnapshotV3(
     }
     releaseCaptureIds.add(captureId);
   }
+  const { metrics: _metrics, ...compatibleSnapshot } = snapshot;
   const compatibleV2 = {
-    ...snapshot,
+    ...compatibleSnapshot,
     schemaVersion: 2,
     reversionSegments: snapshot.reversionSegments.map((entry) => {
       const segment = entry as Record<string, unknown>;

package/ts/utils.sessionmetrics.ts

@@ -0,0 +1,104 @@
+import type {
+  IFlexSessionMetrics,
+  IFlexSessionMetricsState,
+  TFlexModelCallUsage,
+} from './interfaces.js';
+
+/** Fixed-size accumulator. One owner per generation / actual compactor invocation. */
+export interface ISessionMetricsOperation {
+  id: string;
+  source: 'generation' | 'compaction';
+  reportedTokens: number;
+  reportedTokensExact: boolean;
+  complete: boolean;
+  sawCall: boolean;
+  lastObservedInputTokens?: number;
+  lastObservedInputTokensAt?: string;
+}
+
+export const createSessionMetricsState = (complete: boolean): IFlexSessionMetricsState => ({
+  reportedLifetimeUsedTokens: 0,
+  reportedLifetimeUsedTokensExact: true,
+  lifetimeUsageComplete: complete,
+});
+
+export const createSessionMetricsOperation = (
+  id: string,
+  source: ISessionMetricsOperation['source'],
+): ISessionMetricsOperation => ({
+  id, source, reportedTokens: 0, reportedTokensExact: true, complete: true, sawCall: false,
+});
+
+const isTokenCount = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+
+/** Saturation is a safe lower bound, never a rounded purported exact total. */
+const addTokens = (left: number, right: number): { tokens: number; exact: boolean } =>
+  right > Number.MAX_SAFE_INTEGER - left
+    ? { tokens: Number.MAX_SAFE_INTEGER, exact: false }
+    : { tokens: left + right, exact: true };
+
+export function observeSessionMetricsCall(
+  operation: ISessionMetricsOperation,
+  call: TFlexModelCallUsage,
+): void {
+  operation.sawCall = true;
+  if (call.status === 'unreported') {
+    operation.complete = false;
+    return;
+  }
+  const { usage } = call;
+  if (call.usageComplete === false) operation.complete = false;
+  if (!Object.values(usage).every(isTokenCount)
+    || !isTokenCount(usage.totalTokens)
+    || usage.inputTokens > Number.MAX_SAFE_INTEGER - usage.outputTokens
+    || usage.totalTokens !== usage.inputTokens + usage.outputTokens) {
+    operation.complete = false;
+    operation.reportedTokensExact = false;
+    return;
+  }
+  const sum = addTokens(operation.reportedTokens, usage.totalTokens);
+  operation.reportedTokens = sum.tokens;
+  operation.reportedTokensExact &&= sum.exact;
+  if (operation.source === 'generation' && call.usageComplete !== false) {
+    operation.lastObservedInputTokens = usage.inputTokens;
+    operation.lastObservedInputTokensAt = new Date().toISOString();
+  }
+}
+
+export function settleSessionMetricsOperation(
+  metrics: IFlexSessionMetricsState,
+  operation: ISessionMetricsOperation,
+): void {
+  const key = operation.source === 'generation' ? 'pendingGenerationId' : 'pendingCompactionId';
+  if (metrics[key] !== operation.id) throw new Error('Session metrics operation ownership changed.');
+  const sum = addTokens(metrics.reportedLifetimeUsedTokens, operation.reportedTokens);
+  metrics.reportedLifetimeUsedTokens = sum.tokens;
+  metrics.reportedLifetimeUsedTokensExact &&= sum.exact && operation.reportedTokensExact;
+  metrics.lifetimeUsageComplete &&= operation.complete
+    && metrics.reportedLifetimeUsedTokensExact
+    // An arbitrary compactor may make uninstrumented calls. No report is not proof of zero spend.
+    && (operation.source === 'generation' || operation.sawCall);
+  if (operation.lastObservedInputTokens !== undefined) {
+    metrics.lastObservedInputTokens = operation.lastObservedInputTokens;
+    metrics.lastObservedInputTokensAt = operation.lastObservedInputTokensAt;
+  }
+  delete metrics[key];
+}
+
+export function sessionMetricsView(metrics: IFlexSessionMetricsState): IFlexSessionMetrics {
+  const inFlight = metrics.pendingGenerationId !== undefined || metrics.pendingCompactionId !== undefined;
+  const lifetimeUsageComplete = metrics.lifetimeUsageComplete && !inFlight;
+  return {
+    reportedLifetimeUsedTokens: metrics.reportedLifetimeUsedTokens,
+    reportedLifetimeUsedTokensExact: metrics.reportedLifetimeUsedTokensExact,
+    lifetimeUsageComplete,
+    inFlight,
+    ...(lifetimeUsageComplete ? { lifetimeUsedTokens: metrics.reportedLifetimeUsedTokens } : {}),
+    ...(metrics.lastObservedInputTokens === undefined ? {} : {
+      lastObservedInputTokens: metrics.lastObservedInputTokens,
+      lastObservedInputTokensAt: metrics.lastObservedInputTokensAt,
+      lastObservedInputTokensFreshness: 'historical' as const,
+    }),
+  };
+}

package/ts_chat_harness/readme.md

@@ -4,7 +4,7 @@ A FlexHarness session as the inputs of the `@design.estate/dees-catalog` harness
 pnpm add @modelprofile.com/flexharness @design.estate/dees-catalog
 ```
 
-The optional peer range is `^17.0.0 || ^19.5.0`; the package builds and is tested against 19.5.
+The optional peer range is `^17.0.0 || ^19.5.0 || ^20.0.0 || ^21.0.0`; the package builds and is tested against 21.
 
 The subpath imports only types from `@design.estate/dees-catalog` and no runtime code at all, so it runs in the browser beside the components as well as on the server beside the harness.