@50arms/session-telemetry 0.0.0-stage → 0.1.66

package/dist/usage-ledger.d.ts

@@ -0,0 +1,256 @@
+/**
+ * DX-2963 — the ONE usage counter. Turns Claude Code transcript lines into
+ * per-reply usage-ledger entries; every counter in danxbot (the worker's
+ * accumulator, `claude-probe.ts`'s usage summer, the stall sweep's productivity signal,
+ * the cross-consumer tests) uses it instead of its own summing.
+ *
+ * The rule it implements, measured on real transcripts (DX-2963 card,
+ * 2026-09-18): Claude Code writes one assistant reply as SEVERAL lines that
+ * share a `message.id`, and the later lines carry the real (larger) usage —
+ * the last line held the maximum in 28,121 of 28,124 multi-line replies. A
+ * reply's usage is therefore the per-FIELD MAXIMUM over its lines, never its
+ * first line (the old rule every counter shared, which undercounted output
+ * 3.17x on sub-agent transcripts) and never a sum (which over-counts).
+ * Far-later repeats of a `message.id` are replays of re-written history and
+ * never raise usage, so a max-based counter credits them nothing for free.
+ *
+ * Pure arithmetic — no `node:` imports — so it is exported through the
+ * browser-safe `./browser` subpath as well as the main entry.
+ */
+import type { PricedTokens } from "./pricing.js";
+import { type LedgerTiming } from "./ledger-timing.js";
+import { type TranscriptLine } from "./transcript-timing.js";
+import type { AgentLogEntry } from "./types.js";
+/** Per-reply usage, both cache-write lifetimes kept apart (priced apart). */
+export type LedgerUsage = PricedTokens;
+/**
+ * One reply's ledger entry as the collector reports it: the per-field
+ * MAXIMUM usage seen over the reply's lines so far, plus every `tool_use`
+ * id seen in it.
+ */
+export interface LedgerEntry {
+    /** `message.id`, or the synthetic `nomsg:<source>:<byteOffset>` key. */
+    messageId: string;
+    /** `"main"` for the dispatch's own transcript, else the sub-agent id. */
+    source: string;
+    /** First non-empty `message.model` seen for the reply; `null` if none. */
+    model: string | null;
+    /** `usage.speed` (`standard` / `fast`); `"standard"` when the line has none. */
+    speed: string;
+    usage: LedgerUsage;
+    /** DX-3964 - the reply's measured time and lines; see {@link LedgerTiming}. */
+    timing: LedgerTiming;
+    /** The reply's own transcript timestamp (its FIRST line's), epoch ms. */
+    repliedAt: number;
+    toolUseIds: string[];
+    /**
+     * DX-3962 - the card this reply is credited to, or `null`. Fixed by the
+     * reply's FIRST line and never changed by a later one. Only an operator-session
+     * collector (`DispatchUsage`, `"operator-bridge"` mode) ever sets it; every
+     * other producer of an entry carries `null`.
+     */
+    issueId: string | null;
+    /**
+     * DX-4939 - whether the reply did real work: any tool use of any of its lines edits or writes a file, writes a card or spawns
+     * a sub-agent (`real-work.ts`). It only ever rises as later lines of the reply arrive.
+     */
+    realWork: boolean;
+}
+/** DX-4922 - what started a compaction: Claude Code's own threshold (`auto`) or the user's `/compact` (`manual`). */
+export declare const COMPACTION_TRIGGERS: readonly ["auto", "manual"];
+export type CompactionTrigger = (typeof COMPACTION_TRIGGERS)[number];
+/**
+ * DX-4922 - the facts of one `compact_boundary` transcript line (`type: "system"`, `subtype: "compact_boundary"`;
+ * shape taken from real transcripts): its `uuid`, `compactMetadata.trigger` and `compactMetadata.preTokens`, the
+ * context size Claude Code measured just before it replaced the history with a summary.
+ */
+export interface CompactionBoundary {
+    /** The boundary line's own `uuid`: the compaction's identity, stable across a re-read of the file. */
+    id: string;
+    trigger: CompactionTrigger;
+    contextBefore: number;
+    /**
+     * DX-4939 - `compactMetadata.postTokens`: the context size Claude Code measured just after the compaction, summary and preserved
+     * messages together, or `null` when the line does not carry it (Claude Code versions differ; a sub-agent's boundary may lack it).
+     * `null` means not recorded, never zero.
+     */
+    postTokens: number | null;
+    /** DX-4939 - `compactMetadata.durationMs`: how long the compaction paused the session, or `null` when the line does not carry it. */
+    durationMs: number | null;
+}
+/**
+ * DX-4922 - one compaction as the collector reports it. A resend of the same `id` is an idempotent upsert on the server,
+ * which also derives the restart point (the context size of the source's first reply after the boundary) from the
+ * replies it stores, so a collector restart can never lose it.
+ */
+export interface CompactionEntry extends CompactionBoundary {
+    /** `"main"` or the sub-agent id, as {@link LedgerEntry.source}. */
+    source: string;
+    /** The boundary line's transcript timestamp, epoch ms. */
+    at: number;
+    /**
+     * DX-4939 - the length in characters of the compaction's summary text (the `isCompactSummary` user line that follows the boundary),
+     * or `null` until that line is read. `null` means NOT OBSERVED, and it can stay so for good: a transcript with no summary line, or a collector
+     * restarted between the boundary line and the summary line (it re-reads from its cursor, which is past the boundary, so it never learns
+     * which compaction the summary belongs to). The cost report leaves such a compaction out of its medians. The summary call's output tokens are not in the
+     * transcript; the summary's text is, and its length is the truest figure there is (`compactMetadata.postTokens` also counts the
+     * preserved messages and fixed prompt, about 6.8x the summary on the local transcripts of 2026-10-12, DX-4939).
+     */
+    summaryChars: number | null;
+}
+/** The fields of one assistant line the counter needs. */
+export interface LedgerLine {
+    messageId: string | undefined;
+    source: string;
+    /** Byte offset of the line's first byte in its file — keys a line with no id. */
+    byteOffset: number;
+    model: string | undefined;
+    /** The line's raw `message.usage` block, if it carries one. */
+    usage: Record<string, unknown> | undefined;
+    /** The line's transcript timestamp, epoch ms. */
+    timestamp: number;
+    /** `tool_use` block ids on this line. */
+    toolUseIds: readonly string[];
+    /** DX-3962 - the card the line's reply is credited to when this is its first line; see {@link LedgerEntry.issueId}. */
+    issueId: string | null;
+    /** DX-4939 - whether this line's tool uses include real work; see {@link LedgerEntry.realWork}. */
+    realWork: boolean;
+}
+export declare const MAIN_SOURCE = "main";
+/**
+ * DX-3261 — a producer handed this module a line it cannot safely key or
+ * date: no valid `byte_offset` on a no-`message.id` line (would collapse
+ * every such line in the source onto the same synthetic key, crediting only
+ * the largest — see {@link syntheticMessageKey}), or a `timestamp` that
+ * doesn't parse (would read as `repliedAt: 0`, invisible to every
+ * account-window lookback). Both were silent `0` defaults before this card;
+ * thrown here instead, so a broken producer fails immediately and visibly
+ * rather than quietly losing or mis-crediting usage.
+ */
+export declare class LedgerLineDataError extends Error {
+}
+/**
+ * DX-2963 — a usage line with no `message.id` (never observed in the 22,087
+ * usage lines of the 20 newest local transcripts, 2026-09-18) is keyed by its
+ * source and the byte offset of its line, so it is credited exactly once
+ * however often the file is re-read, instead of once per read.
+ */
+export declare function syntheticMessageKey(source: string, byteOffset: number): string;
+export declare function isSyntheticMessageKey(key: string): boolean;
+/**
+ * Read a raw `message.usage` block into {@link LedgerUsage}. The two
+ * cache-write lifetimes come from `usage.cache_creation.ephemeral_5m_input_tokens`
+ * / `ephemeral_1h_input_tokens`. A line that carries only the flat
+ * `cache_creation_input_tokens` (no split object) wrote with the API's
+ * default 5-minute lifetime, so the whole amount is a 5-minute write — that
+ * is what the flat field meant before the split existed.
+ */
+export declare function parseUsageBlock(raw: Record<string, unknown>): LedgerUsage;
+export declare function zeroUsage(): LedgerUsage;
+export declare const LEDGER_USAGE_FIELDS: readonly ["input", "output", "cacheRead", "cacheWrite5m", "cacheWrite1h"];
+export declare function maxUsage(a: LedgerUsage, b: LedgerUsage): LedgerUsage;
+export declare function addUsage(a: LedgerUsage, b: LedgerUsage): LedgerUsage;
+/** Per-field `max(0, a - b)`. */
+export declare function excessUsage(a: LedgerUsage, b: LedgerUsage): LedgerUsage;
+export declare function isZeroUsage(u: LedgerUsage): boolean;
+/** Window tokens: input + output + both cache writes (the account-window unit). */
+export declare function windowTokensOfUsage(u: LedgerUsage): number;
+/** All five fields summed. */
+export declare function totalTokensOfUsage(u: LedgerUsage): number;
+/**
+ * The per-process counter: one entry per reply, updated line by line.
+ * `observe` returns true when the line CHANGED the reply's entry (a new
+ * reply, a raised field, or a new tool-use id) — a replay returns false —
+ * and the entry is queued for {@link takeChanged}. Holds one small entry per
+ * reply for the life of the process; no transcript text is kept.
+ */
+export declare class UsageLedgerCounter {
+    private readonly entries;
+    private readonly changed;
+    /** DX-3964 - one timing reducer per source (transcript file); see `transcript-timing.ts`. */
+    private readonly reducers;
+    /** DX-4922 - every compaction boundary read, by its id. */
+    private readonly compactions;
+    private readonly compactionsChanged;
+    /** DX-4939 - per source, the compaction whose summary line has not been read yet. */
+    private readonly openSummary;
+    /**
+     * DX-3964 - feed one line of the fed set (assistant, user, attachment, system) in FILE ORDER. An assistant
+     * line credits usage exactly as {@link observe} does; every kind also feeds its source's timing reducer,
+     * and a reply's timing that RISES - including one raised by a later tool_result, after the reply's last line,
+     * with no token growth - counts as a change, so {@link takeChanged} re-sends it.
+     */
+    observeLine(t: TranscriptLine): boolean;
+    private observeCompaction;
+    /**
+     * DX-4939 - the summary text follows its boundary in the same source's file: the next `isCompactSummary` user line belongs to the
+     * compaction last read there. A compaction is reported at its boundary and again (a changed entry) once its summary length is known,
+     * so a session that ends right after compacting still reports it.
+     */
+    private observeCompactSummary;
+    /** DX-4922 - the compactions read since the last call, oldest first, as snapshots; clears the queue. */
+    takeChangedCompactions(): CompactionEntry[];
+    /** DX-4922 - put compactions back on the changed queue (a write that failed). */
+    requeueCompactions(ids: readonly string[]): void;
+    /**
+     * DX-3964 - a source's file was truncated and is read again from 0: its timing reducer starts fresh and
+     * first-line-anchored, so a stale `hwm` of the old file can never credit a gap at the reset. Entries keep their
+     * values (max semantics); the re-read can only raise them.
+     */
+    resetSource(source: string): void;
+    observe(line: LedgerLine): boolean;
+    /** Entries changed since the last call, as snapshots; clears the queue. */
+    takeChanged(): LedgerEntry[];
+    /** Put entries back on the changed queue (a write that failed). */
+    requeue(messageIds: readonly string[]): void;
+    get(messageId: string): LedgerEntry | undefined;
+    all(): LedgerEntry[];
+    /** Per-field sum of every reply's maximum — the transcript's true total. */
+    totals(): LedgerUsage;
+    /** Distinct tool-use ids across all replies. */
+    toolUseCount(): number;
+}
+/**
+ * DX-4922 - whether a reader reports the compactions it reads. A reader that ships its ledger entries to the server
+ * (`DispatchUsage`) reports the compactions of the session it reads; one that only measures locally (the sub-agent live
+ * view, the probe, the bench attempt telemetry) says so by name, and a boundary it meets is then a plain system line.
+ */
+export type CompactionReading = {
+    readonly report: false;
+} | {
+    readonly report: true;
+    readonly sessionId: string;
+};
+/** The reader ships nothing, so it reports no compactions. */
+export declare const REPORT_NO_COMPACTIONS: CompactionReading;
+/** The reader reports the compactions of `sessionId`: the session its transcript FILE belongs to. */
+export declare function reportCompactionsOf(sessionId: string): CompactionReading;
+/**
+ * The reading for a transcript of a FRESH session read as text: the session id its own lines carry. Only right where
+ * nothing is inherited (a bench attempt starts a new session); a fork's file starts with its parent's lines, so a
+ * live reader takes the session from the file's location instead (`transcriptSessionId`). A transcript with no line
+ * carrying a session id has no compaction boundary either, so it reports none.
+ */
+export declare function reportCompactionsOfFreshTranscript(text: string): CompactionReading;
+/**
+ * Parse one raw transcript line (a parsed JSONL object) of the fed set - assistant, user (tool_result and human
+ * prompts), attachment, system - into a {@link TranscriptLine}. Returns `null` for every other `type`
+ * (`queue-operation`, `last-prompt`, `file-history-*`, `custom-title`, ...). THE one parser for the usage feed:
+ * the live watcher subscription, `observeTranscriptText` (claude-probe) and the tests all go through it.
+ */
+export declare function ledgerLineFromRaw(raw: Record<string, unknown>, source: string, byteOffset: number, compactions: CompactionReading): TranscriptLine | null;
+/**
+ * Count a whole transcript text (one file) into a counter. Byte offsets are
+ * computed on UTF-8 bytes so a no-id line keys identically to the live
+ * watcher's own offset for the same line.
+ */
+export declare function observeTranscriptText(counter: UsageLedgerCounter, text: string, source: string, compactions: CompactionReading, startByteOffset?: number): void;
+/**
+ * The counter's {@link LedgerLine} for one converted watcher entry
+ * (`AgentLogEntry`, as `SessionLogWatcher` emits it: `data.messageId`,
+ * `data.model`, `data.usage`, `data.content`, `data.subagent_id`,
+ * `data.byte_offset`). `null` for anything that is not an assistant entry.
+ * Shared by every counter fed from watcher entries (the worker's dispatch
+ * usage, the stall sweep's productivity signal).
+ */
+export declare function ledgerLineFromLogEntry(entry: AgentLogEntry): LedgerLine | null;