@50arms/platform-mcp 0.0.0-stage → 0.1.436

package/dist/compaction-control.js

@@ -0,0 +1,142 @@
+/**
+ * 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 50arms 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, agents, valves, mode} | null, askedAt: string | null}`.
+ * DX-5218: `agents` holds each SUB-AGENT's own control by agent id, `{passAtTokens}`: the sub-agent's own safety-valve size. DX-6184: it carries no
+ * request and no release (a handover is proposed to the orchestrator through the main `ask`); a key beyond `passAtTokens` is ignored, as the dashboard's
+ * `isCompactionControl` and the plugin's gate ignore it. `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 { homedir } from "node:os";
+import { prefixedLine } from "./one-line.js";
+import { sessionControlDir, sessionControlFilePath, sessionControlFilesIn } from "./session-control-file.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;
+const isTime = (v) => typeof v === "number" && Number.isFinite(v);
+const isAsk = (a) => isRecord(a) && isCount(a.seq) && typeof a.at === "string" && a.at !== "" && typeof a.text === "string" && a.text.trim() !== "";
+/** Why an ask / release pair (the main agent's, or a sub-agent's) cannot be read, or `null` when it can. */
+function invalidAskAndRelease(c) {
+    if (c.ask !== null && !isAsk(c.ask))
+        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 && !isTime(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;
+}
+/** 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";
+    const own = invalidAskAndRelease(c);
+    if (own !== null)
+        return own;
+    if (!isRecord(c.agents))
+        return "agents must be an object keyed by agent id";
+    // DX-5222: no default for a missing table - a frame from a dashboard that predates it is refused, never read as "no valves"
+    if (!isRecord(c.valves))
+        return "valves must be an object keyed by model id";
+    // DX-6732: no default for a missing mode - a frame from a dashboard that predates it is refused, as with `valves`
+    if (c.mode !== "compact" && c.mode !== "clear")
+        return `mode must be "compact" or "clear"`;
+    for (const [modelId, size] of Object.entries(c.valves)) {
+        if (modelId === "")
+            return "valves has an empty model id";
+        if (!isCount(size) || size === 0)
+            return `valves.${modelId} must be a positive whole number`;
+    }
+    for (const [id, a] of Object.entries(c.agents)) {
+        if (id === "")
+            return "agents has an empty agent id";
+        if (!isRecord(a))
+            return `agents.${id} is not an object`;
+        if (!isCount(a.passAtTokens))
+            return `agents.${id}.passAtTokens must be a whole number`;
+    }
+    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,
+                agents: Object.fromEntries(Object.entries(control.agents).map(([id, a]) => [id, { passAtTokens: a.passAtTokens }])),
+                valves: control.valves,
+                mode: control.mode,
+            },
+        askedAt,
+    };
+}
+const COMPACTION_DIR = "compaction";
+export function compactionDir(home = homedir()) {
+    return sessionControlDir(COMPACTION_DIR, home);
+}
+/** `~/.config/danxbot/compaction/<sessionId>.json`, next to the plugin's other per-session records. */
+export function compactionFilePath(sessionId, home = homedir()) {
+    return sessionControlFilePath(COMPACTION_DIR, sessionId, home);
+}
+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` (`sessionControlFilesIn`: atomic writes, the weekly pruning of files no live relay touches). */
+export function compactionFilesIn(home = homedir(), now = Date.now) {
+    return sessionControlFilesIn(COMPACTION_DIR, parseCompactionFile, home, now);
+}

package/dist/credential.js

@@ -0,0 +1,104 @@
+/**
+ * DX-2862 / DX-4390 - the ONE resolver for this package's dashboard credential.
+ *
+ * WHY IT IS ONE FUNCTION AND NOT TWO. Two kinds of caller speak to the dashboard for the same
+ * Claude Code session: the MCP SERVER (the session's tools and its event relay) and the `restart_notice` predecessor lookup.
+ * When they resolved their credential independently they could differ (DX-2862): the session's tools worked, a
+ * lookup authenticated as somebody else, and its result was dropped with no error anywhere. So resolution lives HERE,
+ * both go through it, and the lookup additionally PROVES it holds the server's credential by comparing fingerprints
+ * (`session-connection.ts`).
+ *
+ * A credential comes from exactly one of two places:
+ *
+ *   - `DANX_DASHBOARD_CREDENTIAL` - the bearer verbatim. A DISPATCH declares it: the worker
+ *     substitutes it into the materialized `.mcp.json` from the dispatch overlay. Authoritative
+ *     when set, and it never signs out.
+ *   - a SESSION KEY (`session-key.ts`) - the key a user approved for this one session through
+ *     `plan_connect`. An operator session has no other credential: with neither of these it boots
+ *     signed out, and `plan_connect` asks for access.
+ *
+ * There is no token-file source (DX-4390): a long-lived bearer placed on disk by hand is exactly
+ * what request-and-approve replaces.
+ */
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { SessionKeyAbsentError, readSessionKeyFile, sessionKeyPath, } from "./session-key.js";
+export const CREDENTIAL_TOKEN_ENV = "DANX_DASHBOARD_CREDENTIAL";
+/**
+ * A credential that cannot be resolved. Carries the remedy beside the reason, because both of this
+ * module's callers report failures to a human who is not reading a log: the server prints it to
+ * stderr, and `restart_notice` answers it to the session.
+ */
+export class CredentialError extends Error {
+    fix;
+    constructor(detail, fix) {
+        super(detail);
+        this.name = "CredentialError";
+        this.fix = fix;
+    }
+}
+function readEnv(env, name) {
+    const value = env[name];
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+/** One line naming a source, for a message a human reads. Holds no secret. */
+export function describeCredentialSource(source) {
+    return source.kind === "session-key"
+        ? `the session key file ${source.path}`
+        : `the environment variable ${source.name}`;
+}
+/** The credential a source yields. Every failure is fatal and named. */
+export function readCredential(source, env) {
+    if (source.kind === "env") {
+        const token = readEnv(env, source.name);
+        if (token === null) {
+            throw new CredentialError(`${describeCredentialSource(source)} is unset or empty in this process`, `set ${source.name} for this process`);
+        }
+        return token;
+    }
+    try {
+        return readSessionKeyFile(source.path);
+    }
+    catch (err) {
+        throw new CredentialError(`cannot read ${describeCredentialSource(source)}: ${err.message}`, "call plan_connect to request access again; the key file is written when the request is approved");
+    }
+}
+/**
+ * A credential's IDENTITY, for comparing two processes' credentials without either of them
+ * handling the other's. The first 12 hex of SHA-256 - 48 bits, enough that two distinct tokens
+ * colliding is not a thing that happens, and nothing an attacker can invert.
+ */
+export function credentialFingerprint(token) {
+    return createHash("sha256").update(token).digest("hex").slice(0, 12);
+}
+/**
+ * This session's stored key, or `null` (never signed in here). A key file that is there but
+ * unusable throws `SessionKeyUnusableError`: the caller decides what to do with the file, nothing
+ * is guessed here. Never reads the environment: an operator tool that must authenticate as the
+ * session (`make finish-worktree`) uses this alone, so an inherited dispatch credential cannot win.
+ */
+export function resolveSessionKeyCredential(where) {
+    if (where.sessionId === undefined)
+        return null;
+    const path = sessionKeyPath(where.dashboardUrl, where.sessionId, where.home ?? homedir());
+    try {
+        const key = readSessionKeyFile(path);
+        return { source: { kind: "session-key", path }, token: key, fingerprint: credentialFingerprint(key) };
+    }
+    catch (err) {
+        if (err instanceof SessionKeyAbsentError)
+            return null;
+        throw err;
+    }
+}
+/**
+ * What this server boots with: the dispatch credential when the env declares one, else this
+ * session's stored key, else `null` (signed out).
+ */
+export function resolveBootCredential(env, where) {
+    const token = readEnv(env, CREDENTIAL_TOKEN_ENV);
+    if (token !== null) {
+        return { source: { kind: "env", name: CREDENTIAL_TOKEN_ENV }, token, fingerprint: credentialFingerprint(token) };
+    }
+    return resolveSessionKeyCredential(where);
+}

package/dist/danxbot-api-examples.js

@@ -0,0 +1,97 @@
+/**
+ * DX-3923 — correct first calls for the routes every card session uses,
+ * rendered into the `50arms_api` tool description (index.ts). The DX-3678
+ * grading run found the same avoidable 4xx in session after session (a card
+ * read's `fields` sent as a comma string, `fields.parent`, top-level list
+ * filters, a card edit sent to `PATCH /api/issues/:id`, a comment keyed
+ * `body`, retro `tests[].kind: "unit"`, the AC-tick route hunted through a
+ * 36 KB `50arms_api_list`) because nothing an agent
+ * reads before its first call showed the right shape. The tool description
+ * is the one surface every profile and every operator session carries.
+ * DX-4016 — the DX-3678 phase C run found the non-work profiles still paying
+ * a 4xx on three writes: a card create without `plan`, an edit whose `ac[]`
+ * items were keyed `text` (and one with no `content_hash`), and a retro whose
+ * flag was false but whose description was missing, then prose.
+ * DX-3917 / DX-4015 — the phase D run found 9 work sessions writing the
+ * retro before the `complete` transition (the list went AC tick -> retro,
+ * with no transition between) and 14 of 24 writing the transition with no
+ * spec call: the transition is now a shown write, placed before the retro.
+ * DX-3923 (phase E) — four triage card reads asked `fields` for
+ * `status_derived`, a LIST filter key the card-list example showed, so the
+ * list example filters by `q`/`include_closed` instead. Two haiku AC ticks
+ * read `ac` (no checklist id) and sent `ac` / `0` as the checklist id: the
+ * card read shows only `checklists`, and both tick ids name it.
+ * DX-4525 - the card-list and comment examples were trimmed: a list or a comment sent wrong is refused with a body naming
+ * the fix, and the spec call the description asks for first shows both. The dispatch-callback calls (complete, gate sign-off,
+ * code review) are NOT shown here: only a dispatch makes them, so every operator session would pay for them in this
+ * description; each profile's own instructions name its route and body.
+ *
+ * Kept as data, not prose, so danxbot's own tests can check each example
+ * against the live server contract (route table, resource fields, body
+ * schemas) and fail when one drifts — this package cannot import the
+ * server's constants itself (it is published on its own).
+ */
+export const DANXBOT_API_EXAMPLES = {
+    cardRead: {
+        method: "GET",
+        path: "/api/issues/<id>",
+        query: { fields: { description: true, agent_notes: true, comments: true, checklists: true, parent_title: true } },
+    },
+    cardCreate: {
+        method: "POST",
+        path: "/api/issues",
+        body: {
+            board: 3,
+            type: "Bug",
+            title: "<title>",
+            summary: "<one plain line: what this card is>",
+            description: "<markdown>",
+            plan: null,
+        },
+    },
+    cardEdit: {
+        method: "PATCH",
+        path: "/api/issues/<id>/edit",
+        body: { description: "<markdown>", ac: [{ title: "<criterion>" }], content_hash: "<content_hash from your read>" },
+    },
+    acTick: {
+        method: "PATCH",
+        path: "/api/issues/<id>/checklists/<checklists[].id>/items/<checklists[].items[].id>",
+        body: { status: "passing" },
+    },
+    transition: {
+        method: "POST",
+        path: "/api/issues/<id>/transition",
+        body: { action: "<action>", summary: "<text>" },
+    },
+    retro: {
+        method: "PUT",
+        path: "/api/issues/<id>/retro",
+        body: {
+            good: "<text>",
+            bad: "<text>",
+            correctable_danxbot_problem: false,
+            correctable_danxbot_problem_description: "",
+            action_item_ids: [],
+            commits: [{ sha: "<sha>" }],
+            tests: [],
+        },
+    },
+};
+/** The retro route's accepted `tests[].kind` values. */
+export const RETRO_TEST_KIND_EXAMPLES = ["group", "e2e"];
+function render(example) {
+    const { method, path, query, body } = example;
+    return JSON.stringify({ method, path, ...(query ? { query } : {}), ...(body ? { body } : {}) });
+}
+/** The description sentence `50arms_api` carries. */
+export function danxbotApiExamplesText() {
+    const e = DANXBOT_API_EXAMPLES;
+    return (`Correct first calls: card read ${render(e.cardRead)} (\`fields\` is an object, never a comma string); ` +
+        `card create ${render(e.cardCreate)} (\`plan\` required: "mine" or null; \`summary\` required, on every phase_children[] item too); ` +
+        `card edit ${render(e.cardEdit)} (only the keys you change; \`ac\` replaces the list); ` +
+        `AC tick ${render(e.acTick)}; ` +
+        `transition ${render(e.transition)}; ` +
+        `retro, only after \`complete\` or \`cancel\`, ${render(e.retro)} (description "" unless the flag is true; ` +
+        `\`tests[].kind\` ${RETRO_TEST_KIND_EXAMPLES.map((k) => `"${k}"`).join(" or ")}).`);
+}

