@thehammer/danx-dashboard-mcp 0.1.284 → 0.1.286

package/README.md

@@ -65,7 +65,7 @@ A program calls this, not a person: the danxbot Claude Code plugin's relay loop,
 
 Input `{plan_id: number, cursor: string | null, timeout_ms: 1000..30000, transcript_path?: string}`. Answer, one of:
 
-- `{events: [{cursor: string, text: string}]}`: every record the caller has not delivered, in arrival order (empty at the timeout). Each record carries the cursor to store once THAT record is delivered. There is no `id`: the caller compares nothing.
+- `{events: [{cursor: string, text: string, urgent: boolean}]}`: every record the caller has not delivered, in arrival order (empty at the timeout). Each record carries the cursor to store once THAT record is delivered. There is no `id`: the caller compares nothing. `urgent` (DX-4721) is decided in one place by the record's kind (`src/urgent-records.ts`): true for a critical usage-pacing stop and the revoked-key notice, false for everything else (activity events, nudge, resume message, digest, the relay's failure notice, an unreadable line). The caller adds an urgent record to a running turn at once and delivers any other after the turn ends; `urgent` never changes order, seq or acknowledgement. The dashboard writes no operator-stop record yet; when it does, it becomes one more kind in that function.
 - `{stopped: {reason, detail, fix}}`: a terminal outcome (`not_connected`, `plan_archived`, `unauthorized`, `key_revoked`, `mint_refused`, `mint_bad_response`, `session_is_worker`, `superseded`, `replaced`, `revoked`, `refused`, `credential_unavailable`, `relay_failed`). `fix` is the remedy text (`STOP_FIXES`, `src/stop-fixes.ts`). The next call starts from scratch.
 
 The contract the plugin builds against:

package/dist/design-publish.js

