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

package/dist/session-title-marks.d.ts

@@ -0,0 +1,2 @@
+/** `title` without the plugin's leading marks (and the whitespace after them). */
+export declare function stripSessionTitleMarks(title: string): string;

package/dist/session-title-marks.js

@@ -0,0 +1,16 @@
+/**
+ * DX-6078 (from DX-5975 / DX-5992 / DX-5995 / DX-6004 / DX-6021): the 50arms plugin leads a desktop session's title with one mark
+ * (`sessionTitle`, claude-plugins `danxbot/hooks/plan/words.ts`): a hand (U+270B) while its plan has Needs You cards, a pause sign (U+23F8)
+ * while its agent has paused itself, a hammer (U+1F528), a warning sign (U+26A0) while it waits only on a person, or a green or red circle
+ * (U+1F7E2 / U+1F534) for a live or lost connection; the first four may carry the emoji selector U+FE0F. The marks are display only: they
+ * belong to the desktop app's label and never to the stored title.
+ *
+ * THE ONE LIST. The dashboard strips it on every session-title write (`optionalTitle`), so a session on an older MCP cannot store a mark, and a new mark needs only this list. The dashboard MCP's
+ * transcript reader (`session-title.ts`) takes this list over once the package carrying it is published and the MCP pins it. A run of marks is dropped, since two plugin versions marking one title in
+ * turn can stack several.
+ */
+const TITLE_MARKS = /^(?:(?:\u{270B}\u{FE0F}?|\u{23F8}\u{FE0F}?|\u{1F528}\u{FE0F}?|\u{26A0}\u{FE0F}?|\u{1F7E2}|\u{1F534})\s*)+/u;
+/** `title` without the plugin's leading marks (and the whitespace after them). */
+export function stripSessionTitleMarks(title) {
+    return title.replace(TITLE_MARKS, "");
+}

package/dist/stats-wire.d.ts