package/dist/dashboard-identity.js

@@ -0,0 +1,14 @@
+export function dashboardIdentity(baseUrl) {
+    const url = baseUrl.replace(/\/+$/, "");
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`the dashboard URL is not an http(s) URL: ${JSON.stringify(baseUrl)}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new Error(`the dashboard URL is not an http(s) URL: ${JSON.stringify(baseUrl)}`);
+    }
+    return { url, host: parsed.host };
+}

package/dist/design-screenshot.js

@@ -0,0 +1,138 @@
+/**
+ * DX-4077 (operator decision, DX-4083 problem 1856) - the screenshot a design revision carries: a 1280x800 viewport PNG of the built
+ * page, taken in a headless Chromium with the network off.
+ *
+ * The browser is resolved the way Vite is, never as a package dependency: Playwright (or `playwright-core`) from the TARGET root first,
+ * then from this server's own working directory (`createRequire(<dir>/package.json)`, never a global lookup). The operator's rule is
+ * that "no preview image is a fine degraded mode": no browser, a failed launch, a failed capture or a PNG over 1 MiB all publish
+ * WITHOUT a screenshot and say why in the result (`none: <reason>`). That is the one stated degraded mode, reported and never silent,
+ * and it never fails the publish. `captureWith` is the shared launch-drive-shoot-close path (DX-5256): `plugin-screenshot.ts` drives it online
+ * against the dashboard's preview page, where a design capture runs offline against its own HTML.
+ */
+import { createRequire } from "node:module";
+import path from "node:path";
+export const SCREENSHOT_WIDTH = 1280;
+export const SCREENSHOT_HEIGHT = 800;
+/** The revision route's cap on a decoded screenshot (`MAX_SCREENSHOT_BYTES`, `src/issues/design-limits.ts`): 1 MiB. */
+export const MAX_SCREENSHOT_BYTES = 1024 * 1024;
+/** How long a loaded page may take to say it mounted (`danx-design:ready`) before the capture goes ahead anyway. */
+const READY_WAIT_MS = 5000;
+/** The message a design's harness posts when it has mounted (`DESIGN_FRAME_READY` in `@danxbot/ui`, restated: this package cannot import it). */
+export const READY_MESSAGE = "danx-design:ready";
+const READY_LISTENER = `window.__danxDesignReady = false; window.addEventListener("message", function (e) { ` +
+    `if (e.data && e.data.type === ${JSON.stringify(READY_MESSAGE)}) window.__danxDesignReady = true; });`;
+/**
+ * DX-5350: the screenshot renders the page outside `SandboxedFrame`, so `window.danxMiniApp` (which the frame injects, `@danxbot/ui` 27.0.0)
+ * is restated here as a stub: `holdReady`, a once-only `ready` and ready-on-`load` unless held, posting the same ready message the listener
+ * above hears. `reportError` and `onAppearance` are no-ops so a harness never throws.
+ */
+export const MINI_APP_STUB = `(function () { var held = false, posted = false; ` +
+    `function ready() { if (posted) return; posted = true; window.postMessage({ type: ${JSON.stringify(READY_MESSAGE)} }, "*"); } ` +
+    `window.danxMiniApp = { holdReady: function () { held = true; }, ready: ready, reportError: function () {}, onAppearance: function () { return function () {}; } }; ` +
+    `window.addEventListener("load", function () { if (!held) ready(); }); })();`;
+/**
+ * DX-5880: the screenshot renders the page outside the viewer, so `window.danxDesignOptions` (the viewer's option-picks channel,
+ * `frontend/src/lib/design-frame-options.ts`) is restated here with the RECOMMENDED picks, so the tile's screenshot shows the recommended combination.
+ * The groups are the revision's as the designer passed them; the server validates them when the revision is posted, so this stub reads them as typed.
+ * A design with no groups gets no global (the page then shows its own default).
+ */
+export function designOptionsStub(groups) {
+    if (groups.length === 0)
+        return null;
+    return (`(function () { var groups = ${JSON.stringify(groups).replace(/</g, "\\u003c")}; var picks = {}; ` +
+        `groups.forEach(function (g) { picks[g.key] = g.options.filter(function (o) { return g.recommended.indexOf(o) !== -1; }); }); ` +
+        `window.danxDesignOptions = { groups: groups, picks: function () { return JSON.parse(JSON.stringify(picks)); }, subscribe: function () { return function () {}; } }; })();`);
+}
+function none(reason) {
+    return { png_base64: null, screenshot: `none: ${reason}` };
+}
+/** One line of an error: its first line, bounded, so a long Playwright launch log never floods the result. */
+function oneLine(err) {
+    const text = err instanceof Error ? err.message : String(err);
+    const first = text.split("\n")[0].trim();
+    return first.length > 200 ? `${first.slice(0, 200)}...` : first;
+}
+/**
+ * The first of `playwright` / `playwright-core` that resolves from the target root, else from `cwd`. Returns the loaded module, or null
+ * when neither resolves.
+ */
+function resolvePlaywright(rootAbs, cwd) {
+    for (const base of [rootAbs, cwd]) {
+        const req = createRequire(path.join(base, "package.json"));
+        for (const name of ["playwright", "playwright-core"]) {
+            let resolved;
+            try {
+                resolved = req.resolve(name);
+            }
+            catch {
+                continue;
+            }
+            return { module: req(resolved), from: `${name} from ${base}` };
+        }
+    }
+    return null;
+}
+/**
+ * The one capture path (DX-4077, DX-5256): resolve a browser, open a 1280x800 device-scale-1 page, let `drive` bring it to the state to shoot,
+ * take the viewport PNG, and close the browser in a `finally` on every path. `offline` cuts the network (a design page is self-contained; a
+ * plugin's render needs the dashboard's own page and shims).
+ */
+export async function captureWith(where, offline, drive) {
+    let playwright;
+    try {
+        playwright = resolvePlaywright(where.rootAbs, where.cwd);
+    }
+    catch (err) {
+        return none(`playwright could not be loaded: ${oneLine(err)}`);
+    }
+    if (playwright === null) {
+        return none(`neither playwright nor playwright-core resolves from the target root ${where.rootAbs} or from ${where.cwd}`);
+    }
+    let browser;
+    try {
+        browser = await playwright.module.chromium.launch({ headless: true });
+    }
+    catch (err) {
+        return none(`the browser could not be launched (${playwright.from}): ${oneLine(err)}`);
+    }
+    try {
+        const context = await browser.newContext({ viewport: { width: SCREENSHOT_WIDTH, height: SCREENSHOT_HEIGHT }, deviceScaleFactor: 1, offline });
+        const page = await context.newPage();
+        const refusal = await drive(page);
+        if (typeof refusal === "string")
+            return none(refusal);
+        const png = await page.screenshot({ type: "png" });
+        if (png.length > MAX_SCREENSHOT_BYTES) {
+            return none(`the screenshot is ${png.length} bytes, over the ${MAX_SCREENSHOT_BYTES} byte (1 MiB) limit`);
+        }
+        return { png_base64: png.toString("base64"), screenshot: "captured" };
+    }
+    catch (err) {
+        return none(`the screenshot failed: ${oneLine(err)}`);
+    }
+    finally {
+        // A browser that will not close must not fail a publish whose screenshot is already decided.
+        await browser.close().catch((err) => console.error(`[platform-mcp] could not close the browser: ${oneLine(err)}`));
+    }
+}
+/** DX-5319: where the built html is served for the capture: a route answered by the capture itself, so the page is a real navigation and never reaches a network. */
+const DESIGN_PAGE_URL = "https://design.invalid/";
+/**
+ * Capture `html` as a 1280x800 viewport PNG (device scale 1, network disabled). The page is served from a route and navigated to, never
+ * `setContent`-ed: an init script runs on a navigation and not on `setContent`'s `document.write`, so the ready listener and the
+ * `window.danxMiniApp` stub would not exist and every capture would wait out the whole ready timeout (DX-5319, measured: 5.2 s, the stub
+ * undefined). It then gets a short wait for the harness's ready message (the page has loaded either way).
+ */
+export function captureScreenshot(html, where, optionGroups) {
+    return captureWith(where, true, async (page) => {
+        await page.addInitScript(READY_LISTENER);
+        await page.addInitScript(MINI_APP_STUB);
+        const options = designOptionsStub(optionGroups);
+        if (options !== null)
+            await page.addInitScript(options);
+        await page.route(DESIGN_PAGE_URL, (route) => route.fulfill({ status: 200, contentType: "text/html; charset=utf-8", body: html }));
+        await page.goto(DESIGN_PAGE_URL, { waitUntil: "load" });
+        // The page has loaded; a design that never posts ready (it threw) is still captured as it stands.
+        await page.waitForFunction("window.__danxDesignReady === true", undefined, { timeout: READY_WAIT_MS }).catch(() => undefined);
+    });
+}

package/dist/digest-hold.js

@@ -0,0 +1,67 @@
+import { isUrgent } from "./urgent-records.js";
+export const DIGEST_INTERVAL_MS = 10 * 60_000;
+export const DIGEST_PREFIX = "[plan events]";
+/** ONE combined record for every event held since the last flush. */
+function formatDigest(entries) {
+    const header = `${DIGEST_PREFIX} digest — ${entries.length} agent/machine event${entries.length === 1 ? "" : "s"} since the last update:`;
+    return [header, ...entries.map((e) => e.text)].join("\n");
+}
+export class DigestHold {
+    emit;
+    held = [];
+    timer = null;
+    /** `emit` receives every record the session should now be told, in order. */
+    constructor(emit) {
+        this.emit = emit;
+    }
+    /**
+     * Decide immediate vs. held. `operator` and `null` flush any pending digest first and then emit at once. `agent` /
+     * `machine` are appended to the hold, arming the timer only for the FIRST held event since the last flush: a later
+     * addition must never push the deadline out, or "at most every 10 minutes" would erode into "10 minutes after the last
+     * event", which can never fire while events keep arriving. Deduped by id (defense in depth, see the module docblock).
+     */
+    route(event) {
+        // DX-5846 / problem 2579: an event carrying acks is sent at once whoever made it (a changes-requested review is machine-made); the digest cannot carry one ack per event.
+        if ((event.origin === "agent" || event.origin === "machine") && event.acks.length === 0) {
+            if (event.id !== null && this.heldIds().includes(event.id))
+                return;
+            this.held.push(event);
+            // unref'd: a held digest never keeps the MCP server alive after its session ended
+            this.timer ??= setTimeout(() => this.flush(), DIGEST_INTERVAL_MS).unref();
+            return;
+        }
+        this.flush();
+        this.emit(event);
+    }
+    /** Combine every held event into ONE record and emit it, if there is anything to combine. */
+    flush() {
+        this.cancel();
+        if (this.held.length === 0)
+            return;
+        const entries = this.held;
+        this.held = [];
+        const ids = entries.map((e) => e.id).filter((id) => id !== null);
+        this.emit({ type: "event", id: ids.length === 0 ? null : Math.max(...ids), ids, text: formatDigest(entries), origin: null, urgent: isUrgent({ source: "digest" }), acks: [] });
+    }
+    /**
+     * Stop the timer WITHOUT flushing. For a stop where a newer listener already streams this session and will receive (and
+     * hold) the same events via the dashboard's replay, flushing here too would double-deliver the digest; for any other stop
+     * whatever is held was never marked delivered, so a later start picks it up the same way. A live, un-fired timer would also
+     * keep a process's event loop alive for no reason.
+     */
+    cancel() {
+        if (this.timer === null)
+            return;
+        clearTimeout(this.timer);
+        this.timer = null;
+    }
+    /** Drop everything held, without emitting it: the caller is letting go of the stream and the dashboard replays it. */
+    reset() {
+        this.cancel();
+        this.held = [];
+    }
+    /** Every id currently held, unflushed: handed to the next listener so it drops a replay of one. */
+    heldIds() {
+        return this.held.map((e) => e.id).filter((id) => id !== null);
+    }
+}