@thehammer/danx-dashboard-mcp 0.1.193 → 0.1.194

package/README.md

@@ -21,7 +21,7 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 
 | Tool | Purpose |
 |---|---|
-| `danxbot_api` | `{method, path, query?, body?}` — calls any dashboard route the caller's credential may reach (card/plan CRUD, comments, dependencies, problems/solutions, quality gates, retro, triage, transitions, …). Returns `{ok, status, body}`; `body` carries the route's own response, or its structured error verbatim when `ok:false`. |
+| `danxbot_api` | `{method, path, query?, body?}` — calls any dashboard route the caller's credential may reach (card/plan CRUD, comments, dependencies, problems/solutions, quality gates, retro, triage, transitions, …). Returns `{ok, status, body}`; `body` carries the route's own response, or its structured error verbatim when `ok:false`. While this session is plan-connected, the dashboard's own reminders for it (today: `plan_list.listener_unattached`, attached by the server to `GET /api/plans` when the event listener is unattached past the startup grace, DX-3997) are relayed into the body's `reminders[]`; the MCP carries no reminder text or state of its own and re-reads at most every 30s. |
 | `danxbot_api_list` | No args. Lists the routes this caller's credential may reach, one line each (`{method, path, summary, permission}`) — call this first when you don't know the route for what you need to do. |
 | `danxbot_api_spec` | `{endpoints}` (comma-joined `METHOD /path` list, required, min 1). Returns the exact OpenAPI contract for those routes — call this when you know the route but not its exact request/response shape. |
 

package/dist/index.js

@@ -79,6 +79,7 @@ import { ACTIVITY_SUBCOMMAND, runActivityCommand } from "./activity.js";
 import { EVENT_TEXT_SUBCOMMAND, runEventTextCommand } from "./event-text.js";
 import { resolveDeclaredCredential } from "./credential.js";
 import { recordSessionConnectionAfterConnect } from "./session-connection.js";
+import { createListenerReminder, isPlanConnectedOnThisMachine, } from "./listener-reminder.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -114,6 +115,8 @@ function readEnvOptional(name) {
 // while a real run still fails loud on missing env via `boot()`.
 let config;
 let client;