@@ -0,0 +1,345 @@
+/**
+ * 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 { type CompactionEntry, type LedgerEntry, type LedgerUsage } from "./usage-ledger.js";
+import { type ClaimState } from "./claim-tracker.js";
+/**
+ * DX-2963 — cap on entries per stats write. A from-0 backlog (a reattach, a
+ * 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 declare const STATS_BATCH_CAP = 500;
+/**
+ * DX-2954 — the two offsets a collector keeps per `(dispatch, source)`, where
+ * `source` is the value the ledger keys by (`main`, or a sub-agent id).
+ *
+ *   - `acked` — the RESUME point: every line before it has had its ledger
+ *     entry acknowledged (and, once DX-2956 ships, its log line too).
+ *   - `delivered` — the highest line already handed to transcript subscribers.
+ *
+ * Lines between them are re-read on a restart and handed on as REPLAYS.
+ *
+ * `claims` (DX-3962) is the source's claim state AS OF `acked` - the card(s) the
+ * sub-agent holds, so a collector that resumes at `acked` attributes the next
+ * reply to the right card without re-reading the pickup that sits before it.
+ * A worker's is always empty: it has no claim tracker.
+ *
+ * "None stored" is the ABSENCE of a source's key, never `{acked: 0}` — 0 is a
+ * legitimate stored cursor meaning "start of file", and CP1 forbids a reader
+ * defaulting a missing persisted value.
+ */
+export interface SourceCursor {
+    acked: number;
+    delivered: number;
+    claims: ClaimState;
+}
+/** DX-2954 — per-source cursors. An absent key means none stored (never 0). */
+export type SourceCursors = Record<string, SourceCursor>;
+/**
+ * DX-2954 — the collector found its stored cursor PAST the end of the file (it
+ * was replaced or truncated) and restarted that source at 0. Reported so the
+ * server can record a `transcript_cursor_past_eof` event with both numbers.
+ *
+ * This is the ONE sanctioned backwards move of a stored `acked`: without it the
+ * write would be refused as a `cursor_regression` and the source would tail
+ * nothing for the rest of the dispatch (the pre-card watcher's `size <=
+ * byteOffset` early return, silently).
+ */
+export interface PastEofReset {
+    storedOffset: number;
+    fileSize: number;
+}
+/** DX-2954 — the payload form of a cursor: what a collector REPORTS. */
+export interface SourceCursorReport extends SourceCursor {
+    pastEof?: PastEofReset;
+}
+/** DX-2954 — per-source cursor reports, as a stats write carries them. */
+export type SourceCursorReports = Record<string, SourceCursorReport>;
+/**
+ * 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 declare const ACTIVITY_KINDS: readonly ["agent", "bash"];
+export type ActivityKind = (typeof ACTIVITY_KINDS)[number];
+/**
+ * DX-2954 — one activity's current state, as a stats write reports it. Applied
+ * as an idempotent upsert keyed by `(dispatch, kind, activityId)`: a hook that
+ * fires twice, or a batch resent after a failed flush, must not duplicate it.
+ *
+ * `activityId` for a sub-agent is its transcript file's basename
+ * (`agent-<agent_id>`) — the SAME value the ledger credits its tokens under as
+ * `source`, which is how per-sub-agent tokens join to the running set without
+ * this table carrying a token column. A hook producer builds it from the hook's
+ * `agent_id` as `agent-${agent_id}` (never the bare `agent_id`, and never from
+ * `transcript_path`, which on these events is the MAIN session's transcript) or
+ * it upserts a duplicate row. For a background script it is the Bash call's
+ * `tool_use_id`.
+ */
+export interface ActivityChange {
+    kind: ActivityKind;
+    activityId: string;
+    /** The `agent_type` hook field; null for a background script. */
+    agentType: string | null;
+    /** The Bash call's `description`; null for a sub-agent. */
+    description: string | null;
+    startedAt: number;
+    lastActivityAt: number;
+    /** Epoch ms when it finished, or null while it is still running. */
+    finishedAt: number | null;
+    /**
+     * DX-4498 — the sub-agent that spawned this one (`agent-<parentAgentId>` from its `meta.json`), or null for a
+     * sub-agent the session itself spawned and for a background script.
+     */
+    parentActivityId: string | null;
+    /** DX-4498 — the reasoning effort its latest reply ran at (the assistant line's own `effort`); null until one is read. */
+    effort: string | null;
+    /**
+     * DX-4498 — what it is doing now: its latest tool call as `<Tool>` or `<Tool>: <label>`, where the label is only ever
+     * text the agent wrote AS a label (see {@link describeToolCall}); null until it calls a tool.
+     */
+    currentActivity: string | null;
+    /** DX-4498 — how it ended, when an explicit end event named it; null while running and for an end that named none. */
+    endStatus: ActivityEndStatus | null;
+    /**
+     * DX-4508 — the card its spawning `Agent` call names: the first card id in its (redacted) `description`, else the
+     * first anywhere in its brief; null when neither names one. The name stays `briefIssueId` (and the column
+     * `brief_issue_id`): renaming a required wire field would make every relay already published fail the strict parser.
+     */
+    briefIssueId: string | null;
+    /**
+     * DX-5333 — the repo HEAD in the sub-agent's checkout when it started (`git rev-parse HEAD` at its first transcript line's
+     * `cwd`), so a replay can start from the same code. Optional on the wire like `activityMessages`: absent means "this collector
+     * does not report it" (an older one), never "reset"; null means it could not be read (no git checkout, or a source the
+     * collector found already running). The first stamp wins, server-side and in {@link collapseActivityChanges}.
+     */
+    startSha?: string | null;
+    /**
+     * DX-5898 - the leading word of its brief when shaped like an agent profile name (`<profile> <CARD-ID>`, DX-5899), else null. Optional
+     * like {@link startSha}: absent means an older collector; the first non-null word wins, server-side and in {@link collapseActivityChanges}.
+     */
+    briefProfile?: string | null;
+}
+/**
+ * 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 declare const ACTIVITY_MESSAGE_KINDS: readonly ["brief", "followup", "final"];
+export type ActivityMessageKind = (typeof ACTIVITY_MESSAGE_KINDS)[number];
+/** DX-5333 — the longest message text a collector sends (and the server stores); a longer one is cut by the collector. */
+export declare const ACTIVITY_MESSAGE_MAX_CHARS = 100000;
+/** DX-5333 — cap on messages per stats write, so one write's lock hold stays bounded; the rest stay queued for the next. */
+export declare const ACTIVITY_MESSAGE_BATCH_CAP = 100;
+/**
+ * DX-5333 — one message of a sub-agent's conversation, as a stats write reports it. Applied as an idempotent insert keyed by
+ * `(dispatch, activityId, messageKey)`: `messageKey` is the transcript line's own `uuid`, so a collector that re-reads a
+ * file after a restart, or a batch resent after a failed flush, never stores a message twice. `text` has had its secrets
+ * masked (`redactSecrets`) before it leaves the collector, and the server masks it again.
+ */
+export interface ActivityMessage {
+    activityId: string;
+    kind: ActivityMessageKind;
+    messageKey: string;
+    text: string;
+    /** Epoch ms of the transcript line. */
+    at: number;
+    /** The checkout the sub-agent was in when the line was written (the line's own `cwd`), or null when it carried none. */
+    cwd: string | null;
+    /** The git branch the line was written on (the line's own `gitBranch`), or null when it carried none. */
+    gitBranch: string | null;
+}
+/**
+ * DX-5333 — a card problem the sub-agent itself created (its own `50arms_api` `POST /api/issues/<id>/problems` call and the
+ * 201 that answered it), so a replay can tell the builder's problems from its spawner's: `issue_history.via_key` is the
+ * spawner's key and cannot.
+ */
+export interface ActivityProblemLink {
+    activityId: string;
+    /** DX-5516 (PLAN-50 G-2): the problem's number within its team (the n of `PBLM-n`), as the create answer names it (`ref_num`); the dashboard resolves it within the dispatch's team. */
+    problemRefNum: number;
+}
+/** DX-5333 — cap on problem links per stats write. */
+export declare 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 declare const ACTIVITY_END_STATUSES: readonly ["completed", "failed", "stopped"];
+export type ActivityEndStatus = (typeof ACTIVITY_END_STATUSES)[number];
+/** DX-4498 — the longest `currentActivity` a collector sends (and the server stores). */
+export declare const CURRENT_ACTIVITY_MAX_CHARS = 120;
+export interface StatsPayload {
+    entries: LedgerEntry[];
+    /**
+     * DX-2954 — this collector's cursors for every source it has opened. Optional
+     * because an old worker in the deploy window sends none; absent means
+     * "nothing to store", never "reset to 0".
+     */
+    sourceCursors?: SourceCursorReports;
+    /**
+     * DX-2954 — the running set's changes since the last write. Optional for the
+     * same deploy-window reason as {@link StatsPayload.sourceCursors}.
+     */
+    activities?: ActivityChange[];
+    /**
+     * DX-5333 — the messages of sub-agent conversations read since the last write (see {@link ActivityMessage}), at most
+     * {@link ACTIVITY_MESSAGE_BATCH_CAP} per payload. Optional for the same deploy-window reason as {@link StatsPayload.compactions}:
+     * absent means "none to report", never "none exist".
+     */
+    activityMessages?: ActivityMessage[];
+    /** DX-5333 — the problems sub-agents created since the last write (see {@link ActivityProblemLink}); optional like {@link StatsPayload.activityMessages}. */
+    activityProblems?: ActivityProblemLink[];
+    /**
+     * DX-4922 — compactions read since the last write, at most {@link COMPACTION_BATCH_CAP} per payload; each an idempotent
+     * upsert keyed by the boundary's id. Optional for the same deploy-window reason as {@link StatsPayload.sourceCursors}:
+     * a collector that predates compaction detection sends none; absent means "none to report", never "none exist".
+     */
+    compactions?: CompactionEntry[];
+    /**
+     * DX-2954 — the session's own transcript file path, recorded on the
+     * dispatch's `jsonl_path`.
+     *
+     * **This is the ONE path field of a heartbeat's ledger and cursors, and the ONE
+     * exception to the card's privacy rule** that they carry only numbers, ids,
+     * model names, the `speed` value and timestamps. It is sent once, in the
+     * first stats-bearing write, because an operator session has no other way to
+     * tell the server where its transcript lives (a worker's tracker already
+     * records it from the watcher). The strict parser below allows a path HERE
+     * and in {@link ActivityMessage.cwd} (DX-5333, with the sub-agent's text,
+     * admin-readable only) and nowhere else — no other key may carry one.
+     */
+    transcriptPath?: string;
+}
+/** The dispatch's flat totals, as derived from its ledger. */
+export interface UsageTotals {
+    tokensIn: number;
+    tokensOut: number;
+    cacheRead: number;
+    /** 5-minute + 1-hour (+ any pre-card unsplit baseline) cache writes. */
+    cacheWrite: number;
+    tokensTotal: number;
+    costUsd: number;
+    turnCount: number;
+    toolCallCount: number;
+}
+/** Per-source (main / sub-agent id) credited usage. */
+export interface SourceUsage extends LedgerUsage {
+    costUsd: number;
+}
+export interface StatsResponse {
+    totals: UsageTotals;
+    bySource: Record<string, SourceUsage>;
+    /**
+     * Per sent `message_id`, the per-field total now credited for that reply
+     * across ALL dispatches — what the worker's ceiling estimate subtracts.
+     */
+    perMessage: Record<string, LedgerUsage>;
+    /**
+     * DX-2954 — the dispatch's STORED cursors after this write, per source. This
+     * is what a process takes at start to know where to read on from; an absent
+     * source key means none stored (distinct from 0).
+     */
+    sourceCursors: SourceCursors;
+    /**
+     * DX-2954 — sources whose reported `acked` was LOWER than the stored one and
+     * was therefore refused (a `cursor_regression` event was recorded for each).
+     * The rest of the write still applied. Empty on the happy path.
+     */
+    cursorRegressions: string[];
+    /** DX-2954 — running (`finished_at IS NULL`) activities after this write. */
+    runningActivities: number;
+}
+export declare function chunkEntries(entries: readonly LedgerEntry[], cap?: number): LedgerEntry[][];
+export declare class StatsPayloadError extends Error {
+}
+/**
+ * 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 declare const ACTIVITY_BATCH_CAP = 500;
+/** DX-4922 — cap on compaction rows per stats write; a session compacts a handful of times, so a longer list is a defect. */
+export declare const COMPACTION_BATCH_CAP = 100;
+/** DX-2954 — cap on sources per stats write, for the same reason. */
+export declare const CURSOR_BATCH_CAP = 500;
+/**
+ * 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 declare function collapseActivityChanges(changes: readonly ActivityChange[]): ActivityChange[];
+/**
+ * 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 declare const ACTIVITY_RESUME_GRACE_MS = 10000;
+/**
+ * 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 declare function mergedFinish(stored: Pick<ActivityChange, "lastActivityAt" | "finishedAt" | "endStatus">, incoming: Pick<ActivityChange, "lastActivityAt" | "finishedAt" | "endStatus">): Pick<ActivityChange, "finishedAt" | "endStatus">;
+/**
+ * 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 declare function isClaimState(raw: unknown): raw is ClaimState;
+/** DX-5898: the longest profile word stored. */
+export declare 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 declare const GIT_OBJECT_ID: RegExp;
+/**
+ * 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 declare function parseStatsPayload(body: unknown): StatsPayload;
+/**
+ * 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 declare class DispatchUsageTerminalError extends Error {
+    readonly dispatchId: string;
+    readonly status: string;
+    constructor(dispatchId: string, status: string);
+}