@thehammer/danx-dashboard-mcp 0.1.171 → 0.1.173

package/dist/background-work.js

@@ -1,5 +1,5 @@
 /**
- * `danx-dashboard-mcp background-work <count|clear>` — the ONE-SHOT client of
+ * `danx-dashboard-mcp background-work <count|clear> <event-at>` — the ONE-SHOT client of
  * `PUT /api/plan-sessions/me/background-work` (DX-3367).
  *
  * WHO RUNS IT. The danxbot Claude Code plugin's `Stop` / `SubagentStop` /
@@ -29,10 +29,15 @@
  *     no-op — `{"ok":false,"reason":"no_connection_record"}` — the plugin
  *     hook simply does not forward anything further in this case, exactly
  *     what "no-op when the session isn't plan-connected" means in practice;
- *   - on success, `{"ok":true,"count":<number|null>}` echoes the `count`
- *     that was SUBMITTED for storage, not a re-read of the row — see
- *     `recordBackgroundWork`'s own doc (`db/plan-session-background-work.ts`)
- *     for why a plain no-op write is indistinguishable from a real one here;
+ *   - on success, `{"ok":true,"count":<number|null>,"applied":<boolean>}`
+ *     echoes the SUBMITTED `count`; `applied` is the server's answer to
+ *     whether it was stored (DX-3676: `false` for an out-of-order report
+ *     older than the one already on file — the caller must not treat it as
+ *     the dashboard's current count);
+ *   - DX-3676 — `<event-at>` is the ISO-8601 UTC time the reporting HOOK
+ *     fired, captured by the caller, never this process's own clock: the
+ *     hooks are async and can finish out of order, and the server orders
+ *     reports by this time;
  *   - human-readable diagnostics go to stderr only, never stdout.
  *
  * THE CREDENTIAL — the SAME resolver `bridge` and `plan-state` use, via
@@ -56,7 +61,7 @@ export const BACKGROUND_WORK_SUBCOMMAND = "background-work";
 export const BACKGROUND_WORK_PATH = "/api/plan-sessions/me/background-work";
 /** How long this one-shot call may take before it counts as a timeout. */
 export const BACKGROUND_WORK_REQUEST_TIMEOUT_MS = 5_000;
-const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${BACKGROUND_WORK_SUBCOMMAND} <non-negative-integer|clear>`;
+const USAGE = `usage: CLAUDE_CODE_SESSION_ID=<session-id> danx-dashboard-mcp ${BACKGROUND_WORK_SUBCOMMAND} <non-negative-integer|clear> <event-at ISO-8601 UTC>`;
 /**
  * Parse the ONE positional argument: `clear`, or a non-negative integer
  * string. Anything else is a usage error — never guessed or floored.
@@ -68,6 +73,15 @@ export function parseCountArg(raw) {
         return { error: `count must be "clear" or a non-negative integer, got "${raw}"` };
     return Number.parseInt(raw, 10);
 }
+/** DX-3676 — an ISO-8601 UTC instant, as `Date#toISOString` writes it (the server accepts exactly this). */
+const ISO_UTC_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+/** Parse the event-time argument (DX-3676). Never substituted with this process's clock. */
+export function parseEventAtArg(raw) {
+    if (!ISO_UTC_INSTANT.test(raw) || Number.isNaN(Date.parse(raw))) {
+        return { error: `event-at must be an ISO-8601 UTC timestamp (e.g. 2026-09-30T00:00:00.000Z), got "${raw}"` };
+    }
+    return raw;
+}
 /**
  * One authenticated PUT, with a hard timeout, classified into the output
  * shape this subcommand always prints — never a throw, never a non-2xx
@@ -81,8 +95,8 @@ export function parseCountArg(raw) {
  * (no `409 session_not_connected` equivalent), so status alone decides
  * whether a body read is even attempted.
  */
