@thehammer/danx-session-telemetry 0.1.47 → 0.1.49

package/dist/.source-hash

@@ -1 +1 @@
-ecc5da92c3cb5fcb4ef6668b9d9307de4f31ba3665c1d9437fdc1f45bd6f8b06
+b6fe84abf58a5a669072ebe58339676af7f647461c02913638f5756219baa2dc

package/dist/dispatch-usage.js

@@ -16,9 +16,9 @@
  * DB-free: runs in the DB-less worker. The sink decides the transport
  * (HTTP on a registered worker, getPool-direct on the dashboard).
  */
-import { UsageLedgerCounter, ledgerLineFromRaw, excessUsage, } from "./usage-ledger.js";
+import { UsageLedgerCounter, ledgerLineFromRaw, reportCompactionsOf, excessUsage, } from "./usage-ledger.js";
 import { ClaimTracker, emptyClaimState } from "./claim-tracker.js";
-import { ACTIVITY_BATCH_CAP, DispatchUsageTerminalError, chunkEntries, collapseActivityChanges, } from "./stats-wire.js";
+import { ACTIVITY_BATCH_CAP, COMPACTION_BATCH_CAP, DispatchUsageTerminalError, chunkEntries, collapseActivityChanges, } from "./stats-wire.js";
 import { createUsageWriteQueue } from "./write-queue.js";
 import { createLogger } from "./internal-logger.js";
 const log = createLogger("dispatch-usage");
@@ -34,6 +34,13 @@ export function zeroUsageTotals() {
         toolCallCount: 0,
     };
 }
