@thehammer/danx-dashboard-mcp 0.1.304 → 0.1.305

package/dist/compaction-control.js

@@ -0,0 +1,145 @@
+/**
+ * DX-4993 (PLAN-42 rule R-4) - the compaction control of an OPERATOR session, as this package relays it.
+ *
+ * 50 Arms decides when a session is asked to prepare for a compaction and when its agent has said ready (the dashboard's `compaction-handshake/`). The
+ * session's stream carries the decision as a `compaction` frame (`event: compaction`, data `{"control": <control> | null}`, level-triggered: the current
+ * control on connect and whenever it changes). The relay does two things with each frame:
+ *
+ *   - the REQUEST (`control.ask`) reaches the agent as an urgent record, once per request (`ask.at` names it), so it arrives inside a running turn;
+ *   - the rest is written to ONE local file the danxbot plugin's `PreCompact` gate reads: `~/.config/danxbot/compaction/<sessionId>.json`. The gate never
+ *     asks the network: Claude Code proposes a compaction before every model request.
+ *
+ * The file is `{v: 1, sessionId, control: {floorTokens, passAtTokens, windowTokens, releaseUntilMs, releaseId} | null, askedAt: string | null}`. `sessionId` is the
+ * session the file was written for (the plugin refuses a file that names another); `windowTokens` is the context window the dashboard assumed for the session's
+ * model line (the plugin does not arm a session whose real window is smaller). `control: null` says the session is not under the handshake (the plugin disarms). `askedAt` is the relay's own memory of the last request it showed the agent, kept in the file so a restart
+ * of this server does not show it again; the plugin ignores it.
+ *
+ * The shapes below mirror the dashboard's `OperatorCompactionControl` (`src/dashboard/compaction-handshake/operator-session.ts`) and the plugin's gate
+ * (`danxbot/hooks/compaction/control.ts` in the plugin repo): this published package cannot import either. Each side tolerates the other's previous
+ * version by ignoring a frame or a file key it does not know and refusing nothing else (see the release order on DX-4993).
+ */
+import { mkdirSync, readFileSync, renameSync, utimesSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { prefixedLine } from "./one-line.js";
+import { assertSessionIdSegment, pruneStaleSessionFiles } from "./session-connection.js";
+/** The longest request line relayed whole (the pacing line's bound): the dashboard's request is a few hundred characters. */
+export const COMPACTION_ASK_MAX_CODE_POINTS = 1000;
+const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isCount = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
+/** Why a `compaction` frame's data cannot be read, or `null` when it can. */
+export function invalidCompactionReason(value) {
+    if (!isRecord(value) || !("control" in value))
+        return "the frame has no control";
+    const c = value.control;
+    if (c === null)
+        return null;
+    if (!isRecord(c))
+        return "control is not an object or null";
+    if (c.v !== 1)
+        return `control version ${JSON.stringify(c.v)} is not 1`;
+    if (!isCount(c.floorTokens) || !isCount(c.passAtTokens) || !isCount(c.windowTokens))
+        return "floorTokens, passAtTokens and windowTokens must be whole numbers";
+    // DX-4993: the plugin refuses a control whose valve is not above its floor, and the dashboard never sends one; a frame that would become such a file is a fault line
+    if (c.passAtTokens <= c.floorTokens)
+        return "passAtTokens must be above floorTokens";
+    if (c.windowTokens <= c.passAtTokens)
+        return "windowTokens must be above passAtTokens";
+    if (c.ask !== null) {
+        if (!isRecord(c.ask) || !isCount(c.ask.seq) || typeof c.ask.at !== "string" || c.ask.at === "" || typeof c.ask.text !== "string" || c.ask.text.trim() === "") {
+            return "ask must be null or {seq, at, text}";
+        }
+    }
+    if ((c.releaseUntilMs === null) !== (c.releaseId === null))
+        return "releaseUntilMs and releaseId are both set or both null";
+    if (c.releaseUntilMs !== null && !(typeof c.releaseUntilMs === "number" && Number.isFinite(c.releaseUntilMs)))
+        return "releaseUntilMs must be a number or null";
+    if (c.releaseId !== null && (typeof c.releaseId !== "string" || c.releaseId === ""))
+        return "releaseId must be a string or null";
+    return null;
+}
+/** The control of a valid frame's data (`invalidCompactionReason` is `null`). */
+export function controlOfFrame(value) {
+    const reason = invalidCompactionReason(value);
+    if (reason !== null)
+        throw new Error(`malformed compaction frame: ${reason}`);
+    return value.control;
+}
+/** The line the agent reads for a request: the dashboard's text on one line, prefixed like every stream line. */
+export function formatCompactionAskLine(ask) {
+    return prefixedLine(ask.text, COMPACTION_ASK_MAX_CODE_POINTS);
+}
+/** The file of session `sessionId` for `control` (`null`: not under the handshake) after the request `askedAt` was shown last. */
+export function fileOf(control, askedAt, sessionId) {
+    return {
+        v: 1,
+        sessionId,
+        control: control === null
+            ? null
+            : { floorTokens: control.floorTokens, passAtTokens: control.passAtTokens, windowTokens: control.windowTokens, releaseUntilMs: control.releaseUntilMs, releaseId: control.releaseId },
+        askedAt,
+    };
+}
+export function compactionDir(home = homedir()) {
+    return join(home, ".config", "danxbot", "compaction");
+}
+/** `~/.config/danxbot/compaction/<sessionId>.json`, next to the plugin's other per-session records. */
+export function compactionFilePath(sessionId, home = homedir()) {
+    assertSessionIdSegment(sessionId);
+    return join(compactionDir(home), `${sessionId}.json`);
+}
+export function parseCompactionFile(text, where) {
+    const parsed = JSON.parse(text);
+    if (!isRecord(parsed) || parsed.v !== 1 || typeof parsed.sessionId !== "string" || !("control" in parsed) || (parsed.askedAt !== null && typeof parsed.askedAt !== "string")) {
+        throw new Error(`${where} is not a compaction file`);
+    }
+    const reason = parsed.control === null ? null : invalidCompactionReason({ control: { ...parsed.control, v: 1, ask: null } });
+    if (reason !== null)
+        throw new Error(`${where}: ${reason}`);
+    return parsed;
+}
+/**
+ * The real store, under `home`. Every write also removes the files nothing has touched for a week (`pruneStaleSessionFiles`, like the session's connection
+ * record and key file). A live session's file is never among them: its relay touches the file at every heartbeat (`touch`), so only the files of sessions whose
+ * relay has been gone for a week are removed.
+ */
+export function compactionFilesIn(home = homedir(), now = Date.now) {
+    return {
+        read(sessionId) {
+            const path = compactionFilePath(sessionId, home);
+            let text;
+            try {
+                text = readFileSync(path, "utf-8");
+            }
+            catch (err) {
+                if (err.code === "ENOENT")
+                    return null;
+                throw err;
+            }
+            const file = parseCompactionFile(text, path);
+            if (file.sessionId !== sessionId)
+                throw new Error(`${path} was written for session ${JSON.stringify(file.sessionId)}`);
+            return file;
+        },
+        write(sessionId, file) {
+            const path = compactionFilePath(sessionId, home);
+            mkdirSync(dirname(path), { recursive: true });
+            pruneStaleSessionFiles(dirname(path), now());
+            // A sibling then a rename: the plugin's gate reads this file on every compaction proposal and must never see half of one.
+            const temp = `${path}.${process.pid}.tmp`;
+            writeFileSync(temp, JSON.stringify(file), "utf-8");
+            renameSync(temp, path);
+        },
+        touch(sessionId) {
+            const at = new Date(now());
+            try {
+                utimesSync(compactionFilePath(sessionId, home), at, at);
+            }
+            catch (err) {
+                // a session with no file has nothing to keep; any other failure is the caller's to report
+                if (err.code !== "ENOENT")
+                    throw err;
+            }
+        },
+    };
+}

package/dist/index.js

@@ -82,6 +82,7 @@
  * 5xx and network failures throw — never silently swallowed.
  */
 import { isEntrypointModule } from "./entrypoint.js";
+import { compactionFilesIn } from "./compaction-control.js";
 import { PlanEventRelay, WAIT_MAX_MS, WAIT_MIN_MS } from "./plan-events-relay.js";
 import { READ_IDLE_TIMEOUT_MS } from "./listen.js";
 import { REQUEST_TIMEOUT_MS, realScheduleInterval, realSleep } from "./session-stream.js";
@@ -256,6 +257,7 @@ function boot() {
         readIdleTimeoutMs: READ_IDLE_TIMEOUT_MS,
         requestTimeoutMs: REQUEST_TIMEOUT_MS,
         scheduleInterval: realScheduleInterval,
+        compactionFiles: compactionFilesIn(),
     });
     permissionWatch = new PermissionWatch({
         dashboardUrl,

package/dist/listen.js

@@ -41,6 +41,7 @@
  * (`src/issues/db/issue-activity.ts`); this published package cannot import
  * danxbot source.
  */
+import { controlOfFrame, invalidCompactionReason } from "./compaction-control.js";
 import { LINE_PREFIX, oneLine } from "./one-line.js";
 import { pacingRelayLine } from "./pacing-relay.js";
 import { isUrgent } from "./urgent-records.js";
@@ -524,6 +525,22 @@ export async function runListener(options, deps) {
             remember(id);
         return null;
     };
+    const emitCompaction = (message) => {
+        let parsed;
+        let invalid;
+        try {
+            parsed = JSON.parse(message.data);
+            invalid = invalidCompactionReason(parsed);
+        }
+        catch (err) {
+            invalid = `not JSON: ${err.message}`;
+        }
+        if (invalid === null)
+            deps.write({ type: "compaction", control: controlOfFrame(parsed) });
+        else
+            deps.write({ type: "event", id: null, text: `${LINE_PREFIX} could not read compaction control (${invalid}): ${oneLine(message.data, 300)}`, origin: null, urgent: isUrgent({ source: "fault" }), scope: "session" });
+        return null;
+    };
     const handle = (message) => {
         if (message.event === "end") {
             // DX-2920 (round 3) — a JSON.parse failure here falls through to the
@@ -551,6 +568,9 @@ export async function runListener(options, deps) {
         // DX-4342 - the auto-resume's message once the limit that paused or stopped this session has reset: advisory like a pacing message.
         if (message.event === "resume")
             return emitAdvisory(message, "resume message", invalidResumeReason, (p) => formatResumeLine(p), () => ({ source: "resume" }), "session");
+        // DX-4993 - the compaction control: level-triggered, no id, no replay. A frame that cannot be read is a fault line (never silence), and the next frame still lands.
+        if (message.event === "compaction")
+            return emitCompaction(message);
         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

package/dist/plan-events-relay.js

@@ -53,11 +53,13 @@
  * mint / inventory requests are aborted by `close()`, and `close()` also clears a pending call's wait timer (the one ref'd timer,
  * held only until the call answers). The server calls `close()` when its transport closes and when its stdin ends (`shutdown.ts`).
  */
+import { fileOf, formatCompactionAskLine } from "./compaction-control.js";
 import { DigestHold } from "./digest-hold.js";
 import { HeartbeatReporter } from "./heartbeat-reporter.js";
 import { capResumeIds, DELIVERED_ID_MEMORY, HEALTHY_CONNECTION_MS, INITIAL_BACKOFF_MS, MAX_BACKOFF_MS, runListener, } from "./listen.js";
 import { fetchPlanInventory, HEARTBEAT_INTERVAL_MS, heartbeatConnection, MAX_REFUSED_TICKETS_IN_A_ROW, mintTicket, } from "./session-stream.js";
 import { fixForStop } from "./stop-fixes.js";
+import { LINE_PREFIX } from "./one-line.js";
 import { isUrgent } from "./urgent-records.js";
 /** The shortest and longest wait one call may ask for; a short ceiling keeps an orphaned waiter's life short. */
 export const WAIT_MIN_MS = 1_000;
@@ -295,10 +297,22 @@ export class PlanEventRelay {
             this.suspend();
             return;
         }
-        if (this.deps.auth() === null)
+        const auth = this.deps.auth();
+        if (auth === null)
             return;
+        this.touchCompactionFile(auth.sessionId);
         this.reporter?.tick();
     }
+    /** DX-4993: a live relay keeps its session's compaction file out of the weekly pruning (`CompactionFiles.touch`); a failure is reported to stderr, never ends the heartbeat. */
+    touchCompactionFile(sessionId) {
+        try {
+            this.deps.compactionFiles.touch(sessionId);
+        }
+        catch (err) {
+            process.stderr.write(`plan_events_wait: the compaction control file could not be kept alive: ${err instanceof Error ? err.message : String(err)}
+`);
+        }
+    }
     /**
      * Let go of everything the relay holds for a caller: the stream, the heartbeat, the digest, and the plan-scoped records.
      * What was held for a digest was never marked delivered, so the dashboard's replay (after the caller's cursor) returns it to
@@ -338,6 +352,38 @@ export class PlanEventRelay {
             this.terminal(run, "relay_failed", message);
         });
     }
+    /**
+     * DX-4993 - the session's compaction control arrived: show the agent a request it has not been shown, and write the file the plugin's gate reads.
+     * A control with a new request (`ask.at`) is shown once: the file remembers which, so a reconnect, a restart of this server or a repeat of the same
+     * frame shows nothing twice. A file that cannot be read or written is a line to the agent (a fault: the gate cannot work), never silence.
+     */
+    applyCompaction(control) {
+        const auth = this.deps.auth();
+        if (auth === null)
+            return;
+        // DX-4993: a file that cannot be read is no memory of what was shown, never a reason not to write: the write below replaces it (otherwise the same fault repeats
+        // at every frame and the plugin's gate never gets a readable control). The agent is told once per frame that it happened.
+        let askedAt = null;
+        try {
+            askedAt = this.deps.compactionFiles.read(auth.sessionId)?.askedAt ?? null;
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            this.digest.route({ type: "event", id: null, text: `${LINE_PREFIX} the compaction control file of this session could not be read (${detail}); it is replaced`, origin: null, urgent: isUrgent({ source: "fault" }), scope: "session" });
+        }
+        try {
+            const ask = control?.ask ?? null;
+            const show = ask !== null && ask.at !== askedAt;
+            this.deps.compactionFiles.write(auth.sessionId, fileOf(control, ask === null ? null : show ? ask.at : askedAt, auth.sessionId));
+            if (show) {
+                this.digest.route({ type: "event", id: null, text: formatCompactionAskLine(ask), origin: null, urgent: isUrgent({ source: "compaction_ask" }), scope: "session" });
+            }
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            this.digest.route({ type: "event", id: null, text: `${LINE_PREFIX} the compaction control could not be kept for this session (${detail}), so its compaction gate cannot work`, origin: null, urgent: isUrgent({ source: "fault" }), scope: "session" });
+        }
+    }
     current(run) {
         return this.run === run && !run.abort.signal.aborted;
     }
@@ -415,6 +461,10 @@ export class PlanEventRelay {
                         return;
                     }
                     attempt.emitted = true;
+                    if (output.type === "compaction") {
+                        this.applyCompaction(output.control);
+                        return;
+                    }
                     this.digest.route(output);
                 },
                 onState: (state) => {

package/dist/session-connection.js

@@ -67,7 +67,10 @@ export function sessionConnectionPath(sessionId, home = homedir()) {
     assertSessionIdSegment(sessionId);
     return join(sessionConnectionDir(home), `${sessionId}.json`);
 }
-/** Remove the per-session `.json` files in `dir` that nothing has touched for `STALE_RECORD_MS`. */
+/**
+ * Remove the per-session `.json` files in `dir` that nothing has touched for `STALE_RECORD_MS`, and the `.tmp` files a failed
+ * write-then-rename left beside them (DX-4993).
+ */
 export function pruneStaleSessionFiles(dir, now) {
     let names;
     try {
@@ -77,7 +80,7 @@ export function pruneStaleSessionFiles(dir, now) {
         return; // nothing written yet
     }
     for (const name of names) {
-        if (!name.endsWith(".json"))
+        if (!name.endsWith(".json") && !name.endsWith(".tmp"))
             continue;
         const file = join(dir, name);
         try {

package/dist/urgent-records.js

@@ -7,8 +7,8 @@
  * creates a record names its source and calls `isUrgent`; none writes an `urgent` literal of its own. The flag is a required
  * boolean on `ListenEvent`, so a site that forgets it fails `make typecheck`, and no reader defaults a missing one.
  *
- * Urgent: a critical usage-pacing stop (the account is about to hit its limit and the session must wind down now), and the
- * notice that this session's key was revoked (it can no longer call the dashboard). Everything else is not: activity events
+ * Urgent: a critical usage-pacing stop (the account is about to hit its limit and the session must wind down now), the
+ * notice that this session's key was revoked (it can no longer call the dashboard), and 50 Arms' request to prepare for a compaction. Everything else is not: activity events
  * (comments, answers, problems, blocks, design and pull-request outcomes), the idle nudge, the auto-resume message, a digest,
  * the relay's own failure notice, and any line that reports an unreadable event or frame (a fault line).
  *
@@ -23,6 +23,9 @@ export function isUrgent(record) {
             return record.level === "critical";
         case "key_revoked":
             return true;
+        // DX-4993: 50 Arms' request to prepare for a compaction must reach the agent inside a running turn, not after it: the compaction waits for the agent's ready.
+        case "compaction_ask":
+            return true;
         case "activity":
         case "nudge":
         case "resume":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/danx-dashboard-mcp",
-  "version": "0.1.304",
+  "version": "0.1.305",
   "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, request_permission, attach_file, and danxbot_slack_reply) (DX-3465, PLN-11 R-25).",
   "license": "MIT",
   "type": "module",