@thehammer/danx-dashboard-mcp 0.1.227 → 0.1.229

package/dist/bridge.js

@@ -76,6 +76,7 @@ import { readSessionConnection, sessionConnectionPath } from "./session-connecti
 import { capResumeIds, DELIVERED_ID_MEMORY, HEALTHY_CONNECTION_MS, READ_IDLE_TIMEOUT_MS, runListener, } from "./listen.js";
 import { isClaimState } from "@thehammer/danx-session-telemetry";
 import { OperatorSessionStats, transcriptPathFromEnv, } from "./session-stats.js";
+import { TranscriptTitleReader } from "./session-title.js";
 /**
  * DX-2730 D4 — WHICH EVENTS WAKE THE SESSION, NOW THAT EVERY ONE OF THEM CAN.
  *
@@ -586,7 +587,9 @@ 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, stats) {
+async function sendHeartbeat(options, deps, connection, stats, 
+// DX-4461 - the session's current Claude title, read from its transcript (`session-title.ts`).
+title) {
     const body = { state: connection.state };
     if (connection.reason !== undefined)
         body.reason = connection.reason;
@@ -594,7 +597,7 @@ async function sendHeartbeat(options, deps, connection, stats) {
         body.inventory = connection.inventory;
     const outcome = await request(options, deps, "heartbeat", `${options.dashboardUrl}${HEARTBEAT_PATH}`, {
         method: "POST",
-        body: JSON.stringify(stats === undefined ? { connection: body } : { connection: body, stats }),
+        body: JSON.stringify({ connection: body, ...(stats !== undefined ? { stats } : {}), ...(title !== undefined ? { title } : {}) }),
     });
     // 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
@@ -604,7 +607,7 @@ async function sendHeartbeat(options, deps, connection, stats) {
     // request never landed at all, which is exactly the signal the silent-
     // failure counter in `runBridge` below needs. Still never throws.
     if (outcome.kind !== "answer")
-        return { landed: false, status: null, stats: null, revocation: null };
+        return { landed: false, status: null, stats: null, revocation: null, title: 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;
@@ -623,7 +626,15 @@ async function sendHeartbeat(options, deps, connection, stats) {
         ? statsBody
         : null;
     // DX-4418 - the dashboard refuses the beat of a session whose key a person revoked, and says so.
-    return { landed: true, status: outcome.status, stats: answered, revocation: keyRevocationOf({ ok: false, status: outcome.status, body: outcome.body }) };
+    // DX-4461 - the dashboard's stored title for this session; an answer without one is an older dashboard's.
+    const storedTitle = ok && isRecord(outcome.body) && typeof outcome.body.title === "string" ? outcome.body.title : null;
+    return {
+        landed: true,
+        status: outcome.status,
+        stats: answered,
+        revocation: keyRevocationOf({ ok: false, status: outcome.status, body: outcome.body }),
+        title: storedTitle,
+    };
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -669,11 +680,39 @@ export async function runBridge(options, deps) {
         : connectionState === "stopped"
             ? { state: "stopped", reason: stoppedReason ?? undefined }
             : { state: "reconnecting" };
+    // DX-4461 - a rename reaches the dashboard without the agent: the title in the session's transcript rides the heartbeat
+    // when it differs from the one the dashboard last answered with. Only the LATEST landed answer counts: one without a
+    // title (an older dashboard, including one rolled back to mid-session, or a refusal) stops the title until an answer
+    // carries one again, since an older dashboard refuses the `title` key and a refused heartbeat is a dead listener.
+    const titleReader = options.transcriptPath !== undefined ? new TranscriptTitleReader(options.transcriptPath) : null;
+    let dashboardTitle;
+    let lastTitleError = null;
+    const titleToReport = () => {
+        if (titleReader === null || dashboardTitle === undefined)
+            return undefined;
+        // The title is cosmetic and the heartbeat is liveness: a transcript the title cannot be read from costs the title
+        // (said once per distinct failure), never the beat.
+        try {
+            const title = titleReader.read();
+            lastTitleError = null;
+            return title !== null && title !== dashboardTitle ? title : undefined;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (message !== lastTitleError)
+                process.stderr.write(`session title: ${message}\n`);
+            lastTitleError = message;
+            return undefined;
+        }
+    };
     const heartbeatTick = () => {
         if (heartbeatSuppressed)
             return;
+        const title = titleToReport();
         void sessionStats.tick(async (stats) => {
-            const answer = await sendHeartbeat(options, deps, connectionNow(), stats);
+            const answer = await sendHeartbeat(options, deps, connectionNow(), stats, title);
+            if (answer.landed)
+                dashboardTitle = answer.title ?? undefined;
             // DX-4418 - a person revoked this session's key: tell the session to stop, at once and only once, as an ordinary event
             // line (the same delivery the silent-failure notice below uses). Its next dashboard call says the same.
             if (answer.revocation !== null && !revocationAnnounced) {

package/dist/handlers.js

@@ -47,9 +47,11 @@ const PLAN_SESSIONS_BASE_PATH = "/api/plan-sessions";
  * would end the bridge's stream.
  *
  * `title` (DX-2816) rides here, not on a header, because the AGENT — not this
- * server — is the one thing able to read Claude's own session title (via a
+ * server — can read Claude's own session title at connect time (via a
  * Desktop-side `get_session` tool no MCP server subprocess can call). Sent
  * only when the caller supplied one; the server leaves an unset title alone.
+ * The event bridge keeps it current afterwards, from the transcript (DX-4461,
+ * `session-title.ts`).
  */
 export async function planConnect(client, args) {
     if (args.disconnect === true) {

package/dist/index.js

@@ -221,10 +221,14 @@ function resolveInitialCredential(dashboardUrl, sessionId) {
  * MCP-server-reachable signal carries Claude's own session title — this
  * SERVER genuinely cannot read it. The AGENT can, though (a Desktop-side
  * `get_session` tool this server has no access to), and the agent is what
- * calls `plan_connect` — so the title now travels as that tool's own
- * `title` argument (see `handlers.ts#planConnect`), not as a header stamped
- * here. A session that never connects with a title keeps the dashboard's own
- * placeholder (`session <id prefix>`) — an honest placeholder beats a guess.
+ * calls `plan_connect` — so the title travels as that tool's own `title`
+ * argument (see `handlers.ts#planConnect`) at connect time, not as a header
+ * stamped here. DX-4461: the session's TRANSCRIPT carries every rename as a
+ * `custom-title` record, so the event bridge (not this server) reads it from
+ * there and reports it on its heartbeat (`session-title.ts`) and a later rename needs no
+ * agent call. A session that never connects with a title keeps the
+ * dashboard's own placeholder (`session <id prefix>`) until its bridge reports
+ * one — an honest placeholder beats a guess.
  */
 function readSessionConfig() {
     const id = readEnvOptional("CLAUDE_CODE_SESSION_ID");

package/dist/session-title.js

@@ -0,0 +1,127 @@
+/**
+ * DX-4461 - a session's live Claude title, read from its own transcript with no help from the agent.
+ *
+ * WHY THE TRANSCRIPT. The dashboard stores a plan session's title, and until now it arrived only as the `title`
+ * argument of `plan_connect`, so a session renamed afterwards showed a stale name until the agent happened to connect
+ * again. DX-2816 found no env var, hook input or MCP-reachable signal carrying the title, but Claude Code writes every
+ * title change into the session's transcript as a `{"type":"custom-title","customTitle":"..."}` line the moment the
+ * rename happens, even while the session is idle (observed on session 952f0739: 76 records of the old title, then the
+ * renamed one, no turn in between). The bridge already holds the transcript path (the plugin passes the hook input's
+ * `transcript_path` as `DANX_BRIDGE_TRANSCRIPT_PATH`, `session-stats.ts`), so it reads the last such record on each
+ * heartbeat and reports it when it differs from the title the dashboard answered with (`bridge.ts`); the dashboard
+ * stores it (`plan-sessions-routes.ts`).
+ *
+ * INCREMENTAL, NEVER A RE-READ. The reader remembers how far it has scanned (always a line boundary) and the title it
+ * found, so a heartbeat reads only the bytes appended since the last one. The first read of a long transcript is
+ * bounded to its last {@link TRANSCRIPT_TITLE_MAX_SCAN_BYTES}: Claude Code repeats the record on every turn, so the
+ * latest one is always near the end, and a transcript with none in that window has nothing to report.
+ *
+ * It reads synchronously on purpose: the bridge's heartbeat tick is synchronous up to its first request, and a read
+ * of a few appended kilobytes every 15 seconds costs less than the plumbing an async read would need.
+ */
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+/**
+ * The longest title the dashboard accepts (`SESSION_TITLE_MAX_CHARS`, `src/issues/db/plan-sessions.ts`, counted in
+ * UTF-16 units). A longer one would 400 the whole heartbeat, which is liveness, so the reader cuts it first.
+ */
+export const SESSION_TITLE_MAX_CHARS = 200;
+/** How much of a transcript's end the first read looks at. */
+export const TRANSCRIPT_TITLE_MAX_SCAN_BYTES = 2 * 1024 * 1024;
+/** The marker of a title record. A message quoting it carries escaped quotes, so it never matches. */
+const TITLE_RECORD_MARKER = '"type":"custom-title"';
+export class TranscriptTitleReader {
+    path;
+    /** Offset just past the last complete line already scanned; always 0 or a line boundary. */
+    scannedTo = 0;
+    title = null;
+    constructor(path) {
+        this.path = path;
+    }
+    /**
+     * The session's current title, or `null` when its transcript has none (yet). Throws on a transcript this cannot
+     * read, or a complete title record that is not JSON: the caller decides what a failed read costs.
+     */
+    read() {
+        const fd = this.open();
+        if (fd === null)
+            return this.title;
+        try {
+            const size = fstatSync(fd).size;
+            if (size < this.scannedTo) {
+                // The file was rewritten shorter than what was already scanned; nothing remembered about it holds.
+                this.scannedTo = 0;
+                this.title = null;
+            }
+            if (size === this.scannedTo)
+                return this.title;
+            const start = Math.max(this.scannedTo, size - TRANSCRIPT_TITLE_MAX_SCAN_BYTES);
+            const buf = Buffer.alloc(size - start);
+            let filled = 0;
+            while (filled < buf.length) {
+                const n = readSync(fd, buf, filled, buf.length - filled, start + filled);
+                if (n === 0)
+                    break;
+                filled += n;
+            }
+            const lastNewline = buf.subarray(0, filled).lastIndexOf(0x0a);
+            if (lastNewline === -1)
+                return this.title;
+            const lines = buf.subarray(0, lastNewline).toString("utf8").split("\n");
+            // A region that starts mid-file (the first read of a long transcript) begins inside a line.
+            if (start !== this.scannedTo)
+                lines.shift();
+            this.scannedTo = start + lastNewline + 1;
+            for (let i = lines.length - 1; i >= 0; i--) {
+                if (!lines[i].includes(TITLE_RECORD_MARKER))
+                    continue;
+                this.title = parseTitleRecord(lines[i], this.path);
+                break;
+            }
+            return this.title;
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    /** The transcript's descriptor, or `null` when it does not exist yet (Claude Code creates it on the first turn). */
+    open() {
+        try {
+            return openSync(this.path, "r");
+        }
+        catch (err) {
+            if (err.code === "ENOENT")
+                return null;
+            throw err;
+        }
+    }
+}
+function parseTitleRecord(line, path) {
+    let record;
+    try {
+        record = JSON.parse(line);
+    }
+    catch (err) {
+        throw new Error(`a custom-title line in ${path} is not JSON: ${err.message}`);
+    }
+    const customTitle = record?.customTitle;
+    if (typeof customTitle !== "string")
+        return null;
+    const trimmed = customTitle.trim();
+    return trimmed === "" ? null : boundTitle(trimmed);
+}
+/**
+ * At most {@link SESSION_TITLE_MAX_CHARS} UTF-16 units, cut on a code-point boundary. A cut that lands after a space is
+ * trimmed again: the dashboard stores the trimmed title, so an untrimmed one would never equal it and the bridge would
+ * resend it on every heartbeat.
+ */
+function boundTitle(title) {
+    if (title.length <= SESSION_TITLE_MAX_CHARS)
+        return title;
+    let out = "";
+    for (const point of title) {
+        if (out.length + point.length > SESSION_TITLE_MAX_CHARS)
+            break;
+        out += point;
+    }
+    return out.trimEnd();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.227",
+  "version": "0.1.229",
   "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",