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

package/dist/subagents-live.js

@@ -0,0 +1,162 @@
+/**
+ * `platform-mcp subagents-live <absolute main transcript .jsonl path>` — the LOCAL live feed of a session's
+ * sub-agents for the 50arms plugin's plan pane (DX-4508).
+ *
+ * WHY IT EXISTS. The pane's dashboard read (`GET /api/plan-sessions/:id/subagents`) lags the transcript by about 80s
+ * (the relay's 5s transcript poll, its 15s heartbeat flush, the pane's 60s read). A hooks module cannot tail the files
+ * itself (`$.fs.read` has no offset and refuses files over 4 MiB), but it can spawn a long-lived child and read its
+ * stdout. This is that child: it tails the session's transcript tree on this machine and prints each change within one
+ * 1s poll of Claude Code writing it.
+ *
+ * ONE PLACE COMPUTES EACH NUMBER. It runs the same `SessionLogWatcher` the relay runs (`session-stats.ts`), over the
+ * same session layout (the main transcript, and `<sessionDir>/<sessionId>/subagents/agent-<id>.jsonl` beside it), into
+ * the shared `createSubagentLiveView`, which feeds the same activity observer, usage ledger counter and pricing rule
+ * the dashboard's numbers come from. Nothing is counted or priced here.
+ *
+ * THE CONTRACT.
+ *   - stdout carries ONLY lines of `{"subagents":[<snapshot>, ...]}` (`SubagentLiveSnapshot`), one per poll in which
+ *     any snapshot changed, holding just the changed ones. The first line, printed once the whole tree has been read
+ *     from byte 0, carries every sub-agent discovered (an empty array for a session with none, so a reader knows the
+ *     catch-up is done). Every later line reads only bytes appended since.
+ *   - diagnostics go to stderr.
+ *   - a missing, relative or non-`.jsonl` path is refused: one stderr line, exit 2.
+ *   - it runs until killed: SIGTERM, SIGINT or a closed stdout stops it cleanly with exit 0.
+ *   - the transcript is a local file; the prices are not. The ONE network call is `GET /api/model-versions` at start (DX-5611: the
+ *     telemetry package holds no prices, so the declared `model_version_prices` price every reply, as the dashboard's ledger does),
+ *     authenticated with the session's approved dashboard key (`session-key.ts`) on `DANXBOT_DASHBOARD_URL`, else the plugin's hosted
+ *     dashboard. A start that cannot read the prices exits 1 with the reason on stderr; a cost is never guessed.
+ */
+import { statSync } from "node:fs";
+import { basename, dirname, isAbsolute } from "node:path";
+import { DEFAULT_DASHBOARD_URL } from "./machine-daemon/install.js";
+import { sendSessionRequest, tryParseJsonBody } from "./restart-notice.js";
+import { readSessionKeyFile, sessionKeyPath } from "./session-key.js";
+import { SessionLogWatcher, priceCardsOfCatalog, priceLookupOfCards, createSubagentLiveView, } from "@50arms/session-telemetry";
+export const SUBAGENTS_LIVE_SUBCOMMAND = "subagents-live";
+/** How often the transcript tree is polled: the pane's ~5s freshness target with room to spare. */
+export const SUBAGENTS_LIVE_POLL_MS = 1_000;
+const USAGE = `usage: platform-mcp ${SUBAGENTS_LIVE_SUBCOMMAND} <absolute path to the session's main transcript .jsonl>`;
+/** The validated transcript path, or the reason it is refused. */
+export function parseSubagentsLiveArgs(args) {
+    if (args.length !== 1)
+        return { ok: false, reason: `expected exactly one argument, got ${args.length}` };
+    const path = args[0];
+    if (!isAbsolute(path))
+        return { ok: false, reason: `"${path}" is not an absolute path` };
+    if (!path.endsWith(".jsonl"))
+        return { ok: false, reason: `"${path}" is not a .jsonl transcript` };
+    let isFile;
+    try {
+        isFile = statSync(path).isFile();
+    }
+    catch {
+        return { ok: false, reason: `"${path}" does not exist` };
+    }
+    if (!isFile)
+        return { ok: false, reason: `"${path}" is not a file` };
+    return { ok: true, path };
+}
+/** The one stdout line a poll's changes are printed as. */
+export function formatSubagentsLine(subagents) {
+    return `${JSON.stringify({ subagents })}\n`;
+}
+export async function runSubagentsLiveCommand(args, deps = realDeps()) {
+    const parsed = parseSubagentsLiveArgs(args);
+    if (!parsed.ok) {
+        deps.writeError(`[platform-mcp] ${SUBAGENTS_LIVE_SUBCOMMAND}: ${parsed.reason}. ${USAGE}`);
+        return 2;
+    }
+    const path = parsed.path;
+    let priceOf;
+    try {
+        priceOf = await deps.loadPrices(basename(path, ".jsonl"));
+    }
+    catch (err) {
+        deps.writeError(`[platform-mcp] ${SUBAGENTS_LIVE_SUBCOMMAND}: the model prices could not be read: ${err.message}`);
+        return 1;
+    }
+    const view = createSubagentLiveView(priceOf);
+    let stopped = false;
+    let caughtUp = false;
+    let watcher = null;
+    let resolveStopped = () => { };
+    const stoppedHere = new Promise((resolve) => {
+        resolveStopped = resolve;
+    });
+    const emit = () => {
+        if (stopped)
+            return;
+        const changed = view.takeChanged();
+        // DX-4508 — the first poll's line is printed even when empty: it tells the reader the catch-up read is complete.
+        if (changed.length === 0 && caughtUp)
+            return;
+        caughtUp = true;
+        if (!deps.writeLine(formatSubagentsLine(changed)))
+            stop();
+    };
+    const stop = () => {
+        stopped = true;
+        watcher?.stop();
+        resolveStopped();
+    };
+    watcher = deps.makeWatcher({
+        cwd: dirname(path),
+        sessionDir: dirname(path),
+        sessionId: basename(path, ".jsonl"),
+        // DX-4508 — no stored cursors: every file is read from byte 0 once, then only its appended bytes.
+        startCursors: {},
+        pollIntervalMs: SUBAGENTS_LIVE_POLL_MS,
+        onSourceDiscovered: view.onSourceDiscovered,
+        onPollComplete: emit,
+    });
+    watcher.onUsageLine(view.onLine);
+    // Either the process is told to stop, or stdout refused a line (`emit`).
+    const stopRequested = Promise.race([deps.untilStopped(), stoppedHere]);
+    await watcher.start();
+    await stopRequested;
+    stop();
+    return 0;
+}
+function realDeps() {
+    return {
+        makeWatcher: (options) => new SessionLogWatcher(options),
+        writeLine: (line) => {
+            if (process.stdout.destroyed || !process.stdout.writable)
+                return false;
+            process.stdout.write(line);
+            return true;
+        },
+        writeError: (line) => process.stderr.write(`${line}\n`),
+        loadPrices: (sessionId) => loadDeclaredPrices(sessionId),
+        untilStopped: () => new Promise((resolve) => {
+            process.once("SIGTERM", () => resolve());
+            process.once("SIGINT", () => resolve());
+            // A reader that closes the pipe ends the command: there is no one left to print to.
+            process.stdout.once("error", () => resolve());
+            process.stdout.once("close", () => resolve());
+        }),
+    };
+}
+/** How long the one price read may take before the command refuses to start. */
+const PRICES_REQUEST_TIMEOUT_MS = 10_000;
+/**
+ * DX-5611 - read the declared prices from the dashboard this session is signed in to, with the session's own approved key
+ * (`DANXBOT_DASHBOARD_URL`, else the plugin's hosted dashboard, as every other command here resolves it). `sendSessionRequest` carries the
+ * bound and the plugin-background header, so this read never extends the session's key.
+ */
+export async function loadDeclaredPrices(sessionId, io = {}) {
+    const envUrl = (io.env ?? process.env).DANXBOT_DASHBOARD_URL;
+    const dashboardUrl = (envUrl === undefined || envUrl === "" ? DEFAULT_DASHBOARD_URL : envUrl).replace(/\/+$/, "");
+    const token = readSessionKeyFile(sessionKeyPath(dashboardUrl, sessionId, io.home));
+    const fields = encodeURIComponent(JSON.stringify({ model_id: true, prices: true }));
+    const sent = await sendSessionRequest({ dashboardUrl, token, sessionId }, `/api/model-versions?fields=${fields}`, { method: "GET" }, { fetch: io.fetch ?? fetch, requestTimeoutMs: PRICES_REQUEST_TIMEOUT_MS });
+    if ("ok" in sent)
+        throw new Error(`GET /api/model-versions failed: ${sent.reason}`);
+    if (sent.status !== 200)
+        throw new Error(`GET /api/model-versions answered ${sent.status}`);
+    const parsed = tryParseJsonBody(sent.text);
+    const versions = parsed.ok ? parsed.body?.model_versions : undefined;
+    if (!Array.isArray(versions))
+        throw new Error("GET /api/model-versions answered no model_versions");
+    return priceLookupOfCards(priceCardsOfCatalog(versions));
+}

