@thehammer/danx-dashboard-mcp 0.1.175 → 0.1.176

package/dist/background-work.js

@@ -5,8 +5,8 @@
  * WHO RUNS IT. The danxbot Claude Code plugin's `Stop` / `SubagentStop` /
  * `SessionStart` / `StopFailure` hooks (`danxbot/hooks/hooks.json` in
  * claude-plugins), via the SAME `npx -y @thehammer/danx-dashboard-mcp`
- * MECHANISM the plugin already uses for `bridge` — no separate install, no
- * deep import of this package's `dist/` internals.
+ * MECHANISM the plugin already uses for `bridge` and `plan-state` — no
+ * separate install, no deep import of this package's `dist/` internals.
  * DX-3367 fix-up — that does NOT mean the SAME PINNED VERSION: `npx -y
  * <pkg>` resolves whatever version string that ONE hook's own invocation
  * names, and this plugin's hooks pin each call independently (verified
@@ -18,8 +18,9 @@
  * sending `clear` on `SessionStart`/`StopFailure`); this module only
  * delivers the report.
  *
- * THE CONTRACT (binding, so a future plugin build against this module can
- * trust it without re-reading this file):
+ * THE CONTRACT, mirroring `plan-state.ts`'s (binding the same way, so a
+ * future plugin build against this module can trust it without re-reading
+ * this file):
  *   - print EXACTLY ONE JSON line on stdout, and ALWAYS exit 0 — success or
  *     failure alike, because a hook must stay silent rather than spam the
  *     session's own turn with a stack trace;
@@ -39,21 +40,21 @@
  *     reports by this time;
  *   - human-readable diagnostics go to stderr only, never stdout.
  *
- * THE CREDENTIAL — the SAME resolver `bridge` uses, via `resolveBridgeOptions`
- * (`bridge.ts`): the dashboard URL, credential source, and credential come
- * from the connection record this session's OWN danx-dashboard MCP server
- * wrote on its last successful `plan_connect` (`session-connection.ts`),
- * never from this process's own ambient env (DX-2862).
+ * THE CREDENTIAL — the SAME resolver `bridge` and `plan-state` use, via
+ * `resolveBridgeOptions` (`bridge.ts`): the dashboard URL, credential
+ * source, and credential come from the connection record this session's OWN
+ * danx-dashboard MCP server wrote on its last successful `plan_connect`
+ * (`session-connection.ts`), never from this process's own ambient env —
+ * the identical DX-2862 reasoning `plan-state.ts` already gives for itself.
  *
  * A HARD TIMEOUT — `BACKGROUND_WORK_REQUEST_TIMEOUT_MS`. A `Stop` hook
  * blocks the session's turn boundary, so this call must never hang: a slow
  * or wedged dashboard is `{ok:false, reason:"timeout"}`, not a stuck hook.
  *
- * THE REQUEST/RUN SCAFFOLDING (`one-shot-session-request.ts`, DX-3367
- * fix-up) is shared, general-purpose plumbing for any one-shot subcommand
- * shaped like this one — not maintained as an independent copy of the
- * authenticated-fetch-with-timeout logic or the session/credential
- * resolution boilerplate.
+ * THE REQUEST/RUN SCAFFOLDING IS SHARED WITH `plan-state.ts`
+ * (`one-shot-session-request.ts`, DX-3367 fix-up) — the two subcommands no
+ * longer maintain independent copies of the authenticated-fetch-with-
+ * timeout logic or the session/credential resolution boilerplate.
  */
 import { resolveSessionOptions, sendSessionRequest, tryParseJsonBody } from "./one-shot-session-request.js";
 export const BACKGROUND_WORK_SUBCOMMAND = "background-work";
