dsh-plugin-auxiliary-runtime

Three sourced usage views

View	Source and meaning
Official	The official Host tokenUsage projection, owned by the Agent loop.
Auxiliary	This plugin's auxiliary_runtime ledger, aggregated from authoritative call rows.
Combined	A read-time, bucket-by-bucket sum of Official and Auxiliary values.

The four disjoint buckets are uncachedInputTokens, outputTokens, cacheReadTokens, and cacheWriteTokens. Combined values are derived for consumers and stay outside the official projection.

Main Session transcript

Auxiliary calls use the existing Session as an identity and routing fence. The main transcript receives formal messages through the normal Session flow, after the user submits an accepted Draft. Clarify questions, answers, and Draft previews remain in Clarify's temporary Host state.

Durable auxiliary ledger

Durable rows contain identifiers, purpose, status, the four token buckets, usageRecorded, normalized failure { category, code }, and timestamps. Prompts, messages, system text, model output, custom answers, credentials, environment values, and filesystem paths remain outside storage. Failure records contain only the normalized { category, code }; the official LlmFailure.message stays outside storage.

Admission, usage, and replay

run writes a durable running row before llm.prepareCall and prepared.stream. Prepared requests complete token-limit admission after provider metadata has been materialized and before streaming begins. The latest provider usage chunk replaces the four buckets on the authoritative row; usageRecorded distinguishes an observed all-zero report from a missing report. Recorded usage survives a later error or aborted finish.

Successful live calls return model text ephemerally to the same-process caller, joined in stream order and bounded to 65,536 UTF-16 code units. Terminal replay returns the durable status and usage with replayed: true and output: null; a caller that needs new text uses a new callId. Active-id reuse, cross-Session reuse, and purpose changes are reported as conflicts.