@thehammer/danx-dashboard-mcp 0.1.282 → 0.1.284

package/README.md

@@ -50,7 +50,7 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 | `danxbot_api_list` | No args. Lists the routes this caller's credential may reach as `{routes: ["METHOD /path"]}` (one bare string per route, exactly what `danxbot_api_spec` takes; a dispatch's own callbacks are in it) — 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. |
 | `attach_file` | `{card_id, path, replaces?, primary?, filename?, content_type?}` — the server reads the LOCAL file at `path` (absolute, `/tmp/a.png` or `C:\x\a.png`) and uploads it, so its bytes never pass through the agent's context. `replaces: <attachment id>` swaps that attachment's file in place (`PUT /api/issues/:id/attachments/:aid`: same id, name and cover flag) instead of adding one; `primary: true` makes it the card's single cover, atomically with the write. Reply: `{issue: <compact row>, attachment_id, url, thumbnail_url, is_primary}`. Shown to a key holding `cards.edit` (DX-4523); a dispatch profile still receives it only when its catalog selection names it (`slack-agent` and `work`, DX-4386, through `extraTools`). A screenshot of browser-visible work: first `primary: true`, then `replaces` at each milestone. |
-| `design_publish` | `{target, dir, card_id?, board?, title?, summary?, description?}` — builds a design with the TARGET repo's own Vite (resolved from the target's root at run time: this package depends on neither `vite` nor `playwright`) and publishes it as a revision of a Design card (DX-4077). `target` names one of the repo's design targets, read from the dashboard (`GET /api/repos/<repo>`, edited in Settings > Board > General), never from a file; `dir` holds `Design.tsx` under the target's root. The repo is the board's `repo_name` (`GET /api/boards/<board>`). The build runs in `<root>/.danx-design/<build-id>/` (removed afterwards), the page is written to `<tmpdir>/danx-design/<build-id>.html` before the upload, and a 1280x800 screenshot is taken when Playwright resolves from the target or this server's cwd (`screenshot: "none: <reason>"` otherwise, never a failed publish). Without `card_id` it creates the Design card first; a refused revision comes back verbatim with that `card_id`. Shown to a key holding `cards.edit`; opt-in, so a dispatch profile receives it only when its catalog selection names it (none does yet). |
+| `design_publish` | `{target, dir, card_id?, board?, title?, summary?, description?}` — builds a design with the TARGET repo's own Vite (resolved from the target's root at run time: this package depends on neither `vite` nor `playwright`) and publishes it as a revision of a Design card (DX-4077). `target` names one of the repo's design targets, read from the dashboard (`GET /api/repos/<repo>`, edited in Settings > Board > General), never from a file; `dir` holds `Design.tsx` under the target's root. The repo is the board's `repo_name` (`GET /api/boards/<board>`). The build runs in `<root>/.danx-design/<build-id>/` (removed afterwards), in a short-lived `node` child process that exits when the build ends, so the server never holds the design's worktree files open and no esbuild outlives the publish (DX-4727), the page is written to `<tmpdir>/danx-design/<build-id>.html` before the upload, and a 1280x800 screenshot is taken when Playwright resolves from the target or this server's cwd (`screenshot: "none: <reason>"` otherwise, never a failed publish). Without `card_id` it creates the Design card first; a refused revision comes back verbatim with that `card_id`. Shown to a key holding `cards.edit`; opt-in, so a dispatch profile receives it only when its catalog selection names it (none does yet). |
 | `request_permission` | `{permissions, reason}` — asks a person to grant this key ONE MORE permission (see "Asking for one more permission" above). Answers at once with the approval URL and confirm code; the grant is picked up in the background. |
 
 There is no dedicated `resource_fields` tool (removed DX-3465 — it was a thin wrapper `danxbot_api` already reaches with no agent-specific behavior earning it its own tool). What an opt-in field TREE may name for one resource (`{resource, description, always, hashes, fields, relations}`) is `danxbot_api({method:"GET", path:"/api/resources/<resource>/fields"})` — install-global, no `board`; `resource: "issue"` is the root, and a relation's own `resource` in the response is what to call this again with, one level deeper.
@@ -61,7 +61,7 @@ Card and plan reads/writes go through `danxbot_api` against the issue/plan route
 
 ## `plan_events_wait` — a working session's plan events (DX-4233)
 
