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

package/dist/urgent-records.js

@@ -0,0 +1,47 @@
+/**
+ * DX-4721 - THE ONE PLACE that decides whether a relayed plan-event record is URGENT.
+ *
+ * Background. `plan_events_wait` hands the caller (the 50arms plugin's relay, or an orchestrator's waiter sub-agent) a
+ * stream of records. The caller delivers an ordinary record after the session's running turn ends, and adds an URGENT one to
+ * the running turn at once. Which record is which is decided here, by the record's KIND, and nowhere else: every site that
+ * 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), the
+ * notice that this session's key was revoked (it can no longer call the dashboard), 50 Arms' request to prepare for a compaction, its ask to get ready to clear once a ready-list job ended (DX-6692), and the notice that the agent this session proposed was created (DX-5554). 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).
+ *
+ * The operator's direct stop. The dashboard writes no stop record today (the activity vocabulary, `IssueActivityKind` in
+ * `src/issues/db/issue-activity.ts`, and the stream's frames have none), so there is no kind to key on. When the dashboard adds
+ * one, it becomes a `RecordSource` here, urgent, in this same function: never a text match.
+ */
+/** DX-4721: true for a critical pacing stop and a revoked key; false for every other source (see the module docblock). */
+export function isUrgent(record) {
+    switch (record.source) {
+        case "pacing":
+            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;
+        // DX-6692: 50 Arms' ask to get ready to clear after the session's job ended must reach the agent inside a running turn, and wake an idle one, like a compaction request.
+        case "clear_ask":
+            return true;
+        // DX-5554: a person created the agent this session proposed; the session waits on that and must act at once, even mid-turn.
+        case "agent_created":
+            return true;
+        case "activity":
+        case "nudge":
+        case "resume":
+        case "assignment":
+        case "docs_land":
+        case "docs_draft":
+        case "owed_comment":
+        case "digest":
+        case "relay_notice":
+        case "fault":
+            return false;
+    }
+}

package/dist/version-floor.js