-export async function putBackgroundWork(options, count, deps) {
-    const sent = await sendSessionRequest(options, BACKGROUND_WORK_PATH, { method: "PUT", body: JSON.stringify({ count }) }, deps);
+export async function putBackgroundWork(options, report, deps) {
+    const sent = await sendSessionRequest(options, BACKGROUND_WORK_PATH, { method: "PUT", body: JSON.stringify({ count: report.count, eventAt: report.eventAt }) }, deps);
     if ("reason" in sent)
         return sent;
     const { status, text } = sent;
@@ -99,10 +113,12 @@ export async function putBackgroundWork(options, count, deps) {
     if (typeof body !== "object" ||
         body === null ||
         !("count" in body) ||
-        (body.count !== null && typeof body.count !== "number")) {
+        (body.count !== null && typeof body.count !== "number") ||
+        typeof body.applied !== "boolean") {
         return { ok: false, reason: "bad_response" };
     }
-    return { ok: true, count: body.count };
+    const shaped = body;
+    return { ok: true, count: shaped.count, applied: shaped.applied };
 }
 /** The bin's `background-work` subcommand, wired to the real process. Always resolves to exit code 0. */
 export async function runBackgroundWorkCommand(argv, env = process.env, 
@@ -111,7 +127,7 @@ resolveFrom = {}) {
     const write = (output) => {
         process.stdout.write(`${JSON.stringify(output)}\n`);
     };
-    if (argv.length !== 1) {
+    if (argv.length !== 2) {
         write({ ok: false, reason: "usage" });
         process.stderr.write(`${USAGE}\n`);
         return 0;
@@ -123,6 +139,12 @@ resolveFrom = {}) {
         return 0;
     }
     const count = parsed;
+    const eventAt = parseEventAtArg(argv[1]);
+    if (typeof eventAt === "object") {
+        write({ ok: false, reason: "usage" });
+        process.stderr.write(`${eventAt.error}\n${USAGE}\n`);
+        return 0;
+    }
     const resolved = await resolveSessionOptions(env, resolveFrom, USAGE);
     if (!resolved.ok) {
         // A session that never `plan_connect`-ed has no connection record — this
@@ -132,7 +154,7 @@ resolveFrom = {}) {
         process.stderr.write(`${resolved.detail}\n`);
         return 0;
     }
-    const output = await putBackgroundWork(resolved.options, count, {
+    const output = await putBackgroundWork(resolved.options, { count, eventAt }, {
         fetch: (input, init) => fetch(input, init),
         requestTimeoutMs: BACKGROUND_WORK_REQUEST_TIMEOUT_MS,
     });

package/dist/index.js

@@ -84,7 +84,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { z } from "zod";
 import { DashboardHttpClient } from "./http-client.js";
 import { planConnect, danxbotApi, danxbotApiList, danxbotApiSpec, attachFile, DANXBOT_API_METHODS, } from "./handlers.js";
-import { queryValueSchema } from "./types.js";
+import { bodyValueSchema, queryValueSchema } from "./types.js";
 import { registerLifecycleTools, applyLifecycleVisibility, readLifecycleUrlsFromEnv, } from "./lifecycle.js";
 function readEnvOrDie(name) {
     const v = process.env[name];
@@ -348,7 +348,16 @@ strictTool("danxbot_api", "Call any dashboard API route your credential may reac
     // elements are restricted to scalars, the only thing a comma-join can
     // represent losslessly.
     query: queryValueSchema.optional(),
-    body: z.unknown().optional(),
+    // DX-3685 — was `z.unknown()` (JSON Schema `{}`), which gave the model
+    // no structural hint that a body must be an OBJECT, so it sometimes
+    // sent `body` as a JSON-encoded string; `http-client.ts` then
+    // `JSON.stringify`'d that string again, and every dashboard route
+    // refused the resulting JSON-string-literal body with `body: must be an
+    // object` (every route's body schema is object-only — see
+    // `bodyValueSchema`'s own doc in `types.ts`). A string/array/etc body
+    // now fails zod validation at this boundary with a clear message
+    // instead of reaching the dashboard malformed.
+    body: bodyValueSchema.optional(),
     ...boardField,
 }, async (args) => jsonResult(await danxbotApi(client, args)));
 // ---------------- danxbot_api_list (DX-3465 A5, PLN-11 R-25) ----------------

package/dist/types.js

@@ -14,3 +14,33 @@ export const queryValueSchema = z.record(z.union([
     z.record(z.unknown()),
     z.array(z.union([z.string(), z.number(), z.boolean()])),
 ]));
+/**
+ * DX-3685 — the zod schema for `danxbot_api`'s `body` argument. Every
+ * dashboard route that takes a body validates it against a
+ * `BodyObjectSchema` (`src/http/body-schema.ts`, this repo) whose top-level
+ * `type` is ALWAYS `"object"` — no route ever accepts a body that is a
+ * string, an array, or any other JSON type at the top level (a plain-object
+ * request is the ONLY shape `validateBody`'s `"object"` case accepts; every
+ * other top-level shape hits its `body: must be an object` refusal).
+ *
+ * The previous schema, `z.unknown()`, compiles to `{}` in the tool's
+ * published JSON Schema — "any value, no structural hint at all" — which
+ * gave the calling model zero signal that an OBJECT was expected. In
+ * production this meant the model sometimes serialized `body` as a
+ * JSON-encoded STRING (e.g. `'{"text":"test"}'` instead of
+ * `{text:"test"}`); `http-client.ts#request` then ran `JSON.stringify` on
+ * that already-stringified value, producing a JSON STRING LITERAL as the
+ * wire body instead of a JSON object, which the dashboard's shared body
+ * validator correctly rejected with `body: must be an object` on every
+ * write (DX-3685).
+ *
+ * `z.record(z.unknown())` (the same idiom `queryValueSchema` above uses for
+ * its own field-tree branch) both (a) advertises `type: "object"` in the
+ * published JSON Schema, giving the model the structural hint it was
+ * missing, and (b) makes zod itself refuse a string/array/number/etc body
+ * at the MCP validation boundary with a clear, actionable
+ * `Expected object, received string`-class error — never silently
+ * forwarded, and never auto-`JSON.parse`d back into shape (Core Principle 1
+ * forbids tolerating a second input shape).
+ */
+export const bodyValueSchema = z.record(z.unknown());

package/package.json

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