@thehammer/danx-dashboard-mcp 0.1.188 → 0.1.190

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
@@ -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/index.js

@@ -422,7 +422,7 @@ strictTool("attach_file", "Attach a LOCAL file to a card: `card_id` + `path` (an
 // no existing plan for an id to name yet.
 strictTool("plan_connect", 
 // DX-2735: trimmed with the problem tools to stay inside the work-profile budget.
-"Connect THIS session to a plan. ONE CALL IS ENOUGH TO START: the reply carries `{session, movedFrom, browserInstruction, briefing, listenerHealth}` — `browserInstruction` is a server-built action to take NOW: it names the plan's URL and tells you to open it (in-app browser if you have one, else default), keep that tab open for the whole session without navigating it away, and use a different tab for your own browsing — the operator's tab for following and talking to you. Returned on every connect, including a re-connect, so it doubles as the post-context-loss reminder. `briefing` is every goal/rule/caveat (ref+body), every architecture section (id+title), the plan's own ref/name/status, a first page of open cards (id/type/status/title/openProblemCount/assignedAgent) with a `morePagesHint` when more exist, and the closed-card count — usually replacing the plan read + card batch-read a fresh session used to need. A session is on AT MOST ONE plan: connecting elsewhere MOVES it, and `movedFrom: {id, name} | null` says which plan it left (null = no plan, or already this one). Binds only your OWN session, resolved from the session id this server forwards; afterwards a `danxbot_api` call to a `/api/plans/mine/...` route (there is no dedicated plan-write tool) acts on this plan and takes no plan id. `listenerHealth` reports the event bridge's state — `null` (no session), or `{attached, state: \"unattached\"|\"credential_mismatch\"|\"healthy\", nextStep}` naming a concrete fix per unhealthy state (same shape the plan list/get routes report). Once healthy, every comment, answer, problem added and block/unblock on this plan's cards reaches the session unpolled, relayed by the plugin's event bridge as a line like `[DX-8 \"Title\" repo:board] newms87 answered \"<statement>\": chose \"Pause E2E\"`. Pass `title` (call `get_session({session_id:\"self\"})` first and forward its `title` verbatim) so the dashboard shows the same name Claude does — this server cannot read it itself. The response's `reminders[]` (when present) carries the mantra — read and follow it.", {
+"Connect THIS session to a plan. ONE CALL IS ENOUGH TO START: the reply carries `{session, movedFrom, browserInstruction, briefing, listenerHealth}` — `browserInstruction` is a server-built action to take NOW: it names the plan's URL and tells you to open it (in-app browser if you have one, else default), keep that tab open for the whole session without navigating it away, and use a different tab for your own browsing — the operator's tab for following and talking to you. Returned on every connect, including a re-connect, so it doubles as the post-context-loss reminder. `briefing` is every goal/rule/caveat (ref+body), every architecture section (id+title), the plan's own ref/name/status, a first page of open cards (id/type/status/title/openProblemCount/assignedAgent) with a `morePagesHint` when more exist, and the closed-card count — usually replacing the plan read + card batch-read a fresh session used to need. A session is on AT MOST ONE plan: connecting elsewhere MOVES it, and `movedFrom: {id, name} | null` says which plan it left (null = no plan, or already this one). Binds only your OWN session, resolved from the session id this server forwards; afterwards a `danxbot_api` call to a `/api/plans/mine/...` route (there is no dedicated plan-write tool) acts on this plan and takes no plan id. `listenerHealth` reports the event bridge's state — `null` (no session), or `{attached, state: \"unattached\"|\"credential_mismatch\"|\"healthy\", nextStep}` naming a concrete fix per unhealthy state (same shape the plan list/get routes report). Once healthy, every comment, answer, problem added and block/unblock on this plan's cards reaches the session unpolled, relayed by the plugin's event bridge as a line like `[DX-8 \"Title\" repo:board] newms87 answered \"<statement>\": chose \"Pause E2E\"`. An action the operator DECLINES arrives as `... rejected the action \"<title>\" for \"<statement>\" — reason: \"<note>\". Do not perform it; re-plan from the reason` (a decision with `outcome: \"rejected\"` — never treat it as work done). Pass `title` (call `get_session({session_id:\"self\"})` first and forward its `title` verbatim) so the dashboard shows the same name Claude does — this server cannot read it itself. The response's `reminders[]` (when present) carries the mantra — read and follow it.", {
     plan_id: z.number().int().positive().describe("The plan id, from the plans list (`danxbot_api` `GET /api/plans`)."),
     title: z
         .string()

package/dist/listen.js

@@ -78,6 +78,27 @@ function isRecord(value) {
 function isCappedText(value) {
     return isRecord(value) && typeof value.text === "string" && typeof value.truncated === "boolean";
 }
+/**
+ * DX-3880 — the part `solution_answered` and `problem_answer_changed` share: the
+ * decision's `outcome` and the either/or body it implies. A rejection (the
+ * operator DECLINED an action) always names the solution and carries its reason
+ * as `solution.note`; an answer is a solution (optional note) or free-form text.
+ */
+function invalidDecisionBody(d) {
+    if (d.outcome !== "answered" && d.outcome !== "rejected")
+        return 'detail.outcome is not "answered" or "rejected"';
+    if (d.solution === null) {
+        if (d.outcome === "rejected")
+            return "detail.solution is null on a rejection";
+        return isCappedText(d.freeform) ? null : "detail.freeform is not capped text";
+    }
+    if (!isRecord(d.solution) || typeof d.solution.title !== "string")
+        return "detail.solution is not {title, note}";
+    if (d.outcome === "rejected") {
+        return isCappedText(d.solution.note) ? null : "detail.solution.note (the rejection reason) is not capped text";
+    }
+    return d.solution.note === null || isCappedText(d.solution.note) ? null : "detail.solution.note is not capped text";
+}
 /**
  * DX-2735 — why an event cannot be described, or `null` when it can.
  *
@@ -122,11 +143,7 @@ export function invalidEventReason(value) {
             if (!isRecord(problem) || typeof problem.id !== "number" || !isCappedText(problem.statement)) {
                 return "detail.problem is not {id, statement}";
             }
-            if (d.solution === null)
-                return isCappedText(d.freeform) ? null : "detail.freeform is not capped text";
-            if (!isRecord(d.solution) || typeof d.solution.title !== "string")
-                return "detail.solution is not {title, note}";
-            return d.solution.note === null || isCappedText(d.solution.note) ? null : "detail.solution.note is not capped text";
+            return invalidDecisionBody(d);
         }
         case "problem_added": {
             const problem = d.problem;
@@ -155,11 +172,7 @@ export function invalidEventReason(value) {
                 return "detail.retracted_decision_id is not a number";
             if (typeof d.decision_id !== "number")
                 return "detail.decision_id is not a number";
-            if (d.solution === null)
-                return isCappedText(d.freeform) ? null : "detail.freeform is not capped text";
-            if (!isRecord(d.solution) || typeof d.solution.title !== "string")
-                return "detail.solution is not {title, note}";
-            return d.solution.note === null || isCappedText(d.solution.note) ? null : "detail.solution.note is not capped text";
+            return invalidDecisionBody(d);
         }
         case "blocked":
             return isCappedText(d.reason) ? null : "detail.reason is not capped text";
@@ -196,8 +209,13 @@ function describe(event) {
             // so the line names the problem — otherwise the agent cannot tell which of its
             // questions just closed.
             const problem = d.problem;
-            const answered = `${who} answered ${quoted(problem.statement)}:`;
             const solution = d.solution;
+            // DX-3880 — a REJECTION is the opposite of work done: the operator declined
+            // the action, so the line says so and names the reason; the agent must not
+            // perform it and re-plans from the note.
+            if (d.outcome === "rejected")
+                return `${who} rejected the action "${solution.title}" for ${quoted(problem.statement)} — reason: ${quoted(solution.note)}. Do not perform it; re-plan from the reason`;
+            const answered = `${who} answered ${quoted(problem.statement)}:`;
             if (solution === null)
                 return `${answered} ${quoted(d.freeform)}`;
             const note = solution.note === null ? "" : ` — note: ${quoted(solution.note)}`;
@@ -222,6 +240,8 @@ function describe(event) {
             // open questions knows which one just moved.
             const problem = d.problem;
             const solution = d.solution;
+            if (d.outcome === "rejected")
+                return `${who} changed the answer to ${quoted(problem.statement)}: now REJECTED the action "${solution.title}" — reason: ${quoted(solution.note)}. Do not perform it; re-plan from the reason`;
             const now = solution === null ? quoted(d.freeform) : `"${solution.title}"`;
             return `${who} changed the answer to ${quoted(problem.statement)}: now ${now}`;
         }

package/package.json

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