@@ -48,6 +48,9 @@ async function resolveBoard(client, args, deps) {
     return { ok: true, board };
 }
 export async function designPublish(client, args, deps) {
+    // DX-4729: refused before any call, so a blank note never leaves a built page, a screenshot or a card behind.
+    if (args.note.trim() === "")
+        fail("`note` is required: say what changed since the last revision, which decision note it answers and what is still open");
     // With `card_id` the card already exists: its title, summary and description are not this call's to set, and silently ignoring them would hide the mistake.
     if (args.card_id !== undefined) {
         const given = ["title", "summary", "description"].filter((k) => args[k] !== undefined);
@@ -103,6 +106,7 @@ export async function designPublish(client, args, deps) {
             method: "POST",
             path: `/api/issues/${encodeURIComponent(cardId)}/design/revisions`,
             body: {
+                note: args.note,
                 target: target.name,
                 entry: repoRelative(repoRoot, path.join(checked.dirAbs, DESIGN_FILE)),
                 source_files: sourceFiles,

package/dist/digest-hold.js

@@ -1,3 +1,4 @@
+import { isUrgent } from "./urgent-records.js";
 export const DIGEST_INTERVAL_MS = 10 * 60_000;
 export const DIGEST_PREFIX = "[plan events]";
 /** ONE combined record for every event held since the last flush. */
@@ -39,7 +40,7 @@ export class DigestHold {
         const entries = this.held;
         this.held = [];
         const ids = entries.map((e) => e.id).filter((id) => id !== null);
-        this.emit({ type: "event", id: ids.length === 0 ? null : Math.max(...ids), ids, text: formatDigest(entries), origin: null });
+        this.emit({ type: "event", id: ids.length === 0 ? null : Math.max(...ids), ids, text: formatDigest(entries), origin: null, urgent: isUrgent({ source: "digest" }) });
     }
     /**
      * Stop the timer WITHOUT flushing. For a stop where a newer listener already streams this session and will receive (and

package/dist/heartbeat-reporter.js

@@ -85,7 +85,7 @@ export class HeartbeatReporter {
             // dashboard call says the same.
             if (answer.revocation !== null && !this.revocationAnnounced) {
                 this.revocationAnnounced = true;
-                this.deps.announce(keyRevokedHalt(answer.revocation, false));
+                this.deps.announce(keyRevokedHalt(answer.revocation, false), "key_revoked");
             }
             return answer;
         })
@@ -104,7 +104,7 @@ export class HeartbeatReporter {
             // The session finds out, rather than continuing to believe it is connected.
             this.deps.announce(oneLine(`${DIGEST_PREFIX} this session's listener stopped reaching the dashboard for ` +
                 `${Math.round((HEARTBEAT_SILENT_FAILURE_THRESHOLD * HEARTBEAT_INTERVAL_MS) / 1000)}s while it still ` +
-                `believed it was streaming — forcing a fresh connection now.`));
+                `believed it was streaming — forcing a fresh connection now.`), "relay_notice");
             // End the CURRENT connection now, rather than wait on the stream reader's own read-idle timeout (which this exact
             // failure mode can outlive indefinitely: the connection reads as established and keeps producing keep-alive bytes,
             // only the outbound heartbeat silently never lands). The new attempt reconnects with the SAME ticket; the

package/dist/index.js

@@ -650,8 +650,12 @@ strictTool("design_publish", "Build a design against this repo's REAL components
     "`captured` (1280x800) or `none: <reason>` (no Playwright in the repo: the publish still succeeds). Build errors and a " +
     "refused revision (400, 413) come back verbatim; a refusal after the card was created carries its `card_id`: fix the " +
     "design and call again with it. Limits: the frame has no network, so a component that fetches its own data fails inside " +
-    "it (use fixture props); React only; targets are edited in Settings > Board > General, never in a file.", {
-    target: z.string().min(1).describe("A design target's name, as declared in Settings > Board > General (Design targets)."),
+    "it (use fixture props); React only; targets are a dashboard setting, read from `design_targets` of `GET /api/repos/<repo>`, never a file.", {
+    target: z.string().min(1).describe("A design target's name, as listed in `design_targets` of `GET /api/repos/<repo>` (`danxbot_api`, fields {design_targets: true})."),
+    note: z
+        .string()
+        .min(1)
+        .describe("The revision note, shown beside the revision on the card: what changed since the last revision, which decision note it answers, what is still open."),
     dir: z
         .string()
         .min(1)
@@ -790,14 +794,16 @@ async (args) => {
 strictTool("plan_events_wait", 
 // 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
+// `{cursor, text, urgent}`; 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: " +
+    "when none). Answers `{events: [{cursor, text, urgent}]}`, 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. Only one wait is pending per session: a newer call ends the older. " +
+    "`cursor` passes it. `urgent` is true for an event the session must hear at once (a critical usage limit, a revoked " +
+    "key) and false for every other: deliver an urgent one to the session even while it is working, and any other once its " +
+    "current turn ends. 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/listen.js

@@ -51,6 +51,7 @@
 import { errorCodeOf } from "./json-body.js";
 import { LINE_PREFIX, oneLine } from "./one-line.js";
 import { pacingRelayLine } from "./pacing-relay.js";
+import { isUrgent } from "./urgent-records.js";
 export const INITIAL_BACKOFF_MS = 1_000;
 export const MAX_BACKOFF_MS = 30_000;
 /** Three of the dashboard's 15 s keep-alives without a byte means the connection is dead. */
@@ -503,7 +504,7 @@ export async function runListener(options, deps) {
      * 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, scope) => {
+    const emitAdvisory = (message, what, invalidReason, format, sourceOf, scope) => {
         let parsed;
         let invalid;
         try {
@@ -514,7 +515,9 @@ export async function runListener(options, deps) {
             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, ...(scope === undefined ? {} : { scope }) });
+        // DX-4721: an unreadable frame is a fault line, never the frame it failed to be (a malformed `critical` pacing frame is not a stop).
+        const urgent = isUrgent(invalid === null ? sourceOf(parsed) : { source: "fault" });
+        deps.write({ type: "event", id: null, text, origin: null, urgent, ...(scope === undefined ? {} : { scope }) });
         return null;
     };
     const handle = (message) => {
@@ -537,13 +540,13 @@ export async function runListener(options, deps) {
             return { kind: "ended", reason: isKnownWireEndReason(reason) ? reason : "unknown" };
         }
         if (message.event === "nudge")
-            return emitAdvisory(message, "nudge", invalidNudgeReason, (p) => formatNudgeLine(p));
+            return emitAdvisory(message, "nudge", invalidNudgeReason, (p) => formatNudgeLine(p), () => ({ source: "nudge" }));
         // 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), "session");
+            return emitAdvisory(message, "pacing message", invalidPacingReason, (p) => formatPacingLine(p), (p) => ({ source: "pacing", level: p.level }), "session");
         // DX-4342 - the auto-resume's message once the limit that paused or stopped this session has reset: advisory like a pacing message.
         if (message.event === "resume")
-            return emitAdvisory(message, "resume message", invalidResumeReason, (p) => formatResumeLine(p), "session");
+            return emitAdvisory(message, "resume message", invalidResumeReason, (p) => formatResumeLine(p), () => ({ source: "resume" }), "session");
         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
@@ -577,7 +580,9 @@ export async function runListener(options, deps) {
         // 10-minute digest wait just because it happened to come from an agent or
         // a machine writer.
         const origin = invalid === null ? parsed.origin : null;
-        deps.write({ type: "event", id: knownId ? id : null, text, origin });
+        // DX-4721: an unreadable event is a fault line; a readable one is urgent by its kind (none is today).
+        const urgent = isUrgent(invalid === null ? { source: "activity", kind: parsed.kind } : { source: "fault" });
+        deps.write({ type: "event", id: knownId ? id : null, text, origin, urgent });
         if (knownId)
             remember(id);
         return null;

package/dist/plan-events-relay.js

@@ -57,6 +57,7 @@ import { HeartbeatReporter } from "./heartbeat-reporter.js";
 import { capResumeIds, DELIVERED_ID_MEMORY, HEALTHY_CONNECTION_MS, INITIAL_BACKOFF_MS, MAX_BACKOFF_MS, runListener, } from "./listen.js";
 import { classifyAdmissionRefusal, fetchPlanInventory, HEARTBEAT_INTERVAL_MS, heartbeatConnection, MAX_REFUSED_TICKETS_IN_A_ROW, mintTicket, } from "./session-stream.js";
 import { fixForStop } from "./stop-fixes.js";
+import { isUrgent } from "./urgent-records.js";
 /** The shortest and longest wait one call may ask for; a short ceiling keeps an orphaned waiter's life short. */
 export const WAIT_MIN_MS = 1_000;
 export const WAIT_MAX_MS = 30_000;
@@ -183,7 +184,7 @@ export class PlanEventRelay {
     }
     /** Everything buffered, each record with the cursor to store once it is delivered. */
     answer() {
-        return { events: this.buffer.map(({ seq, recent, text }) => ({ cursor: formatCursor({ seq, ids: recent }), text })) };
+        return { events: this.buffer.map(({ seq, recent, text, urgent }) => ({ cursor: formatCursor({ seq, ids: recent }), text, urgent })) };
     }
     // ------------------------------------------------------------------------------------------------------------ the buffer
     /**
@@ -200,7 +201,7 @@ export class PlanEventRelay {
                 this.seenIds.shift();
         }
         this.seq += 1;
-        this.buffer.push({ seq: this.seq, own, recent: [...this.recentIds], text: event.text, scope: event.scope ?? "plan" });
+        this.buffer.push({ seq: this.seq, own, recent: [...this.recentIds], text: event.text, scope: event.scope ?? "plan", urgent: event.urgent });
         const waiter = this.waiter;
         if (waiter === null)
             return;
@@ -246,7 +247,7 @@ export class PlanEventRelay {
             connection: () => heartbeatConnection(this.connectionState, this.stoppedReason, this.lastInventoryError),
             streaming: () => this.connectionState === "streaming",
             // `origin: null` skips the agent/machine hold: the notice reaches the session at once. It is about the session, not a plan.
-            announce: (text) => this.digest.route({ type: "event", id: null, text, origin: null, scope: "session" }),
+            announce: (text, source) => this.digest.route({ type: "event", id: null, text, origin: null, scope: "session", urgent: isUrgent({ source }) }),
             forceReconnect: () => this.run?.forceReconnect?.(),
         }, transcriptPath ?? null);
     }

package/dist/urgent-records.js

@@ -0,0 +1,34 @@
+/**
+ * DX-4721 - THE ONE PLACE that decides whether a relayed plan-event record is URGENT.
+ *
+ * Background. `plan_events_wait` hands the caller (the danxbot plugin's relay, or a plan orchestrator's waiter sub-agent) a
+ * stream of records. The caller delivers an ordinary record after the session's running turn ends, and adds an URGENT one to
+ * the running turn at once. Which record is which is decided here, by the record's KIND, and nowhere else: every site that
+ * creates a record names its source and calls `isUrgent`; none writes an `urgent` literal of its own. The flag is a required
+ * boolean on `ListenEvent`, so a site that forgets it fails `make typecheck`, and no reader defaults a missing one.
+ *
+ * Urgent: a critical usage-pacing stop (the account is about to hit its limit and the session must wind down now), and the
+ * notice that this session's key was revoked (it can no longer call the dashboard). Everything else is not: activity events
+ * (comments, answers, problems, blocks, design and pull-request outcomes), the idle nudge, the auto-resume message, a digest,
+ * the relay's own failure notice, and any line that reports an unreadable event or frame (a fault line).
+ *
+ * The operator's direct stop. The dashboard writes no stop record today (the activity vocabulary, `IssueActivityKind` in
+ * `src/issues/db/issue-activity.ts`, and the stream's frames have none), so there is no kind to key on. When the dashboard adds
+ * one, it becomes a `RecordSource` here, urgent, in this same function: never a text match.
+ */
+/** DX-4721: true for a critical pacing stop and a revoked key; false for every other source (see the module docblock). */
+export function isUrgent(record) {
+    switch (record.source) {
+        case "pacing":
+            return record.level === "critical";
+        case "key_revoked":
+            return true;
+        case "activity":
+        case "nudge":
+        case "resume":
+        case "digest":
+        case "relay_notice":
+        case "fault":
+            return false;
+    }
+}

package/package.json

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