@thehammer/danx-dashboard-mcp 0.1.180 → 0.1.181

package/dist/bridge.js

@@ -71,6 +71,7 @@ import { oneLine } from "./one-line.js";
 import { credentialFingerprint, describeCredentialSource, readCredential, } from "./credential.js";
 import { readSessionConnection, sessionConnectionPath } from "./session-connection.js";
 import { capResumeIds, DELIVERED_ID_MEMORY, HEALTHY_CONNECTION_MS, READ_IDLE_TIMEOUT_MS, runListener, } from "./listen.js";
+import { OperatorSessionStats, transcriptPathFromEnv, } from "./session-stats.js";
 /**
  * DX-2730 D4 — WHICH EVENTS WAKE THE SESSION, NOW THAT EVERY ONE OF THEM CAN.
  *
@@ -241,7 +242,11 @@ export function parseBridgeArgs(argv, env) {
     const resumeIds = withResume ? argv[1].split(",").map(positiveInteger) : [];
     if (resumeIds.some((id) => id === null))
         throw new Error(USAGE);
-    return { sessionId, resumeIds: resumeIds };
+    const parsed = { sessionId, resumeIds: resumeIds };
+    const transcriptPath = transcriptPathFromEnv(env);
+    if (transcriptPath !== null)
+        parsed.transcriptPath = transcriptPath;
+    return parsed;
 }
 /** A start this process cannot make, named the way the session will be told about it. */
 export class BridgeStartError extends Error {
@@ -334,6 +339,7 @@ export function resolveBridgeOptions(args, env, options = {}) {
         resumeIds: args.resumeIds,
         instanceId,
         watchedPaths,
+        ...(args.transcriptPath !== undefined ? { transcriptPath: args.transcriptPath } : {}),
     };
 }
 /**
@@ -542,7 +548,7 @@ export function degradePolicyFor(reason) {
  * heartbeat call itself was rejected". This gap is real and is recorded on
  * the card rather than silently papered over.
  */
