@thehammer/danx-dashboard-mcp 0.1.229 → 0.1.230

package/README.md

@@ -23,19 +23,26 @@ An operator session has no stored credential. Signed out, `plan_connect` (option
 - **A 401 on the stored key** deletes the file and returns the sign-in halt (in `plan_connect`: a new request in the same call). That is a key that lapsed. A key a PERSON revoked is answered `401 key_revoked` (DX-4418): the key file is deleted and EVERY dashboard tool, `plan_connect` included, returns one stop halt (who revoked it and when; commit work in progress and end; a dispatched agent ends with `danxbot_complete`), for the rest of the process. No access request is made. `danxbot_complete` and the other worker lifecycle tools do not use the dashboard key, so a dispatched agent can still end. The session's event bridge ends with the stop reason `key_revoked` the same way. **A 404 on create** means the dashboard predates request-and-approve and says so.
 - A dispatch's `DANX_DASHBOARD_CREDENTIAL` skips all of this. There is no token-file credential source.
 
+### Asking for one more permission (DX-4434)
+
+A call the dashboard refuses `403 {error: "forbidden", permission}` means the key lacks that one permission. `request_permission({permissions, reason})` asks the key's owner to grant it: it posts `POST /api/permission-requests` (the key's own bearer, through `SessionAccess.guard`, so a revoked or signed-out session never asks) and answers at once `{state: "approval_required", approvalUrl, confirmCode, expiresAt, instruction}`. The agent shows the person the code and URL and keeps working; this process polls `POST /api/permission-requests/:publicId/claim` in the background (`src/permission-request.ts`, the same poll shape as above) and a grant is live on the key's very next call, with the same key. The dashboard does not dedupe, so this server keeps one in-flight request per permission set (sorted, de-duplicated): the same set again while pending answers `approval_pending` with the original code and URL and posts nothing. A decided, expired or reaped request frees its set so a later call asks again. A dashboard 4xx on the create (`unknown_permission`, `already_held`, `owner_lacks_permission`, `key_not_live`, 429) is returned verbatim as `{ok: false, status, body}`; 5xx throws.
+
+The hint: every dashboard result that is `403 {error: "forbidden", permission}` (and only that) gains one `reminders[]` entry naming the permission, `request_permission`, and saying to raise a problem on the card if blocked (`src/forbidden-hint.ts`, applied once in `guardedCall` in `src/index.ts`).
+
 ## Tool surface (DX-3465 — one generic tool, not one per operation)
 
-All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `mcp.template.json`. There is no per-operation tool any more (no `issue_get`, `issue_create`, `plan_add_note`, …) — three tools cover the whole dashboard API:
+All exposed as `mcp__danx-dashboard__<name>` once wired through the workspace `mcp.template.json`. There is no per-operation tool any more (no `issue_get`, `issue_create`, `plan_add_note`, …) — three tools cover the whole dashboard API (a fourth, `request_permission`, asks for more access):
 
 | Tool | Purpose |
 |---|---|
 | `danxbot_api` | `{method, path, query?, body?}` — calls any dashboard route the caller's credential may reach (card/plan CRUD, comments, dependencies, problems/solutions, quality gates, retro, triage, transitions, …). Returns `{ok, status, body}`; `body` carries the route's own response, or its structured error verbatim when `ok:false`. While this session is plan-connected, the dashboard's own reminders for it (today: `plan_list.listener_unattached`, attached by the server to `GET /api/plans` when the event listener is unattached past the startup grace, DX-3997) are relayed into the body's `reminders[]`; the MCP carries no reminder text or state of its own and re-reads at most every 30s. |
 | `danxbot_api_list` | No args. Lists the routes this caller's credential may reach, one line each (`{method, path, summary, permission}`) — 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. |
