@thehammer/danx-dashboard-mcp 0.1.45 → 0.1.47

package/dist/handlers.js

@@ -581,3 +581,73 @@ export async function issueAttach(client, args, deps = {}) {
         board: args.board,
     });
 }
+/* ── Plans: what a connected session may read and add to (DX-2683) ────────── */
+const PLANS_BASE_PATH = "/api/plans";
+const PLAN_SESSIONS_BASE_PATH = "/api/plan-sessions";
+/** Every plan, plus which one THIS session is connected to. */
+export async function planList(client) {
+    return client.request({ method: "GET", path: "", basePath: PLANS_BASE_PATH });
+}
+/**
+ * One plan, entire — its cards, the boards they cover, its goals + rules +
+ * caveats, its architecture document, and the sessions working on it. ONE
+ * call rather than five, which is what keeps this tool surface small enough
+ * to be worth an agent's context.
+ */
+export async function planGet(client, args = {}) {
+    return client.request({
+        method: "GET",
+        path: args.plan_id === undefined ? "/mine" : `/${args.plan_id}/full`,
+        basePath: PLANS_BASE_PATH,
+    });
+}
+/**
+ * Connect THIS session to a plan — the same write the operator's Connect
+ * action performs, reaching the same server-side code path. `me` in the URL
+ * is resolved from the forwarded session id, so this can only ever bind the
+ * caller's own session.
+ *
+ * A session already on another plan is MOVED, and the response says which
+ * plan it left (`movedFrom`).
+ */
+export async function planConnect(client, args) {
+    return client.request({
+        method: "POST",
+        path: "/me/plan",
+        basePath: PLAN_SESSIONS_BASE_PATH,
+        body: { plan_id: args.plan_id },
+    });
+}
+/** Add a goal, rule or caveat to the connected plan. */
+export async function planAddRecord(client, args) {
+    return client.request({
+        method: "POST",
+        path: "/mine/records",
+        basePath: PLANS_BASE_PATH,
+        body: { kind: args.kind, body: args.body },
+    });
+}
+/** Add an existing card to the connected plan. */
+export async function planAddCard(client, args) {
+    return client.request({
+        method: "POST",
+        path: "/mine/cards",
+        basePath: PLANS_BASE_PATH,
+        body: { card_id: args.card_id },
+    });
+}
+/**
+ * Write the connected plan's architecture document, under the same
+ * optimistic-concurrency guard the dashboard editor uses: `base_hash` must be
+ * the `contentHash` the last `plan_get` returned, and a stale base is refused
+ * with `{error: "stale_plan_architecture", currentHash}` rather than
+ * overwriting whoever wrote in between.
+ */
+export async function planSetArchitecture(client, args) {
+    return client.request({
+        method: "PUT",
+        path: "/mine/architecture",
+        basePath: PLANS_BASE_PATH,
+        body: { content: args.content, base_hash: args.base_hash },
+    });
+}

package/dist/http-client.js

