@thehammer/danx-dashboard-mcp 0.1.246 → 0.1.247

package/README.md

@@ -67,6 +67,10 @@ CLAUDE_CODE_SESSION_ID=<session> npx -y @thehammer/danx-dashboard-mcp@<version>
 
 Run by the danxbot plugin's SessionStart hook for a session that is **not** plan-connected. A restarted Claude Code session gets a new session id and no plan binding, so nothing told it that the plan it had been working was unattended. `plan_connect` writes the session's working directory into its connection record (`projectKey`, record schema v2); this subcommand finds the newest OTHER session's record for the same project within `STALE_RECORD_MS`, resolves that record's own credential, and asks `GET /api/plan-sessions/<predecessor>/restart-notice` which plan it was on and how many operator events wait there (the connect digest's own query, read-only). Exit 0 with text on stdout = say it (the registry's `plan_restart.waiting_events` text — this package carries no wording); exit 0 with nothing = nothing to say (never connected from this project, plan archived or deleted, record stale); exit 1 = the lookup failed. A record from an older server (schema v1) is skipped here and refused, with the fix, everywhere a session reads its OWN record.
 
+## `ready-cards` — the plan's cards anyone could pick up now (DX-4534)
+
+Run by the danxbot plugin's Stop hook for a plan-connected session. `GET /api/plans/mine` answers the session's plan and the boards its cards live on (a session on no plan is a 409 `session_not_connected`, read as an empty answer); then, for each board, `GET /api/issues?board=` with `filter.plan_id` + `filter.status_derived` returns the plan's ToDo cards, and the ready ones are kept: a Story, Bug or Chore with no assigned agent, no live dispatch, no block, no open problem, no unmet `depends_on` and no active `conflict_on`. No dashboard route was added. Exit 0 prints one JSON line `{"plan_id": <n|null>, "cards": [{"id", "title"}]}`; exit 1 prints one stderr line that starts with its reason (`credential_unavailable`, `no_connection_record`, `http_error`, ...) and nothing on stdout.
+
 ## `subagents-live` — the plan pane's local live sub-agent feed (DX-4508)
 
 `danx-dashboard-mcp subagents-live <absolute path to the session's main transcript .jsonl>`. Spawned by the danxbot plugin's plan pane, which cannot tail files itself; the dashboard's sub-agent read lags the transcript by about 80s, this by about one second. It tails the session's transcript tree (the main file and `<session-id>/subagents/agent-*.jsonl` beside it) with the same `SessionLogWatcher` the bridge runs, from byte 0 once and then only appended bytes, polling every second, and computes each sub-agent through `@thehammer/danx-session-telemetry`'s `createSubagentLiveView` (the same observer, ledger counter and pricing rule the dashboard uses). stdout carries only `{"subagents":[...]}` lines: the first, after the catch-up read, holds every sub-agent (an empty array when there are none); each later one holds only the sub-agents a poll changed. No network, no credential. A missing, relative or non-`.jsonl` path exits 2 with one stderr line; SIGTERM, SIGINT or a closed stdout exits 0.

package/dist/index.js

@@ -87,6 +87,7 @@ import { BACKGROUND_WORK_SUBCOMMAND, runBackgroundWorkCommand } from "./backgrou
 import { ACTIVITY_SUBCOMMAND, runActivityCommand } from "./activity.js";
 import { EVENT_TEXT_SUBCOMMAND, runEventTextCommand } from "./event-text.js";
 import { RESTART_NOTICE_SUBCOMMAND, runRestartNoticeCommand } from "./restart-notice.js";
+import { READY_CARDS_SUBCOMMAND, runReadyCardsCommand } from "./ready-cards.js";
 import { SUBAGENTS_LIVE_SUBCOMMAND, runSubagentsLiveCommand } from "./subagents-live.js";
 import { resolveBootCredential } from "./credential.js";
 import { SessionKeyUnusableError, deleteSessionKey } from "./session-key.js";
@@ -687,6 +688,13 @@ if (isEntrypointModule(import.meta.url, process.argv[1])) {
             process.exit(1);
         });
     }