package/dist/terms-halt.js

@@ -0,0 +1,39 @@
+const TERMS_ACCEPTANCE_PATH = "/api/account/terms-acceptance";
+// Mirrors `termsAcceptUrl("/")` in src/lib/terms-accept-path.ts (a published package cannot import it);
+// terms-gate.integration.test.ts pins the server's link to the same literal. Only meaningful for an
+// operator session: a dispatch's DANXBOT_DASHBOARD_URL is internal, and a dispatch's own key is its
+// owner's API key (DX-4191), so a dispatched agent can meet this refusal too and hands the link to the
+// owner's operator.
+const ACCEPT_SCREEN_PATH = "/terms/accept?return=%2F";
+/** Keep in step with `termsRefusalInstruction` in src/dashboard/route-policy.ts. */
+export function haltText(acceptUrl, owner) {
+    return ("STOP ALL WORK NOW. The dashboard refuses your access until " +
+        (owner === undefined ? "the person you act for" : `${owner}, the user you act for,`) +
+        " accepts the current Terms of Use.\n\n" +
+        `Give the person this link to accept them: ${acceptUrl}\n\n` +
+        "Do not retry, do not look for another route, and never accept the Terms yourself. " +
+        "A dispatched agent ends with 50arms_api POST /api/dispatch-callbacks/complete {status: \"failed\", summary} " +
+        "naming this link (stop if that call is refused too), and never blocks the card.");
+}
+/** The halt text for a `403 terms_not_accepted` result, or null for any other result. */
+export function termsHaltFor(result) {
+    if (result.ok || result.status !== 403)
+        return null;
+    const body = result.body;
+    if (body?.error !== "terms_not_accepted")
+        return null;
+    if (typeof body.acceptUrl !== "string") {
+        throw new Error("[platform-mcp] a terms_not_accepted refusal carried no acceptUrl");
+    }
+    if (typeof body.owner !== "string") {
+        throw new Error("[platform-mcp] a terms_not_accepted refusal carried no owner");
+    }
+    return haltText(body.acceptUrl, body.owner);
+}
+/** The refusal for a call that would accept the Terms (never an agent's act), or null for any other call. */
+export function termsAcceptanceCallHalt(args, dashboardUrl) {
+    const path = args.path.split("?")[0].replace(/\/+$/, "");
+    if (args.method !== "POST" || path !== TERMS_ACCEPTANCE_PATH)
+        return null;
+    return haltText(`${dashboardUrl.replace(/\/+$/, "")}${ACCEPT_SCREEN_PATH}`);
+}