@@ -89,10 +90,10 @@ export function parseEventAtArg(raw) {
  * DX-3367 fix-up — STATUS IS CHECKED BEFORE THE BODY IS EVER PARSED. A 5xx
  * (or any other non-2xx) response can carry an HTML error page instead of
  * JSON; parsing first would misreport that as `bad_response` when the true
- * classification is `http_error`. This subcommand has no status that needs
- * the BODY inspected to classify (no `409 session_not_connected`
- * equivalent), so status alone decides whether a body read is even
- * attempted.
+ * classification is `http_error`. Unlike `plan-state.ts`'s `fetchTurnState`,
+ * this subcommand has no status that needs the BODY inspected to classify
+ * (no `409 session_not_connected` equivalent), so status alone decides
+ * whether a body read is even attempted.
  */
 export async function putBackgroundWork(options, report, deps) {
     const sent = await sendSessionRequest(options, BACKGROUND_WORK_PATH, { method: "PUT", body: JSON.stringify({ count: report.count, eventAt: report.eventAt }) }, deps);

package/dist/event-text.js

@@ -10,10 +10,11 @@
  * collapse into the one hook + this one subcommand). `<event>` is one of
  * `session_start` | `session_resume` | `after_compaction` |
  * `sub_agent_start` — the SAME `npx -y @thehammer/danx-dashboard-mcp@<pin>`
- * path the plugin's other dashboard calls already use (`bridge`) — never a
- * separate install, never a deep import of this package's `dist/` internals.
+ * path the plugin's other dashboard calls already use (`plan-state`,
+ * `bridge`) — never a separate install, never a deep import of this
+ * package's `dist/` internals.
  *
- * THE CREDENTIAL — the SAME resolver `bridge` uses
+ * THE CREDENTIAL — the SAME resolver `bridge` / `plan-state` use
  * (`resolveBridgeOptions`, `bridge.ts`): the dashboard URL, credential source
  * and credential all come from the connection record this session's OWN
  * danx-dashboard MCP server wrote on its last successful `plan_connect`
@@ -36,8 +37,8 @@
  *     stderr, exit 1. `event-hook.sh` is the one that decides what to print
  *     for the agent — this module only reports whether the fetch worked.
  *
- * A HARD TIMEOUT — a SessionStart hook must never hang on a wedged
- * dashboard.
+ * A HARD TIMEOUT (mirrors `plan-state.ts`) — a SessionStart hook must never
+ * hang on a wedged dashboard.
  */
 import { SESSION_ID_HEADER, resolveBridgeOptions } from "./bridge.js";
 export const EVENT_TEXT_SUBCOMMAND = "event-text";

package/dist/index.js

@@ -74,6 +74,7 @@
  */
 import { isEntrypointModule } from "./entrypoint.js";
 import { BRIDGE_SUBCOMMAND, runBridgeCommand } from "./bridge.js";
+import { PLAN_STATE_SUBCOMMAND, runPlanStateCommand } from "./plan-state.js";
 import { BACKGROUND_WORK_SUBCOMMAND, runBackgroundWorkCommand } from "./background-work.js";
 import { EVENT_TEXT_SUBCOMMAND, runEventTextCommand } from "./event-text.js";
 import { resolveDeclaredCredential } from "./credential.js";
@@ -459,14 +460,22 @@ async function main() {
 // symlink-aware (DX-1647) so it holds under the symlinked `npx` bin the worker
 // spawns, not just a direct `node dist/index.js`.
 //
-// `bridge` is the session event stream client the danxbot plugin's plan
-// event bridge runs. It never boots the MCP server; its only input is
-// `CLAUDE_CODE_SESSION_ID` (read from its environment) plus `--resume-ids` —
-// 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
-// exact bug this repo fixed).
+// `bridge` and `plan-state` are the two subcommands. `bridge` is the session
+// event stream client the danxbot plugin's plan event bridge runs. It never
+// boots the MCP server; its only input is `CLAUDE_CODE_SESSION_ID` (read from
+// its environment) plus `--resume-ids` — 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 exact bug this repo fixed).
+//
+// `plan-state` (DX-2921) is the ONE-SHOT client of
+// `GET /api/plan-sessions/me/turn-state`, run by the DX-2888 plugin's
+// turn-start / turn-end hooks — see `plan-state.ts`'s own doc comment for the
+// full contract. It ALWAYS exits 0 (success or failure alike: the hook must
+// stay silent), so even an unexpected rejection here is caught and reported
+// the same `{ok:false, reason}` way rather than propagating a non-zero exit
+// or an uncaught stack trace into the hook.
 //
 // Any OTHER argument is refused rather than ignored, so a typo cannot
 // silently start an MCP server on stdio where a subcommand was meant to run.
@@ -478,6 +487,13 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
             process.exit(1);
         });
     }
