@thehammer/danx-dashboard-mcp 0.1.85 → 0.1.87

package/dist/bridge.js

@@ -89,6 +89,71 @@ import { oneLine } from "./one-line.js";
 import { credentialFingerprint, describeCredentialSource, readCredential, } from "./credential.js";
 import { readSessionConnection } from "./session-connection.js";
 import { DELIVERED_ID_MEMORY, HEALTHY_CONNECTION_MS, READ_IDLE_TIMEOUT_MS, runListener, } from "./listen.js";
+/**
+ * DX-2730 D4 — WHICH EVENTS WAKE THE SESSION, NOW THAT EVERY ONE OF THEM CAN.
+ *
+ * Every `ListenEvent` carries the origin its writer set (`operator` / `agent` /
+ * `machine`, or `null` for the idle-nudge exemption and an event this listener
+ * could not parse — see `ListenEvent.origin`'s docblock in `listen.ts`). This
+ * module is the ONLY place that decides what happens next:
+ *
+ *   - `operator` (a real human) and `null` (nudge / unreadable) emit AT ONCE,
+ *     exactly as every event did before this card — a session must never wait
+ *     to hear from the person it is working with, and a fault or a nudge must
+ *     never be hidden behind a delay either.
+ *   - `agent` and `machine` are HELD. Every dispatched agent's own writes and
+ *     every server-side guard/reviewer/recovery write share this treatment:
+ *     gate reviews, triage notes, auto-blocks. Held events are combined into
+ *     ONE digest record, flushed the moment either `DIGEST_INTERVAL_MS`
+ *     elapses with no operator event, or an operator event arrives (flushed
+ *     just ahead of it, never after — a session must never read the digest
+ *     as if it postdates the operator's own message).
+ *
+ * NOTHING HELD IS EVER DROPPED, AND NOTHING HELD IS EVER DOUBLE-DELIVERED
+ * EITHER — across a full process restart OR a same-process re-mint. An id is
+ * added to `delivered` (this run's own resume cursor, seeded from
+ * `options.resumeIds` and handed to the next mint/re-mint as `--resume-ids`)
+ * ONLY at the moment it is actually written to stdout — never at the moment it
+ * is merely held. So a process that dies mid-hold has, by construction, never
+ * marked those ids delivered: the next process starts from the SAME cursor,
+ * the dashboard's replay resends exactly the events this process never
+ * finished relaying, and they are held and flushed again there. This is "the
+ * existing resumeIds/delivered-id cursor" the card's AC names — no new
+ * persistence was needed, only NOT marking a held event delivered until it is
+ * actually flushed.
+ *
+ * THE SAME REPLAY CAN ALSO ARRIVE WITHIN ONE STILL-RUNNING PROCESS, on a
+ * same-process re-mint (a real `lease_expired`, not merely a dropped
+ * connection): a fresh `runListener()` call starts a FRESH internal duplicate
+ * guard, seeded only from the `resumeIds` this call hands it — and a held id
+ * was, by the paragraph above, never in `delivered`. Left unhandled this
+ * would let the SAME held event be counted into TWO digests once flushed
+ * twice. `heldIds()` closes this: every `runListener()` call is seeded with
+ * `[...delivered, ...heldIds()]`, so the fresh listener's own guard
+ * (`listen.ts`'s `delivered` Set) already knows about a held id and silently
+ * drops a replay of it before it ever reaches `routeEvent` again —
+ * `routeEvent`'s own id check on `held` is the second, cheaper layer behind
+ * that, for defense in depth.
+ *
+ * A digest record rides the exact same `{type:"event", id, text}` shape a
+ * single event does (`id` is the highest id it combines, or `null` if every
+ * combined event carried none) — the plugin that relays bridge output
+ * (`plan-event-bridge.mjs`, outside this repo) already forwards any such
+ * record generically, so a digest needs no change on that side.
+ *
+ * A REAL TIMER, NOT `deps.sleep`. Unlike every other timing decision in this
+ * module (mint backoff, reconnect backoff), the digest interval is not tied to
+ * stream activity — it must fire even while the stream sits idle between
+ * events — so it is a plain `setTimeout`, mockable with fake timers in tests,
+ * rather than routed through the deliberately stream-driven `deps.sleep`.
+ */
+export const DIGEST_INTERVAL_MS = 10 * 60_000;
+const DIGEST_PREFIX = "[danx-dashboard bridge]";
+/** ONE combined record for every event held since the last flush. */
+function formatDigest(entries) {
+    const header = `${DIGEST_PREFIX} digest — ${entries.length} agent/machine event${entries.length === 1 ? "" : "s"} since the last update:`;
+    return [header, ...entries.map((e) => e.text)].join("\n");
+}
 export const BRIDGE_SUBCOMMAND = "bridge";
 export const STREAM_TICKET_PATH = "/api/plan-sessions/me/stream-ticket";
 export const SESSION_ID_HEADER = "x-danx-session-id";