-async function sendHeartbeat(options, deps, connection) {
+async function sendHeartbeat(options, deps, connection, stats) {
     const body = { state: connection.state };
     if (connection.reason !== undefined)
         body.reason = connection.reason;
@@ -550,7 +556,7 @@ async function sendHeartbeat(options, deps, connection) {
         body.inventory = connection.inventory;
     const outcome = await request(options, deps, "heartbeat", `${options.dashboardUrl}${HEARTBEAT_PATH}`, {
         method: "POST",
-        body: JSON.stringify({ connection: body }),
+        body: JSON.stringify(stats === undefined ? { connection: body } : { connection: body, stats }),
     });
     // DX-3099 — this is now the ONE place a heartbeat's own outcome is
     // inspected. `request()` still never throws, and a 401/403 is still an
@@ -559,7 +565,23 @@ async function sendHeartbeat(options, deps, connection) {
     // "transient" outcome (network error, timeout, 5xx, 408/429) means the
     // request never landed at all, which is exactly the signal the silent-
     // failure counter in `runBridge` below needs. Still never throws.
-    return outcome.kind === "answer";
+    if (outcome.kind !== "answer")
+        return { landed: false, status: null, stats: null };
+    // DX-2954 — the answer's `stats` (the operator dispatch's stored or
+    // just-written totals and cursors) feed the session's stats collector.
+    const ok = outcome.status >= 200 && outcome.status < 300;
+    // A heartbeat whose carried stats were NOT applied (`statsError`) still
+    // landed; its `stats` are the stored values, so the collector must re-queue
+    // rather than treat them as the answer to its write.
+    const applied = ok && isRecord(outcome.body) && outcome.body.statsError === undefined;
+    const statsBody = applied && isRecord(outcome.body) && isRecord(outcome.body.stats) ? outcome.body.stats : null;
+    const answered = statsBody !== null && isRecord(statsBody.sourceCursors) && isRecord(statsBody.totals)
+        ? statsBody
+        : null;
+    return { landed: true, status: outcome.status, stats: answered };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 /**
  * Mint, stream, re-mint — until a terminal outcome, which it writes as the one
@@ -589,14 +611,18 @@ export async function runBridge(options, deps) {
     // ended is a harmless no-op.
     let heartbeatFailureStreak = 0;
     let forceReconnect = null;
+    // DX-2954 — the session's stats ride this same heartbeat. Created ONCE per
+    // process, so an in-process re-mint never touches its state.
+    const sessionStats = new OperatorSessionStats(options.transcriptPath ?? null, deps.makeStatsWatcher);
+    const connectionNow = () => connectionState === "streaming"
+        ? { state: "streaming", inventory: lastInventoryOk ? "ok" : "unavailable" }
+        : connectionState === "stopped"
+            ? { state: "stopped", reason: stoppedReason ?? undefined }
+            : { state: "reconnecting" };
     const heartbeatTick = () => {
         if (heartbeatSuppressed)
             return;
-        void sendHeartbeat(options, deps, connectionState === "streaming"
-            ? { state: "streaming", inventory: lastInventoryOk ? "ok" : "unavailable" }
-            : connectionState === "stopped"
-                ? { state: "stopped", reason: stoppedReason ?? undefined }
-                : { state: "reconnecting" }).then((landed) => {
+        void sessionStats.tick((stats) => sendHeartbeat(options, deps, connectionNow(), stats)).then((landed) => {
             // DX-3099 — only counts while THIS process still believes it is
             // streaming: that is the exact desync the card found (the client
             // believes it is fine; the dashboard has nothing recent for it). A
@@ -661,6 +687,7 @@ export async function runBridge(options, deps) {
         deps.write({ type: "stopped", reason, detail, refusal: extra?.refusal, fix, instanceId: options.instanceId, paths: options.watchedPaths, degraded });
         if (policy === "exit") {
             heartbeat.stop();
+            sessionStats.stop();
             return { kind: "exit", code };
         }
         stoppedReason = reason;

package/dist/session-stats.js

@@ -0,0 +1,158 @@
+/**
+ * DX-2954 — an operator session's live stats, collected by the bridge and sent
+ * in its DX-2952 heartbeat.
+ *
+ * Workers and operator sessions report the same stats the same way (epic
+ * DX-2958), so this module owns NO counting or cursor logic of its own: it runs
+ * the ONE collector from the shared package (`DispatchUsage`, the shared ledger
+ * counter + transcript cursors + running-set queue), fed by the ONE transcript
+ * tailer (`SessionLogWatcher`) and the ONE transcript-side running-set producer
+ * (`createActivityObserver`) — the exact trio the worker runs in
+ * `attach-monitoring-stack.ts`. The server side is the ONE writer too:
+ * `POST /api/plan-sessions/me/heartbeat` applies the `stats` field through the
+ * same `applyStatsInTx` the worker's `/stats` route uses.
+ *
+ * ## Process start: the first heartbeat's answer, never the mint (round 22)
+ *
+ * A restarted bridge (watchdog restart, compact, resume) may fail its mint and
+ * still heartbeat (DX-2952), so the heartbeat is the one call that always
+ * answers. Until this process holds that answer it sends ONLY its connection
+ * state: no ledger entries, no cursors — the transcript is not even opened. The
+ * answer's `sourceCursors` are where each source resumes (start-order rule 1: an
+ * operator dispatch is one per session id, so its own stored `acked` is the
+ * whole answer; a source with none starts at 0 — rule 3, so a session connected
+ * mid-way, or a fork, has its full transcript counted). There is no predecessor
+ * and never an end-of-file skip for an operator session.
+ *
+ * An in-process re-mint (lease expiry, a refused ticket, transient backoff)
+ * never reaches this module: it lives for the whole process, so its in-memory
+ * state is untouched by anything the mint loop does.
+ *
+ * ## The one path that leaves the machine
+ *
+ * `transcriptPath` comes from the Claude Code hook input `transcript_path` (the
+ * plugin hands it to this process as {@link TRANSCRIPT_PATH_ENV}). It is sent
+ * once, in the first stats-bearing heartbeat, and recorded on the dispatch's
+ * `jsonl_path`; the strict stats parser refuses every other path field.
+ */
+import { basename, dirname, isAbsolute } from "node:path";
+import { DispatchUsage, SessionLogWatcher, createActivityObserver, } from "@thehammer/danx-session-telemetry";
+/** The environment variable the plugin passes the hook input's `transcript_path` in. */
+export const TRANSCRIPT_PATH_ENV = "DANX_BRIDGE_TRANSCRIPT_PATH";
+/**
+ * The session's transcript path from the environment, or `null` when the
+ * plugin supplied none (an older plugin, a hand run): the bridge then runs
+ * exactly as before, heartbeating its connection state only. A value that is
+ * present but is not an absolute `.jsonl` path is refused loudly — silently
+ * ignoring it would leave the session's usage uncounted with nothing to say why.
+ */
+export function transcriptPathFromEnv(env) {
+    const raw = env[TRANSCRIPT_PATH_ENV];
+    if (raw === undefined || raw.trim() === "")
+        return null;
+    const path = raw.trim();
+    if (!isAbsolute(path) || !path.endsWith(".jsonl")) {
+        throw new Error(`${TRANSCRIPT_PATH_ENV} must be an absolute path to a session .jsonl transcript (got "${path}")`);
+    }
+    return path;
+}
+const realWatcher = (options) => new SessionLogWatcher(options);
+/** The collector's dispatch-id argument; the heartbeat is addressed by session, not dispatch. */
+const OPERATOR_DISPATCH_REF = "operator-session";
+export class OperatorSessionStats {
+    transcriptPath;
+    makeWatcher;
+    usage = new DispatchUsage();
+    watcher = null;
+    stopped = false;
+    constructor(transcriptPath, makeWatcher = realWatcher) {
+        this.transcriptPath = transcriptPath;
+        this.makeWatcher = makeWatcher;
+    }
+    /** Whether this process holds the stored stats (and is therefore collecting). */
+    collecting() {
+        return this.watcher !== null;
+    }
+    /**
+     * One heartbeat tick. Before the process holds the stored stats: a plain
+     * connection-state heartbeat, whose answer starts collection. After: the
+     * collector's flush, carried by the heartbeat (a flush with nothing new
+     * sends one plain heartbeat instead, so an idle session still heartbeats).
+     * Returns whether a heartbeat landed, for the bridge's silent-failure count.
+     */
+    async tick(send) {
+        if (this.watcher === null) {
+            const answer = await send(undefined);
+            if (answer.stats !== null)
+                this.begin(answer.stats);
+            return answer.landed;
+        }
+        let carried = false;
+        let landed = true;
+        await this.usage.flush({
+            applyStats: async (_dispatchId, payload) => {
+                carried = true;
+                const answer = await send(payload);
+                if (!answer.landed) {
+                    landed = false;
+                    throw new Error("stats heartbeat did not reach the dashboard");
+                }
+                if (answer.stats === null) {
+                    throw new Error(`stats heartbeat answered HTTP ${answer.status} without stats`);
+                }
+                return answer.stats;
+            },
+        }, OPERATOR_DISPATCH_REF);
+        if (carried)
+            return landed;
+        return (await send(undefined)).landed;
+    }
+    /** Stop tailing. Idempotent; a stopped collector never starts again. */
+    stop() {
+        this.stopped = true;
+        this.watcher?.stop();
+    }
+    begin(stored) {
+        if (this.transcriptPath === null || this.stopped)
+            return;
+        const path = this.transcriptPath;
+        const activities = createActivityObserver({
+            recordActivities: (changes) => this.usage.recordActivities(changes),
+        });
+        const watcher = this.makeWatcher({
+            cwd: dirname(path),
+            sessionDir: dirname(path),
+            sessionId: basename(path, ".jsonl"),
+            startCursors: stored.sourceCursors,
+            onCursorPastEof: (info) => this.usage.recordPastEof(info),
+            onSourceDiscovered: (info) => activities.onSourceDiscovered(info),
+        });
+        this.usage.attachCursors(() => watcher.cursorState(), stored.sourceCursors);
+        this.usage.setTranscriptPath(path);
+        // Replays are credited (the ledger is idempotent) and marked so the
+        // collector's own estimate never counts them twice; the bridge has no
+        // side-effecting transcript subscriber to skip them for.
+        watcher.onEntry((entry, meta) => this.usage.observeEntry(entry, meta.replay));
+        watcher.onEntry(activities.onEntry);
+        this.watcher = watcher;
+        void watcher
+            .start()
+            .then(async () => {
+            // The watcher's discovery gives up after a bounded wait when the
+            // transcript file does not exist yet (Claude Code may create it lazily,
+            // on the session's first turn). Collecting "forever" from a watcher that
+            // adopted no file would read nothing, so drop it: the next heartbeat's
+            // answer starts collection again from the stored cursors.
+            if (this.watcher !== watcher || this.stopped)
+                return;
+            if ((await watcher.resolveSessionFileNow()) !== null)
+                return;
+            watcher.stop();
+            this.watcher = null;
+            this.usage = new DispatchUsage();
+        })
+            .catch((err) => {
+            process.stderr.write(`operator session stats: transcript watcher failed: ${err.message}\n`);
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.180",
+  "version": "0.1.181",
   "description": "Stdio MCP server fronting danxbot's dashboard API for agents (operator sessions and dispatched workers alike): the generic danxbot_api/danxbot_api_list/danxbot_api_spec tools reach any route the caller's credential may call, plus dedicated agent-specific tools (plan_connect, danxbot_complete, and other per-dispatch lifecycle callbacks) (DX-3465, PLN-11 R-25).",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
+    "@thehammer/danx-session-telemetry": "0.1.15",
     "zod": "^3.25.76"
   },
   "devDependencies": {