@thehammer/danx-session-telemetry 0.1.14 → 0.1.16

package/dist/activity-observer.d.ts

@@ -0,0 +1,83 @@
+/**
+ * DX-2954 — the TRANSCRIPT-side producer of a dispatch's running set.
+ *
+ * `dispatch_activities` answers "what is this dispatch running RIGHT NOW" — one
+ * row per sub-agent or background script, with `finished_at` NULL while it is
+ * still going. This module produces the sub-agent half of that set from the one
+ * signal danxbot owns end-to-end: the session-log watcher discovering a
+ * sub-agent's transcript file and then tailing it.
+ *
+ * ## Why the transcript, and where the hooks come in
+ *
+ * Claude Code's `SubagentStart` / `SubagentStop` hooks carry strictly more (an
+ * `agent_type` before the sub-agent has written anything, and — the part this
+ * module cannot supply — a FINISH). Those hooks ship from the danxbot plugin in
+ * the claude-plugins repo, and DX-3284 builds them, next. They were not built in
+ * DX-2954 itself, but not because a plugin change cannot ship from a danxbot
+ * card: DX-2954's own `transcript_path` change shipped as claude-plugins
+ * `c0c134d`. Keying the running set solely on them before they exist would ship
+ * a set that is permanently empty (`subagent_count` 0 on every dispatch, a
+ * REGRESSION against the transcript-derived counter this replaced).
+ *
+ * So the transcript is the producer, and the hooks are an ENRICHMENT layered on
+ * the same rows:
+ *
+ * | Signal | Sub-agent start | Sub-agent finish | Background script |
+ * |---|---|---|---|
+ * | Transcript (here) | file discovered | dispatch terminal (`finishOpenActivities`) | not visible |
+ * | Hooks (DX-3284) | `SubagentStart` | `SubagentStop` | `PostToolUse` start; end at dispatch terminal (no documented completion event) |
+ *
+ * **Until DX-3284 lands, "running" over-counts.** With no finish signal, every
+ * sub-agent this dispatch ever started stays in the running set until the
+ * dispatch itself ends, and the silent-too-long warning fires
+ * `RUNNING_ACTIVITY_SILENT_AFTER_MS` after a sub-agent that has in fact
+ * finished. `SubagentStop` is what closes that gap.
+ *
+ * ## Why the two producers cannot double-count
+ *
+ * Every row is an upsert keyed `(dispatch_id, kind, activity_id)`, and BOTH
+ * producers derive `activity_id` from the same thing: the sub-agent's transcript
+ * file basename. The watcher has it directly; a hook has it as the basename of
+ * its `transcript_path`. That is also the key the ledger credits the sub-agent's
+ * tokens under, which is how per-sub-agent tokens join to the running set
+ * without this table carrying a token column.
+ *
+ * ## What this module deliberately does NOT do
+ *
+ * It never reports a FINISH. A transcript gives no "this sub-agent is done"
+ * signal — a finished sub-agent's file simply stops growing, which is
+ * indistinguishable from a slow one. Guessing a finish from an idle gap would
+ * mark a long-thinking sub-agent as complete. So open rows are closed exactly
+ * once, at the dispatch's own terminal transition (`finishOpenActivities`),
+ * unless DX-3284's `SubagentStop` hook closes a row first.
+ */
+import type { ActivityChange } from "./stats-wire.js";
+import type { EntryMeta, SourceDiscoveredInfo } from "./session-log-watcher.js";
+import type { AgentLogEntry } from "./types.js";
+/** What the observer needs from the dispatch's usage accumulator. */
+export interface ActivityObserverDeps {
+    /**
+     * Queue activity changes onto the next stats write. Called with the full
+     * current state of each changed activity — the server's upsert is idempotent,
+     * so re-reporting an unchanged field is free and a dropped batch is
+     * self-healing on the next write.
+     */
+    recordActivities: (changes: ActivityChange[]) => void;
+    /**
+     * DX-2954 — ignore every sub-agent file that already existed when the watcher
+     * attached. Set for a dispatch that continues an earlier one's session
+     * (`StartCursorPlan.inheritsPredecessorSubagents`): those files are the
+     * predecessor's sub-agents, which ended with its process, and reporting them
+     * would open a never-closing "running" row per predecessor sub-agent on the
+     * new dispatch — inflating `subagent_count` / `running_activity_count` and
+     * tripping the silent-too-long warning ten minutes later.
+     */
+    ignorePreexisting?: boolean;
+}
+export interface ActivityObserver {
+    /** Wire to the watcher's `onSourceDiscovered`. */
+    onSourceDiscovered: (info: SourceDiscoveredInfo) => void;
+    /** Wire to the watcher's `onEntry`. */
+    onEntry: (entry: AgentLogEntry, meta: EntryMeta) => void;
+}
+export declare function createActivityObserver(deps: ActivityObserverDeps): ActivityObserver;

