@thehammer/danx-dashboard-mcp 0.1.226 → 0.1.228

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,38 @@ 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. Until an answer carries a title (an older dashboard
+    // never does) nothing is sent, since that 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.title !== null)
+                dashboardTitle = answer.title;
             // 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

@@ -87,6 +87,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { DashboardHttpClient } from "./http-client.js";
 import { planConnect, danxbotApi, danxbotApiList, danxbotApiSpec, attachFile, DANXBOT_API_METHODS, } from "./handlers.js";
+import { boundedResultText } from "./result-limit.js";
 import { bodyValueSchema, queryValueSchema } from "./types.js";
 import { termsAcceptanceCallHalt, termsHaltFor } from "./terms-halt.js";
 import { danxbotApiExamplesText } from "./danxbot-api-examples.js";
@@ -220,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");
@@ -283,18 +288,28 @@ function accessReply(ready, note) {
     if (ready.halt !== undefined)
         return haltResult(ready.halt);
     const answer = note ? { ...ready.answer, note } : ready.answer;
-    return ready.isError ? haltResult(JSON.stringify(answer, null, 2)) : jsonResult(answer);
+    return ready.isError ? haltResult(JSON.stringify(answer)) : jsonResult(answer);
 }
 /** DX-4390 — a tool's dashboard call behind the sign-in halt (and the 401 sign-out). */
 async function guardedJson(run) {
     const guarded = await access.guard(run);
     return "halt" in guarded ? haltResult(guarded.halt) : jsonResult(guarded.result);
 }
+/** DX-4400 — `guardedJson` for the read tools whose answer can be a whole document: bounded. */
+async function guardedBoundedJson(run) {
+    const guarded = await access.guard(run);
+    return "halt" in guarded ? haltResult(guarded.halt) : boundedJsonResult(guarded.result);
+}
 function jsonResult(value) {
     return {
-        content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+        // DX-4400: compact — nothing parses the indentation and it costs every call 16% to 55% more characters.
+        content: [{ type: "text", text: JSON.stringify(value) }],
     };
 }
+/** DX-4400 — a dashboard route's result, refused with the way to narrow it when over `MCP_MAX_RESULT_CHARS`. */
+function boundedJsonResult(result) {
+    return { content: [{ type: "text", text: boundedResultText(result) }] };
+}
 /**
  * DX-3238 — every tool on this server MUST reject an undeclared/mistyped
  * argument instead of silently stripping it. `server.tool(name, description,
@@ -407,14 +422,14 @@ async (args) => {
     const halt = termsHaltFor(result);
     if (halt)
         return haltResult(halt);
-    return jsonResult(await listenerReminder.apply(result));
+    return boundedJsonResult(await listenerReminder.apply(result));
 });
 // ---------------- danxbot_api_list (DX-3465 A5, PLN-11 R-25) ----------------
 strictTool("danxbot_api_list", 
 // DX-3528 — the list is filtered by the same permission check every request takes.
 "Lists the dashboard API routes your credential may call: `[{method, path, summary, permission}]`, each " +
     "`path` a route template (`/api/issues/:id/transition`), the form `danxbot_api_spec` takes. A route not " +
-    "listed is not callable by you.", {}, async () => guardedJson(() => danxbotApiList(client)));
+    "listed is not callable by you.", {}, async () => guardedBoundedJson(() => danxbotApiList(client)));
 // ---------------- danxbot_api_spec (DX-3465, PLN-11 R-25) ----------------
 strictTool("danxbot_api_spec", 
 // DX-3527 — the contract is generated from the route table.
@@ -423,7 +438,7 @@ strictTool("danxbot_api_spec",
     '(e.g. `"POST /api/issues/:id/transition"`), never a real path with ids. An endpoint the dashboard does ' +
     "not serve, or your credential may not call, is refused and named.", {
     endpoints: z.array(z.string().min(1)).min(1),
-}, async (args) => guardedJson(() => danxbotApiSpec(client, args)));
+}, async (args) => guardedBoundedJson(() => danxbotApiSpec(client, args)));
 // ---------------- attach_file (DX-3465 A4, checklist item 36140) ----------------
 //
 // The "25 MB" ceiling quoted below tracks the backend route's

package/dist/result-limit.js

@@ -0,0 +1,25 @@
+/**
+ * DX-4400 — the most characters one `danxbot_api`, `danxbot_api_spec` or `danxbot_api_list` result may carry
+ * back to the agent. Every character is context the agent pays for on every later call, and Claude Code itself
+ * saves a larger result to a file with no hint how to narrow, after the cost is paid. A deliberate, narrow
+ * exception to PLAN-11 rule R-25 (verbatim forwarding): `plan_connect` and the lifecycle tools never pass here.
+ */
+export const MCP_MAX_RESULT_CHARS = 100_000;
+/** A runtime result text, not a tool description: the DX-4318 text limit does not apply to it. */
+const HOW_TO_NARROW = "Ask for less: `limit` and `offset` page a collection, `fields` names only the columns or relations you need, " +
+    "`filter` and `since` (epoch milliseconds) select rows. Then repeat the call.";
+/**
+ * The text the agent receives for `result`: its compact JSON when that fits `MCP_MAX_RESULT_CHARS`, otherwise
+ * `{ok, status, body_omitted:{chars, limit, how_to_narrow}}`. Never truncates, never forwards a part. `ok`
+ * and `status` stay so a write that already committed is still reported as committed.
+ */
+export function boundedResultText(result) {
+    const text = JSON.stringify(result);
+    if (text.length <= MCP_MAX_RESULT_CHARS)
+        return text;
+    return JSON.stringify({
+        ok: result.ok,
+        status: result.status,
+        body_omitted: { chars: text.length, limit: MCP_MAX_RESULT_CHARS, how_to_narrow: HOW_TO_NARROW },
+    });
+}

package/dist/session-title.js

@@ -0,0 +1,123 @@
+/**
+ * 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. */
+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;
+}

package/package.json

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