@thehammer/danx-dashboard-mcp 0.1.252 → 0.1.256

package/README.md

@@ -11,8 +11,8 @@ Stdio MCP server fronting danxbot's dashboard HTTP API. Since DX-3465 it exposes
 | `DANXBOT_DASHBOARD_URL` | Dashboard base, e.g. `http://danxbot-dashboard:5555` (inside compose) or `http://localhost:5555` (host) |
 | `DANX_DASHBOARD_CREDENTIAL` | A DISPATCH's credential: the bearer verbatim, substituted into the materialized `.mcp.json` from its overlay (DX-2862, `src/credential.ts`). Authoritative when set; it never signs out. An operator session sets nothing: with no credential the server boots SIGNED OUT, every tool except `plan_connect` returns one "not signed in" halt, and `plan_connect` requests access (below). The same resolver serves the `bridge` subcommand, so a session's tools and its event stream can never sign in as two different identities |
 | `DANXBOT_TEAM` | OPTIONAL, non-secret (DX-4446): the team slug (or id) whose approvers see this session's access request in their danxbot site. Set it in the repo's `.mcp.json` env block or the shell. Unset, the request is answered by link only. A value that is not a team slug fails at boot; a team the dashboard does not know makes `plan_connect` answer `unknown_team` (fix `DANXBOT_TEAM`), never a silent link fallback |