+| `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.
 
-A dedicated tool survives only for something about the agent itself, never a card/plan operation: `plan_connect` (binds the session to a plan; the event-bridge hook keys on it) and the per-dispatch worker callbacks (`danxbot_complete`, `danxbot_slack_reply`, `danxbot_slack_post_update`, `load_template_app`/`save_template_app`, `quality_gate_complete`, `link_thread_to_issue`, `attach_file`, the `slack_recovery_*` trio, `danxbot_set_evaluator_summary`) — see `src/lifecycle.ts`. The live list is always `tool-defs.json` in this package, regenerated by `npm run gen-tool-defs` — read it rather than trusting a list copied into prose.
+A dedicated tool survives only for something about the agent itself, never a card/plan operation: `request_permission` (asks for a permission its key lacks), `plan_connect` (binds the session to a plan; the event-bridge hook keys on it) and the per-dispatch worker callbacks (`danxbot_complete`, `danxbot_slack_reply`, `danxbot_slack_post_update`, `load_template_app`/`save_template_app`, `quality_gate_complete`, `link_thread_to_issue`, `attach_file`, the `slack_recovery_*` trio, `danxbot_set_evaluator_summary`) — see `src/lifecycle.ts`. The live list is always `tool-defs.json` in this package, regenerated by `npm run gen-tool-defs` — read it rather than trusting a list copied into prose.
 
 Card and plan reads/writes go through `danxbot_api` against the issue/plan route families documented in `GET /api/openapi` (via `danxbot_api_spec`) — `POST /api/issues`, `GET /api/issues/:id` (or `/batch` for many at once, DX-2727), `PATCH /api/issues/:id/edit`, `POST /api/issues/:id/transition`, the problems/solutions/dependencies/comments/quality-gates/retro sub-resource routes, and the equivalent `/api/plans/*` family (`GET /api/plans/:planId` — cheap scalars by default, `fields` opts into `cards`/`records`/`architecture`/`session_history`/`worker_dispatches`; `GET /api/plans` for the list, with an optional `status` filter over the same computed `complete`/`awaiting-session`/`building`/`planning` value `GET /api/plans/:planId` always returns ungated).
 

package/dist/forbidden-hint.js

@@ -0,0 +1,23 @@
+export const FORBIDDEN_HINT_KEY = "forbidden.request_permission";
+function hintText(permission) {
+    return (`Refused: your key lacks the permission \`${permission}\`. Call \`request_permission({permissions: ["${permission}"], reason})\` ` +
+        "to ask a person to grant it (it answers at once; keep working on anything else). If you are blocked without it, " +
+        "raise a problem on the card: a person sees problems in Needs You.");
+}
+/** `result` with the hint appended to its `reminders[]` when it is a `403 forbidden` naming a permission, else `result` itself. */
+export function withForbiddenHint(result) {
+    if (result.ok || result.status !== 403)
+        return result;
+    const body = result.body;
+    if (typeof body !== "object" || body === null || Array.isArray(body))
+        return result;
+    const { error, permission, reminders } = body;
+    if (error !== "forbidden" || typeof permission !== "string" || permission === "")
+        return result;
+    if (reminders !== undefined && !Array.isArray(reminders))
+        return result;
+    const existing = (reminders ?? []);
+    if (existing.some((r) => r?.key === FORBIDDEN_HINT_KEY))
+        return result;
+    return { ...result, body: { ...body, reminders: [...existing, { key: FORBIDDEN_HINT_KEY, text: hintText(permission) }] } };
+}

package/dist/index.js

@@ -23,6 +23,11 @@
  *                            first to find the route for something you need to do.
  *   - danxbot_api_spec       discovers the exact request/response shape of any route
  *                            `danxbot_api` can call, before calling it.
+ *   - request_permission     POST   /api/permission-requests (DX-4434) — asks a person to grant
+ *                            this key ONE MORE permission while the agent works; answers at once
+ *                            with the approval URL and confirm code, and the grant is picked up in
+ *                            the background (`permission-request.ts`). A dashboard call refused
+ *                            `403 forbidden` carries a hint to call it (`forbidden-hint.ts`).
  *   - plan_connect           POST   /api/plan-sessions/me/plan — SESSION-BOUND (kept as a
  *                            dedicated tool; every plan READ or WRITE operation goes
  *                            through danxbot_api now, e.g. GET /api/plans/mine or
@@ -79,6 +84,8 @@ import { RESTART_NOTICE_SUBCOMMAND, runRestartNoticeCommand } from "./restart-no
 import { resolveBootCredential } from "./credential.js";
 import { SessionKeyUnusableError, deleteSessionKey } from "./session-key.js";
 import { SessionAccess } from "./session-access.js";
+import { PermissionRequests } from "./permission-request.js";
+import { withForbiddenHint } from "./forbidden-hint.js";
 import { readOwnVersion } from "./version-floor.js";
 import { projectKeyOf, recordSessionConnectionAfterConnect, removeSessionConnectionAfterLeave } from "./session-connection.js";
 import { createListenerReminder, isPlanConnectedOnThisMachine, } from "./listener-reminder.js";
@@ -129,6 +136,8 @@ let listenerReminder;
  * credential itself), written to the session's connection record on a successful `plan_connect`.
  */
 let access;