-A program calls this, not a person: the danxbot Claude Code plugin's relay loop, inside the session, calls it over and over on the session's own danx-dashboard MCP server and hands every event it gets to the session. The `bridge` subcommand is gone: no process is spawned, no `npx` cold start, and nothing outlives the session, because the stream lives in the MCP server, which ends with its session.
+A program calls this, not a person: the danxbot Claude Code plugin's relay loop, inside the session, calls it over and over on the session's own danx-dashboard MCP server and hands every event it gets to the session. A plan-orchestrator dispatch (a headless session that works one plan) has no plugin relay, so it keeps ONE background waiter sub-agent that loops on this tool until events exist and returns them with the last cursor, and the orchestrator passes that cursor to the next waiter it arms (DX-4667); the `plan-orchestrator` profile alone is granted the tool on a dispatch (it is an opt-in tool). The `bridge` subcommand is gone: no process is spawned, no `npx` cold start, and nothing outlives the session, because the stream lives in the MCP server, which ends with its session.
 
 Input `{plan_id: number, cursor: string | null, timeout_ms: 1000..30000, transcript_path?: string}`. Answer, one of:
 

package/dist/design-build-child.js

@@ -0,0 +1,17 @@
+/**
+ * DX-4727 - the short-lived process `buildDesign` runs the target's Vite build in. Its one argument is a JSON `ViteBuildInput`.
+ * Everything Vite loads (native modules, the esbuild service) belongs to this process and is released when it exits, so the
+ * long-lived MCP server never holds a file of the design's worktree. A failure writes its message to stderr and exits 1; the
+ * parent turns that text into the tool's error.
+ */
+import { runViteBuild } from "./design-build.js";
+try {
+    await runViteBuild(JSON.parse(process.argv[2]));
+    // An explicit exit: Vite's esbuild service would otherwise keep the loop alive until it is stopped. The empty write's callback
+    // runs once earlier stderr output (Vite's warnings) has been flushed, so the exit cannot cut it off.
+    process.stderr.write("", () => process.exit(0));
+}
+catch (error) {
+    // Vite's build() rethrows without logging (only its CLI logs), so the message is written once, here.
+    process.stderr.write(error instanceof Error ? error.message : String(error), () => process.exit(1));
+}

package/dist/design-build.js

@@ -9,12 +9,13 @@
  * This module carries no validator for the document it produces: that the document is self-contained is checked by exactly ONE
  * validator, the dashboard's own parse5 check on the revision route, whose 400 comes back to the caller verbatim.
  */
