@thehammer/danx-dashboard-mcp 0.1.243 → 0.1.245

package/README.md

@@ -67,6 +67,10 @@ CLAUDE_CODE_SESSION_ID=<session> npx -y @thehammer/danx-dashboard-mcp@<version>
 
 Run by the danxbot plugin's SessionStart hook for a session that is **not** plan-connected. A restarted Claude Code session gets a new session id and no plan binding, so nothing told it that the plan it had been working was unattended. `plan_connect` writes the session's working directory into its connection record (`projectKey`, record schema v2); this subcommand finds the newest OTHER session's record for the same project within `STALE_RECORD_MS`, resolves that record's own credential, and asks `GET /api/plan-sessions/<predecessor>/restart-notice` which plan it was on and how many operator events wait there (the connect digest's own query, read-only). Exit 0 with text on stdout = say it (the registry's `plan_restart.waiting_events` text — this package carries no wording); exit 0 with nothing = nothing to say (never connected from this project, plan archived or deleted, record stale); exit 1 = the lookup failed. A record from an older server (schema v1) is skipped here and refused, with the fix, everywhere a session reads its OWN record.
 
+## `subagents-live` — the plan pane's local live sub-agent feed (DX-4508)
+
+`danx-dashboard-mcp subagents-live <absolute path to the session's main transcript .jsonl>`. Spawned by the danxbot plugin's plan pane, which cannot tail files itself; the dashboard's sub-agent read lags the transcript by about 80s, this by about one second. It tails the session's transcript tree (the main file and `<session-id>/subagents/agent-*.jsonl` beside it) with the same `SessionLogWatcher` the bridge runs, from byte 0 once and then only appended bytes, polling every second, and computes each sub-agent through `@thehammer/danx-session-telemetry`'s `createSubagentLiveView` (the same observer, ledger counter and pricing rule the dashboard uses). stdout carries only `{"subagents":[...]}` lines: the first, after the catch-up read, holds every sub-agent (an empty array when there are none); each later one holds only the sub-agents a poll changed. No network, no credential. A missing, relative or non-`.jsonl` path exits 2 with one stderr line; SIGTERM, SIGINT or a closed stdout exits 0.
+
 ## Build + test
 
 ```bash

package/dist/activity.js

@@ -88,7 +88,7 @@ export function subagentActivityId(agentId) {
 }
 /**
  * DX-4498 — the facts only a transcript knows (the spawning sub-agent, effort, current tool call, how a background task
- * ended, the brief's card). A hook envelope carries none of them, so it reports each as unknown; the server's merge
+ * ended, the card its spawning `Agent` call names). A hook envelope carries none of them, so it reports each as unknown; the server's merge
  * never lets an unknown erase a value the transcript producer stored. A `SubagentStop` names no status either: its
  * finish reads as `done` unless a task notification says otherwise.
  */

package/dist/index.js

@@ -87,6 +87,7 @@ import { BACKGROUND_WORK_SUBCOMMAND, runBackgroundWorkCommand } from "./backgrou
 import { ACTIVITY_SUBCOMMAND, runActivityCommand } from "./activity.js";
 import { EVENT_TEXT_SUBCOMMAND, runEventTextCommand } from "./event-text.js";
 import { RESTART_NOTICE_SUBCOMMAND, runRestartNoticeCommand } from "./restart-notice.js";
+import { SUBAGENTS_LIVE_SUBCOMMAND, runSubagentsLiveCommand } from "./subagents-live.js";
 import { resolveBootCredential } from "./credential.js";
 import { SessionKeyUnusableError, deleteSessionKey } from "./session-key.js";
 import { assertMcpTeamRef } from "./access-request.js";
@@ -686,9 +687,18 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
             process.exit(1);
         });
     }
+    else if (subcommand === SUBAGENTS_LIVE_SUBCOMMAND) {
+        // DX-4508 — the plugin pane's local live sub-agent feed: stdout is its JSON Lines channel, so a fatal goes to
+        // stderr only and exits 1; a refused path exits 2 from the command itself.
+        runSubagentsLiveCommand(rest).then((code) => process.exit(code), (err) => {
+            console.error(`[danx-dashboard-mcp] ${SUBAGENTS_LIVE_SUBCOMMAND} fatal: ${err.message}`);
+            process.exit(1);
+        });
+    }
     else if (subcommand !== undefined) {
         console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only ones are ` +
