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

package/dist/stats-wire.js

@@ -0,0 +1,636 @@
+/**
+ * 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";
+/**
+ * DX-2963 — cap on entries per stats write. A from-0 backlog (a reattach, a
+ * session read from the start) is sent as consecutive capped batches, so one
+ * request never carries an unbounded body or holds the dispatch lock for an
+ * unbounded time. 500 entries is well under a second of upsert work.
+ */
+export const STATS_BATCH_CAP = 500;
+/**
+ * DX-2954 — the running set's two kinds. `agent` is a sub-agent, produced from
+ * the TRANSCRIPT: one row per sub-agent transcript file the session-log watcher
+ * discovers (`packages/danx-session-telemetry/src/activity-observer.ts`; orchestrator decision, DX-2954
+ * comment 8004), and — for an operator session — from the plugin's
+ * `SubagentStart` / `SubagentStop` hooks. The transcript ends a row from the
+ * spawner's spawn result (foreground, DX-5576) or task notification
+ * (background, DX-4498); `SubagentStop` is the fallback finish. `bash` is a
+ * background script, produced only by the plugin's `PostToolUse` hook on a
+ * backgrounded Bash call (DX-3284; the transcript cannot see it). No hook event
+ * observes a background shell FINISHING (verified against the hooks reference —
+ * see the Step 0 note on DX-2954), so an open `bash` row is closed by the
+ * dispatch's own terminal write, never by inferring an end from transcript
+ * lines.
+ */
+export const ACTIVITY_KINDS = ["agent", "bash"];
+/**
+ * DX-5333 — which part of a sub-agent's conversation a stored message is: `brief` (the prompt its spawner gave it), `followup`
+ * (a later message sent to it) or `final` (a reply that ended its turn).
+ */
+export const ACTIVITY_MESSAGE_KINDS = ["brief", "followup", "final"];
+/** DX-5333 — the longest message text a collector sends (and the server stores); a longer one is cut by the collector. */
+export const ACTIVITY_MESSAGE_MAX_CHARS = 100_000;
+/** DX-5333 — cap on messages per stats write, so one write's lock hold stays bounded; the rest stay queued for the next. */
+export const ACTIVITY_MESSAGE_BATCH_CAP = 100;
+/** DX-5333 — cap on problem links per stats write. */
+export const ACTIVITY_PROBLEM_BATCH_CAP = 100;
+/**
+ * DX-4498 / DX-5576 — how an activity ended, when something explicitly said so: a foreground spawn's own
+ * `tool_result` (`completed`; `failed` if errored; `stopped` if interrupted or rejected), Claude Code's
+ * background-task notification (`completed`, `failed`, and `killed`/`stopped` as `stopped`), or the session ending
+ * while it still ran (`stopped`).
+ */
+export const ACTIVITY_END_STATUSES = ["completed", "failed", "stopped"];
+/** DX-4498 — the longest `currentActivity` a collector sends (and the server stores). */
+export const CURRENT_ACTIVITY_MAX_CHARS = 120;
+export function chunkEntries(entries, cap = STATS_BATCH_CAP) {
+    const out = [];
+    for (let i = 0; i < entries.length; i += cap)
+        out.push(entries.slice(i, i + cap));
+    return out;
+}
+export class StatsPayloadError extends Error {
+}
+function isNonNegInt(v) {
+    return typeof v === "number" && Number.isInteger(v) && v >= 0;
+}
+const USAGE_KEYS = ["input", "output", "cacheRead", "cacheWrite5m", "cacheWrite1h"];
+/**
+ * DX-2954 — the ONLY keys a stats body may carry. An unknown key is a 400, so
+ * a worker that invents a field (or a renamed one that never reached a
+ * consumer) fails loud instead of being silently dropped — the pre-DX-2954
+ * parser rebuilt the object field by field and swallowed every extra key.
+ *
+ * `transcriptPath` is the ONE key allowed to carry a filesystem path.
+ */
+const STATS_PAYLOAD_KEYS = new Set([
+    "entries",
+    "sourceCursors",
+    "activities",
+    "activityMessages",
+    "activityProblems",
+    "compactions",
+    "transcriptPath",
+]);
+/**
+ * DX-2954 — cap on activity rows per stats write. The running set is bounded by
+ * how many sub-agents and background scripts one dispatch has ever started;
+ * this keeps a malformed or runaway sender from holding the dispatch lock while
+ * 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;
+/**
+ * DX-2954 — collapse a queue of activity changes to ONE per
+ * `(kind, activityId)`, applying the SAME merge the server's upsert applies.
+ *
+ * Both sides need this rule, so it is stated once, here, beside the wire types:
+ * the server merges an incoming row against what it has stored, and a SENDER
+ * merges the changes it has queued since its last write against each other. The
+ * two are the same operation on the same monotone fields, so a client-side
+ * collapse is lossless — the server reaches the identical row either way.
+ *
+ * Why a sender needs it at all: a producer reports an activity's full current
+ * state every time anything about it moves, and a chatty sub-agent moves its
+ * `lastActivityAt` continuously. Queuing those raw would grow one entry per
+ * change between writes, blow {@link ACTIVITY_BATCH_CAP}, and take the WHOLE
+ * stats write down with it — not merely the activity part — for a payload that
+ * describes a handful of activities.
+ *
+ * A plain last-one-wins would be WRONG here, which is why this merges field by
+ * field: a still-running report queued after a finish must not un-finish the row unless its activity is later than the finish ({@link mergedFinish}).
+ */
+export function collapseActivityChanges(changes) {
+    const byKey = new Map();
+    for (const c of changes) {
+        // NUL separator: neither a kind (a fixed enum) nor an activity id (a
+        // transcript basename or a tool-use id) can contain one, so no pair of
+        // distinct keys can collide into one string.
+        const key = `${c.kind}\u0000${c.activityId}`;
+        const prior = byKey.get(key);
+        if (prior === undefined) {
+            byKey.set(key, { ...c });
+            continue;
+        }
+        byKey.set(key, {
+            kind: c.kind,
+            activityId: c.activityId,
+            // COALESCE(incoming, stored) — a later report may FILL one in, never erase
+            // it (a Bash launch knows the description, a sub-agent stop knows the type;
+            // neither knows the other's).
+            agentType: c.agentType ?? prior.agentType,
+            description: c.description ?? prior.description,
+            // LEAST — a start never moves later.
+            startedAt: Math.min(prior.startedAt, c.startedAt),
+            // GREATEST — liveness never moves backwards.
+            lastActivityAt: Math.max(prior.lastActivityAt, c.lastActivityAt),
+            // DX-6815 — the LATEST finish stands while no activity is later than it (see {@link mergedFinish}); a still-running report
+            // that predates the finish never resurrects a stopped activity, and activity after it (a resumed sub-agent) reopens it.
+            ...mergedFinish(prior, c),
+            // DX-4498 — COALESCE(incoming, stored): a spawn fact, known or not, never changes once known.
+            parentActivityId: c.parentActivityId ?? prior.parentActivityId,
+            // DX-4498 — the report with the LATER liveness carries the current effort and tool call (a tie goes to the later
+            // report, which a producer queues after the one it supersedes); a report that knows neither keeps the stored ones.
+            ...latestOf(prior, c),
+            // DX-4508 — COALESCE(incoming, stored): the producer reports its best id and may improve it (a late sidecar's
+            // description outranks the brief); a null never erases one.
+            briefIssueId: c.briefIssueId ?? prior.briefIssueId,
+            // DX-5333 — COALESCE(stored, incoming): the start commit is a fact of the moment the sub-agent started, so the first
+            // one read stands; a field no report carries stays absent.
+            ...(prior.startSha !== undefined || c.startSha !== undefined ? { startSha: prior.startSha ?? c.startSha ?? null } : {}),
+            // DX-5898 - COALESCE(stored, incoming): the brief is read once, so the first word known stands.
+            ...(prior.briefProfile !== undefined || c.briefProfile !== undefined ? { briefProfile: prior.briefProfile ?? c.briefProfile ?? null } : {}),
+        });
+    }
+    return [...byKey.values()];
+}
+/**
+ * DX-6815 — a finish this close to (or before) an activity's latest activity still ends it. A finish is stamped from the line that reports it,
+ * which Claude Code writes after the sub-agent's last line: in production the gap is 0 to 90 ms, and the next gap seen is 11 seconds, a sub-agent
+ * resumed with `SendMessage`. The server's upsert and {@link collapseActivityChanges} both read it from here.
+ */
+export const ACTIVITY_RESUME_GRACE_MS = 10_000;
+/**
+ * DX-6815 — the finish and end status both sides apply when `incoming` meets `stored`. The latest finish known stands only while the latest activity
+ * is not later than it by more than {@link ACTIVITY_RESUME_GRACE_MS}: later activity means the sub-agent was resumed, so it is running again
+ * (`finishedAt` and `endStatus` null), and a finish older than the activity is one of an earlier life. While it stands, the latest explicit end status wins
+ * (a notification read after the session's own close names how it really ended). Every operand is a maximum, so writes may arrive in any order.
+ */
+export function mergedFinish(stored, incoming) {
+    const finish = stored.finishedAt === null || incoming.finishedAt === null ? (stored.finishedAt ?? incoming.finishedAt) : Math.max(stored.finishedAt, incoming.finishedAt);
+    const activity = Math.max(stored.lastActivityAt, incoming.lastActivityAt);
+    if (finish === null || activity > finish + ACTIVITY_RESUME_GRACE_MS)
+        return { finishedAt: null, endStatus: null };
+    return { finishedAt: finish, endStatus: incoming.endStatus ?? stored.endStatus };
+}
+/**
+ * DX-4498 — the `effort` / `currentActivity` merge both sides apply: the report with the later `lastActivityAt` wins
+ * (ties go to `incoming`), and a null never erases a stored value.
+ */
+function latestOf(stored, incoming) {
+    const [newer, older] = incoming.lastActivityAt >= stored.lastActivityAt ? [incoming, stored] : [stored, incoming];
+    return { effort: newer.effort ?? older.effort, currentActivity: newer.currentActivity ?? older.currentActivity };
+}
+const CURSOR_KEYS = new Set(["acked", "delivered", "claims", "pastEof"]);
+const CLAIM_STATE_KEYS = new Set(["held", "pending"]);
+const PENDING_KEYS = new Set(["op", "issueId"]);
+/** DX-3962 - a card id as a claim or a ledger entry names it: the issue routes' own shape, within the column's width. */
+function isIssueId(v) {
+    return typeof v === "string" && v.length <= ISSUE_ID_MAX_LENGTH && ISSUE_ID_PATTERN.test(v);
+}
+/**
+ * DX-3962 - whether `raw` is a well-formed claim state. A STORED cursor from a server that predates attribution has
+ * none, and a collector must refuse such an answer instead of dereferencing it.
+ */
+export function isClaimState(raw) {
+    try {
+        parseClaimState(raw, "claims");
+        return true;
+    }
+    catch (err) {
+        if (err instanceof StatsPayloadError)
+            return false;
+        throw err;
+    }
+}
+/** DX-3962 - strict parse of one source's claim state (a collector bug, never coerced). */
+function parseClaimState(raw, where) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        throw new StatsPayloadError(where);
+    const c = raw;
+    for (const k of Object.keys(c)) {
+        if (!CLAIM_STATE_KEYS.has(k))
+            throw new StatsPayloadError(`${where}.${k} is not a claim-state field`);
+    }
+    if (!Array.isArray(c.held) || c.held.length > MAX_HELD_CLAIMS || !c.held.every(isIssueId)) {
+        throw new StatsPayloadError(`${where}.held must be at most ${MAX_HELD_CLAIMS} card ids`);
+    }
+    if (!c.pending || typeof c.pending !== "object" || Array.isArray(c.pending)) {
+        throw new StatsPayloadError(`${where}.pending must be an object`);
+    }
+    const pendingEntries = Object.entries(c.pending);
+    if (pendingEntries.length > MAX_PENDING_TRANSITIONS) {
+        throw new StatsPayloadError(`${where}.pending exceeds the cap of ${MAX_PENDING_TRANSITIONS}`);
+    }
+    const pending = {};
+    for (const [toolUseId, value] of pendingEntries) {
+        const w = `${where}.pending[${toolUseId}]`;
+        if (!toolUseId)
+            throw new StatsPayloadError(`${where}.pending key must be a non-empty tool-use id`);
+        if (!value || typeof value !== "object")
+            throw new StatsPayloadError(w);
+        const p = value;
+        for (const k of Object.keys(p)) {
+            if (!PENDING_KEYS.has(k))
+                throw new StatsPayloadError(`${w}.${k} is not a pending-transition field`);
+        }
+        if (p.op !== "claim" && p.op !== "release")
+            throw new StatsPayloadError(`${w}.op must be claim or release`);
+        if (!isIssueId(p.issueId))
+            throw new StatsPayloadError(`${w}.issueId`);
+        pending[toolUseId] = { op: p.op, issueId: p.issueId };
+    }
+    return { held: [...c.held], pending };
+}
+const PAST_EOF_KEYS = new Set(["storedOffset", "fileSize"]);
+function parsePastEof(raw, where) {
+    if (!raw || typeof raw !== "object")
+        throw new StatsPayloadError(where);
+    const p = raw;
+    for (const k of Object.keys(p)) {
+        if (!PAST_EOF_KEYS.has(k))
+            throw new StatsPayloadError(`${where}.${k} is not a pastEof field`);
+    }
+    if (!isNonNegInt(p.storedOffset))
+        throw new StatsPayloadError(`${where}.storedOffset`);
+    if (!isNonNegInt(p.fileSize))
+        throw new StatsPayloadError(`${where}.fileSize`);
+    return { storedOffset: p.storedOffset, fileSize: p.fileSize };
+}
+function parseSourceCursors(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new StatsPayloadError("sourceCursors must be an object");
+    }
+    const entries = Object.entries(raw);
+    if (entries.length > CURSOR_BATCH_CAP) {
+        throw new StatsPayloadError(`sourceCursors exceeds the cap of ${CURSOR_BATCH_CAP}`);
+    }
+    const out = {};
+    for (const [source, value] of entries) {
+        if (!source)
+            throw new StatsPayloadError("sourceCursors key must be a non-empty source");
+        if (!value || typeof value !== "object") {
+            throw new StatsPayloadError(`sourceCursors[${source}] must be an object`);
+        }
+        const c = value;
+        for (const k of Object.keys(c)) {
+            if (!CURSOR_KEYS.has(k)) {
+                throw new StatsPayloadError(`sourceCursors[${source}].${k} is not a cursor field`);
+            }
+        }
+        if (!isNonNegInt(c.acked))
+            throw new StatsPayloadError(`sourceCursors[${source}].acked`);
+        if (!isNonNegInt(c.delivered))
+            throw new StatsPayloadError(`sourceCursors[${source}].delivered`);
+        // `delivered` is the highest line HANDED ON, `acked` the highest
+        // ACKNOWLEDGED — acknowledging a line necessarily means it was handed on
+        // first, so delivered < acked is structurally impossible and a sender bug.
+        if (c.delivered < c.acked) {
+            throw new StatsPayloadError(`sourceCursors[${source}]: delivered (${c.delivered}) is behind acked (${c.acked})`);
+        }
+        const report = {
+            acked: c.acked,
+            delivered: c.delivered,
+            claims: parseClaimState(c.claims, `sourceCursors[${source}].claims`),
+        };
+        if (c.pastEof !== undefined) {
+            report.pastEof = parsePastEof(c.pastEof, `sourceCursors[${source}].pastEof`);
+        }
+        out[source] = report;
+    }
+    return out;
+}
+const ACTIVITY_KEYS = new Set([
+    "kind",
+    "activityId",
+    "agentType",
+    "description",
+    "startedAt",
+    "lastActivityAt",
+    "finishedAt",
+    "parentActivityId",
+    "effort",
+    "currentActivity",
+    "endStatus",
+    "briefIssueId",
+    "startSha",
+    "briefProfile",
+]);
+/** DX-4498 — a nullable string field of an activity: present, and either null or a non-empty string. */
+function nullableText(a, key, where, maxChars) {
+    if (!(key in a))
+        throw new StatsPayloadError(`${where}.${key} is required (null when unknown)`);
+    const v = a[key];
+    if (v === null)
+        return null;
+    if (typeof v !== "string" || v === "")
+        throw new StatsPayloadError(`${where}.${key} must be a non-empty string or null`);
+    if (maxChars !== undefined && v.length > maxChars) {
+        throw new StatsPayloadError(`${where}.${key} exceeds ${maxChars} characters`);
+    }
+    return v;
+}
+function parseActivities(raw) {
+    if (!Array.isArray(raw))
+        throw new StatsPayloadError("activities must be an array");
+    if (raw.length > ACTIVITY_BATCH_CAP) {
+        throw new StatsPayloadError(`activities exceeds the cap of ${ACTIVITY_BATCH_CAP}`);
+    }
+    return raw.map((entry, i) => {
+        const where = `activities[${i}]`;
+        if (!entry || typeof entry !== "object")
+            throw new StatsPayloadError(where);
+        const a = entry;
+        for (const k of Object.keys(a)) {
+            if (!ACTIVITY_KEYS.has(k))
+                throw new StatsPayloadError(`${where}.${k} is not an activity field`);
+        }
+        if (typeof a.kind !== "string" || !ACTIVITY_KINDS.includes(a.kind)) {
+            throw new StatsPayloadError(`${where}.kind must be one of ${ACTIVITY_KINDS.join(", ")}`);
+        }
+        if (typeof a.activityId !== "string" || !a.activityId) {
+            throw new StatsPayloadError(`${where}.activityId`);
+        }
+        if (a.agentType !== null && typeof a.agentType !== "string") {
+            throw new StatsPayloadError(`${where}.agentType`);
+        }
+        if (a.description !== null && typeof a.description !== "string") {
+            throw new StatsPayloadError(`${where}.description`);
+        }
+        if (!isNonNegInt(a.startedAt))
+            throw new StatsPayloadError(`${where}.startedAt`);
+        if (!isNonNegInt(a.lastActivityAt))
+            throw new StatsPayloadError(`${where}.lastActivityAt`);
+        if (a.finishedAt !== null && !isNonNegInt(a.finishedAt)) {
+            throw new StatsPayloadError(`${where}.finishedAt`);
+        }
+        // DX-4498 — REQUIRED, `null` when unknown: an activity without them comes from a collector that predates them, which
+        // the `stats` surface floor refuses rather than this parser defaulting them.
+        const parentActivityId = nullableText(a, "parentActivityId", where);
+        const effort = nullableText(a, "effort", where);
+        const currentActivity = nullableText(a, "currentActivity", where, CURRENT_ACTIVITY_MAX_CHARS);
+        const endStatus = nullableText(a, "endStatus", where);
+        if (endStatus !== null && !ACTIVITY_END_STATUSES.includes(endStatus)) {
+            throw new StatsPayloadError(`${where}.endStatus must be one of ${ACTIVITY_END_STATUSES.join(", ")}, or null`);
+        }
+        const briefIssueId = nullableText(a, "briefIssueId", where);
+        if (briefIssueId !== null && !isIssueId(briefIssueId))
+            throw new StatsPayloadError(`${where}.briefIssueId`);
+        // DX-5333 - OPTIONAL: absent = a collector that predates it; present = null (unreadable) or a full git object id.
+        if (a.startSha !== undefined && a.startSha !== null && (typeof a.startSha !== "string" || !GIT_OBJECT_ID.test(a.startSha))) {
+            throw new StatsPayloadError(`${where}.startSha must be a git object id, or null`);
+        }
+        // DX-5898 - OPTIONAL like startSha: absent = an older collector; present = null or a profile-shaped word.
+        const briefProfile = a.briefProfile === undefined ? undefined : nullableText(a, "briefProfile", where, PROFILE_WORD_MAX_LENGTH);
+        return {
+            kind: a.kind,
+            activityId: a.activityId,
+            agentType: a.agentType,
+            description: a.description,
+            startedAt: a.startedAt,
+            lastActivityAt: a.lastActivityAt,
+            finishedAt: a.finishedAt,
+            parentActivityId,
+            effort,
+            currentActivity,
+            endStatus: endStatus,
+            briefIssueId,
+            ...(a.startSha !== undefined ? { startSha: a.startSha } : {}),
+            ...(briefProfile !== undefined ? { briefProfile } : {}),
+        };
+    });
+}
+/** DX-5898: the longest profile word stored. */
+export const PROFILE_WORD_MAX_LENGTH = 64;
+/** DX-5333 - a full git object id (SHA-1 or SHA-256), as `git rev-parse HEAD` prints it. */
+export const GIT_OBJECT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const ACTIVITY_MESSAGE_KEYS = new Set(["activityId", "kind", "messageKey", "text", "at", "cwd", "gitBranch"]);
+function parseActivityMessages(raw) {
+    if (!Array.isArray(raw))
+        throw new StatsPayloadError("activityMessages must be an array");
+    if (raw.length > ACTIVITY_MESSAGE_BATCH_CAP) {
+        throw new StatsPayloadError(`activityMessages exceeds the cap of ${ACTIVITY_MESSAGE_BATCH_CAP}`);
+    }
+    return raw.map((entry, i) => {
+        const where = `activityMessages[${i}]`;
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            throw new StatsPayloadError(where);
+        const m = entry;
+        for (const k of Object.keys(m)) {
+            if (!ACTIVITY_MESSAGE_KEYS.has(k))
+                throw new StatsPayloadError(`${where}.${k} is not an activity message field`);
+        }
+        if (typeof m.activityId !== "string" || !m.activityId)
+            throw new StatsPayloadError(`${where}.activityId`);
+        if (typeof m.kind !== "string" || !ACTIVITY_MESSAGE_KINDS.includes(m.kind)) {
+            throw new StatsPayloadError(`${where}.kind must be one of ${ACTIVITY_MESSAGE_KINDS.join(", ")}`);
+        }
+        if (typeof m.messageKey !== "string" || !m.messageKey)
+            throw new StatsPayloadError(`${where}.messageKey`);
+        if (typeof m.text !== "string" || !m.text)
+            throw new StatsPayloadError(`${where}.text`);
+        // A NUL cannot be stored (Postgres refuses it), and a write that fails is re-sent forever: refuse it here instead.
+        if (m.text.includes("\u0000") || m.messageKey.includes("\u0000"))
+            throw new StatsPayloadError(`${where} holds a NUL character`);
+        if (m.text.length > ACTIVITY_MESSAGE_MAX_CHARS) {
+            throw new StatsPayloadError(`${where}.text exceeds ${ACTIVITY_MESSAGE_MAX_CHARS} characters`);
+        }
+        if (!isNonNegInt(m.at))
+            throw new StatsPayloadError(`${where}.at`);
+        const cwd = nullableText(m, "cwd", where);
+        const gitBranch = nullableText(m, "gitBranch", where);
+        if (cwd?.includes("\u0000") || gitBranch?.includes("\u0000"))
+            throw new StatsPayloadError(`${where} holds a NUL character`);
+        return { activityId: m.activityId, kind: m.kind, messageKey: m.messageKey, text: m.text, at: m.at, cwd, gitBranch };
+    });
+}
+function parseActivityProblems(raw) {
+    if (!Array.isArray(raw))
+        throw new StatsPayloadError("activityProblems must be an array");
+    if (raw.length > ACTIVITY_PROBLEM_BATCH_CAP) {
+        throw new StatsPayloadError(`activityProblems exceeds the cap of ${ACTIVITY_PROBLEM_BATCH_CAP}`);
+    }
+    return raw.map((entry, i) => {
+        const where = `activityProblems[${i}]`;
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            throw new StatsPayloadError(where);
+        const p = entry;
+        for (const k of Object.keys(p)) {
+            if (k !== "activityId" && k !== "problemRefNum")
+                throw new StatsPayloadError(`${where}.${k} is not an activity problem field`);
+        }
+        if (typeof p.activityId !== "string" || !p.activityId)
+            throw new StatsPayloadError(`${where}.activityId`);
+        if (!isNonNegInt(p.problemRefNum) || p.problemRefNum === 0)
+            throw new StatsPayloadError(`${where}.problemRefNum`);
+        return { activityId: p.activityId, problemRefNum: p.problemRefNum };
+    });
+}
+const COMPACTION_KEYS = new Set(["id", "source", "trigger", "at", "contextBefore", "postTokens", "durationMs", "summaryChars"]);
+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`);
+        // DX-4939 - REQUIRED, a count or `null` (the boundary line did not carry it): a compaction that omits the key comes from a
+        // collector that predates it, which the MCP version floor refuses rather than this parser tolerating.
+        if (c.postTokens !== null && !isNonNegInt(c.postTokens))
+            throw new StatsPayloadError(`${where}.postTokens`);
+        if (c.durationMs !== null && !isNonNegInt(c.durationMs))
+            throw new StatsPayloadError(`${where}.durationMs`);
+        if (c.summaryChars !== null && !isNonNegInt(c.summaryChars))
+            throw new StatsPayloadError(`${where}.summaryChars`);
+        return {
+            id: c.id,
+            source: c.source,
+            trigger: c.trigger,
+            at: c.at,
+            contextBefore: c.contextBefore,
+            postTokens: c.postTokens,
+            durationMs: c.durationMs,
+            summaryChars: c.summaryChars,
+        };
+    });
+    // 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
+ * (DX-2954) any key outside {@link STATS_PAYLOAD_KEYS}.
+ */
+export function parseStatsPayload(body) {
+    if (!body || typeof body !== "object")
+        throw new StatsPayloadError("body must be an object");
+    const b = body;
+    const unknown = Object.keys(b).filter((k) => !STATS_PAYLOAD_KEYS.has(k));
+    if (unknown.length > 0) {
+        throw new StatsPayloadError(`unknown field(s): ${unknown.join(", ")} — allowed: ${[...STATS_PAYLOAD_KEYS].join(", ")}`);
+    }
+    if (!Array.isArray(b.entries))
+        throw new StatsPayloadError("entries must be an array");
+    if (b.entries.length > STATS_BATCH_CAP) {
+        throw new StatsPayloadError(`entries exceeds the cap of ${STATS_BATCH_CAP}`);
+    }
+    if (b.transcriptPath !== undefined && (typeof b.transcriptPath !== "string" || !b.transcriptPath)) {
+        throw new StatsPayloadError("transcriptPath must be a non-empty string when present");
+    }
+    const entries = b.entries.map((raw, i) => {
+        const e = raw;
+        const where = `entries[${i}]`;
+        if (typeof e.messageId !== "string" || !e.messageId)
+            throw new StatsPayloadError(`${where}.messageId`);
+        if (typeof e.source !== "string" || !e.source)
+            throw new StatsPayloadError(`${where}.source`);
+        if (e.model !== null && typeof e.model !== "string")
+            throw new StatsPayloadError(`${where}.model`);
+        if (typeof e.speed !== "string" || !e.speed)
+            throw new StatsPayloadError(`${where}.speed`);
+        if (!isNonNegInt(e.repliedAt))
+            throw new StatsPayloadError(`${where}.repliedAt`);
+        const u = e.usage;
+        if (!u || typeof u !== "object")
+            throw new StatsPayloadError(`${where}.usage`);
+        for (const k of USAGE_KEYS) {
+            if (!isNonNegInt(u[k]))
+                throw new StatsPayloadError(`${where}.usage.${k}`);
+        }
+        // DX-3964 - REQUIRED: an entry without `timing` comes from a collector that predates it, which the MCP
+        // version floor refuses rather than this parser tolerating.
+        const t = e.timing;
+        if (!t || typeof t !== "object" || Array.isArray(t))
+            throw new StatsPayloadError(`${where}.timing`);
+        const timing = {};
+        for (const k of LEDGER_TIMING_FIELDS) {
+            if (!isNonNegInt(t[k]))
+                throw new StatsPayloadError(`${where}.timing.${k}`);
+            timing[k] = t[k];
+        }
+        if (!Array.isArray(e.toolUseIds) || e.toolUseIds.some((t) => typeof t !== "string")) {
+            throw new StatsPayloadError(`${where}.toolUseIds`);
+        }
+        // DX-3962 - REQUIRED, `null` or a card id: an entry that omits it comes from a collector that predates
+        // attribution, which the MCP version floor refuses rather than this parser tolerating.
+        if (e.issueId !== null && !isIssueId(e.issueId))
+            throw new StatsPayloadError(`${where}.issueId`);
+        // DX-4939 - REQUIRED: an entry without the real-work flag comes from a collector that predates it, which the MCP version
+        // floor refuses rather than this parser tolerating.
+        if (typeof e.realWork !== "boolean")
+            throw new StatsPayloadError(`${where}.realWork`);
+        return {
+            messageId: e.messageId,
+            source: e.source,
+            model: e.model,
+            speed: e.speed,
+            repliedAt: e.repliedAt,
+            usage: {
+                input: u.input,
+                output: u.output,
+                cacheRead: u.cacheRead,
+                cacheWrite5m: u.cacheWrite5m,
+                cacheWrite1h: u.cacheWrite1h,
+            },
+            timing,
+            toolUseIds: e.toolUseIds,
+            issueId: e.issueId,
+            realWork: e.realWork,
+        };
+    });
+    const payload = { entries };
+    if (b.sourceCursors !== undefined)
+        payload.sourceCursors = parseSourceCursors(b.sourceCursors);
+    if (b.activities !== undefined)
+        payload.activities = parseActivities(b.activities);
+    if (b.activityMessages !== undefined)
+        payload.activityMessages = parseActivityMessages(b.activityMessages);
+    if (b.activityProblems !== undefined)
+        payload.activityProblems = parseActivityProblems(b.activityProblems);
+    if (b.compactions !== undefined)
+        payload.compactions = parseCompactions(b.compactions);
+    if (b.transcriptPath !== undefined)
+        payload.transcriptPath = b.transcriptPath;
+    return payload;
+}
+/**
+ * DX-2963 — a terminal dispatch is never written: the server refuses a stats
+ * write for one. Defined here (DB-free) so both sinks throw the SAME error —
+ * the getPool-direct writer directly, the worker client on the route's 409.
+ */
+export class DispatchUsageTerminalError extends Error {
+    dispatchId;
+    status;
+    constructor(dispatchId, status) {
+        super(`usage ledger: dispatch ${dispatchId} is terminal (${status}) — a terminal dispatch is never written`);
+        this.dispatchId = dispatchId;
+        this.status = status;
+        this.name = "DispatchUsageTerminalError";
+    }
+}

package/dist/subagent-live.d.ts

@@ -0,0 +1,36 @@
+import { type PriceLookup } from "./pricing.js";
+import type { EntryMeta, SourceDiscoveredInfo } from "./session-log-watcher.js";
+import type { ActivityEndStatus } from "./stats-wire.js";
+/** One sub-agent as the live view reports it. Every time is epoch ms. The plugin pane renders exactly this shape. */
+export interface SubagentLiveSnapshot {
+    /** `agent-<agentId>`: its transcript basename, the ledger source key and the dashboard row's activity id. */
+    id: string;
+    /** The sub-agent that spawned it, or null for one the session itself spawned. */
+    parentId: string | null;
+    description: string | null;
+    agentType: string | null;
+    /** Its newest reply's model, never `<synthetic>`; null before its first reply. */
+    model: string | null;
+    effort: string | null;
+    startedAt: number;
+    lastActivityAt: number;
+    finishedAt: number | null;
+    endStatus: ActivityEndStatus | null;
+    /** input + output + cacheRead + cacheWrite5m + cacheWrite1h, summed over its replies. */
+    tokensTotal: number;
+    costUsd: number;
+    toolCallCount: number;
+    currentActivity: string | null;
+    /** The card its spawning `Agent` call names (description first, then brief); shape-checked only. */
+    cardId: string | null;
+}
+export interface SubagentLiveView {
+    /** Wire to the watcher's `onSourceDiscovered`. */
+    onSourceDiscovered: (info: SourceDiscoveredInfo) => void;
+    /** Wire to the watcher's `onUsageLine` (the raw line feed, main transcript included: it carries task notifications). */
+    onLine: (raw: Record<string, unknown>, meta: EntryMeta) => void;
+    /** The snapshots that changed since the last call (each differs from the one last returned for it); clears the set. */
+    takeChanged: () => SubagentLiveSnapshot[];
+}
+/** `priceOf` is the caller's declared prices (the package holds none, DX-5611): the SAME lookup the server prices a credit with. */
+export declare function createSubagentLiveView(priceOf: PriceLookup): SubagentLiveView;