@@ -0,0 +1,146 @@
+/**
+ * DX-3597 — this package's half of the MCP-version-floor guard whose
+ * server-side half shipped in DX-3525 (`src/mcp-contract.ts`,
+ * `src/dashboard/serve-request.ts`, `src/resources/field-tree.ts`, all in
+ * the main danxbot repo — this package cannot import them, see below).
+ *
+ * The dashboard stamps `X-Danx-Mcp-Min-Version` on every routed `/api/*`
+ * response with the floor of the `api` surface (`MCP_SURFACE_MIN_VERSIONS.api`
+ * in `src/mcp-contract.ts` — DX-3597 made a floor track the version where
+ * its surface's MCP-exposed contract last changed, not "whatever's currently
+ * published"; DX-4215 scoped floors per surface, so only a change to the
+ * `50arms_api` passthrough itself blocks this client's calls. A floor for
+ * another surface, such as the stats wire, is enforced by the server on
+ * requests to that surface alone and never reaches this header; see that
+ * file's module doc for the full decision).
+ *
+ * `DashboardHttpClient.request()` (`./http-client.ts`) reads this header on
+ * the FIRST call this process makes (regardless of outcome — a proactive
+ * check, since a stale client can otherwise appear to work for a while on
+ * routes whose shape didn't change) and on every subsequent 4xx (a response
+ * that might otherwise read as an ordinary caller error, when it's really
+ * "you're running an old MCP"). When this package's own version is behind
+ * the advertised floor, it throws `McpOutdatedError` instead of returning
+ * the ordinary envelope — the same "throw rather than fabricate/silently
+ * pass through" contract `http-client.ts` already applies to a 5xx/network
+ * failure (see that file's own doc): an outdated MCP is exactly that class
+ * of failure, nothing the calling tool can meaningfully work around.
+ *
+ * Everything here is duplicated, not imported, from the server's
+ * `src/mcp-contract.ts` — this package is an INDEPENDENTLY PUBLISHED npm
+ * artifact (DX-2103) and cannot depend on the danxbot service's own `src/`
+ * tree. Keep the header name, the package name, and the version-compare
+ * behavior in agreement with that file by hand when either changes.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Must match `MCP_MIN_VERSION_HEADER` in danxbot's `src/mcp-contract.ts` verbatim. */
+export const MCP_MIN_VERSION_HEADER = "X-Danx-Mcp-Min-Version";
+/**
+ * DX-5897 - request header this package stamps on every call with its own version (`readOwnVersion`), so a dashboard route that enforces a
+ * surface floor of its own (`MCP_SURFACE_MIN_VERSIONS.profiles`: the agent-profile fetch) can refuse a stale session. Must match
+ * `MCP_VERSION_HEADER` in danxbot's `src/mcp-contract.ts` verbatim.
+ */
+export const MCP_VERSION_HEADER = "X-Danx-Mcp-Version";
+/** DX-6272 - response header of the session event stream carrying its `stream` floor. Must match `MCP_STREAM_MIN_VERSION_HEADER` in danxbot's `src/mcp-contract.ts` verbatim. */
+export const MCP_STREAM_MIN_VERSION_HEADER = "X-Danx-Stream-Min-Version";
+/** Must match `MCP_PACKAGE_NAME` in danxbot's `src/mcp-contract.ts` verbatim. */
+export const MCP_PACKAGE_NAME = "@50arms/platform-mcp";
+/**
+ * Numeric-dotted version compare (major.minor.patch, ...) — mirrors
+ * `compareMcpVersions` in danxbot's `src/mcp-contract.ts` behavior
+ * byte-for-byte (duplicated, not imported — see module doc). Both sides of
+ * this contract have only ever used plain numeric dotted versions, so this
+ * throws rather than silently falling back to a lexical compare, which
+ * would misorder "0.1.9" vs "0.1.10".
+ */
+export function compareMcpVersions(a, b) {
+    const parse = (v) => {
+        if (!/^\d+(\.\d+)*$/.test(v)) {
+            throw new Error(`[platform-mcp] "${v}" is not a plain numeric dotted version (major.minor.patch)`);
+        }
+        return v.split(".").map(Number);
+    };
+    const pa = parse(a);
+    const pb = parse(b);
+    const len = Math.max(pa.length, pb.length);
+    for (let i = 0; i < len; i++) {
+        const da = pa[i] ?? 0;
+        const db = pb[i] ?? 0;
+        if (da !== db)
+            return da - db;
+    }
+    return 0;
+}
+let cachedOwnVersion;
+/**
+ * Reads this package's OWN version from its `package.json` — always present
+ * next to `dist/` (or `src/`, under `npm run dev`'s `tsx`) at runtime even
+ * though `files: ["dist","README.md"]` excludes it from the tarball
+ * MANIFEST: npm always includes `package.json` in what it publishes and
+ * what it installs, regardless of `files` (the same guarantee `README` /
+ * `LICENSE` / the `main` entry get) — this reads the copy npm actually
+ * installed next to this module, not danxbot's own source tree. Both
+ * `dist/version-floor.js` and `src/version-floor.ts` sit exactly one
+ * directory below the package root, so `../package.json` resolves
+ * correctly under both the published (dist) and dev (`tsx src/index.ts`)
+ * shapes. Memoized — the version cannot change mid-process.
+ */
+export function readOwnVersion() {
+    if (cachedOwnVersion !== undefined)
+        return cachedOwnVersion;
+    const here = dirname(fileURLToPath(import.meta.url));
+    const pkgJsonPath = join(here, "..", "package.json");
+    const raw = readFileSync(pkgJsonPath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.version !== "string") {
+        throw new Error(`[platform-mcp] could not read this package's own version from ${pkgJsonPath}`);
+    }
+    cachedOwnVersion = parsed.version;
+    return cachedOwnVersion;
+}
+/** Test-only escape hatch — real callers never need to override the memoized read. */
+export function __resetOwnVersionCacheForTests() {
+    cachedOwnVersion = undefined;
+}
+/**
+ * Thrown by `assertVersionFloorSatisfied` when this package is running
+ * behind the server's advertised floor. Carries structured `have`/`need`
+ * fields (not just a prose message) so a caller that wants to branch on
+ * "is this specifically an outdated-MCP failure" can check `error.code`
+ * rather than pattern-match the message text.
+ */
+export class McpOutdatedError extends Error {
+    code = "mcp_outdated";
+    have;
+    need;
+    constructor(have, need) {
+        super(`[platform-mcp] mcp_outdated: this MCP is running ${MCP_PACKAGE_NAME}@${have}, but the dashboard's ` +
+            `50arms_api surface requires >= ${need}. Restart your Claude Code session to pick up the published update.`);
+        this.name = "McpOutdatedError";
+        this.have = have;
+        this.need = need;
+    }
+}
+/**
+ * Whether this package's own version is below the floor a response header
+ * advertised. `false` when `headerValue` is `null`/empty (an old-enough
+ * server, or a test stub, that never stamped one: nothing to compare
+ * against); a malformed floor throws (`compareMcpVersions`), never reads as
+ * no floor.
+ */
+export function ownVersionBelow(headerValue) {
+    if (!headerValue)
+        return false;
+    return compareMcpVersions(readOwnVersion(), headerValue) < 0;
+}
+/**
+ * Throws `McpOutdatedError` when this package is behind the floor a response
+ * header advertised (`ownVersionBelow`); returns otherwise.
+ */
+export function assertVersionFloorSatisfied(headerValue) {
+    if (headerValue && ownVersionBelow(headerValue)) {
+        throw new McpOutdatedError(readOwnVersion(), headerValue);
+    }
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@50arms/platform-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.437",
+  "description": "Stdio MCP server fronting the 50 Arms dashboard API for agents (operator sessions and dispatched workers alike): the generic 50arms_api/50arms_api_list/50arms_api_spec tools reach any route the caller's credential may call, plus dedicated agent-specific tools (plan_connect, request_permission, attach_file, and 50arms_slack_reply) (DX-3465, PLN-11 R-25).",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "platform-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/machine-daemon/run.js",
+    "!dist/machine-daemon/entry.js",
+    "!dist/machine-daemon/report.js",
+    "!dist/machine-toolkit/**",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/newms87/danxbot.git",
+    "directory": "packages/danx-dashboard-mcp"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "prepublishOnly": "bash ../../scripts/assert-tree-contains-origin-main.sh @50arms/platform-mcp",
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && node -e \"require('fs').chmodSync('dist/index.js', 0o755)\" && node scripts/build-machine-daemon.mjs",
+    "prepack": "node scripts/build-machine-daemon.mjs",
+    "verify:boot": "bash scripts/verify-boot.sh",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "gen-tool-defs": "tsx scripts/gen-tool-defs.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@danxbot/docs": "0.1.63",
+    "@danxbot/plugin-sdk": "0.2.39",
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "@50arms/session-telemetry": "0.1.66",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@danxbot/machine-vitals": "file:../machine-vitals",
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.27.3",
+    "tsx": "^4.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.5"
+  }
+}