@thehammer/danx-session-telemetry 0.1.43 → 0.1.45

package/dist/.source-hash

@@ -1 +1 @@
-1f7f247f7e5d5039a351835d2525a04c03edbb7a4ddac07cf83d4d599fe7ef07
+3d2e532980e05f6c38b15f2a85eca3c84c3488c2afec7c285c5ac8a5c20ee254

package/dist/dispatch-usage.d.ts

@@ -68,6 +68,13 @@ export declare class DispatchUsage {
      * its own resume point instead of regressing it.
      */
     private readonly ackedCursor;
+    /**
+     * DX-3972 - per source, the `acked` the server holds for this dispatch: the `acked` of the last ACKNOWLEDGED
+     * report that carried the source. It is NOT {@link DispatchUsage.ackedCursor}: that is what the NEXT report
+     * claims (one write behind `delivered`), this is what the LAST one claimed. The terminal catch-up
+     * ({@link DispatchUsage.flushFinal}) is needed exactly while this lags the watcher's `delivered`.
+     */
+    private readonly storedAcked;
     /**
      * DX-2954 (AC 34324) — the cursors this process STARTED from, reported
      * verbatim for every source the watcher has not opened yet until one write
@@ -157,6 +164,18 @@ export declare class DispatchUsage {
      * 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.
      *
+     * ## The terminal write closes the lag (DX-3972)
+     *
+     * A restart is a crash, and a crash's window is the cost above. A dispatch that
+     * ENDS is not one: its watcher is drained and stopped, so every line it read has been
+     * fed to this collector and nothing will raise a reply any more. The terminal
+     * {@link DispatchUsage.flushFinal} therefore reports `acked` equal to `delivered` for
+     * every source it has opened (see {@link DispatchUsage.catchUpReports}), and a
+     * `--resume` of the session starts at the end of what this dispatch read instead of
+     * replaying the whole file. Without it a dispatch with ONE line-bearing write ended at
+     * `{acked: 0, delivered: EOF}`, and every resume of the session re-read the whole
+     * transcript and re-shipped it into its own `dispatch_logs`.
+     *
      * ## The process-start write carries the STARTING cursors (AC 34324)
      *
      * `attachMonitoringStack` deliberately does NOT await `watcher.start()` —
@@ -195,6 +214,20 @@ export declare class DispatchUsage {
      * is why a write is not forced merely because cursors EXIST.
      */
     private cursorsMoved;
+    /**
+     * DX-3972 - the TERMINAL write's reports: the tick's reports with every source this process has read claiming its
+     * whole `delivered` as `acked`, and the claim state AS OF that offset (the tracker's current state belongs to
+     * `delivered`, so it describes the new `acked` exactly, never a later position). Sources the watcher has not
+     * opened (a start cursor reported verbatim) are untouched: this process read nothing there to claim.
+     */
+    private catchUpReports;
+    /**
+     * DX-3972 - whether the terminal write has anything to say: the server's `acked` still lags what the catch-up now
+     * claims. `ackedCursor` (the NEXT tick's claim) cannot tell, because a dispatch whose last write reported
+     * `delivered` with an older `acked` has `ackedCursor === delivered` and still lags; {@link DispatchUsage.storedAcked}
+     * is what the server holds. A source never reported at all has no entry, so it counts as lagging.
+     */
+    private storedAckedLags;
     /**
      * Feed one raw transcript line of the usage feed set (assistant, user, attachment, system), in file order.
      * DX-3964 - the usage collector is fed from the watcher's collector-only `onUsageLine` subscription, never from
@@ -221,6 +254,21 @@ export declare class DispatchUsage {
      * acknowledged ahead of the entries it covers.
      */
     flush(sink: StatsSink, dispatchId: string): Promise<FlushOutcome>;
+    /**
+     * DX-3972 - the TERMINAL write: {@link DispatchUsage.flush} that also catches the stored `acked` up to
+     * `delivered` for every source (see {@link DispatchUsage.catchUpReports}). Call it once, when the dispatch ends,
+     * after the watcher is drained and stopped (that is the whole precondition: every line it read has reached this
+     * collector, so `delivered` is covered by the entries this very write carries), and BEFORE the row goes terminal
+     * (the server refuses a terminal dispatch's stats, which would drop the catch-up silently). A write that does not
+     * land promotes nothing, exactly as in a tick; a dispatch already caught up sends no write.
+     *
+     * It does NOT wait for the dispatch's log shipper: the spawn path flushes it before this call, the reattach path
+     * after (`reattach.ts` `_cleanup`), so on a reattach `acked` can claim a line whose `dispatch_logs` row is still in
+     * the shipper's buffer. The shipper is best-effort today and a resume's shipper skips replays either way, so
+     * nothing is lost that was not already; acking only after the log line is acknowledged is DX-2956's change.
+     */
+    flushFinal(sink: StatsSink, dispatchId: string): Promise<FlushOutcome>;
+    private write;
     /** The dispatch's totals as the server last returned them. */
     totals(): UsageTotals;
     /** Window tokens (input + output + cache writes) of the server totals. */

package/dist/dispatch-usage.js

@@ -63,6 +63,13 @@ export class DispatchUsage {
      * its own resume point instead of regressing it.
      */
     ackedCursor = new Map();
+    /**
+     * DX-3972 - per source, the `acked` the server holds for this dispatch: the `acked` of the last ACKNOWLEDGED
+     * report that carried the source. It is NOT {@link DispatchUsage.ackedCursor}: that is what the NEXT report
+     * claims (one write behind `delivered`), this is what the LAST one claimed. The terminal catch-up
+     * ({@link DispatchUsage.flushFinal}) is needed exactly while this lags the watcher's `delivered`.
+     */
+    storedAcked = new Map();
     /**
      * DX-2954 (AC 34324) — the cursors this process STARTED from, reported
      * verbatim for every source the watcher has not opened yet until one write
@@ -186,6 +193,18 @@ export class DispatchUsage {
      * 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.
      *
+     * ## The terminal write closes the lag (DX-3972)
+     *
+     * A restart is a crash, and a crash's window is the cost above. A dispatch that
+     * ENDS is not one: its watcher is drained and stopped, so every line it read has been
+     * fed to this collector and nothing will raise a reply any more. The terminal
+     * {@link DispatchUsage.flushFinal} therefore reports `acked` equal to `delivered` for
+     * every source it has opened (see {@link DispatchUsage.catchUpReports}), and a
+     * `--resume` of the session starts at the end of what this dispatch read instead of
+     * replaying the whole file. Without it a dispatch with ONE line-bearing write ended at
+     * `{acked: 0, delivered: EOF}`, and every resume of the session re-read the whole
+     * transcript and re-shipped it into its own `dispatch_logs`.
+     *
      * ## The process-start write carries the STARTING cursors (AC 34324)
      *
      * `attachMonitoringStack` deliberately does NOT await `watcher.start()` —
@@ -281,6 +300,32 @@ export class DispatchUsage {
         }
         return false;
     }
+    /**
+     * DX-3972 - the TERMINAL write's reports: the tick's reports with every source this process has read claiming its
+     * whole `delivered` as `acked`, and the claim state AS OF that offset (the tracker's current state belongs to
+     * `delivered`, so it describes the new `acked` exactly, never a later position). Sources the watcher has not
+     * opened (a start cursor reported verbatim) are untouched: this process read nothing there to claim.
+     */
+    catchUpReports(reports, deliveredAtSend, claimsAtSend) {
+        const caughtUp = { ...reports };
+        for (const [source, delivered] of deliveredAtSend) {
+            caughtUp[source] = { ...reports[source], acked: delivered, claims: claimsAtSend.get(source) };
+        }
+        return caughtUp;
+    }
+    /**
+     * DX-3972 - whether the terminal write has anything to say: the server's `acked` still lags what the catch-up now
+     * claims. `ackedCursor` (the NEXT tick's claim) cannot tell, because a dispatch whose last write reported
+     * `delivered` with an older `acked` has `ackedCursor === delivered` and still lags; {@link DispatchUsage.storedAcked}
+     * is what the server holds. A source never reported at all has no entry, so it counts as lagging.
+     */
+    storedAckedLags(reports) {
+        for (const [source, report] of Object.entries(reports)) {
+            if (report.pastEof !== undefined || report.acked !== this.storedAcked.get(source))
+                return true;
+        }
+        return false;
+    }
     /**
      * Feed one raw transcript line of the usage feed set (assistant, user, attachment, system), in file order.
      * DX-3964 - the usage collector is fed from the watcher's collector-only `onUsageLine` subscription, never from
@@ -329,13 +374,36 @@ export class DispatchUsage {
      * acknowledged ahead of the entries it covers.
      */
     flush(sink, dispatchId) {
+        return this.write(sink, dispatchId, false);
+    }
+    /**
+     * DX-3972 - the TERMINAL write: {@link DispatchUsage.flush} that also catches the stored `acked` up to
+     * `delivered` for every source (see {@link DispatchUsage.catchUpReports}). Call it once, when the dispatch ends,
+     * after the watcher is drained and stopped (that is the whole precondition: every line it read has reached this
+     * collector, so `delivered` is covered by the entries this very write carries), and BEFORE the row goes terminal
+     * (the server refuses a terminal dispatch's stats, which would drop the catch-up silently). A write that does not
+     * land promotes nothing, exactly as in a tick; a dispatch already caught up sends no write.
+     *
+     * It does NOT wait for the dispatch's log shipper: the spawn path flushes it before this call, the reattach path
+     * after (`reattach.ts` `_cleanup`), so on a reattach `acked` can claim a line whose `dispatch_logs` row is still in
+     * the shipper's buffer. The shipper is best-effort today and a resume's shipper skips replays either way, so
+     * nothing is lost that was not already; acking only after the log line is acknowledged is DX-2956's change.
+     */
+    flushFinal(sink, dispatchId) {
+        return this.write(sink, dispatchId, true);
+    }
+    write(sink, dispatchId, catchUp) {
         return this.queue(async () => {
             if (this.refused)
                 return "refused";
             this.flushBegan = true;
             const changed = this.counter.takeChanged();
             const batches = chunkEntries(changed);
-            const { reports, deliveredAtSend, claimsAtSend, reportedResets, carriesStartCursors } = this.buildCursorReports();
+            const built = this.buildCursorReports();
+            const { deliveredAtSend, claimsAtSend, reportedResets, carriesStartCursors } = built;
+            const reports = catchUp
+                ? this.catchUpReports(built.reports, deliveredAtSend, claimsAtSend)
+                : built.reports;
             // 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.
@@ -361,7 +429,7 @@ export class DispatchUsage {
             // whose last batch failed must still deliver it on a later, otherwise idle
             // tick.
             const haveSideData = carriesStartCursors ||
-                this.cursorsMoved(reports) ||
+                (catchUp ? this.storedAckedLags(reports) : this.cursorsMoved(reports)) ||
                 activities.length > 0 ||
                 (this.transcriptPath !== null && !this.transcriptPathSent);
             if (batches.length === 0 && (!this.started || haveSideData))
@@ -390,6 +458,11 @@ export class DispatchUsage {
                         // 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);
+                        // DX-3972 - what the server now holds as each reported source's `acked` (a refused source kept its own).
+                        for (const [source, report] of Object.entries(reports)) {
+                            if (!refused.has(source))
+                                this.storedAcked.set(source, report.acked);
+                        }
                         // 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

package/dist/pricing.d.ts

@@ -114,15 +114,28 @@ export type PriceResult = {
  * cleanly, whatever its id looks like.
  */
 export declare function priceUsage(model: string, speed: string, tokens: PricedTokens): PriceResult;
+/**
+ * The list price `priceUsage` charges for a model at a speed (a fast request on a model that bills fast at the standard rate reads the
+ * 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;
+/**
+ * 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.
+ */
+export declare function costOfTokens(tokens: PricedTokens, price: ModelPrice): number;
 /** True when `model` has a standard-speed price (used by tests + guards). */
 export declare function isPricedModel(model: string): boolean;
+/** What a model costs at a speed, per million tokens; `null` when there is no price. */
+export type PriceLookup = (model: string, speed: string) => ModelPrice | null;
 /**
  * DX-4508 — one ledger credit's cost, exactly as the server's usage-ledger writer stores it (moved here from
  * `src/dashboard/usage-ledger.ts` so the live sub-agent view, `subagent-live.ts`, prices a reply with the SAME rule
  * instead of a copy): a `<synthetic>` reply costs nothing and is never unpriced; a reply with no model is unpriced only
- * when it carries tokens; any other model goes through {@link priceUsage}, an unpriced one costing 0 and naming itself.
+ * when it carries tokens; any other model is priced by `priceOf` (the list prices by default, so as {@link priceUsage} does), an unpriced
+ * one costing 0 and naming itself. DX-4595: spend pacing passes an account's own prices as `priceOf` and so gets the same rule.
  */
-export declare function priceLedgerCredit(model: string | null, speed: string, tokens: PricedTokens): {
+export declare function priceLedgerCredit(model: string | null, speed: string, tokens: PricedTokens, priceOf?: PriceLookup): {
     costUsd: number;
     unpriced: {
         model: string;

package/dist/pricing.js

@@ -163,20 +163,29 @@ export function listListPrices() {
  * cleanly, whatever its id looks like.
  */
 export function priceUsage(model, speed, tokens) {
+    const price = listedPrice(model, speed);
+    return price === null ? { kind: "unpriced", model, speed } : { kind: "priced", costUsd: costOfTokens(tokens, price) };
+}
+/**
+ * The list price `priceUsage` charges for a model at a speed (a fast request on a model that bills fast at the standard rate reads the
+ * standard table), or `null` when the tables have none. The default `PriceLookup` of {@link priceLedgerCredit}.
+ */
+export function listedPrice(model, speed) {
     const useFastTable = speed === FAST_SPEED && !FAST_BILLS_AT_STANDARD_RATE.has(model);
     const table = useFastTable ? FAST_PRICING : PRICING;
-    if (!Object.hasOwn(table, model))
-        return { kind: "unpriced", model, speed };
-    const p = table[model];
-    return {
-        kind: "priced",
-        costUsd: (tokens.input * p.input +
-            tokens.output * p.output +
-            tokens.cacheRead * p.cacheRead +
-            tokens.cacheWrite5m * p.cacheWrite5m +
-            tokens.cacheWrite1h * p.cacheWrite1h) /
-            1_000_000,
-    };
+    return Object.hasOwn(table, model) ? table[model] : null;
+}
+/**
+ * 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.
+ */
+export function costOfTokens(tokens, price) {
+    return ((tokens.input * price.input +
+        tokens.output * price.output +
+        tokens.cacheRead * price.cacheRead +
+        tokens.cacheWrite5m * price.cacheWrite5m +
+        tokens.cacheWrite1h * price.cacheWrite1h) /
+        1_000_000);
 }
 /** True when `model` has a standard-speed price (used by tests + guards). */
 export function isPricedModel(model) {
@@ -188,15 +197,16 @@ export function isPricedModel(model) {
  * DX-4508 — one ledger credit's cost, exactly as the server's usage-ledger writer stores it (moved here from
  * `src/dashboard/usage-ledger.ts` so the live sub-agent view, `subagent-live.ts`, prices a reply with the SAME rule
  * instead of a copy): a `<synthetic>` reply costs nothing and is never unpriced; a reply with no model is unpriced only
- * when it carries tokens; any other model goes through {@link priceUsage}, an unpriced one costing 0 and naming itself.
+ * when it carries tokens; any other model is priced by `priceOf` (the list prices by default, so as {@link priceUsage} does), an unpriced
+ * one costing 0 and naming itself. DX-4595: spend pacing passes an account's own prices as `priceOf` and so gets the same rule.
  */
-export function priceLedgerCredit(model, speed, tokens) {
+export function priceLedgerCredit(model, speed, tokens, priceOf = listedPrice) {
     if (model === SYNTHETIC_MODEL)
         return { costUsd: 0, unpriced: null };
     if (model === null) {
         const zero = tokens.input === 0 && tokens.output === 0 && tokens.cacheRead === 0 && tokens.cacheWrite5m === 0 && tokens.cacheWrite1h === 0;
         return zero ? { costUsd: 0, unpriced: null } : { costUsd: 0, unpriced: { model: "(none)", speed } };
     }
-    const r = priceUsage(model, speed, tokens);
-    return r.kind === "priced" ? { costUsd: r.costUsd, unpriced: null } : { costUsd: 0, unpriced: { model: r.model, speed: r.speed } };
+    const price = priceOf(model, speed);
+    return price === null ? { costUsd: 0, unpriced: { model, speed } } : { costUsd: costOfTokens(tokens, price), unpriced: null };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-session-telemetry",
-  "version": "0.1.43",
+  "version": "0.1.45",
   "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",