package/dist/text-limit.js

@@ -0,0 +1,24 @@
+/**
+ * DX-4318 — Claude Code delivers at most 2,048 characters (string length, not
+ * bytes) of an MCP server's instructions and of each tool description, then
+ * appends `… [truncated]`; nothing fails. Measured 2026-10-03 on three texts
+ * of this server, each cut at index 2,048. The limit here keeps 48 characters
+ * of headroom under that cut.
+ *
+ * Whether Claude Code also cuts a parameter description is unverified: none
+ * is long enough to show it. The package test holds them to the same limit, so
+ * the question stays moot.
+ */
+export const MCP_TEXT_LIMIT_CHARS = 2000;
+/**
+ * Refuses a text an agent would receive cut. Called where each text is
+ * registered, so an over-long one stops the module from loading: the package
+ * tests, the `tool-defs.json` generator and the publish boot check all fail
+ * on it.
+ */
+export function assertWithinTextLimit(label, text) {
+    if (text.length > MCP_TEXT_LIMIT_CHARS) {
+        throw new Error(`[platform-mcp] ${label} is ${text.length} characters, over the ${MCP_TEXT_LIMIT_CHARS}-character limit: ` +
+            `Claude Code would cut it and the agent would never see the rest. Shorten it.`);
+    }
+}

