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

package/README.md

@@ -1,3 +1,69 @@
-# Temporary Holding Version
+# `@50arms/session-telemetry`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DX-2962 — the shared Claude Code transcript collector, extracted from
+danxbot root's `src/agent/session-log-watcher.ts` so the danxbot worker and
+the `platform-mcp` MCP server's plan event relay (DX-2954) run **identical** collector
+code, instead of the worker's copy silently diverging from a re-implementation
+inside the MCP package.
+
+## What's here
+
+- `session-log-watcher.ts` — `SessionLogWatcher`: incremental tailing of a
+  Claude Code session's main + sub-agent JSONL transcripts. No whole-transcript
+  buffer — small per-reply bookkeeping only, and only for the life of the
+  process (see its own header for the DX-2962 "unbounded entries list
+  deleted" note).
+- `types.ts` — `AgentLogEntry` / `AgentLineage`, the collector's emitted
+  shape. Canonical home now; danxbot root's `src/types.ts` re-exports both
+  names verbatim.
+- `tool-summary.ts` — human-readable summary builders the collector uses.
+- `subagent-live.ts` — `createSubagentLiveView` (DX-4508): per-sub-agent snapshots
+  (tokens, cost, tool calls, model, current activity, card) computed by the same
+  activity observer, ledger counter and pricing rule the dashboard's numbers come
+  from; streamed by `platform-mcp subagents-live`.
+- `internal-logger.ts` — this package's own tiny logging shim (see its
+  header for why it does not reuse root's `src/logger.ts`).
+- `index.ts` — the main entry (Node-only; imports `node:fs`/`node:path`/`node:os`).
+- `browser.ts` — the `./browser` subpath. Zero `node:` imports, enforced by
+  `src/__tests__/no-node-imports.test.ts`. Today it re-exports only the two
+  types (`AgentLogEntry`/`AgentLineage`); DX-2963 adds the first runtime
+  export (the usage counter + pricing function).
+
+## Isolation
+
+This package **never imports from the danxbot root repo**. Everything it
+needs (logging, tool-summary formatting, the entry/lineage types) is either
+moved in wholesale (when the root file had no other consumer) or
+re-implemented minimally as this package's own dependency (when the root
+file — like `src/logger.ts`, with ~300 unrelated consumers — was never a
+candidate to move). See `session-log-watcher.ts` and `internal-logger.ts`'s
+own header comments for the per-file reasoning.
+
+## How consumers resolve this package (DX-2962 AC3)
+
+| Consumer | Mechanism | Why |
+|---|---|---|
+| **danxbot worker** (root repo, `tsx src/index.ts`) | npm **workspace** link (`"workspaces": ["packages/*"]` in root `package.json`, `"@50arms/session-telemetry"` in root `dependencies`) | The worker and this package always ship from the SAME repo commit — a workspace link means the worker runs whatever source the current commit carries, with zero drift risk and no dependency on registry propagation timing. The Docker image builds `dist/` for it in a dedicated builder stage (alongside `frontend-builder` in `Dockerfile`) since the final image's `npm ci --omit=dev` never installs this package's own `devDependencies` (`typescript`). |
+| **`platform-mcp` MCP server** (separate npm-published package, DX-2954) | Ordinary npm dependency, **pinned to the exact published version** the worker's commit ships | The MCP server is a genuinely separate installable artifact (`npx -y @50arms/platform-mcp`), so it cannot workspace-link into danxbot's own checkout — it needs the real published bytes. Pinning exact (not `^`/`~`) is what makes "worker and MCP run identical collector code for any given release" true: MCP's own version bump is the only thing that ever changes what collector code it runs. |
+| **Dashboard server** (`src/dashboard/*`) | Same npm dependency shape as the worker (the dashboard server's `src/` is root-repo code, so it resolves through the SAME root workspace link as the worker) | An npm dependency resolves through ordinary node_modules lookup, so no `@backend`-style alias is needed. |
+
+## Release order (DX-2962 AC3)
+
+1. Publish this package (`make publish-session-telemetry`).
+2. Publish `platform-mcp` (only once it depends on this package — DX-2954).
+3. Deploy the danxbot backend.
+
+Publishing comes before deploying because the publish-drift gate
+(`src/dispatch/publish-drift-gate.ts`) refuses a finalize whose bumped
+`packages/*/package.json` version is not yet live on npm.
+
+## Boot check
+
+`npm run verify:boot` (wired into `make publish-session-telemetry`,
+mirroring `packages/danx-dashboard-mcp/scripts/verify-boot.sh`) packs the
+freshly-built package with `npm pack`, installs the tarball into a clean
+temp directory (the way an `npm install` consumer actually would — not a
+relative `require` back into this checkout), and imports both the main
+entry and the `./browser` subpath, calling one exported function from each.
+A broken `exports` map, a missing `dist/` file, or an accidental `node:`
+leak into `browser.ts` fails the publish before anything reaches npm.

package/dist/.source-hash

@@ -0,0 +1 @@
+2ba7b19c6a4f26c9d1b0a2798a82b2e55e3f5aac580245587742c3332dcf6c25

package/dist/activity-observer.d.ts

@@ -0,0 +1,186 @@
+/**
+ * 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 an `agent_type`
+ * before the sub-agent has written anything and a FINISH for every sub-agent,
+ * foreground or background. They ship from the 50arms plugin in the
+ * claude-plugins repo (DX-3284; DX-4235 moved them into the plugin's hooks module), which calls
+ * `50arms_api`, and reach the server
+ * through `POST /api/plan-sessions/me/activity` — which writes the SAME
+ * `dispatch_activities` rows through the same one server writer.
+ *
+ * The transcript stays the producer because it needs no hook to be installed: a
+ * session with no plugin, and every WORKER dispatch, still gets a row for each
+ * sub-agent from here. The hooks are an ENRICHMENT layered on the same rows:
+ *
+ * | Signal | Sub-agent start | Sub-agent finish | Background script |
+ * |---|---|---|---|
+ * | Transcript (here) | file discovered | a foreground sub-agent's own `tool_result` in the spawner's transcript (DX-5576); a background sub-agent's task notification (DX-4498); else the dispatch's terminal write (`finishOpenActivities`) as the fallback | not visible |
+ * | Hooks (DX-3284, operator sessions) | `SubagentStart` | `SubagentStop` | `PostToolUse` start; end at dispatch terminal (no documented completion event) |
+ *
+ * ## What it reports about each sub-agent (DX-4498)
+ *
+ * All of it read from what Claude Code itself writes, with no cooperation from
+ * the sub-agent:
+ *
+ * | Field | Read from |
+ * |---|---|
+ * | `agentType`, `description`, `parentActivityId` | the sub-agent's `meta.json` sidecar (via `SourceDiscoveredInfo`); the description through {@link redactLabel} |
+ * | `lastActivityAt` | the timestamp of its latest `assistant` / `user` line |
+ * | `effort` | its latest `assistant` line's top-level `effort` |
+ * | `currentActivity` | its latest `tool_use` block, through {@link describeToolCall} |
+ * | `briefProfile` | DX-5898: the leading word of its brief (the root `user` line) when shaped like a profile name, else null; the server matches it against the team's profiles |
+ * | `briefIssueId` | the card its spawning `Agent` call names: the first card id in its `description` (redacted), else the first anywhere in its brief (the root `user` line) — see {@link firstIssueId} (DX-4508) |
+ * | `finishedAt`, `endStatus` | what Claude Code writes into the SPAWNER's transcript: a foreground spawn's `tool_result` (DX-5576) or a background spawn's task notification (DX-4498) |
+ *
+ * Model, tokens, cost, tool-call count and the claimed card are NOT here: the
+ * usage ledger already records them per reply, keyed by the same source, and
+ * the read derives them from it (two places recording one number is how they
+ * drift).
+ *
+ * ## 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, `agent-<agent_id>`. The watcher has it directly; a hook has the
+ * `agent_id` and builds the same basename from it: `agent-` plus the id with one leading `agent-` stripped (the hooks docs
+ * show the prefix on some `agent_id`s), so both forms reach this key. That rule lives in the 50arms plugin's hooks module
+ * (claude-plugins repo). A hook's `transcript_path` is NOT the
+ * sub-agent's file — on these events it is the MAIN session's transcript, and only
+ * `SubagentStop` also carries the sub-agent's own as `agent_transcript_path`,
+ * which the plugin uses to refuse a key that disagrees. That basename 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. A task notification names the sub-agent by its bare id
+ * (`<task-id>`), which is mapped onto the same `agent-<id>` key.
+ *
+ * ## A finish is reported only when Claude Code says so
+ *
+ * A sub-agent's OWN 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 this module never does. The finishes it
+ * reports are EXPLICIT, and a row ends one of three ways:
+ *
+ * 1. A FOREGROUND spawn's `tool_result` in the spawner's transcript (DX-5576), written when the sub-agent is done: its status is
+ *    `completed`, `failed` for an errored result, `stopped` for an interrupted or rejected one ({@link foregroundEndStatus}).
+ * 2. A BACKGROUND spawn's `<task-notification>` (DX-4498), which Claude Code delivers to the spawner when the task ends, carrying
+ *    its `<status>` (`completed`, `failed`, `killed`, `stopped`). A foreground spawn gets no notification.
+ * 3. The fallback, for a row neither signal reached: the `SubagentStop` hook (operator sessions) or the dispatch's own terminal
+ *    write, which sets `finishedAt` but names no status.
+ *
+ * Whichever lands first sets `finishedAt`; a later signal only fills the status, unless it is a later end (DX-6815: a sub-agent resumed after its finish ends again), which replaces the finish.
+ */
+import { type ActivityChange, type ActivityEndStatus, type ActivityMessage, type ActivityProblemLink } from "./stats-wire.js";
+import type { EntryMeta, SourceDiscoveredInfo } from "./session-log-watcher.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;
+    /**
+     * DX-5333 — queue the messages read from sub-agent transcripts (see {@link ActivityMessage}). Absent for a consumer that
+     * stores nothing (the local live view).
+     */
+    recordMessages?: (messages: ActivityMessage[]) => void;
+    /** DX-5333 — queue the card problems a sub-agent created (see {@link ActivityProblemLink}). Absent like {@link ActivityObserverDeps.recordMessages}. */
+    recordProblemLinks?: (links: ActivityProblemLink[]) => void;
+    /**
+     * DX-5333 — `git rev-parse HEAD` in `cwd`: the full object id, or null when `cwd` is not a git checkout (or git cannot be
+     * run). Absent when the consumer stamps no start commit. Called at most once per distinct `cwd` per sub-agent, and only for
+     * a sub-agent the collector saw START (never one already running when it attached, whose checkout has moved on since).
+     */
+    readHeadSha?: (cwd: string) => Promise<string | null>;
+}
+export interface ActivityObserver {
+    /** Wire to the watcher's `onSourceDiscovered`. */
+    onSourceDiscovered: (info: SourceDiscoveredInfo) => void;
+    /** DX-4498 — wire to the watcher's `onUsageLine` (the raw line feed: the brief and task notifications are not entries). */
+    onLine: (raw: Record<string, unknown>, meta: EntryMeta) => void;
+    /**
+     * DX-5333 - wire to the watcher's `onPollComplete`. A sub-agent whose end was reported in an EARLIER poll (its spawn's result, or the
+     * task-notification) has all its lines read since (DX-5413: a signal read this poll may precede its child's last lines), so its held reply is confirmed here as its final.
+     */
+    onPollComplete: () => void;
+}
+/**
+ * DX-4498 — a task notification's `(task id, end status)`, or null for a line that is not one, or one whose status is
+ * not an end (`running`). Only the two delivery shapes Claude Code itself writes are read: a `user` line whose
+ * `origin.kind` is `task-notification`, and a `queued_command` attachment with that `commandMode`. A sub-agent's
+ * reply that merely QUOTES a notification carries neither marker, so it can never end anything.
+ */
+export declare function parseTaskNotification(raw: Record<string, unknown>): {
+    taskId: string;
+    endStatus: ActivityEndStatus;
+} | null;
+/** Punctuation a token may be wrapped in, which never stops it from being read as opaque. */
+export declare const WRAPPING_PUNCTUATION: RegExp;
+/**
+ * DX-4498 — an agent-written label as the stats wire may carry it: on one line, with every path-shaped token (any token
+ * holding a `/` or `\`) read as `[path]`, and every secret-shaped token (an `ENV_NAME=value` value, or an opaque run of
+ * 20+ letters and digits such as a key, token or full SHA) read as `[redacted]`. A label is free text the agent wrote
+ * for a person to read (real shell descriptions name absolute paths), and it reaches every reader of the team, so this
+ * is the one way any label leaves a transcript. Empty for a blank label.
+ */
+export declare function redactLabel(label: string): string;
+/**
+ * DX-5333 — a message as the stats wire may carry it: every credential read as `[redacted]` — a URL's password, an
+ * `Authorization`/bearer value, the value of a credential-named assignment, JSON key or `--flag` (`password: x`,
+ * `"password": "x"`, `--password x`), and every opaque run of 20+ characters (a key, a token, a base64 secret that may hold
+ * `/` or end in `=`; a git commit id is kept) — with the text's own whitespace, line breaks, paths and prose kept: a brief is
+ * read to replay the work, and its paths are the work. NUL characters are removed (Postgres refuses them, which would wedge
+ * the write that carries the message). Cut to {@link ACTIVITY_MESSAGE_MAX_CHARS}. The server applies the same function again
+ * on receipt.
+ *
+ * The order of the chain matters: NUL goes first, the PEM block next (its body lines would otherwise be read token by token), then
+ * the structured patterns (URL credentials, headers, named values, flags), and the per-token classifier last, over what is
+ * left. The server re-runs the whole chain on text already masked here, so every step must leave `[redacted]` alone (idempotent).
+ */
+export declare function redactSecrets(text: string): string;
+/** DX-4498 — a transcript value read as a label: {@link redactLabel}'s text, or null for a non-string or blank one. */
+export declare function labelOf(value: unknown): string | null;
+/**
+ * DX-4498 — a sub-agent's current activity, from one `tool_use` block: the tool's name, plus a label only where the
+ * agent wrote one AS a label (a shell call's `description`, an `Agent` call's `description`, a `Skill` call's skill
+ * name), through {@link labelOf}. Never a command, a file path, a secret or a prompt: the stats wire carries ids,
+ * numbers and redacted labels, never free-form transcript content.
+ */
+export declare function describeToolCall(name: string, input: Record<string, unknown>): string;
+/**
+ * DX-4508 — the first card-id-shaped token in a text (`DX-4498`, also `DX-4498:`, `(DX-4498)`), or null when it has
+ * none. A sub-agent's card is the one its spawning `Agent` call names: its `description` ("Review DX-4498 code gates")
+ * first, else its brief ("Quality gate for card DX-4421 ..."), where the first-word rule DX-4498 shipped missed most
+ * real briefs. Only the SHAPE is checked: the server keeps the id only when it is a real card of the team, so a plan ref
+ * (`PLAN-2`) or rule ref (`R-45`) never reaches a reader.
+ */
+export declare function firstIssueId(text: string): string | null;
+/**
+ * DX-5898 - the leading word of a sub-agent's brief when it has a profile name's shape (`gate-designer DX-5875` -> `gate-designer`), else
+ * null. An orchestrator briefs a profile sub-agent as `<profile> <CARD-ID>` (DX-5899); the collector cannot know the team's profiles, so it
+ * keeps only the raw word and the server matches it against the profiles the team may see when it reads the row. A brief that opens with an
+ * ordinary word equal to a profile's name therefore gives a false match: the shape check and that server match are the only filters.
+ */
+export declare function leadingProfileWord(text: string): string | null;
+export declare function createActivityObserver(deps: ActivityObserverDeps): ActivityObserver;