-| `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) |
+| `DANX_REPO_NAME` | OPTIONAL (DX-4555): repo half of the qualified board id; sent as the access request's repo label |
+| `DANXBOT_BOARD_NAME` | OPTIONAL (DX-4555; needs `DANX_REPO_NAME`): board-slug half of the qualified board id (the dispatch injects `board.slug` here). With neither variable set (the danxbot plugin's own server) the server has no default board: a board-scoped call must carry its `board` argument or it fails loud |
 
 BOARD-ONLY (DX-1171): board is the first-level concept; repo is DERIVED from board server-side, never passed. At boot the package composes the dispatch's qualified board id `<repo>:<slug>` from `DANX_REPO_NAME` + `DANXBOT_BOARD_NAME` and appends it as `?board=<id>` (and `body.board` on create) to every `/api/issues/*` request. Each tool exposes an optional `board` arg — a FULL qualified id `<repo>:<slug>` (e.g. `platform:the-supply-operations-hub`) — that overrides it per-call for cross-board reads/writes (unknown board → 404). The dashboard owns board→repo resolution; this package never sends `repo`.
 

package/dist/http-client.js

@@ -111,7 +111,12 @@ export class DashboardHttpClient {
         const params = new URLSearchParams(existingQs ?? "");
         // DX-3750 / DX-4303 — only a route the dashboard takes `?board=` on gets the stamp; see `route-board-scope.ts`.
         if (isBoardScopedRoute(method, `${basePath}${cleanPath}`)) {
-            params.set("board", boardOverride ?? this.config.board);
+            const board = boardOverride ?? this.config.board;
+            // DX-4555: a board-less server (the danxbot plugin's, no DANX_REPO_NAME/DANXBOT_BOARD_NAME) has no board to stamp.
+            if (board === undefined) {
+                throw new Error(`[danx-dashboard-mcp] ${method} ${basePath}${cleanPath} is board-scoped and this server has no configured board: pass the \`board\` argument (a qualified id, <repo>:<slug>)`);
+            }
+            params.set("board", board);
         }
         if (extraQuery) {
             for (const [k, v] of Object.entries(extraQuery)) {

package/dist/index.js

@@ -52,7 +52,7 @@
  * DANX_REPO_NAME + DANXBOT_BOARD_NAME and sends it as `board` — the
  * dashboard owns board→repo resolution.
  *
- * Env at boot (validated fail-loud — missing → process.exit(1)):
+ * Env at boot (validated fail-loud — a missing required var → process.exit(1)):
  *   DANXBOT_DASHBOARD_URL   dashboard base (e.g. http://danxbot-dashboard:5555)
  *   the CREDENTIAL (DX-4390), resolved by the ONE resolver this package's event bridge
  *   also uses (`credential.ts`, DX-2862), and never a reason to exit:
@@ -67,8 +67,8 @@
  *                           Unset: the request is answered by link only. Set but not a
  *                           valid ref, or unknown to the dashboard: fails loud, never a
  *                           silent fall back to the link flow.
- *   DANX_REPO_NAME          repo half of the qualified board id
- *   DANXBOT_BOARD_NAME      board-slug half of the qualified board id
+ *   DANX_REPO_NAME          OPTIONAL (DX-4555): repo half of the qualified board id
+ *   DANXBOT_BOARD_NAME      OPTIONAL (DX-4555; needs DANX_REPO_NAME): board-slug half of the qualified board id
  *                           (the dispatch injects `board.slug` here);
  *                           composed as `<repo>:<slug>` and appended as
  *                           ?board=<id>. Each tool's optional `board` arg
@@ -172,17 +172,25 @@ let permissionWatch;
  * halves the worker injects and build the HTTP client. DANXBOT_BOARD_NAME
  * already carries the board SLUG at the spawn site (src/dispatch/core.ts sets it
  * from `board.slug`), so a plain join yields the canonical id — no transform.
- * Both halves are fail-loud required (Core Principle 1 — no fallback).
+ * Both unset (DX-4555) leaves the server board-less: a board-scoped call must then carry its own `board`
+ * argument (`DashboardHttpClient.buildUrl` refuses otherwise). A slug without its repo fails loud.
  */
 function boot() {
     const dashboardUrl = readEnvOrDie("DANXBOT_DASHBOARD_URL");
-    const repo = readEnvOrDie("DANX_REPO_NAME");
+    const repo = readEnvOptional("DANX_REPO_NAME");
+    const boardName = readEnvOptional("DANXBOT_BOARD_NAME");
+    // DX-4555: a session started from the danxbot plugin's own server names no board; each call then
+    // carries a `board` argument. A board slug with no repo half is a half-written .mcp.json: fail loud.
+    if (boardName !== undefined && repo === undefined) {
+        console.error("[danx-dashboard-mcp] DANXBOT_BOARD_NAME is set but DANX_REPO_NAME is missing or empty");
+        process.exit(1);
+    }
     const session = readSessionConfig();
     config = {
         baseUrl: dashboardUrl,
         // DX-4390 — set by `SessionAccess` below; "" while signed out.
         token: "",
-        board: `${repo}:${readEnvOrDie("DANXBOT_BOARD_NAME")}`,
+        board: boardName === undefined ? undefined : `${repo}:${boardName}`,
         // DX-1398 — OPTIONAL cross-process trace context. Present → stamped on every
         // outbound call so the agent's card writes chain under the launch; absent
         // (untraced dispatch) → omitted, and the dashboard mints a fresh root.
@@ -195,7 +203,7 @@ function boot() {
     access = new SessionAccess({
         dashboardUrl,
         sessionId: session?.id,
-        repo,
+        repo: repo ?? null,
         clientVersion: readOwnVersion(),
         team: readTeamRef(),
         setToken: (token) => dashboardClient.setToken(token),
@@ -724,7 +732,7 @@ async function main() {
     process.stdin.once("end", () => permissionWatch.stop());
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error(`danx-dashboard-mcp running on stdio (dashboard=${config.baseUrl}, board=${config.board})`);
+    console.error(`danx-dashboard-mcp running on stdio (dashboard=${config.baseUrl}, board=${config.board ?? "none, each call names its own"})`);
 }
 // Boot the stdio server ONLY when run as the entrypoint (the published bin).
 // Importing this module (the tool-defs generator + its drift test) registers

package/dist/listen.js

@@ -12,9 +12,10 @@
  *     `text` is what the session reads; an event it cannot read still produces one
  *     (`could not read event …`), never silence. `id` is `null` only for a frame
  *     that carried no usable id — which includes DX-2885's `nudge` frame
- *     (`formatNudgeLine`): it is advisory, re-derived fresh every tick by the
- *     dashboard's own keep-alive tick, and never replayed, so it rides this
- *     same shape with `id: null` rather than growing a THIRD output variant.
+ *     (`formatNudgeLine`) and DX-4340's `pacing` frame (`formatPacingLine`):
+ *     both are advisory, written fresh by the dashboard's own keep-alive tick,
+ *     and never replayed, so they ride this same shape with `id: null` rather
+ *     than growing a THIRD output variant.
  *   - `{type:"stopped", reason, detail, refusal?}` — once, last. `reason`
  *     is the dashboard's own end reason (`superseded`, `replaced`, `revoked`,
  *     `not_connected`), `refused` (the ticket was not admitted), or
@@ -329,6 +330,28 @@ export function formatNudgeLine(event) {
         "Work these cards; any you cannot work, update to its true state: open a problem, add depends_on or " +
         "conflict_on, block it with the real reason, or rollback_pickup.");
 }
+const PACING_LEVELS = ["on_pace", "over_pace", "critical"];
+/** Why a pacing message cannot be read, or `null` when it can. */
+export function invalidPacingReason(value) {
+    if (!isRecord(value))
+        return "the pacing message is not an object";
+    if (!PACING_LEVELS.includes(value.level))
+        return "level is not on_pace, over_pace or critical";
+    if (value.budget !== null && !(typeof value.budget === "number" && Number.isInteger(value.budget) && value.budget >= 0))
+        return "budget is not a count or null";
+    if (typeof value.resets_at !== "string" || Number.isNaN(Date.parse(value.resets_at)))
+        return "resets_at is not a timestamp";
+    if (typeof value.text !== "string" || value.text.trim() === "")
+        return "text is empty";
+    return null;
+}
+/** The one readable line for a pacing message: the dashboard's text, on one line. Throws, naming the fault, on a malformed message. */
+export function formatPacingLine(event) {
+    const invalid = invalidPacingReason(event);
+    if (invalid !== null)
+        throw new Error(`malformed pacing message: ${invalid}`);
+    return oneLine(`${LINE_PREFIX} ${event.text}`, 1000);
+}
 /**
  * Incremental SSE parser. Comment lines (keep-alives, the connect marker) and
  * field-less blocks produce no message, which is what keeps them out of the output.
@@ -416,6 +439,30 @@ export async function runListener(options, deps) {
         deps.write({ type: "stopped", reason, detail, refusal: extra?.refusal });
         return code;
     }
+    /**
+     * The shared path of an ADVISORY frame (DX-2885 `nudge`, DX-4340 `pacing`): it carries no usable id (re-derived or written fresh by the
+     * dashboard's keep-alive tick, never replayed - see `plan-session-stream.ts`'s module doc), so it rides the SAME `{type:"event", id:null, text}`
+     * shape an ordinary activity line uses. That is what lets `bridge.ts` and the plugin's relay (`danxbot/scripts/plan-event-bridge.mjs`, outside
+     * this repo) forward it with NO changes: both forward any `{type:"event", id, text}` line keyed only on `type`.
+     *
+     * `origin: null` is DX-2730 D4's exemption: the frame is delivered at once, never held for a digest flush (a nudge exists to interrupt a quiet
+     * session; a pacing change is an instruction to act now). A frame that is not JSON or not the right shape is reported from an explicit check
+     * naming the fault, and the next frame still emits.
+     */
+    const emitAdvisory = (message, what, invalidReason, format) => {
+        let parsed;
+        let invalid;
+        try {
+            parsed = JSON.parse(message.data);
+            invalid = invalidReason(parsed);
+        }
+        catch (err) {
+            invalid = `not JSON: ${err.message}`;
+        }
+        const text = invalid === null ? format(parsed) : `${LINE_PREFIX} could not read ${what} (${invalid}): ${oneLine(message.data, 300)}`;
+        deps.write({ type: "event", id: null, text, origin: null });
+        return null;
+    };
     const handle = (message) => {
         if (message.event === "end") {
             // DX-2920 (round 3) — a JSON.parse failure here falls through to the
@@ -435,40 +482,11 @@ export async function runListener(options, deps) {
             // `Outcome`'s "ended" reason is a closed set (`EndedReason`).
             return { kind: "ended", reason: isKnownWireEndReason(reason) ? reason : "unknown" };
         }
-        if (message.event === "nudge") {
-            // DX-2885 — a nudge carries no usable id (it is advisory, re-derived
-            // fresh every tick, never replayed — see `plan-session-stream.ts`'s
-            // module doc), so it rides the SAME `{type:"event", id:null, text}`
-            // shape an ordinary activity line uses (`id` is `null` only for a frame
-            // that carried no usable id — a nudge is exactly that case). That is
-            // what lets `bridge.ts` and the plugin's relay
-            // (`danxbot/scripts/plan-event-bridge.mjs`, outside this repo) forward
-            // it with NO changes at all: both already forward any `{type:"event",
-            // id, text}` line generically, keyed only on `type`.
-            //
-            // DX-2885 — this frame must stay exempt from DX-2730 D4's digest-
-            // batching when that lands (see DX-2730 AC 29939, and the matching note
-            // at the dashboard's own emit site): it must keep delivering
-            // immediately, never held for a later digest flush.
-            let parsed;
-            let invalid;
-            try {
-                parsed = JSON.parse(message.data);
-                invalid = invalidNudgeReason(parsed);
-            }
-            catch (err) {
-                invalid = `not JSON: ${err.message}`;
-            }
-            const text = invalid === null
-                ? formatNudgeLine(parsed)
-                : `${LINE_PREFIX} could not read nudge (${invalid}): ${oneLine(message.data, 300)}`;
-            // DX-2730 D4 — `origin: null` here, not the parsed event's own origin
-            // (a nudge has none): this is the exemption the module doc above
-            // describes, letting `bridge.ts` treat it exactly like an operator
-            // event (immediate) without needing a fourth vocabulary member.
-            deps.write({ type: "event", id: null, text, origin: null });
-            return null;
-        }
+        if (message.event === "nudge")
+            return emitAdvisory(message, "nudge", invalidNudgeReason, (p) => formatNudgeLine(p));
+        // DX-4340 - the pacing tick's one message for this session's Claude account (level or budget changed): advisory like a nudge.
+        if (message.event === "pacing")
+            return emitAdvisory(message, "pacing message", invalidPacingReason, (p) => formatPacingLine(p));
         if (message.event !== "activity")
             return null;
         // `Number(null)` is 0, so a frame with no id must never be read as event 0: that id

package/package.json

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