+/** DX-4922 - the compactions as wire-sized chunks. */
+function chunkCompactions(compactions) {
+    const out = [];
+    for (let i = 0; i < compactions.length; i += COMPACTION_BATCH_CAP)
+        out.push(compactions.slice(i, i + COMPACTION_BATCH_CAP));
+    return out;
+}
 export class DispatchUsage {
     counter = new UsageLedgerCounter();
     /** DX-3962 - `null` in `"worker"` mode: the worker can never create a claim, so it can never send an `issueId`. */
@@ -338,7 +345,8 @@ export class DispatchUsage {
      * {@link DispatchUsage.unacknowledged}).
      */
     observeRawLine(raw, meta) {
-        const line = ledgerLineFromRaw(raw, meta.source, meta.byteOffset);
+        // DX-4922: a compaction boundary is judged against the session the file belongs to.
+        const line = ledgerLineFromRaw(raw, meta.source, meta.byteOffset, reportCompactionsOf(meta.sessionId));
         if (!line)
             return;
         const message = raw.message;
@@ -418,6 +426,11 @@ export class DispatchUsage {
             // starts, so the cap is respected here rather than merely made improbable.
             // Splitting across writes is lossless: each row is a full-state idempotent
             // upsert.
+            // DX-4922 - every queued compaction, in chunks of the wire's cap: chunk i rides payload i, so a backlog is
+            // drained by this one write (the terminal one included) and never waits for a later tick; a failed payload puts
+            // its chunk and every later one back on the counter's queue.
+            const compactions = this.counter.takeChangedCompactions();
+            const compactionChunks = chunkCompactions(compactions);
             const activities = this.pendingActivities.slice(0, ACTIVITY_BATCH_CAP);
             this.pendingActivities = this.pendingActivities.slice(ACTIVITY_BATCH_CAP);
             // Consume only the resets that reached a report (see `buildCursorReports`).
@@ -431,11 +444,16 @@ export class DispatchUsage {
             const haveSideData = carriesStartCursors ||
                 (catchUp ? this.storedAckedLags(reports) : this.cursorsMoved(reports)) ||
                 activities.length > 0 ||
+                compactions.length > 0 ||
                 (this.transcriptPath !== null && !this.transcriptPathSent);
             if (batches.length === 0 && (!this.started || haveSideData))
                 batches.push([]);
+            while (batches.length < compactionChunks.length)
+                batches.push([]);
             for (let i = 0; i < batches.length; i++) {
                 const payload = { entries: batches[i] };
+                if (i < compactionChunks.length)
+                    payload.compactions = compactionChunks[i];
                 const isLast = i === batches.length - 1;
                 if (isLast) {
                     if (Object.keys(reports).length > 0)
@@ -492,6 +510,7 @@ export class DispatchUsage {
                     }
                     this.healthy = false;
                     this.counter.requeue(batches.slice(i).flat().map((e) => e.messageId));
+                    this.counter.requeueCompactions(compactionChunks.slice(i).flat().map((c) => c.id));
                     // Re-queue the side data at the FRONT, and leave `ackedCursor` where it
                     // was: the next write re-reports all three. Advancing an
                     // unacknowledged cursor would skip those lines permanently, and

package/dist/pricing.d.ts

@@ -73,6 +73,8 @@ export interface PricedTokens {
 export declare const SYNTHETIC_MODEL = "<synthetic>";
 /** The `usage.speed` value a fast-mode reply carries. */
 export declare const FAST_SPEED = "fast";
+/** DX-4867 - a prompt longer than this many tokens (input + cache reads + cache writes) is billed at the model's long-prompt card. */
+export declare const LONG_PROMPT_TOKENS = 100000;
 /** DX-4593 - whether a `speed:"fast"` request on `model` is billed at the STANDARD row (see `FAST_BILLS_AT_STANDARD_RATE`): it has no fast row of its own. */
 export declare function billsFastAtStandardRate(model: string): boolean;
 /** One row of the list-price table: a model at a speed and its five per-million-token prices. */
@@ -119,6 +121,16 @@ export declare function priceUsage(model: string, speed: string, tokens: PricedT
  * standard table), or `null` when the tables have none. The default `PriceLookup` of {@link priceLedgerCredit}.
  */
 export declare function listedPrice(model: string, speed: string): ModelPrice | null;
+/** The prompt tokens of one reply: everything it sent in, cached or not. */
+export declare function promptTokensOf(tokens: PricedTokens): number;
+/** DX-4867 - whether `model` has a second, long-prompt rate card (a model with one card never switches, whatever the prompt length). */
+export declare function hasLongPromptCard(model: string): boolean;
+/**
+ * DX-4867 - price ONE reply (not a bucket of replies): like {@link priceUsage}, but a reply whose prompt is longer than
+ * {@link LONG_PROMPT_TOKENS} on a model with a long-prompt card is charged that card. A model with one rate card prices
+ * exactly as `priceUsage` does.
+ */
+export declare function priceReplyUsage(model: string, speed: string, tokens: PricedTokens): PriceResult;
 /**
  * DX-4595 - dollars for `tokens` at `price` (USD per million tokens): each bucket with its own price. The ONE copy of the formula: `priceUsage`
  * charges the list price with it, and spend pacing charges an account's own (editable) prices with it.

package/dist/pricing.js

@@ -94,9 +94,23 @@ const PRICING = {
     "claude-sonnet-4-6": price(3, 15, 0.3),
     "claude-sonnet-4-5-20250929": price(3, 15, 0.3),
     "claude-sonnet-4-20250514": price(3, 15, 0.3),
+    // DX-4867 - Claude Haiku 5.5, the page's row for prompts up to 100K tokens ($0.10 in / $0.50 out, cache hits
+    // 0.1x = $0.01, 5m write 1.25x, 1h write 2x). It has a SECOND rate card above 100K prompt tokens
+    // (LONG_CONTEXT_PRICING below): this row is the card a usage BUCKET is priced with, because a bucket sums
+    // many replies and cannot say which of them crossed the line. `priceReplyUsage` picks the card per reply.
+    "claude-haiku-5-5": price(0.1, 0.5, 0.01),
     "claude-haiku-4-5": price(1, 5, 0.1),
     "claude-haiku-4-5-20251001": price(1, 5, 0.1),
 };
+/** DX-4867 - a prompt longer than this many tokens (input + cache reads + cache writes) is billed at the model's long-prompt card. */
+export const LONG_PROMPT_TOKENS = 100_000;
+/**
+ * DX-4867 - the rate card of a reply whose prompt is longer than {@link LONG_PROMPT_TOKENS}, for the models that have
+ * one (Claude Haiku 5.5: $0.50 in / $2.50 out, cache hits 0.1x). Source: the pricing page's Claude Haiku 5.5 row.
+ */
+const LONG_CONTEXT_PRICING = {
+    "claude-haiku-5-5": price(0.5, 2.5, 0.05),
+};
 /**
  * Fast-mode prices (the page's "Fast mode pricing" section): premium
  * input/output with the prompt-caching multipliers applied ON TOP (so a 5m
@@ -175,6 +189,27 @@ export function listedPrice(model, speed) {
     const table = useFastTable ? FAST_PRICING : PRICING;
     return Object.hasOwn(table, model) ? table[model] : null;
 }
+/** The prompt tokens of one reply: everything it sent in, cached or not. */
+export function promptTokensOf(tokens) {
+    return tokens.input + tokens.cacheRead + tokens.cacheWrite5m + tokens.cacheWrite1h;
+}
+/** DX-4867 - whether `model` has a second, long-prompt rate card (a model with one card never switches, whatever the prompt length). */
+export function hasLongPromptCard(model) {
+    return Object.hasOwn(LONG_CONTEXT_PRICING, model);
+}
+/**
+ * DX-4867 - price ONE reply (not a bucket of replies): like {@link priceUsage}, but a reply whose prompt is longer than
+ * {@link LONG_PROMPT_TOKENS} on a model with a long-prompt card is charged that card. A model with one rate card prices
+ * exactly as `priceUsage` does.
+ */
+export function priceReplyUsage(model, speed, tokens) {
+    const long = promptTokensOf(tokens) > LONG_PROMPT_TOKENS && Object.hasOwn(LONG_CONTEXT_PRICING, model);
+    if (!long)
+        return priceUsage(model, speed, tokens);
+    if (speed === FAST_SPEED)
+        return { kind: "unpriced", model, speed };
+    return { kind: "priced", costUsd: costOfTokens(tokens, LONG_CONTEXT_PRICING[model]) };
+}
 /**
  * DX-4595 - dollars for `tokens` at `price` (USD per million tokens): each bucket with its own price. The ONE copy of the formula: `priceUsage`
  * charges the list price with it, and spend pacing charges an account's own (editable) prices with it.

package/dist/session-log-watcher.d.ts

@@ -197,7 +197,20 @@ export interface EntryMeta {
      * skipping them is what would lose data.
      */
     replay: boolean;
+    /**
+     * DX-4922 - the session whose transcript this line is read from, taken from the file's own location (never from a
+     * line: a forked session's file starts with copies of its parent's lines, which keep the PARENT's `sessionId`). A
+     * main transcript is `<session id>.jsonl`; a sub-agent's is `<session id>/subagents/agent-*.jsonl`, and the lines of
+     * both carry that session id.
+     */
+    sessionId: string;
 }
+/**
+ * DX-4922 - the session id a transcript file belongs to: `<session id>.jsonl` for the main transcript, and for a
+ * sub-agent file (`<session id>/subagents/agent-*.jsonl`) the directory above `subagents`. Verified on local
+ * transcripts: a sub-agent's lines carry its parent session's id, never its own agent id.
+ */
+export declare function transcriptSessionId(filePath: string): string;
 /**
  * Encode a working directory to the subdir name Claude Code writes JSONL
  * under. Replaces `/`, `.`, AND `_` with `-`. Verified empirically against

package/dist/session-log-watcher.js

@@ -57,6 +57,17 @@ export function skipReplays(consumer) {
         consumer(entry);
     };
 }
+/**
+ * DX-4922 - the session id a transcript file belongs to: `<session id>.jsonl` for the main transcript, and for a
+ * sub-agent file (`<session id>/subagents/agent-*.jsonl`) the directory above `subagents`. Verified on local
+ * transcripts: a sub-agent's lines carry its parent session's id, never its own agent id.
+ */
+export function transcriptSessionId(filePath) {
+    const dir = dirname(filePath);
+    if (basename(dir) === "subagents")
+        return basename(dirname(dir));
+    return basename(filePath, ".jsonl");
+}
 /**
  * Encode a working directory to the subdir name Claude Code writes JSONL
  * under. Replaces `/`, `.`, AND `_` with `-`. Verified empirically against
@@ -1192,7 +1203,12 @@ export class SessionLogWatcher {
      * unread byte), so a line starting exactly AT it is new.
      */
     entryMeta(state, byteOffset) {
-        return { source: state.source, byteOffset, replay: byteOffset < state.replayUntil };
+        return {
+            source: state.source,
+            byteOffset,
+            replay: byteOffset < state.replayUntil,
+            sessionId: transcriptSessionId(state.filePath),
+        };
     }
     /**
      * Emit an entry to registered consumers. For sub-agent streams,
@@ -1218,11 +1234,7 @@ export class SessionLogWatcher {
         // `delivered` cursor was already handed to a previous incarnation's
         // subscribers. Strictly `<`: `delivered` is an exclusive end (the next
         // unread byte), so a line starting exactly AT it is new.
-        const meta = {
-            source: state.source,
-            byteOffset,
-            replay: byteOffset < state.replayUntil,
-        };
+        const meta = this.entryMeta(state, byteOffset);
         for (const consumer of this.consumers) {
             try {
                 consumer(entry, meta);

package/dist/stats-wire.d.ts

@@ -9,7 +9,7 @@
  * the turn count and the tool-call count are derived from the ledger on the
  * server, and the response hands them back.
  */
-import type { LedgerEntry, LedgerUsage } from "./usage-ledger.js";
+import { type CompactionEntry, type LedgerEntry, type LedgerUsage } from "./usage-ledger.js";
 import { type ClaimState } from "./claim-tracker.js";
 /**
  * DX-2963 — cap on entries per stats write. A from-0 backlog (a reattach, a
@@ -146,6 +146,12 @@ export interface StatsPayload {
      * same deploy-window reason as {@link StatsPayload.sourceCursors}.
      */
     activities?: ActivityChange[];
+    /**
+     * DX-4922 — compactions read since the last write, at most {@link COMPACTION_BATCH_CAP} per payload; each an idempotent
+     * upsert keyed by the boundary's id. Optional for the same deploy-window reason as {@link StatsPayload.sourceCursors}:
+     * a collector that predates compaction detection sends none; absent means "none to report", never "none exist".
+     */
+    compactions?: CompactionEntry[];
     /**
      * DX-2954 — the session's own transcript file path, recorded on the
      * dispatch's `jsonl_path`.
@@ -209,6 +215,8 @@ export declare class StatsPayloadError extends Error {
  * it upserts an unbounded list.
  */
 export declare const ACTIVITY_BATCH_CAP = 500;
+/** DX-4922 — cap on compaction rows per stats write; a session compacts a handful of times, so a longer list is a defect. */
+export declare const COMPACTION_BATCH_CAP = 100;
 /** DX-2954 — cap on sources per stats write, for the same reason. */
 export declare const CURSOR_BATCH_CAP = 500;
 /**

package/dist/stats-wire.js

@@ -1,3 +1,15 @@
+/**
+ * DX-2963 — the stats-write wire contract, shared by the worker (sender) and
+ * the dashboard (the one server writer, `usage-ledger.ts`). DB-free so a
+ * DB-less worker can import it.
+ *
+ * A stats write carries ONLY ledger entries (one per reply: the per-field
+ * maximum usage seen so far, the reply's tool-use ids) that are new or changed
+ * since the last acknowledged write — never totals. Every total, the cost,
+ * the turn count and the tool-call count are derived from the ledger on the
+ * server, and the response hands them back.
+ */
+import { COMPACTION_TRIGGERS, } from "./usage-ledger.js";
 import { LEDGER_TIMING_FIELDS } from "./ledger-timing.js";
 import { ISSUE_ID_MAX_LENGTH, ISSUE_ID_PATTERN, MAX_HELD_CLAIMS, MAX_PENDING_TRANSITIONS, } from "./claim-tracker.js";
 /**
@@ -52,6 +64,7 @@ const STATS_PAYLOAD_KEYS = new Set([
     "entries",
     "sourceCursors",
     "activities",
+    "compactions",
     "transcriptPath",
 ]);
 /**
@@ -61,6 +74,8 @@ const STATS_PAYLOAD_KEYS = new Set([
  * it upserts an unbounded list.
  */
 export const ACTIVITY_BATCH_CAP = 500;
+/** DX-4922 — cap on compaction rows per stats write; a session compacts a handful of times, so a longer list is a defect. */
+export const COMPACTION_BATCH_CAP = 100;
 /** DX-2954 — cap on sources per stats write, for the same reason. */
 export const CURSOR_BATCH_CAP = 500;
 /**
@@ -343,6 +358,46 @@ function parseActivities(raw) {
         };
     });
 }
+const COMPACTION_KEYS = new Set(["id", "source", "trigger", "at", "contextBefore"]);
+function parseCompactions(raw) {
+    if (!Array.isArray(raw))
+        throw new StatsPayloadError("compactions must be an array");
+    if (raw.length > COMPACTION_BATCH_CAP) {
+        throw new StatsPayloadError(`compactions exceeds the cap of ${COMPACTION_BATCH_CAP}`);
+    }
+    const parsed = raw.map((entry, i) => {
+        const where = `compactions[${i}]`;
+        if (!entry || typeof entry !== "object")
+            throw new StatsPayloadError(where);
+        const c = entry;
+        for (const k of Object.keys(c)) {
+            if (!COMPACTION_KEYS.has(k))
+                throw new StatsPayloadError(`${where}.${k} is not a compaction field`);
+        }
+        if (typeof c.id !== "string" || !c.id)
+            throw new StatsPayloadError(`${where}.id`);
+        if (typeof c.source !== "string" || !c.source)
+            throw new StatsPayloadError(`${where}.source`);
+        if (!COMPACTION_TRIGGERS.includes(c.trigger)) {
+            throw new StatsPayloadError(`${where}.trigger must be one of ${COMPACTION_TRIGGERS.join(", ")}`);
+        }
+        if (!isNonNegInt(c.at))
+            throw new StatsPayloadError(`${where}.at`);
+        if (!isNonNegInt(c.contextBefore))
+            throw new StatsPayloadError(`${where}.contextBefore`);
+        return {
+            id: c.id,
+            source: c.source,
+            trigger: c.trigger,
+            at: c.at,
+            contextBefore: c.contextBefore,
+        };
+    });
+    // One statement upserts the list, and Postgres refuses a statement that touches a row twice.
+    if (new Set(parsed.map((c) => c.id)).size !== parsed.length)
+        throw new StatsPayloadError("compactions repeats an id");
+    return parsed;
+}
 /**
  * Strict parse of a stats body (fail loud — a malformed entry is a worker
  * bug, never coerced). Refuses more than {@link STATS_BATCH_CAP} entries, and
@@ -425,6 +480,8 @@ export function parseStatsPayload(body) {
         payload.sourceCursors = parseSourceCursors(b.sourceCursors);
     if (b.activities !== undefined)
         payload.activities = parseActivities(b.activities);
+    if (b.compactions !== undefined)
+        payload.compactions = parseCompactions(b.compactions);
     if (b.transcriptPath !== undefined)
         payload.transcriptPath = b.transcriptPath;
     return payload;

package/dist/subagent-live.js

@@ -37,7 +37,7 @@
  */
 import { createActivityObserver } from "./activity-observer.js";
 import { SYNTHETIC_MODEL, priceLedgerCredit } from "./pricing.js";
-import { MAIN_SOURCE, UsageLedgerCounter, ledgerLineFromRaw, totalTokensOfUsage } from "./usage-ledger.js";
+import { MAIN_SOURCE, REPORT_NO_COMPACTIONS, UsageLedgerCounter, ledgerLineFromRaw, totalTokensOfUsage } from "./usage-ledger.js";
 /** The line's own timestamp in epoch ms, or null when it carries none that parses. */
 function lineTime(raw) {
     if (typeof raw.timestamp !== "string")
@@ -126,7 +126,7 @@ export function createSubagentLiveView() {
                     }
                 }
             }
-            const line = ledgerLineFromRaw(raw, meta.source, meta.byteOffset);
+            const line = ledgerLineFromRaw(raw, meta.source, meta.byteOffset, REPORT_NO_COMPACTIONS);
             if (line !== null && state.counter.observeLine(line))
                 dirty.add(meta.source);
         },

package/dist/transcript-timing.d.ts

@@ -15,7 +15,7 @@
  *    line it sees (a stale queued attachment at a restart must not be a gap), and
  *    credits only what it derived from lines in its own window.
  */
-import type { LedgerLine } from "./usage-ledger.js";
+import type { CompactionBoundary, LedgerLine } from "./usage-ledger.js";
 import { type LedgerTiming } from "./ledger-timing.js";
 /** A single gap above this is a suspend or an unanswered prompt, never work. */
 export declare const MAX_CREDITED_GAP_MS = 600000;
@@ -57,6 +57,14 @@ export type TranscriptLine = {
     source: string;
     timestamp: number;
     byteOffset: number;
+}
+/** DX-4922 - a `system` line whose subtype is `compact_boundary`; it feeds the timing reducer exactly as any system line does. */
+ | {
+    kind: "compaction";
+    source: string;
+    timestamp: number;
+    byteOffset: number;
+    boundary: CompactionBoundary;
 };
 export declare function timestampOf(t: TranscriptLine): number;
 export declare class SourceTimingReducer {

package/dist/transcript-timing.js

@@ -57,6 +57,7 @@ export class SourceTimingReducer {
                 this.candidates.push({ ts, attachment: true });
                 break;
             case "system":
+            case "compaction":
                 this.carried += gap;
                 break;
         }

package/dist/usage-ledger.d.ts

@@ -51,6 +51,31 @@ export interface LedgerEntry {
      */
     issueId: string | null;
 }
+/** 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-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;
+}
 /** The fields of one assistant line the counter needs. */
 export interface LedgerLine {
     messageId: string | undefined;
@@ -120,6 +145,9 @@ export declare class UsageLedgerCounter {
     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-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,
@@ -127,6 +155,11 @@ export declare class UsageLedgerCounter {
      * with no token growth - counts as a change, so {@link takeChanged} re-sends it.
      */
     observeLine(t: TranscriptLine): boolean;
+    private observeCompaction;
+    /** 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
@@ -145,19 +178,41 @@ export declare class UsageLedgerCounter {
     /** 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): TranscriptLine | null;
+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, startByteOffset?: number): void;
+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`,

package/dist/usage-ledger.js

@@ -1,5 +1,7 @@
 import { LEDGER_TIMING_FIELDS, maxTiming, zeroTiming } from "./ledger-timing.js";
 import { SourceTimingReducer, } from "./transcript-timing.js";
+/** DX-4922 - what started a compaction: Claude Code's own threshold (`auto`) or the user's `/compact` (`manual`). */
+export const COMPACTION_TRIGGERS = ["auto", "manual"];
 export const MAIN_SOURCE = "main";
 /**
  * DX-3261 — a producer handed this module a line it cannot safely key or
@@ -123,6 +125,9 @@ export class UsageLedgerCounter {
     changed = new Set();
     /** DX-3964 - one timing reducer per source (transcript file); see `transcript-timing.ts`. */
     reducers = new Map();
+    /** DX-4922 - every compaction boundary read, by its id. */
+    compactions = new Map();
+    compactionsChanged = new Set();
     /**
      * 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,
@@ -131,6 +136,8 @@ export class UsageLedgerCounter {
      */
     observeLine(t) {
         let didChange = t.kind === "assistant" ? this.observe(t.line) : false;
+        if (t.kind === "compaction")
+            this.observeCompaction(t);
         const source = t.kind === "assistant" ? t.line.source : t.source;
         let reducer = this.reducers.get(source);
         if (!reducer) {
@@ -151,6 +158,24 @@ export class UsageLedgerCounter {
         }
         return didChange;
     }
+    observeCompaction(t) {
+        if (this.compactions.has(t.boundary.id))
+            return; // a replay of a boundary already read
+        this.compactions.set(t.boundary.id, { ...t.boundary, source: t.source, at: t.timestamp });
+        this.compactionsChanged.add(t.boundary.id);
+    }
+    /** DX-4922 - the compactions read since the last call, oldest first, as snapshots; clears the queue. */
+    takeChangedCompactions() {
+        const out = [...this.compactionsChanged].map((id) => ({ ...this.compactions.get(id) }));
+        this.compactionsChanged.clear();
+        return out;
+    }
+    /** DX-4922 - put compactions back on the changed queue (a write that failed). */
+    requeueCompactions(ids) {
+        for (const id of ids)
+            if (this.compactions.has(id))
+                this.compactionsChanged.add(id);
+    }
     /**
      * 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
@@ -309,13 +334,42 @@ function toolUsesOf(blocks) {
         input: b.input && typeof b.input === "object" && !Array.isArray(b.input) ? b.input : null,
     }));
 }
+/** The reader ships nothing, so it reports no compactions. */
+export const REPORT_NO_COMPACTIONS = { report: false };
+/** The reader reports the compactions of `sessionId`: the session its transcript FILE belongs to. */
+export function reportCompactionsOf(sessionId) {
+    return { report: true, sessionId };
+}
+const NEWLINE = "\n";
+/**
+ * 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 function reportCompactionsOfFreshTranscript(text) {
+    for (const rawLine of text.split(NEWLINE)) {
+        const trimmed = rawLine.trim();
+        if (!trimmed)
+            continue;
+        try {
+            const sessionId = JSON.parse(trimmed).sessionId;
+            if (typeof sessionId === "string" && sessionId.length > 0)
+                return reportCompactionsOf(sessionId);
+        }
+        catch {
+            // a truncated line carries no session id; the next one may
+        }
+    }
+    return REPORT_NO_COMPACTIONS;
+}
 /**
  * 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 function ledgerLineFromRaw(raw, source, byteOffset) {
+export function ledgerLineFromRaw(raw, source, byteOffset, compactions) {
     const type = raw.type;
     if (typeof type !== "string" || !FED_TYPES.has(type))
         return null;
@@ -352,14 +406,41 @@ export function ledgerLineFromRaw(raw, source, byteOffset) {
     if (type === "user") {
         return { kind: "user", source, timestamp, byteOffset, results: toolResultsOf(raw, blocksOf(message)) };
     }
+    // DX-4922: only the session's OWN compactions are reported. A forked or resumed session's transcript starts with
+    // copies of its parent's lines, boundary lines included, and those keep the parent's `sessionId`; the parent reports
+    // its own, so a copy is read as the plain system line it also is for timing. A reader that reports no compactions
+    // reads every boundary that way.
+    if (type === "system" && raw.subtype === "compact_boundary" && compactions.report) {
+        if (typeof raw.sessionId !== "string" || raw.sessionId.length === 0) {
+            throw new LedgerLineDataError("ledgerLineFromRaw: compact_boundary without a sessionId, so whose compaction it is cannot be told");
+        }
+        if (raw.sessionId === compactions.sessionId) {
+            return { kind: "compaction", source, timestamp, byteOffset, boundary: compactionBoundaryOf(raw) };
+        }
+    }
     return { kind: type, source, timestamp, byteOffset };
 }
+/** DX-4922 - read a `compact_boundary` line; a boundary this reader cannot identify or measure is a loud error, never a guess. */
+function compactionBoundaryOf(raw) {
+    const meta = raw.compactMetadata;
+    const trigger = meta?.trigger;
+    const preTokens = meta?.preTokens;
+    if (typeof raw.uuid !== "string" ||
+        raw.uuid.length === 0 ||
+        !COMPACTION_TRIGGERS.includes(trigger) ||
+        typeof preTokens !== "number" ||
+        !Number.isFinite(preTokens) ||
+        preTokens < 0) {
+        throw new LedgerLineDataError(`ledgerLineFromRaw: compact_boundary without a uuid, a known trigger and a preTokens count (uuid=${JSON.stringify(raw.uuid)}, trigger=${JSON.stringify(trigger)}, preTokens=${JSON.stringify(preTokens)})`);
+    }
+    return { id: raw.uuid, trigger: trigger, contextBefore: Math.round(preTokens) };
+}
 /**
  * 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 function observeTranscriptText(counter, text, source, startByteOffset = 0) {
+export function observeTranscriptText(counter, text, source, compactions, startByteOffset = 0) {
     const encoder = new TextEncoder();
     let offset = startByteOffset;
     for (const rawLine of text.split("\n")) {
@@ -376,7 +457,7 @@ export function observeTranscriptText(counter, text, source, startByteOffset = 0
         catch {
             continue;
         }
-        const line = ledgerLineFromRaw(parsed, source, lineOffset);
+        const line = ledgerLineFromRaw(parsed, source, lineOffset, compactions);
         if (line)
             counter.observeLine(line);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-session-telemetry",
-  "version": "0.1.47",
+  "version": "0.1.49",
   "description": "Shared Claude Code transcript collector (DX-2962) — incremental JSONL tailing for the danxbot worker and the danx-dashboard-mcp MCP server's relay, so both run identical collector code.",
   "license": "MIT",
   "type": "module",