+    else if (subcommand === PLAN_STATE_SUBCOMMAND) {
+        runPlanStateCommand(rest).then((code) => process.exit(code), (err) => {
+            console.error(`[danx-dashboard-mcp] plan-state fatal: ${err.message}`);
+            process.stdout.write(`${JSON.stringify({ ok: false, reason: "fatal" })}\n`);
+            process.exit(0);
+        });
+    }
     else if (subcommand === BACKGROUND_WORK_SUBCOMMAND) {
         runBackgroundWorkCommand(rest).then((code) => process.exit(code), (err) => {
             console.error(`[danx-dashboard-mcp] background-work fatal: ${err.message}`);
@@ -486,11 +502,12 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
         });
     }
     else if (subcommand === EVENT_TEXT_SUBCOMMAND) {
-        // DX-3421 (was DX-3366's `mantra` subcommand) — unlike background-work, a
-        // rejection here is a genuine fatal (never expected: runEventTextCommand
-        // itself already classifies every network/shape failure into its own
-        // {ok:false} exit 1), so it exits 1 too rather than the "always 0, stay
-        // silent" contract background-work's hook-only subcommand uses.
+        // DX-3421 (was DX-3366's `mantra` subcommand) — unlike plan-state/
+        // background-work, a rejection here is a genuine fatal (never expected:
+        // runEventTextCommand itself already classifies every network/shape
+        // failure into its own {ok:false} exit 1), so it exits 1 too rather than
+        // the "always 0, stay silent" contract those two hook-only subcommands
+        // use.
         runEventTextCommand(rest).then((code) => process.exit(code), (err) => {
             console.error(`[danx-dashboard-mcp] event-text fatal: ${err.message}`);
             process.exit(1);
@@ -498,7 +515,7 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
     }
     else if (subcommand !== undefined) {
         console.error(`[danx-dashboard-mcp] unknown subcommand "${subcommand}" (the only ones are ` +
-            `"${BRIDGE_SUBCOMMAND}", "${BACKGROUND_WORK_SUBCOMMAND}", and "${EVENT_TEXT_SUBCOMMAND}")`);
+            `"${BRIDGE_SUBCOMMAND}", "${PLAN_STATE_SUBCOMMAND}", "${BACKGROUND_WORK_SUBCOMMAND}", and "${EVENT_TEXT_SUBCOMMAND}")`);
         process.exit(2);
     }
     else {

package/dist/one-shot-session-request.js

@@ -1,22 +1,21 @@
 /**
  * DX-3367 fix-up — shared scaffolding for a "one-shot session request"
- * subcommand. Extracted when `plan-state` (`GET /api/plan-sessions/me/turn-state`,
- * removed by DX-3689 — it never had a caller) and `background-work`
- * (`PUT /api/plan-sessions/me/background-work`) turned out to duplicate this
- * exact shape independently (`fetchTurnState` / `putBackgroundWork`,
- * `runPlanStateCommand` / `runBackgroundWorkCommand`). This module is the ONE
- * place that shape lives now; a future one-shot subcommand extends it
- * instead of copying `background-work.ts` again.
+ * subcommand: `plan-state` (`GET /api/plan-sessions/me/turn-state`) and
+ * `background-work` (`PUT /api/plan-sessions/me/background-work`) each
+ * duplicated this exact shape independently (`fetchTurnState` /
+ * `putBackgroundWork`, `runPlanStateCommand` / `runBackgroundWorkCommand`).
+ * This module is the ONE place that shape lives now; a future one-shot
+ * subcommand extends it instead of copying either file again.
  *
- * Two pieces:
+ * Two pieces, matching the two duplicated concerns:
  *   - `sendSessionRequest` — the authenticated HTTP call itself: bearer +
  *     session header, a hard abort-timeout, and network-level failure
  *     classification (`timeout` / `request_failed`). Returns the raw
  *     `{status, text}` UNPARSED — each caller decides for itself which
- *     statuses need the body inspected and which don't, so a non-2xx status
- *     with an unparseable (e.g. HTML) body is classified from the status
- *     alone rather than colliding with "the JSON didn't parse"
- *     (`bad_response`).
+ *     statuses need the body inspected (e.g. `plan-state`'s 409
+ *     `session_not_connected`) and which don't, so a non-2xx status with an
+ *     unparseable (e.g. HTML) body is classified from the status alone
+ *     rather than colliding with "the JSON didn't parse" (`bad_response`).
  *   - `resolveSessionOptions` — session-id + credential resolution via
  *     `resolveBridgeOptions`, with `BridgeStartError` narrowed by
  *     `instanceof` rather than an unchecked `as BridgeStartError` cast, so

package/dist/plan-state.js

@@ -0,0 +1,174 @@
+/**
+ * `danx-dashboard-mcp plan-state` — the ONE-SHOT client of
+ * `GET /api/plan-sessions/me/turn-state` (DX-2921).
+ *
+ * WHO RUNS IT. The danxbot Claude Code plugin's DX-2888 turn-start /
+ * turn-end hooks, via the plugin's existing `bridgeCommand()` npx path — the
+ * SAME package pin, no separate install, no deep import of this package's
+ * `dist/` internals (that was DX-2921's whole reason to exist: the DX-2888
+ * architecture review found the first build of this logic vendored a private
+ * copy of the MCP package and hardcoded the dashboard HTTP contract inside
+ * the PLUGIN). The plugin decides what to DO with the answer (inject plan
+ * numbers at turn start, refuse to let a turn end while the session could
+ * legally start work and has nothing running); this module only fetches it.
+ *
+ * THE CONTRACT (agreed with the DX-2888 plugin side, issue comment 4245 on
+ * DX-2921 — binding, because the plugin is already built against it):
+ *   - print EXACTLY ONE JSON line on stdout, and ALWAYS exit 0 — success or
+ *     failure alike, because the hook must stay silent rather than spam the
+ *     session's own turn with a stack trace;
+ *   - a session that is not connected to a plan prints
+ *     `{"ok":false,"reason":"session_not_connected"}` — that EXACT literal,
+ *     because the plugin keys its no-log-spam rule on it (it is also the
+ *     dashboard's own 409 error code for this case — see
+ *     `requireConnectedPlanId`, `plan-session-context.ts`);
+ *   - on success, every count is a finite number, `plan` carries `id` +
+ *     `name`, and every `startable` / `held` entry carries a string `id` +
+ *     `title` — the plugin rejects anything else as `bad_response`, so this
+ *     module validates the server's response BEFORE printing it, rather than
+ *     trusting a 200 status to mean a well-shaped body;
+ *   - human-readable diagnostics go to stderr only, never stdout.
+ *
+ * THE CREDENTIAL — the SAME resolver `bridge` uses (DX-2862 / DX-2921 AC),
+ * via `resolveBridgeOptions` (`bridge.ts`): the dashboard URL, credential
+ * source and credential all come from the connection record this session's
+ * OWN danx-dashboard MCP server wrote on its last successful `plan_connect`
+ * (`session-connection.ts`), never from this process's own ambient env. That
+ * is deliberate here for the identical reason it is deliberate for `bridge`:
+ * a hook process trusting whatever `DANXBOT_DISPATCH_TOKEN` happens to be in
+ * its environment is precisely the DX-2862 bug (a hook's ambient credential
+ * silently pointed at a different dashboard from the one the session's tools
+ * actually use).
+ *
+ * A HARD TIMEOUT (AC 30672) — `PLAN_STATE_REQUEST_TIMEOUT_MS`. This call
+ * blocks a turn boundary the plugin is holding open, so it must never hang:
+ * a slow or wedged dashboard is `{ok:false, reason:"timeout"}`, not a stuck
+ * hook.
+ *
+ * THE REQUEST/RUN SCAFFOLDING IS SHARED WITH `background-work.ts`
+ * (`one-shot-session-request.ts`, DX-3367 fix-up).
+ */
+import { resolveSessionOptions, sendSessionRequest, tryParseJsonBody } from "./one-shot-session-request.js";
+export const PLAN_STATE_SUBCOMMAND = "plan-state";
+export const TURN_STATE_PATH = "/api/plan-sessions/me/turn-state";
+/** How long this one-shot call may take before it counts as a timeout. */
+export const PLAN_STATE_REQUEST_TIMEOUT_MS = 5_000;
+const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${PLAN_STATE_SUBCOMMAND}`;
+function errorCodeOf(body) {
+    return typeof body === "object" && body !== null && typeof body.error === "string"
+        ? body.error
+        : null;
+}
+function isFiniteNumber(v) {
+    return typeof v === "number" && Number.isFinite(v);
+}
+function isCardRef(v) {
+    return (typeof v === "object" &&
+        v !== null &&
+        typeof v.id === "string" &&
+        typeof v.title === "string");
+}
+/**
+ * The strict shape check the contract pins (comment 4245): finite counts, a
+ * `plan` with `id` + `name`, and a string `id` + `title` on every
+ * `startable` / `held` entry. `null` on anything short of that — a 200 whose
+ * body does not match is `bad_response`, exactly like a non-2xx.
+ */
+export function parseTurnStateBody(body) {
+    if (typeof body !== "object" || body === null)
+        return null;
+    const b = body;
+    const plan = b.plan;
+    if (typeof plan !== "object" || plan === null)
+        return null;
+    const p = plan;
+    if (!isFiniteNumber(p.id) || typeof p.name !== "string")
+        return null;
+    const counts = b.counts;
+    if (typeof counts !== "object" || counts === null)
+        return null;
+    const c = counts;
+    if (!isFiniteNumber(c.open) || !isFiniteNumber(c.inProgress) || !isFiniteNumber(c.needsYou))
+        return null;
+    if (!Array.isArray(b.startable) || !b.startable.every(isCardRef))
+        return null;
+    if (!Array.isArray(b.held) || !b.held.every(isCardRef))
+        return null;
+    return {
+        plan: { id: p.id, name: p.name },
+        counts: { open: c.open, inProgress: c.inProgress, needsYou: c.needsYou },
+        startable: b.startable,
+        held: b.held,
+    };
+}
+/**
+ * One authenticated GET, with a hard timeout, classified into the output
+ * shape this subcommand always prints — never a throw, never a non-2xx
+ * bubbling past this function.
+ *
+ * DX-3367 fix-up — status is checked BEFORE the body is parsed, except for
+ * the ONE status (`409`) whose classification genuinely depends on the body
+ * (`session_not_connected`). Any other non-2xx — including a 5xx that comes
+ * back as an HTML error page instead of JSON — is `http_error` without ever
+ * attempting to parse it, so a body-parse failure on those statuses can
+ * never be misreported as `bad_response`.
+ */
+export async function fetchTurnState(options, deps) {
+    const sent = await sendSessionRequest(options, TURN_STATE_PATH, { method: "GET" }, deps);
+    if ("reason" in sent)
+        return sent;
+    const { status, text } = sent;
+    if (status === 409) {
+        // The exact literal the plugin's no-log-spam rule keys on (AC 30672 /
+        // comment 4245) — the dashboard's own 409 error code for an unconnected
+        // session, passed through verbatim rather than renamed. A 409 whose body
+        // does NOT carry that code falls through to the ordinary `http_error`
+        // classification below, same as any other non-2xx.
+        const parsed409 = tryParseJsonBody(text);
+        if (parsed409.ok && errorCodeOf(parsed409.body) === "session_not_connected") {
+            return { ok: false, reason: "session_not_connected" };
+        }
+    }
+    if (status === 401 || status === 403) {
+        return { ok: false, reason: "unauthorized" };
+    }
+    if (status < 200 || status >= 300) {
+        return { ok: false, reason: "http_error" };
+    }
+    const parsed = tryParseJsonBody(text);
+    if (!parsed.ok)
+        return { ok: false, reason: "bad_response" };
+    const turnState = parseTurnStateBody(parsed.body);
+    if (turnState === null) {
+        return { ok: false, reason: "bad_response" };
+    }
+    return { ok: true, ...turnState };
+}
+/** The bin's `plan-state` subcommand, wired to the real process. Always resolves to exit code 0. */
+export async function runPlanStateCommand(argv, env = process.env, 
+/** Test seam: the home the session's connection record is read from. */
+resolveFrom = {}) {
+    const write = (output) => {
+        process.stdout.write(`${JSON.stringify(output)}\n`);
+    };
+    if (argv.length !== 0) {
+        // A malformed invocation is still a "the hook must stay silent" failure,
+        // not a crash — same ok:false/exit-0 contract as every other failure
+        // path here, with the usage line reserved for a human reading stderr.
+        write({ ok: false, reason: "usage" });
+        process.stderr.write(`${USAGE}\n`);
+        return 0;
+    }
+    const resolved = await resolveSessionOptions(env, resolveFrom, USAGE);
+    if (!resolved.ok) {
+        write(resolved.output);
+        process.stderr.write(`${resolved.detail}\n`);
+        return 0;
+    }
+    const output = await fetchTurnState(resolved.options, {
+        fetch: (input, init) => fetch(input, init),
+        requestTimeoutMs: PLAN_STATE_REQUEST_TIMEOUT_MS,
+    });
+    write(output);
+    return 0;
+}

package/package.json

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