+import { spawn } from "node:child_process";
 import { randomBytes } from "node:crypto";
 import { mkdir, readdir, readFile, rm, rmdir, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
-import { pathToFileURL } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { isStrictlyInside, repoRelative } from "./design-checkout.js";
 /** The directory (inside the target root) every build gets its own subdirectory of; the target's `.gitignore` names it. */
 export const BUILD_ROOT_DIR = ".danx-design";
@@ -187,9 +188,97 @@ export function assertConfigContained(merged, rootAbs, buildDir, indexHtml) {
     }
 }
 /**
- * Build the design: generate the three files in a fresh `<root>/.danx-design/<build-id>/`, load the target's Vite and its config,
- * merge the overrides, guard, build, read the output, fold it into one document. The build dir is removed in a `finally`; a failed
- * cleanup never replaces the error that came first.
+ * Run the target's Vite build over the generated files: load its config, merge the overrides, guard, build. This runs ONLY inside the
+ * short-lived build child (`design-build-child.ts`), never in the MCP server: Vite loads native modules (rollup, lightningcss,
+ * @tailwindcss/oxide) and starts an esbuild service, and in the long-lived server those stayed locked / running after the publish and
+ * stranded the design's worktree on Windows (DX-4727).
+ */
+export async function runViteBuild(input) {
+    const { rootAbs, buildDir, indexHtml } = input;
+    const vite = await loadTargetVite(rootAbs);
+    // "warn": Vite logs info to stdout; warnings and errors go to stderr, which the parent relays.
+    const loaded = await vite.loadConfigFromFile({ command: "build", mode: "production" }, input.viteConfigAbs, rootAbs, "warn");
+    if (loaded === null)
+        throw new Error(`design_publish: Vite found no config at ${input.viteConfigAbs}`);
+    const merged = vite.mergeConfig(loaded.config, {
+        // The repo's config is already loaded: the build must not read it a second time.
+        configFile: false,
+        root: rootAbs,
+        base: "./",
+        logLevel: "warn",
+        cacheDir: path.join(buildDir, VITE_CACHE_DIR),
+        build: {
+            outDir: path.join(buildDir, OUT_DIR),
+            assetsInlineLimit: () => true,
+            cssCodeSplit: false,
+            modulePreload: false,
+            emptyOutDir: false,
+            reportCompressedSize: false,
+            rollupOptions: { input: indexHtml, output: { inlineDynamicImports: true } },
+        },
+    });
+    assertConfigContained(merged, rootAbs, buildDir, indexHtml);
+    await vite.build(merged);
+}
+/** The build child's entry: `design-build-child.js` once compiled, `.ts` when the package runs from source (tests, `npm run dev`). */
+function childEntry() {
+    const here = fileURLToPath(import.meta.url);
+    const ext = path.extname(here);
+    const file = path.join(path.dirname(here), `design-build-child${ext}`);
+    // Source runs need tsx to load the .ts child; the compiled package has no such dependency.
+    return { file, execArgv: ext === ".ts" ? ["--import", pathToFileURL(createRequire(import.meta.url).resolve("tsx/esm")).href] : [] };
+}
+/** How long the build child may run before it is killed: a hung Vite must not hold the tool call (and the design's files) forever. */
+export const BUILD_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * Run the Vite build in a fresh `node` child and wait for it to exit. When the child exits, the OS releases every module it loaded
+ * and its esbuild service ends with it, so nothing of the build outlives the publish (DX-4727). A failed build rejects with everything
+ * the child wrote to stdout and stderr, verbatim; a child still running after `timeoutMs` is killed and rejects with the output so far;
+ * warnings from a good build are relayed to this process's stderr.
+ */
+export async function runViteBuildInChild(input, timeoutMs = BUILD_TIMEOUT_MS) {
+    const { file, execArgv } = childEntry();
+    const done = await new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [...execArgv, file, JSON.stringify(input)], {
+            cwd: input.rootAbs,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        let text = "";
+        let timedOut = false;
+        for (const stream of [child.stdout, child.stderr]) {
+            stream.setEncoding("utf8");
+            stream.on("data", (chunk) => void (text += chunk));
+        }
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+        }, timeoutMs);
+        child.once("error", (err) => {
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.once("close", (code, signal) => {
+            clearTimeout(timer);
+            resolve({ code, signal, text, timedOut });
+        });
+    });
+    const output = done.text.trim();
+    if (done.timedOut) {
+        throw new Error(`design_publish: the build did not finish within ${Math.round(timeoutMs / 1000)}s and was killed${output === "" ? "" : `; its output so far:
+${output}`}`);
+    }
+    if (done.code !== 0) {
+        const ended = done.signal !== null ? `was killed by ${done.signal}` : `exited with code ${String(done.code)}`;
+        throw new Error(output || `design_publish: the build process ${ended} and wrote nothing`);
+    }
+    if (done.text !== "")
+        process.stderr.write(done.text);
+}
+/**
+ * Build the design: generate the three files in a fresh `<root>/.danx-design/<build-id>/`, run the target's Vite over them in a
+ * child process, read the output, fold it into one document. The build dir is removed in a `finally`; a failed cleanup never
+ * replaces the error that came first.
  */
 export async function buildDesign(input) {
     const buildDir = path.join(input.rootAbs, BUILD_ROOT_DIR, input.buildId);
@@ -201,32 +290,8 @@ export async function buildDesign(input) {
         await writeFile(indexHtml, files.indexHtml, "utf8");
         await writeFile(path.join(buildDir, ENTRY_FILE), files.entry, "utf8");
         await writeFile(path.join(buildDir, CSS_FILE), files.css, "utf8");
-        const vite = await loadTargetVite(input.rootAbs);
-        // "warn": Vite logs info to stdout, which on this stdio MCP server is the protocol channel; warnings and errors go to stderr.
-        const loaded = await vite.loadConfigFromFile({ command: "build", mode: "production" }, input.viteConfigAbs, input.rootAbs, "warn");
-        if (loaded === null)
-            throw new Error(`design_publish: Vite found no config at ${input.viteConfigAbs}`);
-        const outDir = path.join(buildDir, OUT_DIR);
-        const merged = vite.mergeConfig(loaded.config, {
-            // The repo's config is already loaded: the build must not read it a second time.
-            configFile: false,
-            root: input.rootAbs,
-            base: "./",
-            logLevel: "warn",
-            cacheDir: path.join(buildDir, VITE_CACHE_DIR),
-            build: {
-                outDir,
-                assetsInlineLimit: () => true,
-                cssCodeSplit: false,
-                modulePreload: false,
-                emptyOutDir: false,
-                reportCompressedSize: false,
-                rollupOptions: { input: indexHtml, output: { inlineDynamicImports: true } },
-            },
-        });
-        assertConfigContained(merged, input.rootAbs, buildDir, indexHtml);
-        await vite.build(merged);
-        const built = await readBuildOutput(outDir);
+        await runViteBuildInChild({ rootAbs: input.rootAbs, viteConfigAbs: input.viteConfigAbs, buildDir, indexHtml });
+        const built = await readBuildOutput(path.join(buildDir, OUT_DIR));
         return { html: inlineAssets(built.html.text, built.js, built.css), buildId: input.buildId };
     }
     catch (error) {

package/dist/index.js

@@ -172,7 +172,7 @@ let permissionRequests;
 // DX-4523 - late-bound with `access` and `client`; see `tool-surface.ts` and `permission-watch.ts`.
 let toolAccessSync;
 let permissionWatch;
-// DX-4233 - late-bound with `access`; see `plan-events-relay.ts`. The plugin's relay loop calls `plan_events_wait` on it.
+// DX-4233 - late-bound with `access`; see `plan-events-relay.ts`. The plugin's relay loop (a person's session) and a plan orchestrator's waiter sub-agent (DX-4667) call `plan_events_wait` on it.
 let planEventRelay;
 /**
  * Compose the dispatch's qualified board id (`<repo>:<slug>`) from the two env
@@ -788,15 +788,16 @@ async (args) => {
 });
 // ---------------- plan_events_wait (DX-4233) ----------------
 strictTool("plan_events_wait", 
-// DX-4233 - for the danxbot plugin's relay loop, not for a model to call. It answers `events` (each `{cursor, text}`; empty after
-// `timeout_ms`), the cursor to send being the last delivered event's, or `stopped` with the remedy to tell the session. General-audience text
-// (DX-4550): nothing here names our own setup.
-"Waits for events on the plan this session is connected to. For the danxbot plugin's relay, which calls it in a loop " +
-    "and hands every event to the session: a model never calls it. `plan_id` is the plan the session is on (a different " +
-    "plan than the last call's starts clean). `cursor` is the `cursor` of the last event delivered, as answered (null " +
+// DX-4233 - for the danxbot plugin's relay loop. DX-4667 - and for a background waiter sub-agent of a plan orchestrator, which
+// loops on it until events exist and returns them (and the cursor) to the orchestrator it wakes. It answers `events` (each
+// `{cursor, text}`; empty after `timeout_ms`), the cursor to send being the last delivered event's, or `stopped` with the remedy
+// to tell the session. General-audience text (DX-4550): nothing here names our own setup.
+"Waits for events on the plan this session is connected to. For a relay or a background waiter that calls it in a loop " +
+    "and hands every event to the session; do not call it for any other reason. `plan_id` is the plan the session is on (a " +
+    "different plan than the last call's starts clean). `cursor` is the `cursor` of the last event delivered, as answered (null " +
     "when none). Answers `{events: [{cursor, text}]}`, with `events` empty once `timeout_ms` passes, or `{stopped: " +
     "{reason, detail, fix}}` when the stream ended: tell the session the `fix`. An event stays until a later call's " +
-    "`cursor` passes it. " +
+    "`cursor` passes it. Only one wait is pending per session: a newer call ends the older. " +
     "`transcript_path` is the session's transcript file, for its usage and title.", {
     plan_id: z.number().int().positive().describe("Id of the plan this session is connected to."),
     cursor: z

package/dist/plan-events-relay.js

@@ -1,8 +1,10 @@
 /**
  * DX-4233 - the IN-PROCESS relay of a session's plan events: what the `plan_events_wait` tool serves.
  *
- * WHO CALLS IT. The danxbot plugin's relay loop, inside the Claude Code session, calls `plan_events_wait` over and over on
- * this session's own danx-dashboard MCP server and hands every record it gets to the session. This class is everything on the
+ * WHO CALLS IT. In a person's session, the danxbot plugin's relay loop calls `plan_events_wait` over and over on this
+ * session's own danx-dashboard MCP server and hands every record it gets to the session. In a plan orchestrator's dispatch
+ * (DX-4667), which loads no relay, a background waiter sub-agent calls it the same way and returns the records and the last
+ * cursor to the orchestrator. This class is everything on the
  * server side of that call: it opens the session's dashboard event stream (the mint / stream / heartbeat contract of
  * `session-stream.ts`), buffers records for the caller and reports the session's listener health. There is no process to start,
  * watch or kill: the stream lives exactly as long as the MCP server, which lives exactly as long as its session.
@@ -137,7 +139,7 @@ export class PlanEventRelay {
             this.pendingStop = null;
             return { stopped };
         }
-        // DX-4233: a server holding no key answers a stop without calling the dashboard (a dispatch never reaches here).
+        // DX-4233: a server holding no key answers a stop without calling the dashboard (a dispatch always holds its env key, so it never takes this branch).
         if (this.deps.auth() === null) {
             return { stopped: this.stopRecord("credential_unavailable", "this session holds no dashboard key") };
         }

package/dist/tool-access.js

@@ -29,7 +29,6 @@ const BOOTSTRAP = { permission: null, callback: null };
 const needs = (permission) => ({ permission, callback: null });
 /** DX-4632: usable with no key (a session that has not signed in yet) and only on a person's session. */
 const OPERATOR_SESSION_BOOTSTRAP = { permission: null, callback: null, operatorSessionOnly: true };
-const operatorSessionNeeds = (permission) => ({ permission, callback: null, operatorSessionOnly: true });
 const needsAndPostsTo = (permission, callback) => ({ permission, callback });
 /**
  * Every tool this server registers, with what makes it usable. `index.ts` refuses to register a tool that is not
@@ -49,10 +48,14 @@ export const TOOL_ACCESS = {
     design_publish: needs("cards.edit"),
     // DX-4233 - the plugin's relay waits on the session's plan events here: it opens the listener ticket
     // (`POST /api/plan-sessions/me/stream-ticket`) and heartbeats (`.../me/heartbeat`), both `plans.view`.
-    plan_events_wait: operatorSessionNeeds("plans.view"),
+    // DX-4667 - not operator-session-only: a plan orchestrator's dispatch calls it too, through a background waiter sub-agent that
+    // wakes the orchestrator when a person answers. What keeps it off every other dispatch is the opt-in (`MCP_SERVER_OPT_IN_TOOLS`,
+    // `src/tokens/tool-defs.ts`) granted to the `plan-orchestrator` profile alone, not this table.
+    plan_events_wait: needs("plans.view"),
     // DX-4632 - the plugin's session-start hook asks which plan the session this one replaced was working. A restarted session boots
-    // signed out, so it holds no permission: like `plan_connect` it is a bootstrap tool, and (like `plan_events_wait`) a person's
-    // session's only. The lookup asks the dashboard as the predecessor, with the credential the predecessor's record names.
+    // signed out, so it holds no permission: like `plan_connect` it is a bootstrap tool, and a person's session's only (a dispatch
+    // never loads the plugin that calls it). The lookup asks the dashboard as the predecessor, with the credential the predecessor's
+    // record names.
     restart_notice: OPERATOR_SESSION_BOOTSTRAP,
     // The one dispatch callback that stays a tool (DX-4525): it reads local files. Its dashboard route's own policy names the
     // permission (`route-policies/index.ts`); every other callback is a `danxbot_api` call to a route under `callback-routes.ts`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.282",
+  "version": "0.1.284",
   "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, request_permission, attach_file, and danxbot_slack_reply) (DX-3465, PLN-11 R-25).",
   "license": "MIT",
   "type": "module",