package/dist/activity-observer.js

@@ -0,0 +1,73 @@
+export function createActivityObserver(deps) {
+    // No clock of its own, deliberately. Every stamp this module reports comes from
+    // the event that caused it — the watcher's `discoveredAt` for a start, the
+    // entry's own `timestamp` for an advance — so there is no wall-clock reading
+    // anywhere that a test would need to freeze or that a replay could skew.
+    /** Every sub-agent this observer has reported, by its ledger source key. */
+    const started = new Map();
+    return {
+        onSourceDiscovered(info) {
+            // Not this dispatch's sub-agent (see `ignorePreexisting`). Never added to
+            // `started` either, so its later lines do not stamp activity on a row
+            // that does not exist.
+            if (deps.ignorePreexisting === true && info.preexisting)
+                return;
+            const existing = started.get(info.source);
+            if (existing) {
+                // A second discovery of a source already reported can only ADD an
+                // `agentType` the first pass could not read yet (the sub-agent had not
+                // written a line naming one). Never re-stamp `startedAt`: the server
+                // takes LEAST(startedAt) anyway, but reporting a later start for a
+                // sub-agent that has been running since before this watcher attached
+                // would be wrong in the payload itself.
+                if (existing.agentType === null && info.agentType !== null) {
+                    existing.agentType = info.agentType;
+                    deps.recordActivities([{ ...existing }]);
+                }
+                return;
+            }
+            const change = {
+                kind: "agent",
+                activityId: info.source,
+                agentType: info.agentType,
+                // A sub-agent has no Bash `description`; the field exists for the
+                // background-script kind and stays null here rather than being filled
+                // with a stand-in a reader would have to distinguish from a real one.
+                description: null,
+                startedAt: info.discoveredAt,
+                lastActivityAt: info.discoveredAt,
+                // Never a finish from the transcript — see the module docblock.
+                finishedAt: null,
+            };
+            started.set(info.source, change);
+            deps.recordActivities([{ ...change }]);
+        },
+        onEntry(entry, meta) {
+            // DX-2954 — a REPLAY counts as activity here, unlike the stall detector's
+            // liveness signal. The two ask different questions: the stall detector asks
+            // "is the agent alive NOW" (a re-read proves nothing), while this stamp
+            // answers "when did this sub-agent last actually say something", which a
+            // re-read line genuinely reports.
+            //
+            // Which is exactly why the stamp is the ENTRY's OWN timestamp and never a
+            // wall clock. Stamping `Date.now()` would make a reattach reset every
+            // pre-existing sub-agent's last activity to the moment the collector
+            // restarted: the whole replay window would report as fresh, and a sub-agent
+            // silent for half an hour would come out of it looking live, so
+            // `RUNNING_ACTIVITY_SILENT_AFTER_MS` could never fire for it. That is the
+            // one signal this feature has for "ended or stuck" (DX-3246 fixed the same
+            // wall-clock-for-entry-time confusion in the boot mark). Even with no
+            // replay involved, a wall clock records when the 5s poll NOTICED the line,
+            // not when the agent wrote it.
+            const change = started.get(meta.source);
+            if (!change)
+                return;
+            // GREATEST, mirroring the server: a line read out of order, or an older
+            // line inside a replay window, never drags liveness backwards.
+            if (entry.timestamp <= change.lastActivityAt)
+                return;
+            change.lastActivityAt = entry.timestamp;
+            deps.recordActivities([{ ...change }]);
+        },
+    };
+}

package/dist/dispatch-usage.d.ts

