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

package/dist/one-line.js

@@ -0,0 +1,25 @@
+/**
+ * DX-2735 — the ONE way this package renders human text into an agent-facing
+ * line: the dashboard-event stream's notification line and the problems
+ * reminder both go through it, so they can never disagree about how a
+ * statement looks.
+ *
+ * Every whitespace run (newlines included) collapses to a single space, because
+ * a notification is one line and a reminder quotes statements inline. The
+ * optional cap counts CODE POINTS, never UTF-16 units: `String#slice` can cut
+ * an emoji or any astral character in half and leave a lone surrogate, which
+ * renders as garbage. A capped string ends with "…" so truncation is visible.
+ */
+export function oneLine(text, maxCodePoints) {
+    const collapsed = text.replace(/\s+/g, " ");
+    if (maxCodePoints === undefined)
+        return collapsed;
+    const points = Array.from(collapsed);
+    return points.length > maxCodePoints ? `${points.slice(0, maxCodePoints).join("")}…` : collapsed;
+}
+/** The prefix of every line the stream listener emits for the session to read. */
+export const LINE_PREFIX = "[platform stream]";
+/** `text` as one prefixed listener line, optionally cut (the one template of a listener line, shared with whoever must know its length). */
+export function prefixedLine(text, maxCodePoints) {
+    return oneLine(`${LINE_PREFIX} ${text}`, maxCodePoints);
+}

package/dist/pacing-relay.js

@@ -0,0 +1,16 @@
+import { prefixedLine } from "./one-line.js";
+/**
+ * DX-4341 - the longest pacing line the stream listener relays whole. `formatPacingLine` (`listen.ts`) cuts a pacing line, PREFIX INCLUDED and
+ * after whitespace collapses, to this many code points and ends it with an ellipsis, which would drop the tail of a message first (an
+ * orchestrator's duties, the end of the pause note format). The dashboard renders the message and refuses one that would be cut
+ * (`pacingRelayLength`, used by `src/team-pacing/pacing-message.ts`), so the cut and the refusal measure the very same line.
+ */
+export const PACING_RELAY_MAX_CODE_POINTS = 1000;
+/** The line the listener emits for pacing text `text`: prefixed, on one line, cut at the relay maximum. */
+export function pacingRelayLine(text) {
+    return prefixedLine(text, PACING_RELAY_MAX_CODE_POINTS);
+}
+/** How many code points the listener's line for `text` has before the cut. */
+export function pacingRelayLength(text) {
+    return Array.from(prefixedLine(text)).length;
+}

package/dist/permission-request.js

