@thehammer/danx-dashboard-mcp 0.1.189 → 0.1.192

package/README.md

@@ -9,7 +9,7 @@ Stdio MCP server fronting danxbot's dashboard HTTP API. Since DX-3465 it exposes
 | Var | Purpose |
 |---|---|
 | `DANXBOT_DASHBOARD_URL` | Dashboard base, e.g. `http://danxbot-dashboard:5555` (inside compose) or `http://localhost:5555` (host) |
-| `DANXBOT_DASHBOARD_TOKEN_FILE` **or** `DANXBOT_DISPATCH_TOKEN` | The credential, declared exactly one of two ways (DX-2862, `src/credential.ts`). A FILE holding the bearer (a leading `~` is the user's home) — how an interactive operator session declares one, since its `.mcp.json` is git-tracked and can never carry the token itself. Or the bearer VERBATIM — how a dispatch declares one, substituted from its overlay. A declared file is AUTHORITATIVE and its failure is FATAL: an inherited `DANXBOT_DISPATCH_TOKEN` is never consulted instead, because on an operator machine that value routinely names a different (local-dev) dashboard, which answers healthily and empty. The same resolver serves the `bridge` subcommand below, so a session's tools and its event stream can never sign in as two different identities |
+| `DANXBOT_DASHBOARD_TOKEN_FILE` **or** `DANX_DASHBOARD_CREDENTIAL` | The credential, declared exactly one of two ways (DX-2862, `src/credential.ts`). A FILE holding the bearer (a leading `~` is the user's home) — how an interactive operator session declares one, since its `.mcp.json` is git-tracked and can never carry the token itself. Or the bearer VERBATIM — how a dispatch declares one, substituted from its overlay. A declared file is AUTHORITATIVE and its failure is FATAL: an inherited `DANX_DASHBOARD_CREDENTIAL` is never consulted instead, because on an operator machine that value routinely names a different (local-dev) dashboard, which answers healthily and empty. The same resolver serves the `bridge` subcommand below, so a session's tools and its event stream can never sign in as two different identities |
 | `DANX_REPO_NAME` | Repo half of the qualified board id |
 | `DANXBOT_BOARD_NAME` | Board-slug half of the qualified board id (the dispatch injects `board.slug` here) |
 
@@ -39,7 +39,7 @@ A program runs this, not an agent: the danxbot Claude Code plugin's plan event b
 CLAUDE_CODE_SESSION_ID=<session> npx -y @thehammer/danx-dashboard-mcp@<version> bridge [--resume-ids <id>,<id>,...]
 ```
 
-- **Credential — the session's own, never the ambient one (DX-2862).** The session id is the only thing `bridge` takes from its environment; `--resume-ids` is the only argument and holds no secret. Everything else comes from the connection record this session's own danx-dashboard MCP server wrote on `plan_connect` (`src/session-connection.ts`): the dashboard URL, the credential's SOURCE, and its FINGERPRINT. `bridge` resolves that source through the same resolver the server used and refuses to run unless the result fingerprints identically — `credential_mismatch`. Before that fix it used whatever `DANXBOT_DISPATCH_TOKEN` the session's environment held, and on a machine where that differed from the server's credential the dashboard admitted the stream and dropped every event, with nothing logged anywhere.
+- **Credential — the session's own, never the ambient one (DX-2862).** The session id is the only thing `bridge` takes from its environment; `--resume-ids` is the only argument and holds no secret. Everything else comes from the connection record this session's own danx-dashboard MCP server wrote on `plan_connect` (`src/session-connection.ts`): the dashboard URL, the credential's SOURCE, and its FINGERPRINT. `bridge` resolves that source through the same resolver the server used and refuses to run unless the result fingerprints identically — `credential_mismatch`. Before that fix it used whatever `DANX_DASHBOARD_CREDENTIAL` the session's environment held, and on a machine where that differed from the server's credential the dashboard admitted the stream and dropped every event, with nothing logged anywhere.
 - **No client-side reach check (DX-2920).** `bridge` used to prove board reach itself, before ever opening the stream (`GET /api/plans/mine?fields=cards` + a per-board `GET /api/issues/:id/problems`). That check is DELETED. The dashboard briefly enforced the identical requirement server-side (DX-2863: refusing a mint or stream admission with `403 issuer_cannot_read_plan_boards`, and ending a live stream `{"reason":"scope_narrowed","boards":[…]}`), but DX-3468 removed that mechanism too — DX-3409 made every credential team-bound, so a plan session's issuer and every board its connected plan covers are always in the same team, and the check could never fire any more. `bridge` no longer independently verifies board reach at all, client- or server-side. Once a ticket is minted, `bridge` emits, once, `{"type":"ready"}` — no `boards` field, since reach is no longer proven client-side.
 - **Ticket.** `bridge` mints the session's listener ticket (`POST /api/plan-sessions/me/stream-ticket`, 10 s timeout) and keeps it in the process. A ticket authorizes reading that one session's event stream and nothing else, and is only issued while the session is connected to a plan. Minting a new one ends the previous listener.
 - **Output — JSON Lines.** One `{"type":"event","id":<id|null>,"text":"…"}` per event on the connected plan's cards, where `text` is `[DX-8 "Title" repo:board] newms87 answered "Which rollout order?": chose "Pause E2E" — note: "only this week"`, `… answered "…": "<free-form answer>"`, `… commented: "…"`, `… opened a problem: "…"`, `… blocked the card: "…"`, or `… unblocked the card`. An event it cannot read still produces one, with a `could not read event` text. Nothing for keep-alives, reconnects or re-mints. The session's own writes are never echoed back to it.

package/dist/bridge.js

@@ -34,7 +34,7 @@
  *   5. Streams through `runListener` (`listen.ts`), which reconnects within the
  *      ticket, and re-mints when that ticket's lease runs out or a fresh ticket
  *      is refused once.
- *   6. Writes JSON Lines to stdout: ONE `{type:"ready", boards, cardCount, degraded}`
+ *   6. Writes JSON Lines to stdout: ONE `{type:"ready", boards, cardCount, degraded, inventoryError}`
  *      once a ticket has been minted and streaming is about to start —
  *      DX-2970's `fetchPlanInventory`, a single BEST-EFFORT (never a gate)
  *      read of the connected plan's real board/card counts, purely so a
@@ -140,6 +140,13 @@ function formatDigest(entries) {
     return [header, ...entries.map((e) => e.text)].join("\n");
 }
 export const BRIDGE_SUBCOMMAND = "bridge";
+/**
+ * DX-3912 — the longest heartbeat `reason` the bridge sends: one under the dashboard's own
+ * limit (`HEARTBEAT_REASON_MAX_CHARS` = 200, `src/issues/db/plan-session-heartbeat.ts`),
+ * because `oneLine` appends a "…" to a truncated string and a longer reason refuses the whole
+ * heartbeat. `bridge.test.ts` asserts the cap.
+ */
+const HEARTBEAT_REASON_MAX_CODE_POINTS = 199;
 export const STREAM_TICKET_PATH = "/api/plan-sessions/me/stream-ticket";
 // DX-2970 — the bare (no `fields=`) cheap-scalars read, used ONLY to report the
 // connected plan's real `boards`/`cardCount` on the `ready` record (see
@@ -276,7 +283,7 @@ export class BridgeStartError extends Error {
 /**
  * The session's connection, as its own MCP server recorded it — and the proof
  * that this process holds the SAME credential that server does. Never falls back
- * to an ambient `DANXBOT_DISPATCH_TOKEN`: that fallback is precisely DX-2862.
+ * to an ambient env credential: that fallback is precisely DX-2862.
  */
 const INSTANCE_ID_ENV = "DANX_BRIDGE_INSTANCE_ID";
 /**
@@ -449,15 +456,29 @@ export async function mintTicket(options, deps) {
         leaseMs: ticket.leaseMs,
     };
 }
-/** What is wrong with a 2xx bare `/api/plans/mine` body, or `null` when it carries a usable inventory. */
+/**
+ * What is wrong with a 2xx bare `/api/plans/mine` body, or `null` when it carries a usable inventory.
+ *
+ * DX-3912 — the field names here are the plan resource's WIRE names (`boards`, `card_count`,
+ * snake_case since DX-3428), the same ones `src/resources/plan/plan-resource.ts` emits; the
+ * contract test `src/issues/__tests__/plan-inventory-bridge-contract.test.ts` runs this parser
+ * on the server's own response, so a rename there fails that test instead of silently
+ * degrading every bridge. A missing field lists the keys the body DID carry, so a rename is
+ * named in the first message anyone reads.
+ */
 function badInventoryReason(body) {
-    if (typeof body !== "object" || body === null)
+    if (!isRecord(body))
         return "the body is not a JSON object";
-    const b = body;
-    if (!Array.isArray(b.boards) || b.boards.some((x) => typeof x !== "string"))
-        return "boards is not a string array";
-    if (typeof b.cardCount !== "number" || !Number.isSafeInteger(b.cardCount) || b.cardCount < 0) {
-        return "cardCount is not a non-negative integer";
+    if (!("boards" in body))
+        return `boards is missing (response keys: ${Object.keys(body).join(", ")})`;
+    if (!Array.isArray(body.boards) || body.boards.some((x) => typeof x !== "string")) {
+        return "boards is not an array of strings";
+    }
+    if (!("card_count" in body))
+        return `card_count is missing (response keys: ${Object.keys(body).join(", ")})`;
+    const count = body.card_count;
+    if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0) {
+        return `card_count is not a non-negative integer (got ${typeof count === "number" ? count : typeof count})`;
     }
     return null;
 }
@@ -485,7 +506,7 @@ export async function fetchPlanInventory(options, deps) {
         return { kind: "unavailable", detail: `plan inventory read HTTP ${status}: ${bad}` };
     }
     const b = body;
-    return { kind: "ok", boards: b.boards, cardCount: b.cardCount };
+    return { kind: "ok", boards: b.boards, cardCount: b.card_count };
 }
 /**
  * DX-2920 — a stream admission refusal (`listen.ts`'s STRUCTURED `refused`
@@ -604,7 +625,8 @@ export async function runBridge(options, deps) {
     let connectionState = "reconnecting";
     let stoppedReason = null;
     let heartbeatSuppressed = false;
-    let lastInventoryOk = true;
+    // DX-3912 — `null` is "the inventory read succeeded"; a string is why it did not.
+    let lastInventoryError = null;
     // DX-3099 — consecutive heartbeat POSTs that failed to LAND while this
     // process still believed `connectionState === "streaming"`. Reset to 0 the
     // moment a heartbeat lands, or the moment state leaves "streaming" for any
@@ -619,7 +641,9 @@ export async function runBridge(options, deps) {
     // 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" }
+        ? lastInventoryError === null
+            ? { state: "streaming", inventory: "ok" }
+            : { state: "streaming", inventory: "unavailable", reason: oneLine(lastInventoryError, HEARTBEAT_REASON_MAX_CODE_POINTS) }
         : connectionState === "stopped"
             ? { state: "stopped", reason: stoppedReason ?? undefined }
             : { state: "reconnecting" };
@@ -822,23 +846,24 @@ export async function runBridge(options, deps) {
             readyEmitted = true;
             const inventory = await fetchPlanInventory(options, deps);
             // DX-3028 (AC1, code-review + architecture-review finding) — this is
-            // the ONE place `lastInventoryOk` is ever written; the 15s heartbeat
+            // the ONE place `lastInventoryError` is ever written; the 15s heartbeat
             // reads it on every "streaming" tick (see `heartbeatTick` above). Must
             // agree with the SAME `ready` record's own `degraded` decision below —
             // a heartbeat reporting `inventory:"ok"` while the `ready` record just
             // told the operator `degraded:true` would be exactly the untruthful
             // state AC1 exists to prevent.
-            lastInventoryOk = inventory.kind === "ok";
+            lastInventoryError = inventory.kind === "ok" ? null : inventory.detail;
             if (inventory.kind === "ok") {
                 deps.write({
                     type: "ready",
                     boards: inventory.boards,
                     cardCount: inventory.cardCount,
                     degraded: inventory.boards.length === 0 || inventory.cardCount === 0,
+                    inventoryError: null,
                 });
             }
             else {
-                deps.write({ type: "ready", boards: null, cardCount: null, degraded: true });
+                deps.write({ type: "ready", boards: null, cardCount: null, degraded: true, inventoryError: inventory.detail });
             }
         }
         backoff = MINT_INITIAL_BACKOFF_MS;

package/dist/credential.js

@@ -6,7 +6,7 @@
  * and `danx-dashboard-mcp bridge` (the session's event stream, run by the
  * danxbot plugin's plan event bridge). Before this module they resolved their
  * credential independently — the server through danxbot's operator launcher,
- * which read a token file, and the bridge from whatever `DANXBOT_DISPATCH_TOKEN`
+ * which read a token file, and the bridge from whatever credential variable
  * happened to be in the session's environment. On a machine where those two
  * differ (DX-2862: `ffe9f8a882f0…` in the environment, `6f9bc6e94b83…` in
  * `~/.config/danxbot/dashboard-token-gpt`) the session's tools worked, the
@@ -21,15 +21,15 @@
  *     home). The file's trimmed contents are the credential. This is how an
  *     interactive operator session declares one, because its `.mcp.json` is
  *     git-tracked and can never carry the bearer itself.
- *   - `DANXBOT_DISPATCH_TOKEN` — the credential verbatim. This is how a
+ *   - `DANX_DASHBOARD_CREDENTIAL` — the credential verbatim. This is how a
  *     DISPATCH declares one: the worker substitutes it into the materialized
  *     `.mcp.json` from the dispatch overlay.
  *
  * A DECLARED FILE IS AUTHORITATIVE, AND ITS FAILURE IS FATAL. When the file
- * variable is set, `DANXBOT_DISPATCH_TOKEN` is never consulted — not even when
+ * variable is set, `DANX_DASHBOARD_CREDENTIAL` is never consulted — not even when
  * the file is missing or empty. That is the DX-2483 rule, moved here from the
  * launcher it used to live in: an operator machine routinely carries an
- * inherited `DANXBOT_DISPATCH_TOKEN` naming the LOCAL dev dashboard, which
+ * inherited env credential naming the LOCAL dev dashboard, which
  * answers healthily and empty for a board it does not carry, so preferring it
  * after a failed file read would turn a loud, fixable error into exactly the
  * silent wrong-dashboard answer this whole module exists to prevent.
@@ -39,7 +39,7 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 export const CREDENTIAL_FILE_ENV = "DANXBOT_DASHBOARD_TOKEN_FILE";
-export const CREDENTIAL_TOKEN_ENV = "DANXBOT_DISPATCH_TOKEN";
+export const CREDENTIAL_TOKEN_ENV = "DANX_DASHBOARD_CREDENTIAL";
 /**
  * A credential that cannot be resolved. Carries the remedy beside the reason,
  * because both of this module's callers report failures to a human who is not

package/dist/handlers.js

@@ -81,7 +81,7 @@ export function isDanxbotApiMethod(value) {
  *
  * The credential lives inside `client` (resolved once at boot — the
  * operator's declared token file for a session, the per-dispatch
- * `DANXBOT_DISPATCH_TOKEN` for a worker) and never appears in this
+ * `DANX_DASHBOARD_CREDENTIAL` for a worker) and never appears in this
  * function's arguments or return value — nothing in `DanxbotApiArgs` can
  * carry one. The session id (`x-danx-session-id`) rides every call the SAME
  * way it already does for every other tool on this server

package/dist/index.js

@@ -55,8 +55,8 @@
  *                           session, whose `.mcp.json` is git-tracked and so
  *                           can never carry one); authoritative when set, and
  *                           its failure is fatal — an inherited
- *                           DANXBOT_DISPATCH_TOKEN is never consulted instead
- *     DANXBOT_DISPATCH_TOKEN  the bearer verbatim (a dispatch, substituted into
+ *                           DANX_DASHBOARD_CREDENTIAL is never consulted instead
+ *     DANX_DASHBOARD_CREDENTIAL  the bearer verbatim (a dispatch, substituted into
  *                           the materialized `.mcp.json` from its overlay)
  *   DANX_REPO_NAME          repo half of the qualified board id
  *   DANXBOT_BOARD_NAME      board-slug half of the qualified board id
@@ -466,7 +466,7 @@ async function main() {
 // the dashboard URL, credential source, and credential itself come from the
 // session-connection record this server's own `plan_connect` wrote
 // (`session-connection.ts`), never from the bridge's own environment
-// (DX-2862: a bridge trusting its own ambient `DANXBOT_DISPATCH_TOKEN` is the
+// (DX-2862: a bridge trusting its own ambient env credential is the
 // exact bug this repo fixed).
 //
 // Any OTHER argument is refused rather than ignored, so a typo cannot

package/dist/session-connection.js

@@ -6,7 +6,7 @@
  * in the SESSION's environment — not in the MCP server's, which is the only
  * place the server's `.mcp.json` env block exists. So the bridge cannot see
  * what the server was configured with, and before this it simply used its own
- * ambient `DANXBOT_DISPATCH_TOKEN`. When that was a different credential from
+ * ambient env credential. When that was a different credential from
  * the server's, every event was dropped silently (the card's incident).
  *
  * WHAT IS WRITTEN, AND WHAT IS NOT. On a successful `plan_connect` the server

package/package.json

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