package/dist/tool-access.js

@@ -0,0 +1,114 @@
+/**
+ * DX-4523 (parent DX-4522) - which MCP tool a session is shown, decided in ONE place.
+ *
+ * A session sees a tool only when it can call it. Every tool is declared here with what makes it callable, and
+ * `toolsFor` is the one function that turns what a session holds into the tool names it advertises. The server
+ * (`tool-surface.ts`) applies it, and the danxbot service's budgets (`src/tokens/mcp-surface.ts`) measure it, so no
+ * second list of "which session gets which tool" exists anywhere.
+ *
+ * Three kinds of tool, by what makes them usable:
+ *
+ *   - bootstrap   `{permission: null, callback: null}` - what a session needs BEFORE it holds a key, or to ask for more:
+ *                 `plan_connect` (sign in, bind to a plan), `request_permission`, and the `50arms_api` trio.
+ *   - permission  `{permission}` - the dashboard route the tool calls needs this permission, so a key without it can
+ *                 never succeed. Shown once the key holds it, which includes a grant a person approves mid-session.
+ *   - callback    `{callback}` - the tool posts to a per-dispatch URL the worker injected (`lifecycle.ts`), so it is usable
+ *                 only when that URL exists. It also names the `permission` its dashboard route needs (both must hold).
+ *
+ * This module is pure data and one function, with no imports, because the danxbot service imports it directly and
+ * cannot take this package's MCP-SDK or zod dependencies.
+ */
+/**
+ * The environment variable a worker sets to inject each callback's URL. `lifecycle.ts` reads them, and the worker's overlay
+ * (`src/dispatch/dispatch-callbacks.ts`) writes them, so the name of a callback exists once.
+ */
+export const CALLBACK_ENV = {
+    slackReply: "DANXBOT_SLACK_REPLY_URL",
+};
+const BOOTSTRAP = { permission: null, callback: null };
+const needs = (permission) => ({ permission, callback: null });
+/** DX-4632: usable with no key (a session that has not signed in yet) and only on a person's session. */
+const OPERATOR_SESSION_BOOTSTRAP = { permission: null, callback: null, operatorSessionOnly: true };
+const needsAndPostsTo = (permission, callback) => ({ permission, callback });
+/**
+ * Every tool this server registers, with what makes it usable. `index.ts` refuses to register a tool that is not
+ * here, and `tool-access.test.ts` fails when an entry names no registered tool.
+ */
+export const TOOL_ACCESS = {
+    plan_connect: BOOTSTRAP,
+    // DX-5553 - `POST|DELETE /api/plan-sessions/me/card` (`cards.edit`: it assigns the card to the session's agent): the session holds a card on no plan.
+    card_connect: needs("cards.edit"),
+    request_permission: BOOTSTRAP,
+    "50arms_api": BOOTSTRAP,
+    "50arms_api_list": BOOTSTRAP,
+    "50arms_api_spec": BOOTSTRAP,
+    // DX-6847 / DX-6864 (DEC-571): the names the three API tools had before the rename, served beside the new ones (`LEGACY_TOOL_NAMES`) so a session whose text still
+    // names them keeps working until every install runs a plugin that names the new ones. DX-6864 removes these three entries.
+    danxbot_api: BOOTSTRAP,
+    danxbot_api_list: BOOTSTRAP,
+    danxbot_api_spec: BOOTSTRAP,
+    // `POST /api/issues/:id/attachments` (target `card`) or `POST /api/uploads/images` (target `inline_image`, replies `{url, markdown}`); one gate for both (DX-5241)
+    attach_file: needs("cards.edit"),
+    // DX-5294 (was DX-4077's design_publish) - builds in the agent's own checkout, then `POST /api/issues/:id/designs` (a new design) or `POST /api/issues/:id/designs/:designNo/revisions` (the next revision), both `cards.edit` (DX-4076, DX-5193). The routes it
+    // reads on the way (`GET /api/boards/:id`, `GET /api/repos/:id`, `GET /api/issues/:id`) are separate
+    // checks on the dashboard whose refusals come back verbatim.
+    mini_app_publish: needs("cards.edit"),
+    // DX-6070 - reads one revision's stored source (`GET /api/issues/:id/designs/:designNo/revisions/:revisionNo/source`, `cards.view`, the bundle route's permission) and writes it to the local checkout; the latest-revision lookup is `GET /api/issues/:id`. DX-6102: it declares that route's `cards.view`, since a declaration names the permission of the route it calls; the profiles that grant it (gate-designer, orchestrator) also grant `mini_app_publish`, so the pair is still advertised together.
+    mini_app_restore: needs("cards.view"),
+    // DX-5237 - builds in the agent's own checkout, then `GET /api/plugins` (to find the plugin by key), `POST /api/plugins` (a new key) and
+    // `POST /api/plugins/:id/revisions`; both writes are `plugins.publish`, which the default agent role holds. The lookup is a read the key's
+    // role already has (`boards.view`); a refusal of any step comes back verbatim.
+    plugin_publish: needs("plugins.publish"),
+    // DX-5582 - `docs_search` / `docs_read` read a local docs root with no dashboard call, and a team repo's hosted docs through `GET /api/docs/:repo/search` and
+    // `.../pages/:id` (`docs.view`, which the default agent role holds). One gate for both sources: a key without `docs.view` is not advertised the pair.
+    docs_search: needs("docs.view"),
+    docs_read: needs("docs.view"),
+    // DX-4233 - the plugin's relay waits on the session's plan events here: it opens the listener ticket
+    // (`POST /api/plan-sessions/me/stream-ticket`) and heartbeats (`.../me/heartbeat`), both `plans.view`.
+    // DX-4667 - not operator-session-only: an orchestrator's dispatch calls it too, through a background waiter sub-agent that
+    // wakes the orchestrator when a person answers. What keeps it off every other dispatch is the opt-in (`MCP_SERVER_OPT_IN_TOOLS`,
+    // `src/tokens/tool-defs.ts`) granted to the `orchestrator` profile alone, not this table.
+    plan_events_wait: needs("plans.view"),
+    // DX-4632 - the plugin's session-start hook asks which plan the session this one replaced was working. A restarted session boots
+    // signed out, so it holds no permission: like `plan_connect` it is a bootstrap tool, and a person's session's only (a dispatch
+    // never loads the plugin that calls it). The lookup asks the dashboard as the predecessor, with the credential the predecessor's
+    // record names.
+    restart_notice: OPERATOR_SESSION_BOOTSTRAP,
+    // The one dispatch callback that stays a tool (DX-4525): it reads local files. Its dashboard route's own policy names the
+    // permission (`route-policies/index.ts`); every other callback is a `50arms_api` call to a route under `callback-routes.ts`.
+    "50arms_slack_reply": needsAndPostsTo("slack.threads.post", "slackReply"),
+    // DX-6847 / DX-6864 (DEC-571): its name before the rename, served beside the new one like the three API tools above; DX-6864 removes this entry.
+    danxbot_slack_reply: needsAndPostsTo("slack.threads.post", "slackReply"),
+};
+/**
+ * DX-6847 / DX-6864 (DEC-571): each tool the rename gave a new name (the three generic API tools and the Slack reply), by its current name, mapped to the name it
+ * had before. The server registers the old name as a second tool with the same schema and the same handler, so the two answer identically; DX-6864 deletes this
+ * map and the four old entries above.
+ */
+export const LEGACY_TOOL_NAMES = {
+    "50arms_api": "danxbot_api",
+    "50arms_api_list": "danxbot_api_list",
+    "50arms_api_spec": "danxbot_api_spec",
+    "50arms_slack_reply": "danxbot_slack_reply",
+};
+/** True when a session holding `grant` can call the tool declared by `access`. */
+export function isUsable(access, grant) {
+    if (access.permission !== null && !grant.permissions.has(access.permission))
+        return false;
+    if (access.callback !== null && !grant.callbacks.has(access.callback))
+        return false;
+    if (access.operatorSessionOnly === true && !grant.operatorSession)
+        return false;
+    return true;
+}
+/** The ONE mapping from what a session holds to the tool names it advertises, sorted. */
+export function toolsFor(grant) {
+    return Object.keys(TOOL_ACCESS).filter((name) => isUsable(TOOL_ACCESS[name], grant)).sort();
+}
+/**
+ * The bootstrap set a DISPATCH sees: usable with no key, no callback, and not operator-session-only. A signed-out PERSON's
+ * session is shown this plus the operator-only bootstrap tools (`restart_notice`): see `bootstrapSurfaceTools()`.
+ */
+export function bootstrapTools() {
+    return toolsFor({ permissions: new Set(), callbacks: new Set(), operatorSession: false });
+}