@@ -0,0 +1,134 @@
+import { defaultSleep } from "./session-access.js";
+import { McpOutdatedError } from "./version-floor.js";
+const PERMISSION_REQUESTS_BASE_PATH = "/api/permission-requests";
+const APPROVAL_REQUIRED_INSTRUCTION = "Show the person the approval URL and the confirm code (they check the code matches, then approve). Keep working on anything " +
+    "else: this call has returned and nothing waits. The request stays open until this session ends, however long they take. If " +
+    "they approve, this process picks the grant up in the background and a later call simply succeeds with the same key (no new " +
+    "key, no re-auth). If you are blocked without it, raise a problem on the card; a person sees problems in Needs You.";
+const APPROVAL_PENDING_INSTRUCTION = "This permission is already asked for and not yet decided; the request stays open until this session ends. Remind the person " +
+    "of the confirm code and the approval URL; keep working on anything else. A grant is picked up in the background and a later " +
+    "call simply succeeds with the same key. If you are blocked without it, raise a problem on the card.";
+/** The dedupe set: sorted and de-duplicated, so the order the agent listed them in never matters. */
+function setOf(permissions) {
+    return [...new Set(permissions)].sort();
+}
+function isCreated(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.publicId === "string" &&
+        typeof v.confirmCode === "string" &&
+        typeof v.approvalUrl === "string" &&
+        typeof v.pollMs === "number");
+}
+/** A 429's own `retryAfterMs`, else 0 (the poll then waits its normal interval). */
+function retryAfterMsOf(body) {
+    const ms = body?.retryAfterMs;
+    return typeof ms === "number" && Number.isFinite(ms) && ms > 0 ? ms : 0;
+}
+export class PermissionRequests {
+    deps;
+    pending = new Map();
+    queue = Promise.resolve();
+    sleep;
+    constructor(deps) {
+        this.deps = deps;
+        this.sleep = deps.sleep ?? defaultSleep;
+    }
+    ask(args) {
+        const run = this.queue.then(() => this.askNow(args));
+        this.queue = run.catch(() => undefined);
+        return run;
+    }
+    async askNow(args) {
+        const permissions = setOf(args.permissions);
+        const key = JSON.stringify(permissions);
+        const existing = this.pending.get(key);
+        // DX-4418: a revoked or signed-out session never asks and never reads as pending; `guard` below answers its halt.
+        if (existing !== undefined && this.deps.access.isSignedIn()) {
+            return { answer: this.answer("approval_pending", existing) };
+        }
+        const guarded = await this.deps.access.guard(() => this.deps.request({ method: "POST", basePath: PERMISSION_REQUESTS_BASE_PATH, path: "", body: { permissions, reason: args.reason } }));
+        if ("halt" in guarded)
+            return { halt: guarded.halt };
+        const result = guarded.result;
+        // The dashboard's own 4xx (400, 409, 429 ...) goes back as it came: no retry, no default.
+        if (!result.ok)
+            return { result };
+        if (!isCreated(result.body)) {
+            throw new Error(`[platform-mcp] POST ${PERMISSION_REQUESTS_BASE_PATH} answered without the request fields: ${JSON.stringify(result.body)}`);
+        }
+        const created = result.body;
+        this.pending.set(key, created);
+        void this.pollUntilDecided(key, created);
+        return { answer: this.answer("approval_required", created) };
+    }
+    answer(state, request) {
+        return {
+            state,
+            approvalUrl: request.approvalUrl,
+            confirmCode: request.confirmCode,
+            instruction: state === "approval_required" ? APPROVAL_REQUIRED_INSTRUCTION : APPROVAL_PENDING_INSTRUCTION,
+        };
+    }
+    /**
+     * Polls until the request is decided or expired, then frees its set so a later call may ask again. Every ending is final: a
+     * halt (revoked, signed out, key lapsed) stops it silently, since the session no longer holds a key that could be granted.
+     */
+    async pollUntilDecided(key, request) {
+        try {
+            await this.poll(request);
+        }
+        catch (err) {
+            this.deps.log?.(`[platform-mcp] permission request poll ended: ${err.message}`);
+        }
+        finally {
+            if (this.pending.get(key) === request)
+                this.pending.delete(key);
+        }
+    }
+    // DX-4530: no give-up time - the request is open until it is decided or the key dies (the `guard` halt).
+    async poll(request) {
+        let waitMs = request.pollMs;
+        for (;;) {
+            await this.sleep(waitMs);
+            waitMs = request.pollMs;
+            let guarded;
+            try {
+                // `guard` runs before EVERY claim (DX-4418): a revoked or signed-out session answers its halt without a request.
+                guarded = await this.deps.access.guard(() => this.deps.requestOwn({ method: "POST", basePath: PERMISSION_REQUESTS_BASE_PATH, path: `/${request.publicId}/claim` }));
+            }
+            catch (err) {
+                // An outdated MCP will never get a different answer; any other failure is retried until the request ends.
+                if (err instanceof McpOutdatedError)
+                    throw err;
+                this.deps.log?.(`[platform-mcp] permission request poll failed, retrying: ${err.message}`);
+                continue;
+            }
+            if ("halt" in guarded)
+                return;
+            const claim = guarded.result;
+            if (claim.status === 429) {
+                waitMs = Math.max(request.pollMs, retryAfterMsOf(claim.body));
+                continue;
+            }
+            if (claim.status === 404)
+                return; // unknown or long since deleted: nothing left to wait for
+            if (!claim.ok) {
+                throw new Error(`the dashboard refused the claim (${claim.status}): ${JSON.stringify(claim.body)}`);
+            }
+            const status = claim.body?.status;
+            switch (status) {
+                case "pending":
+                    continue;
+                case "approved":
+                case "claimed":
+                case "denied":
+                case "expired":
+                    return;
+                default:
+                    throw new Error(`the dashboard answered the claim with an unknown status: ${JSON.stringify(claim.body)}`);
+            }
+        }
+    }
+}

package/dist/permission-watch.js