+    else if (subcommand === READY_CARDS_SUBCOMMAND) {
+        // DX-4534 — the plugin Stop hook's read; the event-text exit-code contract: 0 (one JSON line) / 1 (read failed).
+        runReadyCardsCommand(rest).then((code) => process.exit(code), (err) => {
+            console.error(`[danx-dashboard-mcp] ${READY_CARDS_SUBCOMMAND} fatal: ${err.message}`);
+            process.exit(1);
+        });
+    }
     else if (subcommand === SUBAGENTS_LIVE_SUBCOMMAND) {
         // DX-4508 — the plugin pane's local live sub-agent feed: stdout is its JSON Lines channel, so a fatal goes to
         // stderr only and exits 1; a refused path exits 2 from the command itself.
@@ -698,7 +706,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}", "${ACTIVITY_SUBCOMMAND}", "${EVENT_TEXT_SUBCOMMAND}", ` +
-            `"${RESTART_NOTICE_SUBCOMMAND}", and "${SUBAGENTS_LIVE_SUBCOMMAND}")`);
+            `"${RESTART_NOTICE_SUBCOMMAND}", "${READY_CARDS_SUBCOMMAND}", and "${SUBAGENTS_LIVE_SUBCOMMAND}")`);
         process.exit(2);
     }
     else {

package/dist/ready-cards.js

@@ -0,0 +1,176 @@
+/**
+ * `danx-dashboard-mcp ready-cards` — DX-4534. The ONE-SHOT client the claude-plugins `danxbot`
+ * plugin's Stop hook runs for a plan-connected session, to learn which of its plan's cards
+ * anyone could pick up right now.
+ *
+ * WHY IT EXISTS. An orchestrating plan session must keep every unblocked card moving, and
+ * nothing enforced it: on 2026-10-04 one builder ran while two readied, unblocked cards sat
+ * untouched, because the session only looked for work when a builder reported back. The Stop
+ * hook turns that check into something the harness runs. This is its read.
+ *
+ * NO DASHBOARD ROUTE IS ADDED. It composes existing reads on the session's own credential:
+ *   1. `GET /api/plans/mine` answers the session's plan (`id`) and the boards its cards live on
+ *      (`boards`) in one read; a session on no plan is a 409 `session_not_connected`.
+ *   2. `GET /api/issues?board=<b>` with `filter.plan_id` + `filter.status_derived=ToDo` and the
+ *      judged fields, once per board: a plan can span boards (PLAN-11 spans danxbot and
+ *      gpt-manager), and an issues read without `board` sees only the default one.
+ * Server-side filtering narrows the read; `isReadyCard` is the whole definition of "ready".
+ *
+ * READY means a card a dispatcher or a session could claim this minute: a Story, Bug or Chore
+ * (Epic and Feature are containers, a Task is a leaf nobody dispatches), derived status ToDo,
+ * nobody holding it (no assigned agent, no live dispatch), and nothing in its way: no hold
+ * (`blocked`), no open problem (a human is needed), no unmet `depends_on`, no active
+ * `conflict_on`. A card whose reason it cannot run is recorded on it therefore stops counting,
+ * which is how the hook's "dispatch it, or record why not" instruction is satisfiable.
+ *
+ * THE CONTRACT, which the hook reads by exit code:
+ *   - exit 0, one JSON line on stdout: `{"plan_id": <n|null>, "cards": [{"id","title"}...]}`;
+ *     `plan_id` null (the dashboard has the session on no plan) comes with an empty list.
+ *   - exit 1, one reason on stderr, nothing on stdout: credential, network, non-2xx, bad shape.
+ */
+import { resolveSessionOptions, sendSessionRequest, tryParseJsonBody } from "./one-shot-session-request.js";
+export const READY_CARDS_SUBCOMMAND = "ready-cards";
+export const READY_CARDS_REQUEST_TIMEOUT_MS = 5_000;
+/** `GET /api/issues` page size (its maximum): a plan's ToDo cards never approach it. */
+const CARDS_PAGE_SIZE = 1000;
+/** The dispatchable card types: Epic and Feature are containers, a Task is a leaf nobody dispatches. */
+const DISPATCHABLE_TYPES = new Set(["Story", "Bug", "Chore"]);
+/**
+ * The fields `isReadyCard` judges beyond the always-returned row, each with the check a row's value
+ * must pass: the one list the request's `fields` tree and the row parse both come from.
+ */
+const JUDGED_FIELDS = {
+    dispatch: (v) => v !== undefined,
+    blocked: (v) => v !== undefined,
+    open_problem_count: (v) => typeof v === "number",
+    waiting_on: (v) => typeof v === "boolean",
+    conflict_on_active_count: (v) => typeof v === "number",
+};
+const CARD_FIELDS = Object.fromEntries(Object.keys(JUDGED_FIELDS).map((name) => [name, true]));
+const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${READY_CARDS_SUBCOMMAND}`;
+/** The row, or null when any field `isReadyCard` judges is missing or the wrong type: a card never counts on a guess. */
+function parseCardRow(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return null;
+    const r = raw;
+    const assigned = r.assigned_agent;
+    if (typeof r.id !== "string" || typeof r.type !== "string" || typeof r.title !== "string")
+        return null;
+    if (!(assigned === null || typeof assigned === "string"))
+        return null;
+    if (!Object.entries(JUDGED_FIELDS).every(([name, valid]) => valid(r[name])))
+        return null;
+    return r;
+}
+/** Whether a ToDo card could be claimed right now (see the module banner). */
+export function isReadyCard(card) {
+    return (DISPATCHABLE_TYPES.has(card.type) &&
+        card.assigned_agent === null &&
+        card.dispatch === null &&
+        card.blocked === null &&
+        card.open_problem_count === 0 &&
+        !card.waiting_on &&
+        card.conflict_on_active_count === 0);
+}
+function classifyStatus(status) {
+    if (status === 401 || status === 403)
+        return "unauthorized";
+    if (status === 404)
+        return "not_found";
+    if (status < 200 || status >= 300)
+        return "http_error";
+    return null;
+}
+/** The session's plan and its boards, `null` when the dashboard has the session on no plan, or a failure. */
+async function readSessionPlan(options, deps) {
+    const sent = await sendSessionRequest(options, "/api/plans/mine", { method: "GET" }, deps);
+    if ("ok" in sent)
+        return sent;
+    const parsed = tryParseJsonBody(sent.text);
+    const body = parsed.ok ? parsed.body : null;
+    // A session on no plan is the ordinary answer, not a fault: a 409 `session_not_connected`.
+    if (sent.status === 409 && body?.error === "session_not_connected")
+        return { ok: true, plan: null };
+    const failed = classifyStatus(sent.status);
+    if (failed !== null)
+        return { ok: false, reason: failed };
+    if (body === null ||
+        typeof body.id !== "number" ||
+        !Array.isArray(body.boards) ||
+        !body.boards.every((b) => typeof b === "string")) {
+        return { ok: false, reason: "bad_response" };
+    }
+    return { ok: true, plan: { planId: body.id, boards: body.boards } };
+}
+/** The plan's ready cards on one board. */
+async function readBoardReadyCards(options, deps, planId, board) {
+    const filter = encodeURIComponent(JSON.stringify({ plan_id: planId, status_derived: "ToDo" }));
+    const fields = encodeURIComponent(JSON.stringify(CARD_FIELDS));
+    const sent = await sendSessionRequest(options, `/api/issues?board=${encodeURIComponent(board)}&filter=${filter}&fields=${fields}&limit=${CARDS_PAGE_SIZE}&sort=priority`, { method: "GET" }, deps);
+    if ("ok" in sent)
+        return sent;
+    const failed = classifyStatus(sent.status);
+    if (failed !== null)
+        return { ok: false, reason: failed };
+    const parsed = tryParseJsonBody(sent.text);
+    const body = parsed.ok ? parsed.body : null;
+    if (body === null || !Array.isArray(body.issues) || typeof body.total !== "number")
+        return { ok: false, reason: "bad_response" };
+    // A truncated read would silently miss ready cards: fail loudly instead.
+    if (body.total > body.issues.length)
+        return { ok: false, reason: "too_many_cards" };
+    const cards = [];
+    for (const raw of body.issues) {
+        const row = parseCardRow(raw);
+        if (row === null)
+            return { ok: false, reason: "bad_response" };
+        if (isReadyCard(row))
+            cards.push({ id: row.id, title: row.title });
+    }
+    return { ok: true, cards };
+}
+/** One authenticated read of the session's plan's ready cards, across every board the plan spans. Never throws. */
+export async function fetchReadyCards(options, deps) {
+    const read = await readSessionPlan(options, deps);
+    if (!read.ok)
+        return read;
+    if (read.plan === null)
+        return { ok: true, planId: null, cards: [] };
+    const { planId } = read.plan;
+    const perBoard = await Promise.all(read.plan.boards.map((board) => readBoardReadyCards(options, deps, planId, board)));
+    const cards = [];
+    for (const onBoard of perBoard) {
+        if (!onBoard.ok)
+            return onBoard;
+        cards.push(...onBoard.cards);
+    }
+    return { ok: true, planId: read.plan.planId, cards };
+}
+/** The bin's `ready-cards` subcommand, wired to the real process. */
+export async function runReadyCardsCommand(argv, env = process.env, 
+/** Test seams: the home the connection record is read from, and the HTTP client. */
+seams = {}) {
+    if (argv.length !== 0) {
+        process.stderr.write(`unexpected arguments\n${USAGE}\n`);
+        return 1;
+    }
+    // `resolveSessionOptions` words a missing session id as the usage text alone; every stderr line here starts with its reason.
+    if (!env.CLAUDE_CODE_SESSION_ID) {
+        process.stderr.write(`no_session_id: CLAUDE_CODE_SESSION_ID is not set\n${USAGE}\n`);
+        return 1;
+    }
+    const resolved = await resolveSessionOptions(env, { home: seams.home }, USAGE);
+    if (!resolved.ok) {
+        // `detail` names its reason except for a missing session id, where it is only the usage text.
+        const named = resolved.detail.startsWith(`${resolved.output.reason}:`);
+        process.stderr.write(named ? `${resolved.detail}\n` : `${resolved.output.reason}: CLAUDE_CODE_SESSION_ID is not set\n${resolved.detail}\n`);
+        return 1;
+    }
+    const output = await fetchReadyCards(resolved.options, seams.deps ?? { fetch: (input, init) => fetch(input, init), requestTimeoutMs: READY_CARDS_REQUEST_TIMEOUT_MS });
+    if (!output.ok) {
+        process.stderr.write(`${output.reason}: could not read the plan's ready cards from the dashboard\n`);
+        return 1;
+    }
+    process.stdout.write(`${JSON.stringify({ plan_id: output.planId, cards: output.cards })}\n`);
+    return 0;
+}

package/package.json

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