@@ -0,0 +1,227 @@
+/**
+ * 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 } from "./usage-ledger.js";
+import type { CursorPastEofInfo } from "./session-log-watcher.js";
+import type { AgentLogEntry } from "./types.js";
+import { type ActivityChange, type SourceCursors, type StatsPayload, type StatsResponse, type UsageTotals } from "./stats-wire.js";
+/** Where stats writes go — both dispatch-row sinks implement it. */
+export interface StatsSink {
+    applyStats(dispatchId: string, payload: StatsPayload): Promise<StatsResponse>;
+}
+export declare function zeroUsageTotals(): UsageTotals;
+export type FlushOutcome = "ok" | "failed" | "refused";
+export declare class DispatchUsage {
+    readonly counter: UsageLedgerCounter;
+    private serverTotals;
+    private readonly acked;
+    private healthy;
+    private refused;
+    private started;
+    private readonly queue;
+    /** How to read the watcher's live per-source cursor state. */
+    private readCursorState;
+    /**
+     * 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.
+     */
+    private readonly ackedCursor;
+    /**
+     * DX-2954 (AC 34324) — the cursors this process STARTED from, reported
+     * verbatim for every source the watcher has not opened yet until one write
+     * carrying them has landed. See {@link DispatchUsage.buildCursorReports}.
+     */
+    private startCursors;
+    private startCursorsPersisted;
+    /** Past-EOF resets to report once, then forget. */
+    private 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.
+     */
+    private readonly replayedMessageIds;
+    /** Running-set changes to report on the next write. */
+    private pendingActivities;
+    /** The session transcript path — the ONE path field the wire carries. */
+    private transcriptPath;
+    private transcriptPathSent;
+    /**
+     * 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: () => Record<string, {
+        startOffset: number;
+        delivered: number;
+    }>, startCursors: SourceCursors): void;
+    /**
+     * 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: CursorPastEofInfo): void;
+    /**
+     * 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: readonly ActivityChange[]): void;
+    /**
+     * 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: string): void;
+    /**
+     * 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.
+     *
+     * ## The process-start write carries the STARTING cursors (AC 34324)
+     *
+     * `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 its live `cursorState()` is empty.
+     *
+     * So every source in the cursors this process STARTED from that the watcher
+     * has not opened yet is reported VERBATIM — the exact `{acked, delivered}`
+     * pair it resumed from — until one write carrying them has landed. That is
+     * what makes "every attach persists its starting cursors" true on the FIRST
+     * write rather than one stats tick (15-30 s) later: a reattach of this row
+     * inside its first interval reads them back (start-order rule 1) and starts
+     * exactly where this process did, instead of finding no cursor, resolving
+     * rule 4 and skipping every line written since spawn. A fresh session's
+     * starting cursor is explicit too (`resolveStartCursors` rule 3 returns the
+     * main source at 0), and a `--resume`'s is its predecessor's (rule 2).
+     *
+     * Verbatim is the only honest claim for a source this process has not read:
+     * a higher `acked` would let a restart skip the replay window it has not
+     * re-credited, a lower one is refused as a regression. For the same reason
+     * the start write does not PROMOTE such a source's acknowledged floor — it
+     * delivered nothing there — so it stays out of `deliveredAtSend`.
+     *
+     * The one case with nothing to carry is rule 4 (a continuing dispatch with no
+     * cursor for ANY source): its start is "each existing file's end at
+     * discovery", which does not exist until discovery runs. Its cursors reach
+     * the server on the first write after discovery. Rule 4 is the pre-card
+     * deploy transition only — every dispatch since this card stores cursors on
+     * its first write — so that bounded window is the one the card accepts.
+     */
+    private buildCursorReports;
+    /**
+     * 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.
+     */
+    private cursorsMoved;
+    /**
+     * 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: AgentLogEntry, replay?: boolean): void;
+    /**
+     * 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: StatsSink, dispatchId: string): Promise<FlushOutcome>;
+    /** The dispatch's totals as the server last returned them. */
+    totals(): UsageTotals;
+    /** Window tokens (input + output + cache writes) of the server totals. */
+    serverWindowTokens(): number;
+    /** Whether the most recent stats write succeeded. */
+    statsHealthy(): boolean;
+    /**
+     * 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.
+     */
+    private unacknowledged;
+    /**
+     * 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(): {
+        tokensIn: number;
+        tokensOut: number;
+        cacheRead: number;
+        cacheWrite: number;
+    };
+    /** Token-ceiling input: window tokens (input + output + cache writes) of {@link estimate}. */
+    windowTokensEstimate(): number;
+    /** All-field total of {@link estimate}. */
+    totalTokensEstimate(): number;
+}