-            `"${BRIDGE_SUBCOMMAND}", "${BACKGROUND_WORK_SUBCOMMAND}", "${ACTIVITY_SUBCOMMAND}", "${EVENT_TEXT_SUBCOMMAND}", and "${RESTART_NOTICE_SUBCOMMAND}")`);
+            `"${BRIDGE_SUBCOMMAND}", "${BACKGROUND_WORK_SUBCOMMAND}", "${ACTIVITY_SUBCOMMAND}", "${EVENT_TEXT_SUBCOMMAND}", ` +
+            `"${RESTART_NOTICE_SUBCOMMAND}", and "${SUBAGENTS_LIVE_SUBCOMMAND}")`);
         process.exit(2);
     }
     else {

package/dist/subagents-live.js

@@ -0,0 +1,124 @@
+/**
+ * `danx-dashboard-mcp subagents-live <absolute main transcript .jsonl path>` — the LOCAL live feed of a session's
+ * sub-agents for the danxbot plugin's plan pane (DX-4508).
+ *
+ * WHY IT EXISTS. The pane's dashboard read (`GET /api/plan-sessions/:id/subagents`) lags the transcript by about 80s
+ * (the bridge's 5s transcript poll, its 15s heartbeat flush, the pane's 60s read). A hooks module cannot tail the files
+ * itself (`$.fs.read` has no offset and refuses files over 4 MiB), but it can spawn a long-lived child and read its
+ * stdout. This is that child: it tails the session's transcript tree on this machine and prints each change within one
+ * 1s poll of Claude Code writing it.
+ *
+ * ONE PLACE COMPUTES EACH NUMBER. It runs the same `SessionLogWatcher` the bridge runs (`session-stats.ts`), over the
+ * same session layout (the main transcript, and `<sessionDir>/<sessionId>/subagents/agent-<id>.jsonl` beside it), into
+ * the shared `createSubagentLiveView`, which feeds the same activity observer, usage ledger counter and pricing rule
+ * the dashboard's numbers come from. Nothing is counted or priced here.
+ *
+ * THE CONTRACT.
+ *   - stdout carries ONLY lines of `{"subagents":[<snapshot>, ...]}` (`SubagentLiveSnapshot`), one per poll in which
+ *     any snapshot changed, holding just the changed ones. The first line, printed once the whole tree has been read
+ *     from byte 0, carries every sub-agent discovered (an empty array for a session with none, so a reader knows the
+ *     catch-up is done). Every later line reads only bytes appended since.
+ *   - diagnostics go to stderr.
+ *   - a missing, relative or non-`.jsonl` path is refused: one stderr line, exit 2.
+ *   - it runs until killed: SIGTERM, SIGINT or a closed stdout stops it cleanly with exit 0.
+ *   - no network call, no credential, no dashboard client: everything it reads is a local file.
+ */
+import { statSync } from "node:fs";
+import { basename, dirname, isAbsolute } from "node:path";
+import { SessionLogWatcher, createSubagentLiveView, } from "@thehammer/danx-session-telemetry";
+export const SUBAGENTS_LIVE_SUBCOMMAND = "subagents-live";
+/** How often the transcript tree is polled: the pane's ~5s freshness target with room to spare. */
+export const SUBAGENTS_LIVE_POLL_MS = 1_000;
+const USAGE = `usage: danx-dashboard-mcp ${SUBAGENTS_LIVE_SUBCOMMAND} <absolute path to the session's main transcript .jsonl>`;
+/** The validated transcript path, or the reason it is refused. */
+export function parseSubagentsLiveArgs(args) {
+    if (args.length !== 1)
+        return { ok: false, reason: `expected exactly one argument, got ${args.length}` };
+    const path = args[0];
+    if (!isAbsolute(path))
+        return { ok: false, reason: `"${path}" is not an absolute path` };
+    if (!path.endsWith(".jsonl"))
+        return { ok: false, reason: `"${path}" is not a .jsonl transcript` };
+    let isFile;
+    try {
+        isFile = statSync(path).isFile();
+    }
+    catch {
+        return { ok: false, reason: `"${path}" does not exist` };
+    }
+    if (!isFile)
+        return { ok: false, reason: `"${path}" is not a file` };
+    return { ok: true, path };
+}
+/** The one stdout line a poll's changes are printed as. */
+export function formatSubagentsLine(subagents) {
+    return `${JSON.stringify({ subagents })}\n`;
+}
+export async function runSubagentsLiveCommand(args, deps = realDeps()) {
+    const parsed = parseSubagentsLiveArgs(args);
+    if (!parsed.ok) {
+        deps.writeError(`[danx-dashboard-mcp] ${SUBAGENTS_LIVE_SUBCOMMAND}: ${parsed.reason}. ${USAGE}`);
+        return 2;
+    }
+    const path = parsed.path;
+    const view = createSubagentLiveView();
+    let stopped = false;
+    let caughtUp = false;
+    let watcher = null;
+    let resolveStopped = () => { };
+    const stoppedHere = new Promise((resolve) => {
+        resolveStopped = resolve;
+    });
+    const emit = () => {
+        if (stopped)
+            return;
+        const changed = view.takeChanged();
+        // DX-4508 — the first poll's line is printed even when empty: it tells the reader the catch-up read is complete.
+        if (changed.length === 0 && caughtUp)
+            return;
+        caughtUp = true;
+        if (!deps.writeLine(formatSubagentsLine(changed)))
+            stop();
+    };
+    const stop = () => {
+        stopped = true;
+        watcher?.stop();
+        resolveStopped();
+    };
+    watcher = deps.makeWatcher({
+        cwd: dirname(path),
+        sessionDir: dirname(path),
+        sessionId: basename(path, ".jsonl"),
+        // DX-4508 — no stored cursors: every file is read from byte 0 once, then only its appended bytes.
+        startCursors: {},
+        pollIntervalMs: SUBAGENTS_LIVE_POLL_MS,
+        onSourceDiscovered: view.onSourceDiscovered,
+        onPollComplete: emit,
+    });
+    watcher.onUsageLine(view.onLine);
+    // Either the process is told to stop, or stdout refused a line (`emit`).
+    const stopRequested = Promise.race([deps.untilStopped(), stoppedHere]);
+    await watcher.start();
+    await stopRequested;
+    stop();
+    return 0;
+}
+function realDeps() {
+    return {
+        makeWatcher: (options) => new SessionLogWatcher(options),
+        writeLine: (line) => {
+            if (process.stdout.destroyed || !process.stdout.writable)
+                return false;
+            process.stdout.write(line);
+            return true;
+        },
+        writeError: (line) => process.stderr.write(`${line}\n`),
+        untilStopped: () => new Promise((resolve) => {
+            process.once("SIGTERM", () => resolve());
+            process.once("SIGINT", () => resolve());
+            // A reader that closes the pipe ends the command: there is no one left to print to.
+            process.stdout.once("error", () => resolve());
+            process.stdout.once("close", () => resolve());
+        }),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.243",
+  "version": "0.1.245",
   "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,7 +31,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
-    "@thehammer/danx-session-telemetry": "0.1.27",
+    "@thehammer/danx-session-telemetry": "0.1.29",
     "zod": "^3.25.76"
   },
   "devDependencies": {