@thehammer/danx-dashboard-mcp 0.1.87 → 0.1.89

package/dist/bridge.js

@@ -88,7 +88,7 @@ import { errorCodeOf } from "./json-body.js";
 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";
+import { capResumeIds, 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.
  *
@@ -170,11 +170,20 @@ const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${B
  * The remedy per terminal reason THIS module knows about. ONE map, so the
  * message a session is shown and the message a log carries can never drift.
  * `satisfies` makes a reason missing its remedy a compile error here — but
- * `reason` can also arrive at runtime from the dashboard's own SSE end event
- * (`ListenStopped.reason` is an open string, not this union), so a build that
- * predates a newer dashboard reason still needs an honest, generic fallback
- * rather than an index miss: that is `DEFAULT_STOP_FIX`, reached only for a
- * reason genuinely outside this list, never for one of the reasons above.
+ * `KnownStopReason` above is only a SUBSET of `ListenStopReason` (DX-2920
+ * round 4 already made `ListenStopped.reason` a closed union, not a plain
+ * `string` — see `listen.ts`), and `ListenStopReason` itself has an `"unknown"`
+ * member for exactly a newer dashboard's wire reason this build predates
+ * (normalized there, never passed through raw). So a build older than the
+ * dashboard it talks to can still reach a real `ListenStopReason` value this
+ * map has no entry for. `fixForStop` below is deliberately typed to accept a
+ * plain `string`, wider than `ListenStopReason`, purely as defense in depth
+ * for a caller reached some other way (and what lets the forward-compat test
+ * below exercise the fallback with an arbitrary string) — every value that can
+ * actually reach it through `ListenStopped.reason` is already a real,
+ * compile-time-checked member of the closed union. `DEFAULT_STOP_FIX` is the
+ * honest, generic fallback for a reason genuinely outside this list, never a
+ * silent index miss.
  */
 export const STOP_FIXES = {
     no_connection_record: "call plan_connect again in this session — its danx-dashboard MCP server records the connection the bridge needs " +
@@ -457,7 +466,7 @@ function classifyAdmissionRefusal(refusal) {
  * `stopped` record. Returns 0 when another listener took over, 1 otherwise.
  */
 export async function runBridge(options, deps) {
-    const delivered = options.resumeIds.slice(-DELIVERED_ID_MEMORY);
+    const delivered = capResumeIds(options.resumeIds);
     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
@@ -577,6 +586,18 @@ export async function runBridge(options, deps) {
         backoff = MINT_INITIAL_BACKOFF_MS;
         const run = { stopped: null, emitted: false };
         const startedAt = deps.now();
+        // DX-2829 — `runListener`'s own return value (0 for a benign takeover, 1
+        // otherwise) is intentionally discarded here, never reused as this
+        // function's exit code: `runBridge` computes ITS OWN exit code below from
+        // `stopped.reason` via the `stop()` helper above, because a bridge-level
+        // stop can happen for reasons `runListener` never sees at all (mint
+        // failures, the refused-ticket retry budget, `classifyAdmissionRefusal`'s
+        // reclassification) — `stop()` is the one place that has to decide the
+        // exit code for ALL of them, not just the stream-reader's own outcomes.
+        // Reusing `runListener`'s return value here would be redundant at best
+        // (the two happen to agree for `superseded`/`replaced`) and wrong at worst
+        // wherever a bridge-level reason diverges from the stream-level one it
+        // was built from.
         await runListener(
         // DX-2730 D4 — `heldIds()` rides along with `delivered`: a held-but-
         // not-yet-flushed event was never added to `delivered` (see `emitNow`),

package/dist/handlers.js

@@ -566,6 +566,12 @@ export async function issueChecklist(client, args) {
  * card is put in front of one; the reminder that used to ride the retired
  * `issue_requires_human({set: true})` now rides here instead.
  *
+ * DX-2942 — `statement` is capped at 100 characters server-side (a 400 names
+ * the actual length otherwise); `context` is the markdown detail behind it,
+ * sent only when given on `add`, and on `edit` `undefined` keeps the stored
+ * context while `null` clears it — the same omit/null semantics
+ * `plan_update_record` already gives a plan record's context.
+ *
  * No answer action, for the reason `issueSolution` gives.
  */
 export async function issueProblem(client, args) {
@@ -577,6 +583,8 @@ export async function issueProblem(client, args) {
             return client.request({ method: "GET", path: `/${idEnc}/problems`, board });
         case "add": {
             const body = { statement: need.string(args.statement, "statement") };
+            if (args.context !== undefined)
+                body.context = args.context;
             if (args.solutions !== undefined)
                 body.solutions = args.solutions;
             const result = await client.request({ method: "POST", path: `/${idEnc}/problems`, body, board });
@@ -589,7 +597,7 @@ export async function issueProblem(client, args) {
             return client.request({
                 method: "PATCH",
                 path: `/${idEnc}/problems/${problemId}`,
-                body: { base_hash: baseHash, statement },
+                body: { base_hash: baseHash, statement, ...(args.context === undefined ? {} : { context: args.context }) },
                 board,
             });
         }

package/dist/index.js

@@ -548,12 +548,17 @@ const SOLUTION_FIELDS = {
     con: z.string().optional(),
     recommended: z.boolean().optional(),
 };
-server.tool("issue_problem", "A card's PROBLEMS via /api/issues/:id/problems[/:pid]: one statement the operator must resolve (a question, or a flaw in the plan), each with its own solutions/answers — one problem per question. OPEN = not yet answered; the card needs a human exactly while open_problem_count > 0 — there is no separate flag to set, adding a problem IS putting the card in front of a human. list → live problems in order, each {id, statement, content_hash, open, solutions[], decisions[]}; add {statement, solutions?} → problem_id + solution_ids in one transaction (zero solutions is valid: the operator answers free-form) plus `problems_reminder: {open_problem_count, instruction}` naming each open problem's solution count; edit :pid {base_hash, statement}; remove :pid {base_hash} — always allowed, even as the card's last open problem (DX-2830: removing it just means the card no longer needs a human). A stale base_hash → 409 `stale_problem` with currentHash + currentProblem: merge, then retry. No answer action — the operator answers in the dashboard.", {
+server.tool("issue_problem", "A card's PROBLEMS via /api/issues/:id/problems[/:pid]: one statement the operator must resolve (a question, or a flaw in the plan), each with its own solutions/answers — one problem per question. OPEN = not yet answered; the card needs a human exactly while open_problem_count > 0 — there is no separate flag to set, adding a problem IS putting the card in front of a human. list → live problems in order, each {id, statement, context, content_hash, open, solutions[], decisions[]}; add {statement, context?, solutions?} → problem_id + solution_ids in one transaction (zero solutions is valid: the operator answers free-form) plus `problems_reminder: {open_problem_count, instruction}` naming each open problem's solution count; edit :pid {base_hash, statement, context?}; remove :pid {base_hash} — always allowed, even as the card's last open problem (DX-2830: removing it just means the card no longer needs a human). A stale base_hash → 409 `stale_problem` with currentHash + currentProblem: merge, then retry. No answer action — the operator answers in the dashboard. DX-2942 — `statement` is capped at 100 characters (a 400 names the actual length otherwise): write it as ONE plain question, and put any investigation detail in `context` (markdown, no cap) instead of running it on. Good: statement \"Which cache should we use?\", context \"Redis fits the read-heavy path; see benchmark in #123. Memcached is simpler ops but no persistence.\" Bad: statement \"We looked at Redis vs Memcached, ran benchmarks showing Redis 3x faster on reads, but Memcached has simpler ops and we're not sure persistence matters here since the cache is fully rebuildable from Postgres...\" (too long, refused — move it to context).", {
     id: z.string().min(1),
     action: z.enum(["list", "add", "edit", "remove"]),
     problem_id: z.number().int().positive().optional().describe("edit/remove"),
     base_hash: z.string().min(1).optional().describe("content_hash last read; edit/remove"),
-    statement: z.string().min(1).optional().describe("add/edit"),
+    statement: z.string().min(1).optional().describe("add/edit; ONE plain question, at most 100 characters"),
+    context: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("add/edit; markdown detail behind statement — file:line refs, code excerpts, root-cause writeups. add: sent only when given (null/omit means none). edit: omit to keep the stored context, null to clear it."),
     solutions: z
         .array(z.object({ title: z.string().min(1), ...SOLUTION_FIELDS }))
         .optional()
@@ -654,7 +659,7 @@ server.tool("issue_retro", "Replace the retro block via PUT /api/issues/:id/retr
 // route's MAX_DECODED_BYTES (src/issues/write/attachments.ts). This package is
 // a separate published artifact and cannot import that constant, so the number
 // is restated here as prose — keep the two in sync if the backend ceiling moves.
-server.tool("issue_attach", "Attach a LOCAL file to an issue card via POST /api/issues/:id/attachments. Pass `id` (the card) and `file_path` (an ABSOLUTE path to a file on the dispatch's shared filesystem — e.g. a screenshot, exported CSV, or diagram you wrote). This MCP server reads the bytes, infers the MIME type from the extension, and uploads through the dashboard, which: stores the bytes in S3, inserts ONE danxbot-origin issue_attachments row, and auto-mirrors the file to the card's linked Trello card AND its Slack card-view thread (DX-1122 outbound projection) — no extra step needed. Board-scoped; see `board`. Fail-loud: a relative/empty path is rejected at the MCP boundary, and a missing/unreadable file throws BEFORE any upload (no partial S3 object, no row). 25 MB decoded ceiling (413). Returns the hydrated issue plus the new attachment id.", {
+server.tool("issue_attach", "Attach a LOCAL file to an issue card via POST /api/issues/:id/attachments. Pass `id` (the card) and `file_path` (an ABSOLUTE path to a file on the dispatch's shared filesystem — e.g. a screenshot, exported CSV, or diagram you wrote). This MCP server reads the bytes, infers the MIME type from the extension, and uploads through the dashboard, which: stores the bytes in S3, inserts ONE danxbot-origin issue_attachments row, and auto-mirrors the file to the card's linked Trello card AND its Slack card-view thread (DX-1122 outbound projection) — no extra step needed. Board-scoped; see `board`. Fail-loud: a relative/empty path is rejected at the MCP boundary, and a missing/unreadable file throws BEFORE any upload (no partial S3 object, no row). 25 MB decoded ceiling (413). Returns `{issue, attachment_id, s3_key}` — find the new attachment in `issue.attachments` by `attachment_id` to read its public, long-lived `url` (no expiry — never a presigned link). EMBEDDING: that `url` is not only a card-level attachment — paste it into ANY markdown-bearing field (a problem's `statement`/`context` via `issue_problem`, a comment via `issue_comment`, a plan record's `context`, a solution's `body`) as `![description](url)` and the dashboard renders it inline, capped to a compact thumbnail with click-to-enlarge. Use this whenever a screenshot would let a human judge something faster than prose — a UI bug, a before/after, a broken layout. Example: after uploading and reading the attachment's url (say `https://dx-issues.s3.us-east-1.amazonaws.com/abc123.png`), call `issue_comment` with text `Before the fix, the sidebar overlapped the header:\\n\\n![sidebar overlapping header](https://dx-issues.s3.us-east-1.amazonaws.com/abc123.png)`.", {
     id: z.string().min(1),
     file_path: z
         .string()

package/dist/listen.js

@@ -63,7 +63,17 @@ export const READ_IDLE_TIMEOUT_MS = 45_000;
 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]";
+/**
+ * DX-2829 — the ONE place that caps a resume-id list to the last
+ * `DELIVERED_ID_MEMORY` entries. Both `runListener` (seeding its own
+ * duplicate-detection `Set` below) and `bridge.ts`'s `runBridge` (seeding its
+ * own delivered-id array) used to each carry their own `slice(-DELIVERED_ID_MEMORY)`
+ * — the same cap, on the same kind of input, computed twice.
+ */
+export function capResumeIds(ids) {
+    return ids.slice(-DELIVERED_ID_MEMORY);
+}
+const LINE_PREFIX = "[danx-dashboard stream]";
 const ACTIVITY_ORIGINS = new Set(["operator", "agent", "machine"]);
 function quoted(value) {
     return `"${value.text}${value.truncated ? "…" : ""}"`;
@@ -336,6 +346,10 @@ const KNOWN_WIRE_END_REASONS = new Set(["superseded", "replaced", "revoked", "no
 function isKnownWireEndReason(reason) {
     return KNOWN_WIRE_END_REASONS.has(reason);
 }
+/** A thrown value's message, for the one drop path that carries a real JS error — never re-derived elsewhere. */
+function describeDropError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
 /** Statuses that describe the moment, not the ticket — retry them. */
 const RETRYABLE_CLIENT_STATUSES = new Set([408, 429]);
 /**
@@ -348,13 +362,18 @@ export async function runListener(options, deps) {
     let lastEventId = null;
     let unhealthySince = null;
     let attempt = 0;
+    // DX-2829 — the most recent `dropped` outcome's cause, carried across
+    // reconnect attempts so the eventual `lease_expired` stop (the only outcome
+    // reached exclusively via repeated drops) can say what actually failed
+    // instead of only "no healthy connection ... past the ticket's lease".
+    let lastDropDetail = null;
     const remember = (id) => {
         delivered.add(id);
         if (delivered.size > DELIVERED_ID_MEMORY)
             delivered.delete(delivered.values().next().value);
         lastEventId = lastEventId === null ? id : Math.max(lastEventId, id);
     };
-    for (const id of options.resumeIds.slice(-DELIVERED_ID_MEMORY))
+    for (const id of capResumeIds(options.resumeIds))
         remember(id);
     function stop(reason, detail, code, extra) {
         if (reason === "scope_narrowed") {
@@ -520,7 +539,7 @@ export async function runListener(options, deps) {
             }
             if (!response.ok || response.body === null) {
                 await response.body?.cancel();
-                return { kind: "dropped", healthy: false };
+                return { kind: "dropped", healthy: false, detail: `HTTP ${response.status} with no readable body` };
             }
             const parser = new SseParser();
             const decoder = new TextDecoder();
@@ -536,8 +555,14 @@ export async function runListener(options, deps) {
             }
             return { kind: "dropped", healthy: healthy() };
         }
-        catch {
-            return { kind: "dropped", healthy: healthy() };
+        catch (err) {
+            // DX-2829 — was a bare `catch { ... }` that discarded the causing error
+            // entirely: a connection that failed the same way on every retry (DNS
+            // failure, TLS reset, the idle-timeout abort) surfaced nothing beyond
+            // "no healthy connection" once the lease finally expired. Preserving the
+            // message here is what lets `runListener` name the actual last failure
+            // in its final `lease_expired` stop record below.
+            return { kind: "dropped", healthy: healthy(), detail: describeDropError(err) };
         }
         finally {
             clearTimeout(idle);
@@ -568,6 +593,8 @@ export async function runListener(options, deps) {
                 refusal: { status: outcome.status, errorCode: outcome.errorCode, body: outcome.body },
             });
         }
+        if (outcome.detail !== undefined)
+            lastDropDetail = outcome.detail;
         if (outcome.healthy) {
             unhealthySince = null;
             attempt = 0;
@@ -575,7 +602,10 @@ export async function runListener(options, deps) {
         const now = deps.now();
         unhealthySince ??= now;
         if (now - unhealthySince >= options.leaseMs) {
-            return stop("lease_expired", `no healthy connection to ${options.streamUrl} for ${Math.round((now - unhealthySince) / 60_000)} minutes, past the ticket's lease`, 1);
+            // DX-2829 — names the last connection failure when one was ever recorded,
+            // instead of only reporting the timeout itself.
+            const cause = lastDropDetail === null ? "" : ` — last connection attempt failed: ${lastDropDetail}`;
+            return stop("lease_expired", `no healthy connection to ${options.streamUrl} for ${Math.round((now - unhealthySince) / 60_000)} minutes, past the ticket's lease${cause}`, 1);
         }
         await deps.sleep(Math.min(MAX_BACKOFF_MS, INITIAL_BACKOFF_MS * 2 ** attempt));
         attempt += 1;

package/dist/one-line.js

@@ -1,7 +1,8 @@
 /**
  * DX-2735 — the ONE way this package renders human text into an agent-facing
- * line: the listen notification line and the problems reminder both go
- * through it, so they can never disagree about how a statement looks.
+ * line: the dashboard-event stream's notification line and the problems
+ * reminder both go through it, so they can never disagree about how a
+ * statement looks.
  *
  * Every whitespace run (newlines included) collapses to a single space, because
  * a notification is one line and a reminder quotes statements inline. The

package/package.json

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