@@ -0,0 +1,145 @@
+/**
+ * DX-4523 - how this process learns that its key's permissions changed while it runs: the dashboard's live stream.
+ *
+ * `/api/stream` ends every open stream of a key with `event: end {reason: "permissions_changed"}` the moment a person approves a
+ * grant for it, revokes one, or revokes the key (`closeSessionStreams`, `src/dashboard/stream-routes.ts`). This watcher holds one
+ * stream open on the key-self topic `key:self` (`src/dashboard/sse-topic-policy.ts`), which any key may subscribe to with no
+ * permission: a dispatch's agent role holds none of the team read-floor keys, yet is exactly the key that is granted one mid-session.
+ *
+ * Reconnect FIRST, then re-read the permissions (`sync`), after EVERY (re)connect, so a change that landed while the stream was down
+ * is applied and a change after the connect ends the stream. A failed sync is retried with bounded backoff, then logged: the
+ * stream stays up and the next connect syncs again. No polling: the only timers are the reconnect backoff after a drop and the sync
+ * retry. The key is read on every connect, so a replaced key is the one used.
+ *
+ * A refusal (a 4xx other than 408 and 429, which are retried like a drop) ends the watch: a 401 means the key is gone (the next dashboard call halts the session as usual) and a 403
+ * means the dashboard predates the topic or refuses this principal. A 5xx or a dropped connection is retried with backoff, which
+ * starts over once a connection proved healthy (stayed open a while, or ended by a permission change).
+ */
+import { SYNC_ATTEMPTS, retryBounded } from "./bounded-retry.js";
+import { SseParser } from "./listen.js";
+import { PLUGIN_BACKGROUND_HEADER } from "./session-options.js";
+const STREAM_PATH = "/api/stream?topics=key:self";
+const PERMISSIONS_CHANGED = "permissions_changed";
+export const WATCH_INITIAL_BACKOFF_MS = 1_000;
+export const WATCH_MAX_BACKOFF_MS = 30_000;
+/** A connection that stayed open this long was healthy, so the next drop starts the backoff over. */
+export const WATCH_HEALTHY_CONNECTION_MS = 20_000;
+/** A 4xx that means "try again later", not "no": the stream is retried with backoff like a drop. */
+const RETRYABLE_REFUSALS = new Set([408, 429]);
+const defaultSleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms).unref();
+});
+export class PermissionWatch {
+    deps;
+    running = false;
+    stopRequested = false;
+    controller = null;
+    fetchImpl;
+    sleep;
+    now;
+    constructor(deps) {
+        this.deps = deps;
+        this.fetchImpl = deps.fetch ?? fetch;
+        this.sleep = deps.sleep ?? defaultSleep;
+        this.now = deps.now ?? Date.now;
+    }
+    /** Start watching. A watch already running is left alone, so every sign-in may call this. */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.stopRequested = false;
+        void this.run().finally(() => {
+            this.running = false;
+        });
+    }
+    /** Stop watching and close the open stream, so the process can exit. */
+    stop() {
+        this.stopRequested = true;
+        this.controller?.abort();
+    }
+    async run() {
+        let attempt = 0;
+        while (!this.stopRequested) {
+            const token = this.deps.token();
+            if (token === "")
+                return;
+            const outcome = await this.connectOnce(token);
+            if (outcome.kind === "refused")
+                return;
+            if (outcome.kind === "changed" || outcome.healthy)
+                attempt = 0;
+            // A permission change reconnects at once; a drop waits out the backoff first.
+            if (outcome.kind === "dropped" && !this.stopRequested) {
+                await this.sleep(Math.min(WATCH_MAX_BACKOFF_MS, WATCH_INITIAL_BACKOFF_MS * 2 ** attempt));
+                attempt += 1;
+            }
+        }
+    }
+    async connectOnce(token) {
+        const controller = new AbortController();
+        this.controller = controller;
+        const openedAt = this.now();
+        let opened = false;
+        const healthy = () => opened && this.now() - openedAt >= WATCH_HEALTHY_CONNECTION_MS;
+        try {
+            const response = await this.fetchImpl(`${this.deps.dashboardUrl.replace(/\/+$/, "")}${STREAM_PATH}`, {
+                // DX-5354: the watch is this process's own work, never the agent acting, so neither its connect nor any reconnect extends the session's key.
+                headers: { Authorization: `Bearer ${token}`, Accept: "text/event-stream", [PLUGIN_BACKGROUND_HEADER]: "1" },
+                signal: controller.signal,
+            });
+            if (response.status >= 400 && response.status < 500 && !RETRYABLE_REFUSALS.has(response.status)) {
+                this.deps.log?.(`[platform-mcp] the dashboard refused the permission stream (HTTP ${response.status}): a permission granted ` +
+                    `mid-session shows its tools at the next plan_connect instead`);
+                await response.body?.cancel();
+                return { kind: "refused" };
+            }
+            if (!response.ok || response.body === null) {
+                await response.body?.cancel();
+                return { kind: "dropped", healthy: false };
+            }
+            opened = true;
+            await this.syncWithRetry();
+            const parser = new SseParser();
+            const decoder = new TextDecoder();
+            for await (const chunk of response.body) {
+                for (const message of parser.push(decoder.decode(chunk, { stream: true }))) {
+                    if (message.event === "end" && endReason(message.data) === PERMISSIONS_CHANGED)
+                        return { kind: "changed" };
+                }
+            }
+            return { kind: "dropped", healthy: healthy() };
+        }
+        catch (err) {
+            if (!this.stopRequested)
+                this.deps.log?.(`[platform-mcp] permission stream dropped: ${err.message}`);
+            return { kind: "dropped", healthy: healthy() };
+        }
+        finally {
+            controller.abort();
+            if (this.controller === controller)
+                this.controller = null;
+        }
+    }
+    /** One sync, retried with bounded backoff; a sync that keeps failing is logged and the stream stays up. */
+    async syncWithRetry() {
+        try {
+            await retryBounded(() => this.deps.sync(), {
+                attempts: SYNC_ATTEMPTS,
+                sleep: this.sleep,
+                shouldStop: () => this.stopRequested,
+            });
+        }
+        catch (err) {
+            this.deps.log?.(`[platform-mcp] tool list refresh failed after ${SYNC_ATTEMPTS} attempts, tools stay as they are until the next connect: ${err.message}`);
+        }
+    }
+}
+function endReason(data) {
+    try {
+        return JSON.parse(data).reason;
+    }
+    catch {
+        return undefined;
+    }
+}