package/dist/tool-defs.js

@@ -0,0 +1,58 @@
+/**
+ * DX-1606 — expose THIS MCP server's tool DEFINITIONS as plain JSON Schema, so
+ * the danxbot service can count the injected-context token cost of each tool.
+ *
+ * The server registers tools via `server.tool(name, description, zodShape, …)`
+ * (in `index.ts`); the zod shapes are converted to JSON Schema by the MCP SDK
+ * when it answers `tools/list`. Rather than re-declare the schemas (drift), this
+ * module drives the SAME `tools/list` the live agent receives by linking an
+ * in-memory client to the already-registered `server` — so the emitted defs are
+ * byte-identical to what the agent's context is charged for.
+ *
+ * The danxbot service can NOT take a zod / MCP-SDK runtime dependency (and the
+ * Docker image does not install this package's node_modules), so the service
+ * reads the COMMITTED `tool-defs.json` produced by `generateToolDefsJson()`
+ * below — plain data, no runtime deps. `gen-tool-defs.ts` writes that file and
+ * `tool-defs.test.ts` asserts it is in sync (fail-loud on drift).
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { server } from "./index.js";
+/** The server id the platform catalog mcp-server artifact is keyed by. */
+export const DANX_DASHBOARD_SERVER_ID = "platform";
+/**
+ * Introspect `server`'s registered tools via an in-memory `tools/list` — the
+ * exact `{name, description, inputSchema}` the agent's context receives — and
+ * map them to the API's `{name, description, input_schema}` shape, sorted by
+ * name for a stable committed artifact.
+ */
+export async function generateToolDefs() {
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+    const client = new Client({ name: "tool-defs-introspect", version: "0.0.0" });
+    await Promise.all([
+        server.connect(serverTransport),
+        client.connect(clientTransport),
+    ]);
+    try {
+        const { tools } = await client.listTools();
+        return tools
+            .map((t) => ({
+            name: t.name,
+            description: t.description ?? "",
+            input_schema: t.inputSchema,
+        }))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    finally {
+        await client.close();
+        await server.close();
+    }
+}
+/** The full `tool-defs.json` payload (server id + the introspected defs). */
+export async function generateToolDefsFile() {
+    return { server: DANX_DASHBOARD_SERVER_ID, tools: await generateToolDefs() };
+}
+/** Deterministic 2-space JSON the committed file + the drift test compare. */
+export function serializeToolDefsFile(file) {
+    return JSON.stringify(file, null, 2) + "\n";
+}

package/dist/tool-surface.js

@@ -0,0 +1,59 @@
+/**
+ * DX-4523 - applies `toolsFor` (`tool-access.ts`) to the tools this server registered, and keeps it applied as what the
+ * session holds changes: at boot, when sign-in completes, and when a person approves a `request_permission` grant.
+ *
+ * A changed tool list makes Claude Code refetch it (`notifications/tools/list_changed`) and invalidates the prompt cache, so the
+ * surface switches a tool ONLY when its visibility really changes and announces the change ONCE per apply: a grant that adds no
+ * tool, or a repeated sync, sends nothing. The SDK's own `enable()` / `disable()` each send a notification, so the surface sets
+ * `RegisteredTool.enabled` (a plain field the SDK's list handler reads) and calls `onChanged` once instead.
+ */
+import { toolsFor } from "./tool-access.js";
+export class ToolSurface {
+    tools;
+    callbacks;
+    options;
+    constructor(tools, callbacks, options) {
+        this.tools = tools;
+        this.callbacks = callbacks;
+        this.options = options;
+    }
+    /** Show exactly the tools `permissions` and this dispatch's callbacks allow. Returns the names whose visibility changed. */
+    apply(permissions) {
+        const wanted = new Set(toolsFor({ permissions, callbacks: this.callbacks, operatorSession: this.options.operatorSession }));
+        const changed = [];
+        for (const [name, tool] of this.tools) {
+            const want = wanted.has(name);
+            if (tool.enabled === want)
+                continue;
+            tool.enabled = want;
+            changed.push(name);
+        }
+        if (changed.length > 0)
+            this.options.onChanged();
+        return changed.sort();
+    }
+    /** The tool names currently shown. */
+    advertised() {
+        return [...this.tools].filter(([, tool]) => tool.enabled).map(([name]) => name).sort();
+    }
+}
+/** Re-reads the key's permissions and applies them. Calls run one at a time, so two triggers never interleave. */
+export class ToolAccessSync {
+    deps;
+    queue = Promise.resolve();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Resolves with the names whose visibility changed. A failed read rejects: the caller decides how loud that is. */
+    sync() {
+        const run = this.queue.then(async () => {
+            const permissions = (await this.deps.readPermissions()) ?? new Set();
+            const changed = this.deps.surface.apply(permissions);
+            if (changed.length > 0)
+                this.deps.log?.(`[platform-mcp] tool list changed: ${changed.join(", ")}`);
+            return changed;
+        });
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+}

package/dist/transcript-lineage.js

@@ -0,0 +1,105 @@
+/**
+ * DX-4234 - who a session was FORKED from, read from its own transcript. For the `restart_notice` tool.
+ *
+ * A desktop fork copies its parent's rows into the new transcript, then appends its own. The copied rows carry the session
+ * ids of the ancestors that wrote them, so a transcript runs `root ... parent ... own`: for a fork of a fork the FIRST row
+ * names the ROOT ancestor, not the parent. The parent is the LAST session id before the first row carrying this session's own
+ * id, so the read goes forward and stops at that row (it reads the copied prefix, never the rest of a file that can be tens
+ * of MB).
+ *
+ * ANSWERS:
+ *   - `{kind: "fork", parent}` - the nearest earlier session id.
+ *   - `{kind: "not_fork"}` - the first row naming a session is this session's own (a plain resume or a fresh start): it was
+ *     not forked from anything.
+ *   - throws `TranscriptUnreadable` - the file cannot say (missing, unreadable, a row that is not JSON, a row or prefix over
+ *     the caps below, no row names a session). The caller must be told; it is never a "not a fork".
+ *   - throws `TranscriptReadAborted` - the caller's deadline signal fired mid-read.
+ *
+ * BOUNDED: one row may be at most `TRANSCRIPT_MAX_LINE_BYTES` (a first row can be 428 KB or more) and the prefix read at most
+ * `TRANSCRIPT_MAX_PREFIX_BYTES`; over either is `TranscriptUnreadable`, never a quiet truncation.
+ */
+import { createReadStream } from "node:fs";
+export const TRANSCRIPT_MAX_LINE_BYTES = 4 * 1024 * 1024;
+export const TRANSCRIPT_MAX_PREFIX_BYTES = 64 * 1024 * 1024;
+export class TranscriptUnreadable extends Error {
+}
+export class TranscriptReadAborted extends Error {
+}
+const NEWLINE = 0x0a;
+export async function readTranscriptLineage(path, ownSessionId, options = {}) {
+    const source = options.open?.(path) ?? createReadStream(path);
+    const stop = () => {
+        source.destroy?.();
+    };
+    options.signal?.addEventListener("abort", stop, { once: true });
+    let carry = Buffer.alloc(0);
+    let total = 0;
+    let row = 0;
+    const seen = { nearest: null };
+    /** One complete line: the lineage when it settles the answer, else `undefined` to keep reading. */
+    const settle = (line) => {
+        if (line.toString("utf-8").trim() === "")
+            return undefined;
+        row += 1;
+        let parsed;
+        try {
+            parsed = JSON.parse(line.toString("utf-8"));
+        }
+        catch (err) {
+            throw new TranscriptUnreadable(`row ${row} of ${path} is not JSON: ${err.message}`);
+        }
+        const id = parsed?.sessionId;
+        if (typeof id !== "string" || id === "")
+            return undefined;
+        if (id !== ownSessionId) {
+            seen.nearest = id;
+            return undefined;
+        }
+        return seen.nearest === null ? { kind: "not_fork" } : { kind: "fork", parent: seen.nearest };
+    };
+    try {
+        for await (const chunk of source) {
+            if (options.signal?.aborted === true)
+                throw new TranscriptReadAborted("the deadline passed");
+            total += chunk.length;
+            if (total > TRANSCRIPT_MAX_PREFIX_BYTES) {
+                throw new TranscriptUnreadable(`${path} has no row of this session within its first ${TRANSCRIPT_MAX_PREFIX_BYTES} bytes`);
+            }
+            let start = 0;
+            for (let end = chunk.indexOf(NEWLINE, start); end !== -1; end = chunk.indexOf(NEWLINE, start)) {
+                const piece = chunk.subarray(start, end);
+                if (carry.length + piece.length > TRANSCRIPT_MAX_LINE_BYTES) {
+                    throw new TranscriptUnreadable(`row ${row + 1} of ${path} is over ${TRANSCRIPT_MAX_LINE_BYTES} bytes`);
+                }
+                const settled = settle(Buffer.concat([carry, piece]));
+                carry = Buffer.alloc(0);
+                if (settled !== undefined)
+                    return settled;
+                start = end + 1;
+            }
+            const rest = chunk.subarray(start);
+            if (carry.length + rest.length > TRANSCRIPT_MAX_LINE_BYTES) {
+                throw new TranscriptUnreadable(`row ${row + 1} of ${path} is over ${TRANSCRIPT_MAX_LINE_BYTES} bytes`);
+            }
+            carry = Buffer.concat([carry, rest]);
+        }
+    }
+    catch (err) {
+        if (options.signal?.aborted === true)
+            throw new TranscriptReadAborted("the deadline passed");
+        if (err instanceof TranscriptUnreadable || err instanceof TranscriptReadAborted)
+            throw err;
+        throw new TranscriptUnreadable(`cannot read ${path}: ${err.message}`);
+    }
+    finally {
+        options.signal?.removeEventListener("abort", stop);
+        stop();
+    }
+    const settled = settle(carry);
+    if (settled !== undefined)
+        return settled;
+    if (seen.nearest === null)
+        throw new TranscriptUnreadable(`no row of ${path} names a session`);
+    // The file ends before any row of this session: everything in it was copied from an earlier one.
+    return { kind: "fork", parent: seen.nearest };
+}

package/dist/types.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+/**
+ * The zod schema for `50arms_api`'s `query` argument, matching the
+ * `QueryValue` type above — a scalar, a field-tree object, or an array of
+ * scalars (comma-joined). Exported so it can be exercised
+ * directly in tests without going through the MCP tool-call machinery.
+ */
+export const queryValueSchema = z.record(z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.record(z.unknown()),
+    z.array(z.union([z.string(), z.number(), z.boolean()])),
+]));
+/**
+ * DX-3685 — the zod schema for `50arms_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());