@thehammer/danx-dashboard-mcp 0.1.148 → 0.1.149

package/README.md

@@ -26,8 +26,8 @@ All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `m
 | `issue_create` | `POST /api/issues` | Epic REQUIRES non-empty `phase_children[]` (atomic insert). `title` = short domain-naming label; `summary` = 1–3 plain-language sentences, always shown; `description` = the collapsed "Context" body. Root and every phase child take their own `summary` |
 | `issue_edit` | `PATCH /api/issues/:id/edit` | Prose + structured keys (`title`, `summary` (null clears), `description`, `ac`, `checklists`, `effort_level`, `parent_id`, `priority`, `list_id`); semantic keys refused with 400 + pointer to dedicated handler. `priority` (DX-1532) takes a tier word (`low`/`high`/…) or a number in `[0,6)` — the ONLY way to set the numeric column the Trello label + dashboard badge read; never set priority via description prose |
 | `issue_transition` | `POST /api/issues/:id/transition` | Actions: ready, pickup, rollback_pickup, complete, cancel, block, unblock, archive, reopen. `block` is a dispatch hold only — it never marks the card as needing a human; use `issue_problem` add for that |
-| `issue_problem` | `GET/POST/PATCH/DELETE /api/issues/:id/problems[/:pid]` | Actions list / add / edit / remove. A problem is one statement the operator must resolve (a question or a plan flaw) with its own solutions and answers; `add` takes `statement` + optional `solutions[]` in one transaction and IS what puts the card in front of a human (`open_problem_count > 0`) — a successful add also returns a `reminders: [{key, text}]` array (DX-3365 — the reminder registry's middleware, DB-driven and operator-overridable from the dashboard). Edit + remove are hash-guarded (`base_hash`, 409 `stale_problem`); removing the card's last open problem is always allowed — it just means the card no longer needs a human |
-| `issue_solution` | `POST/PATCH/DELETE /api/issues/:id/problems/:pid/solutions[/:sid]` | Actions add / edit / remove, `problem_id` required (list via `issue_problem list`). Edit + remove are hash-guarded (`base_hash`, 409 `stale_solution` with the current row); at most one live `recommended` per problem; a chosen option cannot be edited. No answer action on any tool — the operator answers in the dashboard |
+| `issue_problem` | `GET/POST/PATCH/DELETE /api/issues/:id/problems[/:pid]` + `POST .../answer`, `change-answer`, `unanswer` | Actions list / add / edit / remove / answer / change_answer / unanswer (DX-3471). A problem is one statement the operator must resolve (a question or a plan flaw) with its own solutions and answers; `add` takes `statement` + optional `solutions[]` in one transaction and IS what puts the card in front of a human (`open_problem_count > 0`) — a successful add also returns a `reminders: [{key, text}]` array (DX-3365 — the reminder registry's middleware, DB-driven and operator-overridable from the dashboard). Edit + remove are hash-guarded (`base_hash`, 409 `stale_problem`); removing the card's last open problem is always allowed — it just means the card no longer needs a human. `answer` `{solution_id, note?}` \| `{freeform}` and `change_answer` (same + `base_hash` naming the live DECISION) / `unanswer` (`{base_hash}`) record or retract an operator's decision — server-refused 403 for a dispatched agent's machine credential (DX-2830), reachable from an OPERATOR SESSION relaying an in-chat decision, which also durably records the relaying session (`relayed_by_session`) via the same session header every call already carries |
+| `issue_solution` | `POST/PATCH/DELETE /api/issues/:id/problems/:pid/solutions[/:sid]` | Actions add / edit / remove, `problem_id` required (list via `issue_problem list`). Edit + remove are hash-guarded (`base_hash`, 409 `stale_solution` with the current row); at most one live `recommended` per problem; a chosen option cannot be edited. No answer action on THIS tool — see `issue_problem`'s answer / change_answer / unanswer actions |
 | `issue_triage` | `POST /api/issues/:id/triage` | Send `{confidence, reason}` — an integer 0-5 score; the server computes the verdict (approve/cancel/keep/defer) against the board's configured thresholds (DX-2086). `keep`/`defer` now block the card. None of these are a cross-card ordering gate; use `issue_dependency` to sequence cards |
 | `issue_comment` | `POST/PATCH/DELETE /api/issues/:id/comments[/:cid]` | Author server-stamped, soft-delete preserved |
 | `issue_dependency` | `POST/DELETE /api/issues/:id/dependencies[/:did]` | `depends_on` cycle-checked; remove hardcodes `reason: "recorded_in_error"`. The only mechanism the dispatch picker enforces to sequence one card after another — status alone is not a substitute |

package/dist/handlers.js

@@ -568,7 +568,31 @@ export async function issueChecklist(client, args) {
  * `.describe()` in `index.ts` — that description, not this comment, is what
  * a calling agent actually reads.
  *
- * No answer action, for the reason `issueSolution` gives.
+ * DX-3471 — `answer` {solution_id, note?} | {freeform} → POST :pid/answer;
+ * `change_answer` {base_hash, solution_id, note?} | {base_hash, freeform} →
+ * POST :pid/change-answer (retracts the live decision and records a new one
+ * in ONE server transaction); `unanswer` {base_hash} → POST :pid/unanswer
+ * (retracts with no new answer, reopening the problem). `base_hash` on these
+ * two names the live DECISION (`decisionContentHash`), NOT the problem —
+ * read it off a problem's `decisions[].content_hash` (from `list`), never
+ * off the problem's own `content_hash`. A stale one → 409 `stale_decision`
+ * with `currentHash` + `currentProblem`: merge, then retry.
+ *
+ * ALL THREE ARE OPERATOR-SESSION ONLY. The server's route policy admits only
+ * a `human` principal on these three routes (`route-policies/index.ts`) — a
+ * dispatched agent's machine credential is refused before it ever reaches a
+ * handler, for the DX-2830 reason: an agent that could answer its own
+ * question could release the very human gate it set to stop and wait for.
+ * An operator-session agent (running under the OPERATOR's own dashboard
+ * token, human-authenticated) CAN call these — this is what turns "the
+ * operator decided in chat" into a durable, correctly-attributed decision
+ * instead of a comment or a raw curl call. The decision records the human
+ * decider (`decided_by`) and, when this call carries the session id
+ * `@thehammer/danx-dashboard-mcp` already stamps on every request
+ * (`x-danx-session-id`, DX-2683 — no separate parameter needed here),
+ * which working session relayed it (`relayed_by_session` on the resulting
+ * decision, DX-3471) — so a decision entered from the dashboard's own UI
+ * (no header) stays distinguishable from one an agent relayed in chat.
  */
 /**
  * DX-3310 (nit) — per-action allow-list for `refuseInapplicableFields`.
@@ -583,6 +607,9 @@ const PROBLEM_ACTION_FIELDS = {
     add: ["statement", "context", "type", "summary", "solutions"],
     edit: ["problem_id", "base_hash", "statement", "context", "summary", "type"],
     remove: ["problem_id", "base_hash"],
+    answer: ["problem_id", "solution_id", "note", "freeform"],
+    change_answer: ["problem_id", "base_hash", "solution_id", "note", "freeform"],
+    unanswer: ["problem_id", "base_hash"],
 };
 export async function issueProblem(client, args) {
     const idEnc = encodeURIComponent(args.id);
@@ -652,8 +679,66 @@ export async function issueProblem(client, args) {
                 board,
             });
         }
+        // DX-3471 — answer/change_answer share the exact-one-of solution_id/freeform
+        // shape the server's own `validateAnswer` enforces (`write/problem-answer.ts`);
+        // checked here too so a caller gets the same clear boundary error every
+        // OTHER missing/conflicting-arg case in this tool already gets, rather than
+        // a round trip to the server for a 400 the client could have caught.
+        case "answer": {
+            const problemId = need.id(args.problem_id, "problem_id");
+            return client.request({
+                method: "POST",
+                path: `/${idEnc}/problems/${problemId}/answer`,
+                body: answerChoiceBody(args, "answer"),
+                board,
+            });
+        }
+        case "change_answer": {
+            const problemId = need.id(args.problem_id, "problem_id");
+            const baseHash = need.string(args.base_hash, "base_hash");
+            return client.request({
+                method: "POST",
+                path: `/${idEnc}/problems/${problemId}/change-answer`,
+                body: { base_hash: baseHash, ...answerChoiceBody(args, "change_answer") },
+                board,
+            });
+        }
+        case "unanswer": {
+            const problemId = need.id(args.problem_id, "problem_id");
+            const baseHash = need.string(args.base_hash, "base_hash");
+            return client.request({
+                method: "POST",
+                path: `/${idEnc}/problems/${problemId}/unanswer`,
+                body: { base_hash: baseHash },
+                board,
+            });
+        }
     }
 }
+/**
+ * DX-3471 — the either/or answer shape `answer`/`change_answer` both send:
+ * `{solution_id, note?}` XOR `{freeform}`, mirroring the server's own
+ * `validateAnswer` (`write/problem-answer.ts`) so a caller gets the SAME
+ * refusal at this client boundary that the server would otherwise 400 on,
+ * with no round trip.
+ */
+function answerChoiceBody(args, mode) {
+    const hasSolution = args.solution_id !== undefined;
+    const hasFreeform = args.freeform !== undefined;
+    if (hasSolution === hasFreeform) {
+        throw new Error(`issue_problem ${mode} requires either solution_id or freeform (never both, never neither)`);
+    }
+    if (hasFreeform) {
+        if (args.note !== undefined) {
+            throw new Error(`issue_problem ${mode}: note qualifies a chosen solution — it is not valid with freeform`);
+        }
+        return { freeform: args.freeform };
+    }
+    const body = { solution_id: args.solution_id };
+    if (args.note !== undefined)
+        body.note = args.note;
+    return body;
+}
 /**
  * One problem's candidate solutions, AND (DX-3310) one solution's individual
  * procedure steps, via `/api/issues/:id/problems/:pid/solutions[/:sid][/steps[/:stepId]]`
@@ -664,10 +749,13 @@ export async function issueProblem(client, args) {
  * solution/step id from the wrong scope → 404, nesting past depth 3 → 400)
  * pass through verbatim.
  *
- * There is deliberately NO answer action, on this tool or any other. Answering
- * releases the human gate on a card — an agent that could answer its own
- * question could release the very stop it set to wait for a human. The operator
- * answers in the dashboard.
+ * There is deliberately NO answer action on THIS tool — answering releases the
+ * human gate on a card, and this tool has no notion of "who is calling".
+ * `issue_problem`'s `answer` / `change_answer` / `unanswer` actions (DX-3471)
+ * are where that lives instead: server-side human-principal-only (a
+ * dispatched agent's machine credential is refused 403), so an operator
+ * session can record a decision but a dispatched worker cannot release its
+ * own gate.
  */
 const SOLUTION_ACTION_FIELDS = {
     add: ["title", "body", "pro", "con", "recommended", "steps"],

package/dist/index.js

@@ -657,11 +657,39 @@ const STEP_INPUT = z.lazy(() => z
     steps: z.array(STEP_INPUT).optional().describe("this step's own children, nested — refused past 3 levels total"),
 })
     .strict());
-strictTool("issue_problem", "A card's PROBLEMS: one statement the operator must resolve (a question, or a flaw in the plan) OR an action only a person can carry out, 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 — adding a problem IS putting the card in front of a human, there is no separate flag. list → live problems in order, each {id, statement, context, type, summary, content_hash, open, solutions[], decisions[]}; add {statement, context?, type?, summary?, solutions?} → problem_id + solution_ids in one transaction (zero solutions is valid: the operator answers free-form) plus a `reminders: [{key, text}]` array (DX-3365 — every MCP-response reminder rides this ONE field now, DB-registry-driven and operator-overridable from the dashboard) naming each still-open problem's solution count; edit :pid {base_hash, statement, context?, summary?}; remove :pid {base_hash} — always allowed, even as the card's last open problem (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. `statement` is capped at 200 characters (400 names the actual length otherwise): one plain sentence, with any investigation detail in `context` (markdown, no cap) instead. Read `type`'s and `summary`'s own descriptions below before your first `add` — together they teach which type this is and the three-field split (`statement`/`summary`/`context`) an action needs.", {
+strictTool("issue_problem", "A card's PROBLEMS: one statement the operator must resolve (a question, or a flaw in the plan) OR an action only a person can carry out, 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 — adding a problem IS putting the card in front of a human, there is no separate flag. list → live problems in order, each {id, statement, context, type, summary, content_hash, open, solutions[], decisions[]} (each decision carries `relayed_by_session`, DX-3471 — the working session that recorded it, or null for one entered directly in the dashboard); add {statement, context?, type?, summary?, solutions?} → problem_id + solution_ids in one transaction (zero solutions is valid: the operator answers free-form) plus a `reminders: [{key, text}]` array (DX-3365 — every MCP-response reminder rides this ONE field now, DB-registry-driven and operator-overridable from the dashboard) naming each still-open problem's solution count; edit :pid {base_hash, statement, context?, summary?}; remove :pid {base_hash} — always allowed, even as the card's last open problem (removing it just means the card no longer needs a human). A stale base_hash → 409 `stale_problem` with currentHash + currentProblem: merge, then retry. " +
+    "DX-3471 — answer :pid {solution_id, note?} | {freeform} records the operator's decision on a LIVE problem (exactly one of solution_id/freeform; note only qualifies a chosen solution); change_answer :pid {base_hash, solution_id, note?} | {base_hash, freeform} retracts the current decision and records a new one in ONE server transaction; unanswer :pid {base_hash} retracts with no new answer, reopening the problem. `base_hash` on these two names the live DECISION (from that problem's `decisions[].content_hash` in `list`), NOT the problem's own hash — a stale one → 409 `stale_decision` with currentHash + currentDecision: merge, then retry. " +
+    "**These three are OPERATOR-SESSION ONLY** — the server refuses a dispatched agent's machine credential 403 (DX-2830: an agent that could answer its own question could release the very human gate it set to stop and wait for); call them only when relaying a decision the OPERATOR actually made in this chat, never a decision you are making yourself. Session attribution is automatic (the same `x-danx-session-id` every call already carries, DX-2683) — no session parameter to pass here. " +
+    "`statement` is capped at 200 characters (400 names the actual length otherwise): one plain sentence, with any investigation detail in `context` (markdown, no cap) instead. Read `type`'s and `summary`'s own descriptions below before your first `add` — together they teach which type this is and the three-field split (`statement`/`summary`/`context`) an action needs.", {
     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"),
+    action: z.enum(["list", "add", "edit", "remove", "answer", "change_answer", "unanswer"]),
+    problem_id: z.number().int().positive().optional().describe("edit/remove/answer/change_answer/unanswer"),
+    base_hash: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("edit/remove: content_hash last read for the PROBLEM. change_answer/unanswer: content_hash last read for " +
+        "the live DECISION instead (that problem's `decisions[].content_hash` from `list`) — the two are never " +
+        "interchangeable."),
+    solution_id: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("answer/change_answer only. The chosen option's id, from this problem's own solutions[]. Exactly one of " +
+        "solution_id / freeform — never both, never neither (refused before any request)."),
+    note: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("answer/change_answer only, solution_id answers only: an optional qualification (\"this, but…\"). Refused " +
+        "alongside freeform, which is already the operator's own words."),
+    freeform: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("answer/change_answer only. The operator's own words, when no listed solution fits. Exactly one of " +
+        "solution_id / freeform — never both, never neither."),
     statement: z
         .string()
         .min(1)

package/package.json

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