+// DX-3997 — late-bound with `client`; see `listener-reminder.ts`.
+let listenerReminder;
 /**
  * DX-2862 — what this server would tell the session's plan event bridge about
  * how to reach the dashboard AS THIS SERVER: the URL, where the credential came
@@ -147,6 +150,14 @@ function boot() {
         fingerprint: credential.fingerprint,
     };
     client = new DashboardHttpClient(config);
+    const dashboardClient = client;
+    listenerReminder = createListenerReminder({
+        sessionId: config.session?.id,
+        fetchHealth: () => dashboardClient.request({ method: "GET", basePath: "", path: "/api/plans", query: { limit: 1 } }),
+        isPlanConnected: isPlanConnectedOnThisMachine,
+        now: Date.now,
+        logLine: (line) => console.error(line),
+    });
     // DX-3465 (PLN-11 R-25) — the lifecycle tool set's per-tool visibility is
     // per-dispatch, not static: a tool whose callback URL wasn't injected for
     // THIS dispatch must not even be advertised (mirrors the old standalone
@@ -330,7 +341,8 @@ const boardField = {
 strictTool("danxbot_api", "Call any dashboard API route your credential may reach. `method` + `path` (a FULL path, e.g. " +
     '"/api/issues/DX-1/transition" — substitute real ids yourself, never a route template with `:id` in it) + ' +
     "optional `query`/`body`. The response is the route's JSON body verbatim, `reminders[]` included when the " +
-    "route attaches one. `board` overrides this dispatch's configured board for a board-scoped route only " +
+    "route attaches one — a plan-connected session whose event listener the dashboard reports unattached also gets " +
+    "the dashboard's own `plan_list.listener_unattached` reminder relayed there (DX-3997). `board` overrides this dispatch's configured board for a board-scoped route only " +
     "(ignored by a route that isn't board-scoped). See this server's own instructions (shown once, at connect) " +
     "for the shared resource shape, the stale-hash rule, and how to read a refusal — don't know the route? call " +
     "`danxbot_api_list` first; unsure of its exact shape? call `danxbot_api_spec` first. " +
@@ -364,7 +376,10 @@ strictTool("danxbot_api", "Call any dashboard API route your credential may reac
     // instead of reaching the dashboard malformed.
     body: bodyValueSchema.optional(),
     ...boardField,
-}, async (args) => jsonResult(await danxbotApi(client, args)));
+}, 
+// DX-3997 — the result rides back verbatim, plus the dashboard's own `reminders[]` entries
+// for this plan-connected session (the server decides; `listener-reminder.ts` only relays).
+async (args) => jsonResult(await listenerReminder.apply(await danxbotApi(client, args))));
 // ---------------- danxbot_api_list (DX-3465 A5, PLN-11 R-25) ----------------
 strictTool("danxbot_api_list", "Lists the dashboard API routes your credential may call right now — `[{method, path, summary, permission}]`, " +
     "one line each, in the route TEMPLATE form `danxbot_api_spec` also expects (e.g. " +
@@ -441,6 +456,8 @@ strictTool("plan_connect",
 // whose credential the stream must be minted with.
 async (args) => {
     const result = await planConnect(client, args);
+    // DX-3997 — a (re)connect restarts the bridge; the next `danxbot_api` must re-read health.
+    listenerReminder.invalidate();
     return jsonResult({
         ...result,
         ...recordSessionConnectionAfterConnect(result, {

package/dist/listener-reminder.js

@@ -0,0 +1,119 @@
+import { readSessionConnection } from "./session-connection.js";
+/** DX-3997 — how long one health read serves every response; per server process. */
+export const HEALTH_CACHE_WINDOW_MS = 30_000;
+function isReminder(value) {
+    const r = value;
+    return typeof r === "object" && r !== null && typeof r.key === "string" && typeof r.text === "string";
+}
+/** The reminders the health response carries, or a thrown Error naming why it cannot be read. */
+function readReminders(result) {
+    if (!result.ok)
+        throw new Error(`GET /api/plans answered ${result.status}`);
+    const body = result.body;
+    if (typeof body !== "object" || body === null || Array.isArray(body)) {
+        throw new Error("GET /api/plans did not answer a JSON object");
+    }
+    const reminders = body.reminders;
+    if (reminders === undefined)
+        return [];
+    if (!Array.isArray(reminders) || !reminders.every(isReminder)) {
+        throw new Error("GET /api/plans carried a `reminders` field that is not an array of {key, text} strings");
+    }
+    return reminders.map(({ key, text }) => ({ key, text }));
+}
+export function createListenerReminder(deps) {
+    let cached = null;
+    let inFlight = null;
+    // Bumped by `invalidate()`: a read that started under an older value must not refill the cache.
+    let generation = 0;
+    let failureLogged = false;
+    let shapeLogged = false;
+    const logFailure = (reason) => {
+        if (failureLogged)
+            return;
+        failureLogged = true;
+        deps.logLine(`[danx-dashboard-mcp] plan listener health check failed (${reason}); nothing relayed`);
+    };
+    async function read() {
+        try {
+            const reminders = readReminders(await deps.fetchHealth());
+            failureLogged = false;
+            return reminders;
+        }
+        catch (err) {
+            logFailure(err.message);
+            return [];
+        }
+    }
+    async function remindersNow() {
+        if (cached !== null && deps.now() - cached.at < HEALTH_CACHE_WINDOW_MS)
+            return cached.reminders;
+        // One read serves every caller that arrives while it is outstanding.
+        if (inFlight !== null)
+            return inFlight;
+        const startedUnder = generation;
+        const started = read()
+            .then((reminders) => {
+            if (generation === startedUnder)
+                cached = { reminders, at: deps.now() };
+            return reminders;
+        })
+            .finally(() => {
+            if (inFlight === started)
+                inFlight = null;
+        });
+        inFlight = started;
+        return started;
+    }
+    return {
+        async apply(result) {
+            const sessionId = deps.sessionId;
+            if (sessionId === undefined || sessionId === "")
+                return result;
+            const body = result.body;
+            // Never wrap or alter a body that is not a JSON object.
+            if (typeof body !== "object" || body === null || Array.isArray(body))
+                return result;
+            // Read per call (a file read): a connect made after this process started takes effect on
+            // the next call, and an unconnected session costs zero health reads.
+            let connected;
+            try {
+                connected = deps.isPlanConnected(sessionId);
+            }
+            catch (err) {
+                logFailure(err.message);
+                return result;
+            }
+            if (!connected)
+                return result;
+            const existing = body.reminders;
+            if (existing !== undefined && !Array.isArray(existing)) {
+                if (!shapeLogged) {
+                    shapeLogged = true;
+                    deps.logLine("[danx-dashboard-mcp] listener reminder not relayed: the response's own `reminders` is not an array");
+                }
+                return result;
+            }
+            const relayed = await remindersNow();
+            const present = new Set((existing ?? []).map((r) => (isReminder(r) ? r.key : null)));
+            const fresh = relayed.filter((r) => {
+                if (present.has(r.key))
+                    return false;
+                present.add(r.key);
+                return true;
+            });
+            if (fresh.length === 0)
+                return result;
+            return { ...result, body: { ...body, reminders: [...(existing ?? []), ...fresh] } };
+        },
+        invalidate() {
+            generation += 1;
+            cached = null;
+            inFlight = null;
+        },
+    };
+}
+/** The production wiring: the real local record. */
+export function isPlanConnectedOnThisMachine(sessionId) {
+    return readSessionConnection(sessionId) !== null;
+}

package/package.json

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