@@ -394,6 +459,20 @@ function classifyAdmissionRefusal(refusal) {
 export async function runBridge(options, deps) {
     const delivered = options.resumeIds.slice(-DELIVERED_ID_MEMORY);
     function stop(reason, detail, code, extra) {
+        // DX-2730 D4 — every terminal return goes through here, so this is the ONE
+        // place that cancels a pending digest timer. CANCELLED, never flushed: for
+        // `superseded`/`replaced` a newer process is already streaming this same
+        // session and will receive (and hold, and eventually flush) these same
+        // held events itself via the dashboard's replay — flushing here too would
+        // double-deliver the digest. For every other terminal reason, whatever is
+        // still held was never marked delivered (see `emitNow`), so a future
+        // process picks it up the same way — a live, un-fired `setTimeout` would
+        // otherwise also keep this process's event loop alive for up to
+        // `DIGEST_INTERVAL_MS` after it should have exited.
+        if (digestTimer !== null) {
+            clearTimeout(digestTimer);
+            digestTimer = null;
+        }
         if (reason === "scope_narrowed") {
             if (extra?.boards === undefined) {
                 throw new Error('stop("scope_narrowed", ...) requires boards — unreachable through the exported overloads above');
@@ -407,6 +486,77 @@ export async function runBridge(options, deps) {
     let backoff = MINT_INITIAL_BACKOFF_MS;
     let refusedInRow = 0;
     let readyEmitted = false;
+    // DX-2730 D4 — digest state, declared OUTSIDE the mint/reconnect loop below
+    // so a re-mint (a lapsed lease, still the SAME process) never loses a
+    // pending hold — see the module docblock for the restart case, which the
+    // resume cursor handles instead.
+    let held = [];
+    let digestTimer = null;
+    function markDelivered(id) {
+        if (id === null)
+            return;
+        delivered.push(id);
+        if (delivered.length > DELIVERED_ID_MEMORY)
+            delivered.shift();
+    }
+    /** Write an event downstream at once, and mark its id delivered — never before now. */
+    function emitNow(output) {
+        markDelivered(output.id);
+        deps.write(output);
+    }
+    /** Combine every held event into ONE record and emit it, if there is anything to combine. */
+    function flushDigest() {
+        if (digestTimer !== null) {
+            clearTimeout(digestTimer);
+            digestTimer = null;
+        }
+        if (held.length === 0)
+            return;
+        const entries = held;
+        held = [];
+        const ids = entries.map((e) => e.id).filter((id) => id !== null);
+        emitNow({ type: "event", id: ids.length === 0 ? null : Math.max(...ids), text: formatDigest(entries), origin: null });
+    }
+    /** Every id currently held, unflushed — also fed back into the next `runListener` call's
+     *  `resumeIds` below, so a re-mint's fresh listener knows these were already seen and its
+     *  OWN duplicate guard (`listen.ts`'s `delivered` Set) silently drops a replay of one,
+     *  rather than it reaching here a second time. */
+    function heldIds() {
+        return held.map((e) => e.id).filter((id) => id !== null);
+    }
+    /**
+     * DX-2730 D4 — the ONE place that decides immediate vs. held-for-digest.
+     * `operator` and `null` (nudge / unreadable — see `ListenEvent.origin`'s
+     * docblock) flush any pending digest first (never let a digest arrive AFTER
+     * the operator event that should have superseded it) and then emit at once.
+     * `agent` / `machine` are appended to the hold, arming the interval timer
+     * only for the FIRST held event since the last flush — a later addition
+     * must never push the deadline out, or the "at most every 10 minutes"
+     * guarantee would erode into "10 minutes after the last event," which could
+     * never fire while events keep arriving.
+     *
+     * DEDUPED BY ID (defense in depth): a held event's id is not added to
+     * `delivered` until it is actually flushed (see `emitNow`), which is what
+     * lets a crashed-and-restarted PROCESS recover it via the dashboard's own
+     * replay. The same replay can also legitimately re-arrive WITHIN one still-
+     * running process — a re-mint after a real `lease_expired` starts a fresh
+     * `runListener` whose own duplicate guard is seeded from `resumeIds` alone,
+     * and a still-held id was never in `delivered` to seed it with. `resumeIds`
+     * below closes that for the ordinary case by handing the fresh listener
+     * every held id too; this check is the second, cheaper layer for anything
+     * that reaches here anyway — never trust a single guard to hold alone.
+     */
+    function routeEvent(output) {
+        if (output.origin === "agent" || output.origin === "machine") {
+            if (output.id !== null && heldIds().includes(output.id))
+                return;
+            held.push(output);
+            digestTimer ??= setTimeout(flushDigest, DIGEST_INTERVAL_MS);
+            return;
+        }
+        flushDigest();
+        emitNow(output);
+    }
     for (;;) {
         const minted = await mintTicket(options, deps);
         if (minted.kind === "terminal")
@@ -427,7 +577,18 @@ export async function runBridge(options, deps) {
         backoff = MINT_INITIAL_BACKOFF_MS;
         const run = { stopped: null, emitted: false };
         const startedAt = deps.now();
-        await runListener({ streamUrl: minted.streamUrl, ticket: minted.ticket, leaseMs: minted.leaseMs, resumeIds: [...delivered] }, {
+        await runListener(
+        // DX-2730 D4 — `heldIds()` rides along with `delivered`: a held-but-
+        // not-yet-flushed event was never added to `delivered` (see `emitNow`),
+        // so without this a fresh listener after a re-mint would not recognize
+        // a replay of it as already-seen and would hold (and eventually
+        // digest) it a second time. See `routeEvent`'s docblock. (If this
+        // combined list ever exceeded `DELIVERED_ID_MEMORY`, `runListener`'s own
+        // `slice(-DELIVERED_ID_MEMORY)` would evict the OLDEST entries first —
+        // i.e. `delivered`'s ids before `heldIds()`'s, which is the right order:
+        // a held id is always the more recent of the two and the one a near-
+        // term replay is actually likely to touch.)
+        { streamUrl: minted.streamUrl, ticket: minted.ticket, leaseMs: minted.leaseMs, resumeIds: [...delivered, ...heldIds()] }, {
             ...deps,
             write: (output) => {
                 if (output.type === "stopped") {
@@ -435,12 +596,7 @@ export async function runBridge(options, deps) {
                     return;
                 }
                 run.emitted = true;
-                if (output.id !== null) {
-                    delivered.push(output.id);
-                    if (delivered.length > DELIVERED_ID_MEMORY)
-                        delivered.shift();
-                }
-                deps.write(output);
+                routeEvent(output);
             },
         });
         const stopped = run.stopped;

package/dist/listen.js

@@ -11,7 +11,10 @@
  *   - `{type:"event", id, text}` — exactly one per event, the moment it arrives.
  *     `text` is what the session reads; an event it cannot read still produces one
  *     (`could not read event …`), never silence. `id` is `null` only for a frame
- *     that carried no usable id.
+ *     that carried no usable id — which includes DX-2885's `nudge` frame
+ *     (`formatNudgeLine`): it is advisory, re-derived fresh every tick by the
+ *     dashboard's own keep-alive tick, and never replayed, so it rides this
+ *     same shape with `id: null` rather than growing a THIRD output variant.
  *   - `{type:"stopped", reason, detail, refusal?, boards?}` — once, last. `reason`
  *     is the dashboard's own end reason (`superseded`, `replaced`, `revoked`,
  *     `scope_narrowed`, `not_connected`), `refused` (the ticket was not
@@ -61,6 +64,7 @@ export const HEALTHY_CONNECTION_MS = 20_000;
 /** How many delivered event ids the duplicate guard remembers — well past the replay overlap. */
 export const DELIVERED_ID_MEMORY = 1_000;
 const LINE_PREFIX = "[danx-dashboard listen]";
+const ACTIVITY_ORIGINS = new Set(["operator", "agent", "machine"]);
 function quoted(value) {
     return `"${value.text}${value.truncated ? "…" : ""}"`;
 }
@@ -88,6 +92,11 @@ export function invalidEventReason(value) {
         if (typeof value[field] !== "string")
             return `${field} is not a string`;
     }
+    // DX-2730 D4 — checked with the rest of the envelope, before any kind-specific
+    // detail check, exactly like every other envelope field above.
+    if (typeof value.origin !== "string" || !ACTIVITY_ORIGINS.has(value.origin)) {
+        return "origin is not one of operator, agent, machine";
+    }
     const d = value.detail;
     if (!isRecord(d))
         return "detail is not an object";
@@ -154,9 +163,19 @@ export function invalidEventReason(value) {
             return null;
     }
 }
+/**
+ * DX-2730 D4 — `actor` alone cannot distinguish an `agent` event from a
+ * `machine` one (both stamp `actor: "danxbot"` today), so every line names
+ * the origin next to the actor rather than leaving it to a separate field a
+ * reader would have to cross-reference.
+ */
+function actorLabel(event) {
+    return `${event.actor} (${event.origin})`;
+}
 /** Only ever called on an event `invalidEventReason` accepted, so its casts are checked. */
 function describe(event) {
     const d = event.detail;
+    const who = actorLabel(event);
     switch (event.kind) {
         case "comment_added": {
             // DX-2906 — a comment naming a problem (a follow-up question, without
@@ -165,15 +184,15 @@ function describe(event) {
             // got a reply.
             const problem = d.problem;
             if (problem === undefined)
-                return `${event.actor} commented: ${quoted(d.excerpt)}`;
-            return `${event.actor} commented on problem ${quoted(problem.statement)}: ${quoted(d.excerpt)}`;
+                return `${who} commented: ${quoted(d.excerpt)}`;
+            return `${who} commented on problem ${quoted(problem.statement)}: ${quoted(d.excerpt)}`;
         }
         case "solution_answered": {
             // DX-2735: every answer answers ONE problem on a card that may carry several,
             // so the line names the problem — otherwise the agent cannot tell which of its
             // questions just closed.
             const problem = d.problem;
-            const answered = `${event.actor} answered ${quoted(problem.statement)}:`;
+            const answered = `${who} answered ${quoted(problem.statement)}:`;
             const solution = d.solution;
             if (solution === null)
                 return `${answered} ${quoted(d.freeform)}`;
@@ -184,14 +203,14 @@ function describe(event) {
             // DX-2830 — this IS the "needs a human" signal now: a card needs one
             // exactly when it has an open problem, and this is one being opened.
             const problem = d.problem;
-            return `${event.actor} opened a problem: ${quoted(problem.statement)}`;
+            return `${who} opened a problem: ${quoted(problem.statement)}`;
         }
         case "problem_unanswered": {
             // DX-2935 — MUST read as "a previous answer was withdrawn", never as a
             // brand-new problem: a connected session that already acted on the
             // retracted answer has to stop, not treat this as fresh work to start.
             const problem = d.problem;
-            return `${event.actor} retracted the answer to ${quoted(problem.statement)}`;
+            return `${who} retracted the answer to ${quoted(problem.statement)}`;
         }
         case "problem_answer_changed": {
             // DX-2935 — ONE line for the whole retract-and-reanswer (never two
@@ -200,16 +219,16 @@ function describe(event) {
             const problem = d.problem;
             const solution = d.solution;
             const now = solution === null ? quoted(d.freeform) : `"${solution.title}"`;
-            return `${event.actor} changed the answer to ${quoted(problem.statement)}: now ${now}`;
+            return `${who} changed the answer to ${quoted(problem.statement)}: now ${now}`;
         }
         case "blocked":
-            return `${event.actor} blocked the card: ${quoted(d.reason)}`;
+            return `${who} blocked the card: ${quoted(d.reason)}`;
         case "unblocked":
-            return `${event.actor} unblocked the card`;
+            return `${who} unblocked the card`;
         default:
             // A kind newer than this listener still produces a line: an event the
             // agent is never told about is exactly the failure this reader prevents.
-            return `${event.actor}: ${event.kind}`;
+            return `${who}: ${event.kind}`;
     }
 }
 /** The one readable line for an event. Always a single line; throws, naming the fault, on a malformed event. */
@@ -219,6 +238,46 @@ export function formatActivityLine(event) {
         throw new Error(`malformed activity event: ${invalid}`);
     return oneLine(`[${event.cardId} "${event.cardTitle}" ${event.boardId}] ${describe(event)}`);
 }
+function isNudgeCardRef(value) {
+    return isRecord(value) && typeof value.id === "string" && typeof value.title === "string";
+}
+function isNudgeCardRefArray(value) {
+    return Array.isArray(value) && value.every(isNudgeCardRef);
+}
+/** Why a nudge cannot be read, or `null` when it can — same checked-before-describing shape as `invalidEventReason`. */
+export function invalidNudgeReason(value) {
+    if (!isRecord(value))
+        return "the nudge is not an object";
+    if (typeof value.idleMinutes !== "number" || !Number.isFinite(value.idleMinutes)) {
+        return "idleMinutes is not a number";
+    }
+    if (!isNudgeCardRefArray(value.startable))
+        return "startable is not a {id,title}[] array";
+    if (!isNudgeCardRefArray(value.held))
+        return "held is not a {id,title}[] array";
+    return null;
+}
+function cardList(cards) {
+    return cards.map((c) => `${c.id} "${c.title}"`).join(", ");
+}
+/**
+ * The one readable line for a nudge (DX-2885). Always names the actual
+ * waiting cards — never a generic "keep going" — because that is the whole
+ * point of the feature: a session that only sees "you're idle" learns
+ * nothing a bare timer couldn't have told it. Always a single line; throws,
+ * naming the fault, on a malformed nudge.
+ */
+export function formatNudgeLine(event) {
+    const invalid = invalidNudgeReason(event);
+    if (invalid !== null)
+        throw new Error(`malformed nudge event: ${invalid}`);
+    const parts = [];
+    if (event.startable.length > 0)
+        parts.push(`startable: ${cardList(event.startable)}`);
+    if (event.held.length > 0)
+        parts.push(`held: ${cardList(event.held)}`);
+    return oneLine(`${LINE_PREFIX} this session has been idle ${event.idleMinutes}m with work waiting — ${parts.join("; ")}`);
+}
 /**
  * Incremental SSE parser. Comment lines (keep-alives, the connect marker) and
  * field-less blocks produce no message, which is what keeps them out of the output.
@@ -347,6 +406,40 @@ export async function runListener(options, deps) {
             // elsewhere — see `ListenStopReason`'s docblock.
             return { kind: "ended", reason: isKnownWireEndReason(reason) ? reason : "unknown" };
         }
+        if (message.event === "nudge") {
+            // DX-2885 — a nudge carries no usable id (it is advisory, re-derived
+            // fresh every tick, never replayed — see `plan-session-stream.ts`'s
+            // module doc), so it rides the SAME `{type:"event", id:null, text}`
+            // shape an ordinary activity line uses (`id` is `null` only for a frame
+            // that carried no usable id — a nudge is exactly that case). That is
+            // what lets `bridge.ts` and the plugin's relay
+            // (`danxbot/scripts/plan-event-bridge.mjs`, outside this repo) forward
+            // it with NO changes at all: both already forward any `{type:"event",
+            // id, text}` line generically, keyed only on `type`.
+            //
+            // DX-2885 — this frame must stay exempt from DX-2730 D4's digest-
+            // batching when that lands (see DX-2730 AC 29939, and the matching note
+            // at the dashboard's own emit site): it must keep delivering
+            // immediately, never held for a later digest flush.
+            let parsed;
+            let invalid;
+            try {
+                parsed = JSON.parse(message.data);
+                invalid = invalidNudgeReason(parsed);
+            }
+            catch (err) {
+                invalid = `not JSON: ${err.message}`;
+            }
+            const text = invalid === null
+                ? formatNudgeLine(parsed)
+                : `${LINE_PREFIX} could not read nudge (${invalid}): ${oneLine(message.data, 300)}`;
+            // DX-2730 D4 — `origin: null` here, not the parsed event's own origin
+            // (a nudge has none): this is the exemption the module doc above
+            // describes, letting `bridge.ts` treat it exactly like an operator
+            // event (immediate) without needing a fourth vocabulary member.
+            deps.write({ type: "event", id: null, text, origin: null });
+            return null;
+        }
         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
@@ -374,7 +467,13 @@ export async function runListener(options, deps) {
                 // DX-2735: oneLine caps by code point, so a bad event carrying an emoji
                 // at the cut can never leave a lone surrogate in the line.
                 oneLine(message.data, 300);
-        deps.write({ type: "event", id: knownId ? id : null, text });
+        // DX-2730 D4 — an event this listener could not parse carries `origin: null`
+        // (emit immediately) rather than the unreadable payload's own claimed
+        // origin: a fault worth surfacing at all must never be hidden behind a
+        // 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 });
         if (knownId)
             remember(id);
         return null;

package/package.json

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