@@ -18,6 +18,17 @@ export class DashboardHttpClient {
         if (this.config.traceparent) {
             headers["traceparent"] = this.config.traceparent;
         }
+        // DX-2683 — the working session's identity, stamped at the SAME single
+        // choke point as Authorization above, and for the same reason: it must
+        // ride EVERY call, not the plan calls. That is what lets the dashboard
+        // learn a session exists — and keep its last-active time current — purely
+        // from the card work the agent was already doing, with no cooperation
+        // from the agent and no per-tool parameter it could omit or falsify.
+        // Absent outside a Claude Code session; then nothing is stamped.
+        if (this.config.session) {
+            headers["x-danx-session-id"] = this.config.session.id;
+            headers["x-danx-session-title"] = this.config.session.title;
+        }
         let bodyString;
         if (args.body !== undefined) {
             headers["Content-Type"] = "application/json";

package/dist/index.js

@@ -31,6 +31,20 @@
  *   - master_plan_list       GET    /api/master-plan
  *   - master_plan_get_page   GET    /api/master-plan/page (DX-2083 / DX-2484)
  *   - master_plan_set_page   PUT    /api/master-plan/page (DX-2083 / DX-2484)
+ *   - plan_list              GET    /api/plans (DX-2683)
+ *   - plan_get               GET    /api/plans/:id/full | /api/plans/mine
+ *   - plan_connect           POST   /api/plan-sessions/me/plan
+ *   - plan_add_record        POST   /api/plans/mine/records
+ *   - plan_add_card          POST   /api/plans/mine/cards
+ *   - plan_set_architecture  PUT    /api/plans/mine/architecture
+ *
+ * DX-2683 — THE PLAN TOOLS ARE SESSION-BOUND, and asymmetrically so. Reads
+ * may name any plan; WRITES take no plan id at all and act on the plan this
+ * session is connected to, resolved server-side from the session id this
+ * package forwards on every request. A session therefore cannot modify a plan
+ * it is not connected to, whatever id it believes. A write from an
+ * unconnected session is refused loudly (`session_not_connected`), never
+ * silently dropped and never guessed at.
  *
  * BOARD-ONLY (DX-1171): board is the first-level concept; repo is
  * DERIVED from board server-side, never passed. The package composes the
@@ -55,12 +69,13 @@
  * agent reads `body.error` + structured fields to decide next action.
  * 5xx and network failures throw — never silently swallowed.
  */
+import { basename } from "node:path";
 import { isEntrypointModule } from "./entrypoint.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { DashboardHttpClient } from "./http-client.js";
-import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueQualityGate, issueQualityGateVerdict, issueRequiresHuman, issueRetro, issueTransition, issueTriage, masterPlanGetPage, masterPlanList, masterPlanSetPage, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
+import { issueAttach, issueChecklist, issueComment, issueCreate, issueDependency, issueEdit, issueGet, issueList, issueQualityGate, issueQualityGateVerdict, issueRequiresHuman, issueRetro, issueTransition, issueTriage, masterPlanGetPage, masterPlanList, masterPlanSetPage, planAddCard, planAddRecord, planConnect, planGet, planList, planSetArchitecture, repoKnowledgeGet, repoKnowledgeSet, } from "./handlers.js";
 import { PRIORITY_TIER_WORDS } from "./priority.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -105,9 +120,42 @@ function boot() {
         // outbound call so the agent's card writes chain under the launch; absent
         // (untraced dispatch) → omitted, and the dashboard mints a fresh root.
         traceparent: readEnvOptional("DANXBOT_TRACEPARENT"),
+        // DX-2683 — the working session, when there is one. See below.
+        session: readSessionConfig(),
     };
     client = new DashboardHttpClient(config);
 }
