@thehammer/danx-session-telemetry 0.1.14 → 0.1.15

package/dist/dispatch-usage.js

@@ -0,0 +1,430 @@
+/**
+ * DX-2963 — a running dispatch's usage, worker side.
+ *
+ * The worker no longer sums anything. It feeds every transcript line into
+ * the ONE shared counter (`UsageLedgerCounter`, per-field maximum per reply)
+ * and ships the entries that are new or changed since the last acknowledged
+ * write to the server (`applyStats`), which derives every total from the
+ * ledger and hands them back. The worker's own view of the totals is what the
+ * server last returned — plus, for the token ceiling only, a local estimate of
+ * what it has read but the server has not acknowledged yet.
+ *
+ * Totals are taken from the server ONLY at process start (the first write,
+ * sent with no entries if there are none) and from each write's response —
+ * never seeded by hand (the reattach hand seeds this replaces).
+ *
+ * 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, ledgerLineFromLogEntry, excessUsage, syntheticMessageKey, } from "./usage-ledger.js";
+import { ACTIVITY_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");
+export function zeroUsageTotals() {
+    return {
+        tokensIn: 0,
+        tokensOut: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        tokensTotal: 0,
+        costUsd: 0,
+        turnCount: 0,
+        toolCallCount: 0,
+    };
+}
+/*
+ * DX-2954 — `isPreCardUsageRow` was DELETED here, along with
+ * `src/agent/pre-card-lineage.ts` and `markPreCardLineage` below.
+ *
+ * It answered "did this row count usage before the ledger existed?", which
+ * mattered only because a dispatch had nowhere to record HOW FAR it had read:
+ * the choice was between re-reading a file from 0 (double-counting) and skipping
+ * to its end (losing everything since the last write). `src/agent/start-cursors.ts`
+ * dissolves the question — a row WITH stored cursors resumes from them whatever
+ * its lineage, and a row WITHOUT any is exactly the case the start order's rule
+ * 4 covers. Nothing writes `usage_pre_card_lineage` any more.
+ */
+export class DispatchUsage {
+    counter = new UsageLedgerCounter();
+    serverTotals = zeroUsageTotals();
+    acked = new Map();
+    healthy = true;
+    refused = false;
+    started = false;
+    queue = createUsageWriteQueue();
+    // ── DX-2954: the cursor half ──────────────────────────────────────────────
+    /** How to read the watcher's live per-source cursor state. */
+    readCursorState = null;
+    /**
+     * Per source, the `delivered` offset as of the last ACKNOWLEDGED write — which
+     * is precisely what `acked` means. Seeded from the cursors this process
+     * resumed from, so a restart that writes before reading anything re-reports
+     * its own resume point instead of regressing it.
+     */
+    ackedCursor = new Map();
+    /** Past-EOF resets to report once, then forget. */
+    pastEof = [];
+    /**
+     * DX-2954 — replies this process read as REPLAYS. The server already counted
+     * them for THIS dispatch (they are below its stored `acked`), so they must not
+     * enter the unacknowledged excess the token-ceiling estimate adds on top of the
+     * server totals.
+     */
+    replayedMessageIds = new Set();
+    /** Running-set changes to report on the next write. */
+    pendingActivities = [];
+    /** The session transcript path — the ONE path field the wire carries. */
+    transcriptPath = null;
+    transcriptPathSent = false;
+    /**
+     * DX-2954 — wire the cursor half up at attach.
+     *
+     * `startCursors` are the cursors this process RESUMED from
+     * (`resolveStartCursors`); their `acked` values seed this collector's own
+     * acknowledged floor. `readCursorState` reads the watcher's live offsets at
+     * each write.
+     */
+    attachCursors(readCursorState, startCursors) {
+        this.readCursorState = readCursorState;
+        for (const [source, cursor] of Object.entries(startCursors)) {
+            this.ackedCursor.set(source, cursor.acked);
+        }
+    }
+    /**
+     * DX-2954 — a stored cursor was past its file's end; report the reset on the
+     * next write so the server records a `transcript_cursor_past_eof` event and
+     * permits the one sanctioned backwards move of `acked`.
+     */
+    recordPastEof(info) {
+        this.pastEof.push(info);
+        // The acknowledged floor MUST drop with the file. Leaving it at the old
+        // offset would make the next write report `acked` above its own `delivered`
+        // — which `parseStatsPayload` refuses outright ("delivered is behind
+        // acked"), and which the getPool-direct sink would store as a cursor pair
+        // that can never be satisfied. The bytes we believed acknowledged do not
+        // exist any more, so claiming them is simply false.
+        this.ackedCursor.set(info.source, 0);
+    }
+    /**
+     * DX-2954 — queue running-set changes for the next write.
+     *
+     * Kept COLLAPSED (one entry per `(kind, activityId)`) rather than appended
+     * raw, so the queue is bounded by how many activities the dispatch has, not by
+     * how much they moved since the last write. A producer reports an activity's
+     * full current state every time anything about it changes, and a chatty
+     * sub-agent advances its `lastActivityAt` continuously — appending those would
+     * grow without bound, eventually exceed `ACTIVITY_BATCH_CAP` and take the
+     * WHOLE stats write down (not just its activity part) to describe a handful of
+     * activities.
+     *
+     * `collapseActivityChanges` applies the server's own merge rule, so collapsing
+     * here reaches the identical stored row; it is not a lossy summarisation.
+     */
+    recordActivities(changes) {
+        this.pendingActivities = collapseActivityChanges([
+            ...this.pendingActivities,
+            ...changes,
+        ]);
+    }
+    /**
+     * DX-2954 — the session's own transcript path, recorded on the dispatch's
+     * `jsonl_path`. Sent once, with the first stats write that carries it; the
+     * server also keeps only the first path it is given, so a repeat is harmless.
+     */
+    setTranscriptPath(path) {
+        this.transcriptPath = path;
+    }
+    /**
+     * DX-2954 — this write's cursor reports, plus the `delivered` value to promote
+     * to `acked` per source once the write is acknowledged.
+     *
+     * **`acked` deliberately LAGS `delivered` by one write.** A write reports the
+     * position it has read to (`delivered`) and the position whose entries a
+     * PREVIOUS write already had acknowledged (`acked`); only when THIS write
+     * succeeds does its own `delivered` become the next write's `acked`.
+     *
+     * The lag is not slack — it is what makes the pair safe. A reply's ledger entry
+     * can be RAISED after it was first reported (its usage grows as the reply
+     * streams), and a delivered line need not produce an entry at all (a
+     * `tool_result`), so "the server committed my last write" is NOT the same as
+     * "every line I have read is finally accounted for". Reporting `acked` one
+     * write behind is the conservative claim that is always true.
+     *
+     * What it costs: a restart re-reads the last write's window. That is exactly
+     * the window `EntryMeta.replay` covers — the ledger re-credits nothing (its
+     * excess rule) and every side-effecting subscriber skips it — so the cost is
+     * one window of re-read, never a double count or a duplicate side effect.
+     *
+     * ## KNOWN GAP: the process-start write carries no cursors
+     *
+     * `attachMonitoringStack` deliberately does NOT await `watcher.start()` —
+     * file discovery polls for up to 180 s and must not block the spawn — and the
+     * process-start stats write fires immediately after it. At that moment the
+     * watcher has opened no file, so `cursorState()` is empty and this returns no
+     * reports. Cursors first reach the server on the write AFTER discovery, one
+     * stats tick (15-30 s) later.
+     *
+     * The bound this puts on the card's "every attach persists its starting
+     * cursors in its first stats write": a dispatch that dies inside its first
+     * stats interval stores no cursor at all, so a later dispatch continuing its
+     * session resolves start-order rule 4 (existing files at EOF) and does not
+     * count that first interval's usage. The ledger keeps this from ever
+     * DOUBLE-counting; the cost is the same bounded loss the card already accepts
+     * for the deploy transition. Closing it properly means persisting the starting
+     * cursor on discovery rather than on the next tick — a watcher-discovery
+     * callback wired into the ordered stats channel — which is a separate change,
+     * not something to bolt onto the flush path.
+     */
+    buildCursorReports() {
+        const reports = {};
+        const deliveredAtSend = new Map();
+        if (!this.readCursorState)
+            return { reports, deliveredAtSend, reportedResets: [] };
+        const resetBySource = new Map(this.pastEof.map((p) => [p.source, p]));
+        const reportedResets = [];
+        for (const [source, state] of Object.entries(this.readCursorState())) {
+            // `acked` floors at the source's START offset: a source opened at EOF
+            // under rule 4 must never claim byte 0 as acknowledged, or the next
+            // restart would read the whole file and re-sum the history rule 4 skipped.
+            const acked = Math.max(this.ackedCursor.get(source) ?? 0, state.startOffset);
+            const report = { acked, delivered: state.delivered };
+            const reset = resetBySource.get(source);
+            if (reset) {
+                report.pastEof = { storedOffset: reset.storedOffset, fileSize: reset.fileSize };
+                reportedResets.push(reset);
+            }
+            reports[source] = report;
+            deliveredAtSend.set(source, state.delivered);
+        }
+        // Only the resets that actually reached a report are consumed. A reset for a
+        // source that has left `cursorState()` (its tail dropped on ENOENT) would
+        // otherwise be taken and forgotten, leaving the stored `acked` at a value the
+        // file can never satisfy.
+        return { reports, deliveredAtSend, reportedResets };
+    }
+    /**
+     * DX-2954 — whether the cursor half has anything new to say. An IDLE dispatch
+     * (no new lines, no hook events) must still cost zero writes per tick, which
+     * is why a write is not forced merely because cursors EXIST.
+     */
+    cursorsMoved(reports) {
+        for (const [source, report] of Object.entries(reports)) {
+            if (report.pastEof !== undefined)
+                return true;
+            // A source whose `delivered` has not moved past its last acknowledged
+            // point has nothing to report. A source seen for the FIRST time has no
+            // entry in `ackedCursor` yet, so it always counts as moved — that is how a
+            // newly discovered sub-agent file gets its starting cursor persisted.
+            if (report.delivered !== this.ackedCursor.get(source))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Feed one watcher entry. Only assistant lines carry usage / tool ids.
+     *
+     * `replay` (DX-2954) marks a line re-read after a restart. The line STILL goes
+     * to the counter — the ledger is idempotent and dropping it would lose usage a
+     * restart is meant to recover — but its id is remembered so the local ceiling
+     * estimate does not count it twice (see {@link DispatchUsage.unacknowledged}).
+     */
+    observeEntry(entry, replay = false) {
+        const line = ledgerLineFromLogEntry(entry);
+        if (!line)
+            return;
+        // The counter's OWN key, not `line.messageId`: a usage line with no
+        // `message.id` is keyed by `syntheticMessageKey(source, byteOffset)`
+        // (`usage-ledger.ts`), and recording a different key here would leave that
+        // reply's replay unrecognised — the exact double-count this set prevents.
+        if (replay) {
+            this.replayedMessageIds.add(line.messageId ?? syntheticMessageKey(line.source, line.byteOffset));
+        }
+        this.counter.observe(line);
+    }
+    /**
+     * Ship every changed entry in capped batches, one after another. The first
+     * call always writes (even with nothing to send) so the process takes the
+     * server totals at start. A failed batch re-queues itself and every later
+     * batch; a refusal (the dispatch went terminal) stops all later writes.
+     *
+     * DX-2954 — the write also carries the cursor half. A write happens when there
+     * are entries, OR the cursors moved, OR there are activity changes, OR it is
+     * the process-start write; an idle dispatch still writes nothing. Cursors,
+     * activity changes and the transcript path ride the LAST batch only, so a
+     * multi-batch backlog does not repeat them and the cursor can never be
+     * acknowledged ahead of the entries it covers.
+     */
+    flush(sink, dispatchId) {
+        return this.queue(async () => {
+            if (this.refused)
+                return "refused";
+            const changed = this.counter.takeChanged();
+            const batches = chunkEntries(changed);
+            const { reports, deliveredAtSend, reportedResets } = this.buildCursorReports();
+            // TAKE the queued side data, exactly as `counter.takeChanged()` does, so a
+            // hook that fires during the await lands in the NEXT write rather than
+            // being silently dropped by a post-write reset of the live array.
+            // Take at most one batch's worth and LEAVE the rest queued. The cap is
+            // enforced server-side by the strict parser, and an over-cap payload comes
+            // back as a 400 — which is not a `DispatchUsageTerminalError`, so `flush`
+            // re-queues it and retries the identical over-cap payload forever. That
+            // wedges the dispatch's stats writes PERMANENTLY, entries and cursors
+            // included, not just its activity rows. The collapse in `recordActivities`
+            // makes crossing the cap unlikely (one entry per distinct activity, not per
+            // change), but nothing bounds how many distinct activities a dispatch
+            // 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.
+            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`).
+            const pastEofSent = reportedResets;
+            const sentResets = new Set(reportedResets);
+            this.pastEof = this.pastEof.filter((p) => !sentResets.has(p));
+            const haveSideData = this.cursorsMoved(reports) ||
+                activities.length > 0 ||
+                (this.transcriptPath !== null && !this.transcriptPathSent);
+            if (batches.length === 0 && (!this.started || haveSideData))
+                batches.push([]);
+            for (let i = 0; i < batches.length; i++) {
+                const payload = { entries: batches[i] };
+                const isLast = i === batches.length - 1;
+                if (isLast) {
+                    if (Object.keys(reports).length > 0)
+                        payload.sourceCursors = reports;
+                    if (activities.length > 0)
+                        payload.activities = activities;
+                    if (this.transcriptPath !== null && !this.transcriptPathSent) {
+                        payload.transcriptPath = this.transcriptPath;
+                    }
+                }
+                try {
+                    const res = await sink.applyStats(dispatchId, payload);
+                    this.started = true;
+                    this.serverTotals = res.totals;
+                    for (const [id, u] of Object.entries(res.perMessage))
+                        this.acked.set(id, u);
+                    if (isLast) {
+                        // The write landed, so every line up to the `delivered` we SENT is
+                        // now acknowledged — that is what makes the next restart resume
+                        // there. A source the server REFUSED as a regression keeps its own
+                        // stored value, so we must not promote ours past it.
+                        const refused = new Set(res.cursorRegressions);
+                        // A source whose file was found truncated WHILE this write was in
+                        // flight must NOT have its floor promoted. `recordPastEof` dropped
+                        // that floor to 0 on purpose; re-raising it here would make the next
+                        // report claim `acked` above its own `delivered`, which
+                        // `parseStatsPayload` refuses outright — wedging every later write
+                        // for this dispatch, since nothing lowers `acked` again.
+                        const resetMidFlight = new Set(this.pastEof.map((p) => p.source));
+                        for (const [source, delivered] of deliveredAtSend) {
+                            if (refused.has(source) || resetMidFlight.has(source))
+                                continue;
+                            this.ackedCursor.set(source, delivered);
+                        }
+                        if (payload.transcriptPath !== undefined)
+                            this.transcriptPathSent = true;
+                    }
+                }
+                catch (err) {
+                    if (err instanceof DispatchUsageTerminalError) {
+                        this.refused = true;
+                        return "refused";
+                    }
+                    this.healthy = false;
+                    this.counter.requeue(batches.slice(i).flat().map((e) => e.messageId));
+                    // 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
+                    // dropping a past-EOF reset would leave the server refusing the
+                    // eventual lower `acked` as a regression forever.
+                    // Collapsed on the way back in, so the re-queue keeps the invariant
+                    // `recordActivities` maintains — and so a failed write followed by
+                    // fresh changes for the same activity does not double the queue.
+                    this.pendingActivities = collapseActivityChanges([
+                        ...activities,
+                        ...this.pendingActivities,
+                    ]);
+                    this.pastEof = [...pastEofSent, ...this.pastEof];
+                    log.error(`[Dispatch ${dispatchId}] stats write failed — entries re-queued for the next write`, err);
+                    return "failed";
+                }
+            }
+            this.healthy = true;
+            return "ok";
+        });
+    }
+    /** The dispatch's totals as the server last returned them. */
+    totals() {
+        return this.serverTotals;
+    }
+    /** Window tokens (input + output + cache writes) of the server totals. */
+    serverWindowTokens() {
+        const t = this.serverTotals;
+        return t.tokensIn + t.tokensOut + t.cacheWrite;
+    }
+    /** Whether the most recent stats write succeeded. */
+    statsHealthy() {
+        return this.healthy;
+    }
+    /**
+     * The per-field excess of each local reply's maximum over what the server
+     * last acknowledged for it.
+     *
+     * DX-2954 — REPLAYED replies are excluded. The pre-DX-2954 comment here
+     * asserted that "every id this process observed was read at or after its
+     * starting cursor … so lines re-read on a restart never enter the estimate",
+     * which stopped being true the moment replays became a deliberate input: a
+     * replayed reply has no entry in `this.acked` at process start, so its FULL
+     * usage would be added on top of `serverTotals` that already contain it. That
+     * feeds a fabricated total to the token ceiling (`agent-status.ts` uses this
+     * estimate precisely when a write did NOT land) and to the context-overflow
+     * decision — either can stop a healthy dispatch.
+     */
+    unacknowledged() {
+        return this.counter
+            .all()
+            .filter((e) => !this.replayedMessageIds.has(e.messageId))
+            .map((e) => excessUsage(e.usage, this.acked.get(e.messageId) ?? {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite5m: 0,
+            cacheWrite1h: 0,
+        }));
+    }
+    /**
+     * The dispatch's usage as far as this process knows it: the server totals
+     * plus the per-field excess this process has read but the server has not
+     * acknowledged. A replay block adds nothing (its excess over the
+     * acknowledged total is zero). For a job with no dispatch row (nothing is
+     * ever acknowledged) this is exactly the local counter's total.
+     */
+    estimate() {
+        const t = this.serverTotals;
+        const out = {
+            tokensIn: t.tokensIn,
+            tokensOut: t.tokensOut,
+            cacheRead: t.cacheRead,
+            cacheWrite: t.cacheWrite,
+        };
+        for (const u of this.unacknowledged()) {
+            out.tokensIn += u.input;
+            out.tokensOut += u.output;
+            out.cacheRead += u.cacheRead;
+            out.cacheWrite += u.cacheWrite5m + u.cacheWrite1h;
+        }
+        return out;
+    }
+    /** Token-ceiling input: window tokens (input + output + cache writes) of {@link estimate}. */
+    windowTokensEstimate() {
+        const e = this.estimate();
+        return e.tokensIn + e.tokensOut + e.cacheWrite;
+    }
+    /** All-field total of {@link estimate}. */
+    totalTokensEstimate() {
+        const e = this.estimate();
+        return e.tokensIn + e.tokensOut + e.cacheRead + e.cacheWrite;
+    }
+}

package/dist/index.d.ts

@@ -14,9 +14,13 @@
  * — the dashboard server, the dashboard SPA, and any future browser-side
  * usage display.
  */
-export { SessionLogWatcher, DISPATCH_TAG_PREFIX, encodeClaudeProjectsCwd, deriveSessionDir, sessionUuidExistsInCleanRoom, findNewestJsonlFile, findSessionFileByDispatchId, convertJsonlEntry, } from "./session-log-watcher.js";
-export type { EntryConsumer, SessionLogWatcherOptions, } from "./session-log-watcher.js";
+export { SessionLogWatcher, DISPATCH_TAG_PREFIX, encodeClaudeProjectsCwd, deriveSessionDir, sessionUuidExistsInCleanRoom, findNewestJsonlFile, findSessionFileByDispatchId, convertJsonlEntry, skipReplays, } from "./session-log-watcher.js";
+export type { EntryConsumer, SessionLogWatcherOptions, SourceCursorStart, CursorPastEofInfo, SourceDiscoveredInfo, EntryMeta, } from "./session-log-watcher.js";
 export type { AgentLogEntry, AgentLineage } from "./types.js";
 export { truncStr, summarizeToolInput, buildAssistantSummary, buildToolResultSummary, } from "./tool-summary.js";
 export * from "./usage-ledger.js";
 export * from "./pricing.js";
+export * from "./stats-wire.js";
+export * from "./dispatch-usage.js";
+export * from "./activity-observer.js";
+export * from "./write-queue.js";

package/dist/index.js

@@ -14,7 +14,7 @@
  * — the dashboard server, the dashboard SPA, and any future browser-side
  * usage display.
  */
-export { SessionLogWatcher, DISPATCH_TAG_PREFIX, encodeClaudeProjectsCwd, deriveSessionDir, sessionUuidExistsInCleanRoom, findNewestJsonlFile, findSessionFileByDispatchId, convertJsonlEntry, } from "./session-log-watcher.js";
+export { SessionLogWatcher, DISPATCH_TAG_PREFIX, encodeClaudeProjectsCwd, deriveSessionDir, sessionUuidExistsInCleanRoom, findNewestJsonlFile, findSessionFileByDispatchId, convertJsonlEntry, skipReplays, } from "./session-log-watcher.js";
 // `truncStr` is a generic, dependency-free string helper that moved here
 // alongside the rest of `tool-summary.ts` (it has no other home now that
 // file is gone from root) — re-exported for danxbot root consumers that
@@ -25,3 +25,13 @@ export { truncStr, summarizeToolInput, buildAssistantSummary, buildToolResultSum
 // browser-safe `./browser` subpath; both are pure arithmetic).
 export * from "./usage-ledger.js";
 export * from "./pricing.js";
+// DX-2954 — the ONE stats collector and its wire, shared by the danxbot worker
+// and the desktop bridge (operator sessions) so both report the same stats the
+// same way (epic DX-2958): the stats payload/response schema and its strict
+// parser, the collector that ships ledger entries + transcript cursors +
+// running-set changes, the transcript-side running-set producer, and the FIFO
+// that orders a dispatch's writes.
+export * from "./stats-wire.js";
+export * from "./dispatch-usage.js";
+export * from "./activity-observer.js";
+export * from "./write-queue.js";

package/dist/internal-logger.js

@@ -12,8 +12,11 @@ function emit(level, component, message, error) {
     else if (error !== undefined) {
         entry.error = String(error);
     }
-    const writer = level === "info" ? console.log : console.error;
-    writer(JSON.stringify(entry));
+    // DX-2954 — every level goes to STDERR. The desktop bridge
+    // (`danx-dashboard-mcp bridge`) now runs this collector, and its STDOUT is a
+    // JSON Lines protocol channel the plugin parses record by record; a log line
+    // there would be read as a bridge record. The worker captures both streams.
+    console.error(JSON.stringify(entry));
 }
 export function createLogger(component) {
     return {