+// DX-4434 — late-bound with `access` and `client`; see `permission-request.ts`.
+let permissionRequests;
 /**
  * Compose the dispatch's qualified board id (`<repo>:<slug>`) from the two env
  * halves the worker injects and build the HTTP client. DANXBOT_BOARD_NAME
@@ -163,6 +172,11 @@ function boot() {
         initial: resolveInitialCredential(dashboardUrl, session?.id),
         log: (line) => console.error(line),
     });
+    permissionRequests = new PermissionRequests({
+        access,
+        request: (args) => dashboardClient.request(args),
+        log: (line) => console.error(line),
+    });
     listenerReminder = createListenerReminder({
         sessionId: config.session?.id,
         fetchHealth: () => dashboardClient.request({ method: "GET", basePath: "", path: "/api/plans", query: { limit: 1 } }),
@@ -290,14 +304,22 @@ function accessReply(ready, note) {
     const answer = note ? { ...ready.answer, note } : ready.answer;
     return ready.isError ? haltResult(JSON.stringify(answer)) : jsonResult(answer);
 }
+/**
+ * DX-4390 — a dashboard call behind the sign-in halt (and the 401 sign-out). DX-4434: the ONE place a refused call's
+ * `403 forbidden` gains its `request_permission` hint, so every tool that returns a dashboard result carries it.
+ */
+async function guardedCall(run) {
+    const guarded = await access.guard(run);
+    return "halt" in guarded ? guarded : { result: withForbiddenHint(guarded.result) };
+}
 /** DX-4390 — a tool's dashboard call behind the sign-in halt (and the 401 sign-out). */
 async function guardedJson(run) {
-    const guarded = await access.guard(run);
+    const guarded = await guardedCall(run);
     return "halt" in guarded ? haltResult(guarded.halt) : jsonResult(guarded.result);
 }
 /** DX-4400 — `guardedJson` for the read tools whose answer can be a whole document: bounded. */
 async function guardedBoundedJson(run) {
-    const guarded = await access.guard(run);
+    const guarded = await guardedCall(run);
     return "halt" in guarded ? haltResult(guarded.halt) : boundedJsonResult(guarded.result);
 }
 function jsonResult(value) {
@@ -415,7 +437,7 @@ async (args) => {
     const refused = termsAcceptanceCallHalt(args, config.baseUrl);
     if (refused)
         return haltResult(refused);
-    const guarded = await access.guard(() => danxbotApi(client, args));
+    const guarded = await guardedCall(() => danxbotApi(client, args));
     if ("halt" in guarded)
         return haltResult(guarded.halt);
     const result = guarded.result;
@@ -463,6 +485,29 @@ strictTool("attach_file", "Attach a LOCAL file to a card. This server reads and
     content_type: z.string().min(1).optional().describe("Override for the stored MIME type; default: an extension guess."),
     ...boardField,
 }, async (args) => guardedJson(() => attachFile(client, args)));
+// ---------------- request_permission (DX-4434, parent DX-4432) ----------------
+strictTool("request_permission", "Ask a person to grant this key ONE MORE permission. Call it when a call was refused `403 forbidden` naming a " +
+    "`permission`, or when you know you need one more. It returns AT ONCE with `{state, approvalUrl, confirmCode, " +
+    "expiresAt, instruction}`: show the person the code and URL, and keep working on anything else. If they approve, a " +
+    "later call simply succeeds with the same key (no new key, no re-auth). The same permissions asked again while " +
+    "pending return the pending request. A refusal (unknown permission, already held, rate limited) comes back as " +
+    "`{ok:false, status, body}`. If you are blocked without it, raise a problem on the card.", {
+    permissions: z
+        .array(z.string().min(1))
+        .min(1)
+        .describe("The permission keys to ask for: the `permission` a `403 forbidden` named."),
+    reason: z.string().min(1).describe("Why you need them; shown to the person who approves."),
+}, async (args) => {
+    const asked = await permissionRequests.ask(args);
+    if ("halt" in asked)
+        return haltResult(asked.halt);
+    if ("result" in asked) {
+        // DX-4148 — a terms refusal halts here as on every dashboard call.
+        const halt = termsHaltFor(asked.result);
+        return halt ? haltResult(halt) : jsonResult(asked.result);
+    }
+    return jsonResult(asked.answer);
+});
 // ---------------- plans (DX-2683) ----------------
 // THE BINDING ASYMMETRY IS IN THE SCHEMAS, NOT IN PROSE. `GET /api/plans/:planId`
 // takes a plan id in its path; the plan records, plan cards and

package/dist/permission-request.js

@@ -0,0 +1,141 @@
+import { POLL_GRACE_MS, defaultSleep } from "./session-access.js";
+import { McpOutdatedError } from "./version-floor.js";
+const PERMISSION_REQUESTS_BASE_PATH = "/api/permission-requests";
+const APPROVAL_REQUIRED_INSTRUCTION = "Show the person the approval URL and the confirm code (they check the code matches, then approve). Keep working on anything " +
+    "else: this call has returned and nothing waits. If they approve, this process picks the grant up in the background and a " +
+    "later call simply succeeds with the same key (no new key, no re-auth). If you are blocked without it, raise a problem on " +
+    "the card; a person sees problems in Needs You.";
+const APPROVAL_PENDING_INSTRUCTION = "This permission is already asked for and not yet decided. Remind the person of the confirm code and the approval URL; keep " +
+    "working on anything else. A grant is picked up in the background and a later call simply succeeds with the same key. If you " +
+    "are blocked without it, raise a problem on the card.";
+/** The dedupe set: sorted and de-duplicated, so the order the agent listed them in never matters. */
+function setOf(permissions) {
+    return [...new Set(permissions)].sort();
+}
+function isCreated(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.publicId === "string" &&
+        typeof v.confirmCode === "string" &&
+        typeof v.approvalUrl === "string" &&
+        typeof v.expiresAt === "string" &&
+        Number.isFinite(Date.parse(v.expiresAt)) &&
+        typeof v.pollMs === "number");
+}
+/** A 429's own `retryAfterMs`, else 0 (the poll then waits its normal interval). */
+function retryAfterMsOf(body) {
+    const ms = body?.retryAfterMs;
+    return typeof ms === "number" && Number.isFinite(ms) && ms > 0 ? ms : 0;
+}
+export class PermissionRequests {
+    deps;
+    pending = new Map();
+    queue = Promise.resolve();
+    now;
+    sleep;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+        this.sleep = deps.sleep ?? defaultSleep;
+    }
+    ask(args) {
+        const run = this.queue.then(() => this.askNow(args));
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+    async askNow(args) {
+        const permissions = setOf(args.permissions);
+        const key = JSON.stringify(permissions);
+        const existing = this.pending.get(key);
+        // DX-4418: a revoked or signed-out session never asks and never reads as pending; `guard` below answers its halt.
+        if (existing !== undefined && this.deps.access.isSignedIn()) {
+            return { answer: this.answer("approval_pending", existing) };
+        }
+        const guarded = await this.deps.access.guard(() => this.deps.request({ method: "POST", basePath: PERMISSION_REQUESTS_BASE_PATH, path: "", body: { permissions, reason: args.reason } }));
+        if ("halt" in guarded)
+            return { halt: guarded.halt };
+        const result = guarded.result;
+        // The dashboard's own 4xx (400, 409, 429 ...) goes back as it came: no retry, no default.
+        if (!result.ok)
+            return { result };
+        if (!isCreated(result.body)) {
+            throw new Error(`[danx-dashboard-mcp] POST ${PERMISSION_REQUESTS_BASE_PATH} answered without the request fields: ${JSON.stringify(result.body)}`);
+        }
+        const created = result.body;
+        this.pending.set(key, created);
+        void this.pollUntilDecided(key, created);
+        return { answer: this.answer("approval_required", created) };
+    }
+    answer(state, request) {
+        return {
+            state,
+            approvalUrl: request.approvalUrl,
+            confirmCode: request.confirmCode,
+            expiresAt: request.expiresAt,
+            instruction: state === "approval_required" ? APPROVAL_REQUIRED_INSTRUCTION : APPROVAL_PENDING_INSTRUCTION,
+        };
+    }
+    /**
+     * Polls until the request is decided or lapsed, then frees its set so a later call may ask again. Every ending is final: a
+     * halt (revoked, signed out, key lapsed) stops it silently, since the session no longer holds a key that could be granted.
+     */
+    async pollUntilDecided(key, request) {
+        try {
+            await this.poll(request);
+        }
+        catch (err) {
+            this.deps.log?.(`[danx-dashboard-mcp] permission request poll ended: ${err.message}`);
+        }
+        finally {
+            if (this.pending.get(key) === request)
+                this.pending.delete(key);
+        }
+    }
+    async poll(request) {
+        const giveUpAt = Date.parse(request.expiresAt) + POLL_GRACE_MS;
+        let waitMs = request.pollMs;
+        for (;;) {
+            await this.sleep(waitMs);
+            waitMs = request.pollMs;
+            if (this.now() > giveUpAt)
+                return;
+            let guarded;
+            try {
+                // `guard` runs before EVERY claim (DX-4418): a revoked or signed-out session answers its halt without a request.
+                guarded = await this.deps.access.guard(() => this.deps.request({ method: "POST", basePath: PERMISSION_REQUESTS_BASE_PATH, path: `/${request.publicId}/claim` }));
+            }
+            catch (err) {
+                // An outdated MCP will never get a different answer; any other failure is retried until the request lapses.
+                if (err instanceof McpOutdatedError)
+                    throw err;
+                this.deps.log?.(`[danx-dashboard-mcp] permission request poll failed, retrying: ${err.message}`);
+                continue;
+            }
+            if ("halt" in guarded)
+                return;
+            const claim = guarded.result;
+            if (claim.status === 429) {
+                waitMs = Math.max(request.pollMs, retryAfterMsOf(claim.body));
+                continue;
+            }
+            if (claim.status === 404)
+                return; // unknown or already reaped: nothing left to wait for
+            if (!claim.ok) {
+                throw new Error(`the dashboard refused the claim (${claim.status}): ${JSON.stringify(claim.body)}`);
+            }
+            const status = claim.body?.status;
+            switch (status) {
+                case "pending":
+                    continue;
+                case "approved":
+                case "claimed":
+                case "denied":
+                case "expired":
+                    return;
+                default:
+                    throw new Error(`the dashboard answered the claim with an unknown status: ${JSON.stringify(claim.body)}`);
+            }
+        }
+    }
+}