+/**
+ * DX-2683 — WHO THIS SESSION IS, read from the environment Claude Code
+ * already provides.
+ *
+ * `CLAUDE_CODE_SESSION_ID` is set on every process an interactive Claude Code
+ * session spawns — this server among them — so no launcher, no dispatch
+ * overlay and no agent cooperation is needed for a session to be identifiable.
+ * The same variable is what `src/agent/nested-claude-preflight.ts` already
+ * relies on to detect a nested session, so this is an established fact about
+ * the runtime rather than a new assumption.
+ *
+ * OPTIONAL, unlike every other env this package reads. A process running
+ * outside a Claude Code session has no session to report; it sends no session
+ * headers and behaves exactly as this package did before. Requiring it would
+ * break the tool-defs generator, the drift test, and any non-Claude consumer.
+ *
+ * The TITLE is a CREATION-TIME value only — the dashboard stamps it when the
+ * session first registers and never overwrites it afterwards, because the
+ * operator may have renamed it. `DANX_SESSION_TITLE` lets a launcher say what
+ * a session is; absent that, the working directory's name is what the session
+ * can honestly say about itself, and last-active time is what actually
+ * distinguishes two sessions in the same place.
+ */
+function readSessionConfig() {
+    const id = readEnvOptional("CLAUDE_CODE_SESSION_ID");
+    if (id === undefined)
+        return undefined;
+    const cwdName = basename(process.cwd());
+    const fallback = cwdName === "" ? `session ${id.slice(0, 8)}` : cwdName;
+    return { id, title: readEnvOptional("DANX_SESSION_TITLE") ?? fallback };
+}
 export const server = new McpServer({
     name: "danx-dashboard-mcp",
     version: "0.1.0",
@@ -319,13 +367,18 @@ server.tool("issue_edit", 'Patch prose + structured fields via PATCH /api/issues
     ...boardField,
 }, async (args) => jsonResult(await issueEdit(client, args)));
 // ---------------- issue_transition ----------------
-server.tool("issue_transition", "Stamp a lifecycle transition via POST /api/issues/:id/transition. **THIS IS THE ONLY WAY TO MOVE A CARD'S LIFECYCLE STATE** — DX-835 separated card lifecycle (this tool) from dispatch finalization (`mcp__danxbot__danxbot_complete`). The worker no longer infers card moves from `danxbot_complete.status`; agents that want the card to move MUST call this tool BEFORE calling `danxbot_complete`. Actions: ready (Review→ToDo), pickup (ToDo→In Progress — server checks every dispatch gate: ready_at, blocked_at, requires_human_reason, depends_on partners terminal, conflict_on partners idle; refuses 409 with failed_gate naming the cause; pass manual:true for OPERATOR-SESSION self-pickup — stamps dispatch_kind 'manual', bypasses every card-flow gate except terminal/deleted/already-dispatched, and the worker NEVER auto-transitions the card: no orphan-heal rollback, no Epic auto-rollup — use this whenever the work happens in YOUR current session rather than a worker dispatch, DX-946), rollback_pickup, **complete** (stamps completed_at — moves card to Done; this is YOUR explicit decision, not a side effect of danxbot_complete; REFUSES 409 on Epic if any phase child non-terminal — see non_terminal_phases[]; ALSO refuses 409 with failed_gate 'quality_gate_post' + failed_post_gates[] while any required POST quality gate row != pass — DX-1177), cancel (stamps cancelled_at — terminal), **block** (requires non-empty reason — stamps blocked_at + blocked_reason + clears dispatch; USE THIS when the CARD itself cannot proceed without human intervention; distinct from env-fault dispatch failures which use `danxbot_complete({status:'failed'})`), unblock, archive (parks to Backlog, clears ready_at), reopen (terminal→active, clears completed_at/cancelled_at/archived_at). Terminal cards refuse every action except reopen. Ladder timestamps preserved — forward stamps never clear earlier ones (CLAUDE.md Core Principle 2).", {
+server.tool("issue_transition", "Stamp a lifecycle transition via POST /api/issues/:id/transition. **THIS IS THE ONLY WAY TO MOVE A CARD'S LIFECYCLE STATE** — DX-835 separated card lifecycle (this tool) from dispatch finalization (`mcp__danxbot__danxbot_complete`). The worker no longer infers card moves from `danxbot_complete.status`; agents that want the card to move MUST call this tool BEFORE calling `danxbot_complete`. Actions: ready (Review→ToDo), pickup (ToDo→In Progress — server checks every dispatch gate: ready_at, blocked_at, requires_human_reason, depends_on partners terminal, conflict_on partners idle; refuses 409 with failed_gate naming the cause; pass manual:true for OPERATOR-SESSION self-pickup — stamps dispatch_kind 'manual', bypasses every card-flow gate except terminal/deleted/already-dispatched, and the worker NEVER auto-transitions the card: no orphan-heal rollback, no Epic auto-rollup — use this whenever the work happens in YOUR current session rather than a worker dispatch, DX-946), rollback_pickup, **complete** (stamps completed_at — moves card to Done; this is YOUR explicit decision, not a side effect of danxbot_complete; REFUSES 409 on Epic if any phase child non-terminal — see non_terminal_phases[]; ALSO refuses 409 with failed_gate 'quality_gate_post' + failed_post_gates[] while any required POST quality gate row != pass — DX-1177), cancel (stamps cancelled_at — terminal), **block** (requires non-empty reason — stamps blocked_at + blocked_reason + clears dispatch; USE THIS when the CARD itself cannot proceed without human intervention; distinct from env-fault dispatch failures which use `danxbot_complete({status:'failed'})`), unblock, archive (parks to Backlog, clears ready_at), reopen (terminal→active, clears completed_at/cancelled_at/archived_at). Terminal cards refuse every action except reopen. Ladder timestamps preserved — forward stamps never clear earlier ones (CLAUDE.md Core Principle 2). **DX-2282 — every path into In Progress now requires an identified claimer.** For `manual:true` pickup called from a DISPATCHED-AGENT session (this MCP tool, bearer = your dispatch token): you MUST pass `assigned_agent` set to YOUR resolved agent/profile name — omitting it, or passing the shared dispatch-token identity itself, is refused 409 `assigned_agent (required, distinguishing)`. A genuine human dashboard session may omit it (auto-resolved from the real logged-in user). Every pickup flavor (work/gate/manual) is refused 409 `assigned_agent (required)` if it would otherwise leave the card with no owner at all.", {
     id: z.string().min(1),
     action: z.enum(TRANSITION_ACTIONS),
     reason: z.string().optional(),
     summary: z.string().optional(),
     dispatch_id: z.string().min(1).optional(),
     manual: z.boolean().optional(),
+    assigned_agent: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("DX-2282 — REQUIRED for a manual:true pickup called by a dispatched agent (this MCP tool): your resolved agent/profile name, identifying YOU as the claimer. Never supply the generic shared dispatch-token identity — that is refused. Optional for a human dashboard session (auto-resolved from the real logged-in user). Ignored for every other action."),
     ...boardField,
 }, async (args) => jsonResult(await issueTransition(client, args)));
 // ---------------- issue_triage ----------------
@@ -496,6 +549,40 @@ server.tool("master_plan_set_page", 'Write one Master Plan page via PUT /api/mas
         .describe('The contentHash last read via master_plan_get_page ("" for a true first write). Omitted also normalizes to "" server-side, so it only succeeds against an empty/absent page — always get immediately before set.'),
     ...boardField,
 }, async (args) => jsonResult(await masterPlanSetPage(client, args)));
+// ---------------- plans (DX-2683) ----------------
+// THE BINDING ASYMMETRY IS IN THE SCHEMAS, NOT IN PROSE. `plan_get` takes an
+// optional `plan_id`; `plan_add_record`, `plan_add_card` and
+// `plan_set_architecture` take NO plan id in any form, so a connected session
+// cannot even express "write to that other plan". `plan_connect` takes one
+// because binding a session to a plan is the one operation that is ABOUT a
+// plan id — and it can only ever bind the caller's own session.
+server.tool("plan_list", "List every plan via GET /api/plans (DX-2683), and learn which plan THIS session is connected to. Plans are GLOBAL, not board-scoped: a plan is a named, dated set of cards an operator assembled by hand, and its cards may come from any repository. Returns `{ok, status, body: {plans: [{id, name, createdAt, cardCount, boards}], session}}`. `session` is your own registration — `{sessionId, title, planId, planName, firstSeenAt, lastActiveAt}` — or `null` if this process is not running inside a Claude Code session. A `planId` of null means you are connected to no plan: read any plan with `plan_get`, then `plan_connect` to the one you are working on (or ask the operator to connect you from the Plans list). NOTE this is NOT the board Master Plan (`master_plan_list`), which is a different feature entirely.", {}, async () => jsonResult(await planList(client)));
+server.tool("plan_get", "Read one plan WHOLE via GET /api/plans (DX-2683) — its member cards (with the boards they cover), its goals, rules and caveats, its architecture document, the sessions working on it, and your own session state. One call, not five. Pass `plan_id` to read ANY plan (browsing another plan is useful and changes nothing); OMIT it to read the plan this session is connected to. Omitting it while connected to no plan fails loud with `{error: \"session_not_connected\"}` — connect first. Returns `{plan, cards, boards, records: {goal: [], rule: [], caveat: []}, architecture: {content, contentHash, updatedAt, updatedBy}, sessions, session}`. ALWAYS `plan_get` immediately before `plan_set_architecture` and pass the returned `architecture.contentHash` back as `base_hash`.", {
+    plan_id: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("A plan id from `plan_list`. Omit to read the plan this session is connected to."),
+}, async (args) => jsonResult(await planGet(client, args)));
+server.tool("plan_connect", "Connect THIS session to a plan via POST /api/plan-sessions/me/plan (DX-2683) — the same binding the operator's Connect action writes, through the same server-side path. A session is connected to AT MOST ONE plan (enforced by the schema, not by convention); connecting while already on another plan MOVES you, and the response says which plan you left: `{ok, status, body: {session, movedFrom: {id, name} | null}}`. `movedFrom: null` means you were on no plan, or already on this one. It can only ever bind your OWN session — `me` is resolved from the session id this server forwards, never from anything you pass. After this, every plan WRITE tool acts on this plan, and no plan id is accepted anywhere.", {
+    plan_id: z.number().int().positive().describe("The plan id, from `plan_list`."),
+}, async (args) => jsonResult(await planConnect(client, args)));
+server.tool("plan_add_record", "Add a GOAL, RULE or CAVEAT to the plan this session is connected to, via POST /api/plans/mine/records (DX-2683). A goal is what the plan is FOR (the outcome the work is measured against — not a task). A rule is what must HOLD while it is worked. A caveat is what is known to be AWKWARD — the fact that will surprise the next person. Each gets a permanent short reference within the plan (`G-1`, `R-4`, `CAV-12`) allocated by the server, which is how a person cites it in a card or a commit. TAKES NO PLAN ID: the plan is resolved from your connected session, so you cannot write a plan you are not connected to. Not connected → `{error: \"session_not_connected\"}`; call `plan_connect` first. Returns the new record plus that kind's full list.", {
+    kind: z
+        .enum(["goal", "rule", "caveat"])
+        .describe("Which standing record this is. Determines the reference prefix."),
+    body: z.string().min(1).describe("The record's text. Plain text, not markdown."),
+}, async (args) => jsonResult(await planAddRecord(client, args)));
+server.tool("plan_add_card", "Add an existing card to the plan this session is connected to, via POST /api/plans/mine/cards (DX-2683). The card may live on ANY board — that is what a plan is for. Idempotent: re-adding a card already on the plan is a no-op, not an error, and a card may sit in several plans at once. This adds MEMBERSHIP only; it never edits the card. TAKES NO PLAN ID: the plan is resolved from your connected session. Not connected → `{error: \"session_not_connected\"}`. Unknown card → 404. Returns the plan's full member list.", {
+    card_id: z.string().min(1).describe("An existing card id, e.g. `DX-2683`."),
+}, async (args) => jsonResult(await planAddCard(client, args)));
+server.tool("plan_set_architecture", 'Write the ARCHITECTURE DOCUMENT of the plan this session is connected to, via PUT /api/plans/mine/architecture (DX-2683). One markdown document per plan — how the work is shaped, not a task list. `base_hash` MUST be the `architecture.contentHash` from the immediately-prior `plan_get`; the server compares it against the current hash and, on a mismatch, fails loud with `{ok: false, body: {error: "stale_plan_architecture", currentHash}}` rather than overwriting whoever wrote in between. On that refusal: re-`plan_get`, re-merge your changes into the fresh content, and retry with the new hash — never retry blindly. A never-written document reads as `contentHash: ""`, so a true first write passes `base_hash: ""`. Writing REPLACES the whole document, so send the full merged markdown, not a fragment. TAKES NO PLAN ID: the plan is resolved from your connected session.', {
+    content: z.string().describe("The complete markdown document, replacing what is stored."),
+    base_hash: z
+        .string()
+        .describe('The `architecture.contentHash` from the immediately-prior `plan_get` ("" for a true first write). Required — an absent hash is not read as "".'),
+}, async (args) => jsonResult(await planSetArchitecture(client, args)));
 // ---------------- main ----------------
 async function main() {
     boot();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.45",
+  "version": "0.1.47",
   "description": "Stdio MCP server wrapping danxbot's dashboard /api/issues/* normalized DB-backed HTTP routes for dispatched agents (DX-704 Phase 2).",
   "license": "MIT",
   "type": "module",