package/dist/session-access.js

@@ -29,7 +29,7 @@ import { McpOutdatedError } from "./version-floor.js";
 /** Longest a `plan_connect` call waits for an approval already asked for. */
 export const AWAIT_APPROVAL_MS = 45_000;
 /** The server reaps a lapsed request about a minute after expiry; polling past that finds nothing. */
-const POLL_GRACE_MS = 90_000;
+export const POLL_GRACE_MS = 90_000;
 /** A live server rewrites its key file this often, so an in-use key never ages out of the 7-day prune. */
 const KEEP_KEY_FILE_EVERY_MS = 60 * 60 * 1000;
 /** The request's title when the agent gave none: the session id's first characters. */
@@ -51,7 +51,7 @@ const NO_SESSION_ID_ERROR = "this server has no CLAUDE_CODE_SESSION_ID, so it ca
 const CLAIMED_LOST_ERROR = "the dashboard says this request was already claimed, but this process never received the key; " +
     "start a new request";
 const EXPIRED_NOTE = "The previous request expired before it was approved.";
-const defaultSleep = (ms) => new Promise((resolve) => {
+export const defaultSleep = (ms) => new Promise((resolve) => {
     setTimeout(resolve, ms).unref();
 });
 const notReady = (answer, isError, halt) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.229",
+  "version": "0.1.230",
   "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, danxbot_complete, and other per-dispatch lifecycle callbacks) (DX-3465, PLN-11 R-25).",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.29.0",
-    "@thehammer/danx-session-telemetry": "0.1.23",
+    "@thehammer/danx-session-telemetry": "0.1.25",
     "zod": "^3.25.76"
   },
   "devDependencies": {