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

package/dist/plan-events-relay.js

@@ -0,0 +1,572 @@
+/**
+ * DX-4233 - the IN-PROCESS relay of a session's plan events: what the `plan_events_wait` tool serves.
+ *
+ * WHO CALLS IT. In a person's session, the 50arms plugin's relay loop calls `plan_events_wait` over and over on this
+ * session's own platform MCP server and hands every record it gets to the session. In an orchestrator's dispatch
+ * (DX-4667), which loads no relay, a background waiter sub-agent calls it the same way and returns the records and the last
+ * cursor to the orchestrator. This class is everything on the
+ * server side of that call: it opens the session's dashboard event stream (the mint / stream / heartbeat contract of
+ * `session-stream.ts`), buffers records for the caller and reports the session's listener health. There is no process to start,
+ * watch or kill: the stream lives exactly as long as the MCP server, which lives exactly as long as its session.
+ *
+ * THE WAIT CONTRACT (`wait`). One rule, one reset, and a cursor that is opaque to the caller.
+ *   1. ONE RULE, BY ARRIVAL. Every record (a dashboard event, a digest, a notice, a pacing or resume message) is given the next
+ *      number of a sequence that only ever increases: its `seq`. Each answered record carries a CURSOR, an opaque string. The caller
+ *      sends back, on its next call, the cursor of the newest record it has TAKEN (not necessarily delivered; DX-5403 / DX-5398). A call
+ *      answers every buffered record whose seq is above the cursor's (at once when there is one, else when one arrives, else empty
+ *      at the timeout) and DROPS every record at or below it, at the call (`acknowledged`, the one predicate). An answer is never a
+ *      drain: a record stays buffered until a LATER call's cursor passes it, but the server does NOT promise to keep a record the
+ *      caller has already taken. The 50arms plugin keeps its taken-but-undelivered events in its own `relayOutbox` $.state atom, so
+ *      a reload of its hook module loses none (it may repeat one); a new process with no atom resumes from the plugin's stored
+ *      delivered cursor.
+ *      The dashboard numbers its events when it INSERTS them but publishes them when it COMMITS, so an event can arrive after
+ *      a higher-numbered one; arrival order is the only order the relay can promise, which is why the dashboard's id is never
+ *      what is compared.
+ *   2. THE CURSOR. `<seq>:<id>,<id>,...`: the record's seq, then the dashboard event ids handed out up to and including it, in
+ *      arrival order and bounded to the last `CURSOR_IDS_MAX` (`formatCursor`, `parseCursor`: the seq and every id are base-10
+ *      whole numbers with no leading zero, the ids are distinct and positive; anything else is refused loudly). The ids are what
+ *      makes a restart exact. After a restart of the MCP server (a resumed session) a fresh relay is presented its caller's
+ *      cursor: its sequence continues from that seq, and the stream resumes after the highest of those ids with the listener's
+ *      duplicate guard seeded with all of them. The dashboard replays every event created within its 30 s commit-order overlap
+ *      (`REPLAY_COMMIT_ORDER_OVERLAP_MS`) before the last one seen and relies on that guard, so an already delivered event in
+ *      the overlap is dropped and one never delivered is delivered.
+ *      THE ACCEPTED GAP: an insert that commits more than that 30 s overlap after the event it follows is missed by a RESTART
+ *      resume (the dashboard's own limit); a running relay never misses one. And a burst of more than `CURSOR_IDS_MAX` events
+ *      inside the overlap can replay the oldest of them once (a duplicate, never a loss).
+ *   3. ONE PLAN. A call names the plan the session is on (`planId`), or `null` for a signed-in session on no plan (DX-4882: its stream
+ *      still carries the pacing and resume messages of its account). A plan different from the last call's, to or from `null` included,
+ *      drops the PLAN-scoped records buffered or held for the plan it left, so a move starts clean. SESSION-scoped records (pacing, resume
+ *      and the relay's own failure and revoked-key notices: they say nothing about a plan, and the dashboard never replays
+ *      them) are kept, here and across the 40 s suspend below. The ids of a dropped record leave the cursors of the records that
+ *      stay: delivering a kept record must not claim an event that was dropped undelivered. The stream stays on a move: it
+ *      belongs to the SESSION, and the dashboard delivers an event only while the session is on the event's plan.
+ *
+ * One wait is pending at a time: a newer call supersedes the older, which answers empty at once. A call whose request is
+ * aborted drops its waiter. A terminal outcome answers `{stopped}` with the remedy (`stop-fixes.ts`); the call after it tries
+ * again from scratch.
+ *
+ * WHO IS HEALTHY. The relay heartbeats every `HEARTBEAT_INTERVAL_MS` while a call is pending or one was made within
+ * `HEARTBEAT_ACTIVITY_WINDOW_MS`. After that window the stream is closed and the heartbeat stops, so the dashboard reads the
+ * session not healthy when nothing is reading its events (a dead or unloaded plugin module). The window is 40 s: a pending
+ * call counts, so it only has to outlast the caller's turnaround and failure backoff (the plugin waits 20 s and backs off at
+ * most 10 s), and it must stay under the dashboard's liveness window (`SESSION_LIVENESS_WINDOW_MS`, 60 s) minus one beat. The
+ * sequence and the highest event id survive the gap, so a cursor stays valid across it.
+ *
+ * NOTHING OUTLIVES THE SESSION. The heartbeat interval, the backoff sleep and the digest hold are unref'd, the stream and the
+ * mint / inventory requests are aborted by `close()`, and `close()` also clears a pending call's wait timer (the one ref'd timer,
+ * held only until the call answers). The server calls `close()` when its transport closes and when its stdin ends (`shutdown.ts`).
+ */
+import { fileOf, formatCompactionAskLine } from "./compaction-control.js";
+import { clearFileOf, formatClearAskLine } from "./clear-control.js";
+import { DigestHold } from "./digest-hold.js";
+import { HeartbeatReporter } from "./heartbeat-reporter.js";
+import { capResumeIds, DELIVERED_ID_MEMORY, HEALTHY_CONNECTION_MS, INITIAL_BACKOFF_MS, MAX_BACKOFF_MS, runListener, } from "./listen.js";
+import { fetchPlanInventory, HEARTBEAT_INTERVAL_MS, heartbeatConnection, MAX_REFUSED_TICKETS_IN_A_ROW, mintTicket, } from "./session-stream.js";
+import { fixForStop } from "./stop-fixes.js";
+import { LINE_PREFIX } from "./one-line.js";
+import { isUrgent } from "./urgent-records.js";
+/** The shortest and longest wait one call may ask for; a short ceiling keeps an orphaned waiter's life short. */
+export const WAIT_MIN_MS = 1_000;
+export const WAIT_MAX_MS = 30_000;
+/** How long after a call (or the end of one) the relay keeps heartbeating and streaming; see the module docblock. */
+export const HEARTBEAT_ACTIVITY_WINDOW_MS = 40_000;
+/**
+ * How many delivered dashboard event ids a cursor carries. The dashboard replays the events created within its 30 s overlap
+ * before the last one seen: 64 covers a busy plan's burst in that window many times over while keeping every record's cursor
+ * a few hundred characters. (The listener's own memory, `DELIVERED_ID_MEMORY`, is far larger and is not what a cursor carries.)
+ */
+export const CURSOR_IDS_MAX = 64;
+const WHOLE = "(?:0|[1-9][0-9]*)";
+const CURSOR_PATTERN = new RegExp(`^(${WHOLE}):((?:[1-9][0-9]*)(?:,[1-9][0-9]*)*)?$`);
+export const formatCursor = (cursor) => `${cursor.seq}:${cursor.ids.join(",")}`;
+/** Reads a cursor this relay issued. Anything else is refused loudly: a guess would hide a lost or repeated record. */
+export function parseCursor(raw) {
+    const match = CURSOR_PATTERN.exec(raw);
+    const seq = match === null ? NaN : Number(match[1]);
+    const ids = match === null || match[2] === undefined ? [] : match[2].split(",").map(Number);
+    const valid = Number.isSafeInteger(seq) && ids.length <= CURSOR_IDS_MAX && ids.every(Number.isSafeInteger) && new Set(ids).size === ids.length;
+    if (!valid) {
+        throw new Error(`plan_events_wait: cursor ${JSON.stringify(raw)} is not one this server issued (expected "<seq>:<id>,<id>,...": a whole number, a colon, then up to ${CURSOR_IDS_MAX} distinct positive event ids)`);
+    }
+    return { seq, ids };
+}
+const boundedIds = (ids) => [...new Set(ids)].slice(-CURSOR_IDS_MAX);
+/** DX-4233: the one rule of the cursor: a record at or below the presented cursor's seq has been taken by the caller, so the server drops it. */
+export const acknowledged = (seq, cursor) => cursor !== null && seq <= cursor.seq;
+export class PlanEventRelay {
+    deps;
+    buffer = [];
+    waiter = null;
+    run = null;
+    /** The plan the last call named (`null` = a session on no plan); `undefined` before the first call, which has no plan to have moved from. */
+    lastPlanId = undefined;
+    /** The last seq given: it continues from a presented cursor and survives a suspend, so a cursor stays valid across the gap. */
+    seq = 0;
+    /** The dashboard event ids that arrived (or were presented in a cursor), oldest first, bounded: the next record's `recent`. */
+    recentIds = [];
+    /** A terminal outcome nobody was waiting for: answered by the next call. */
+    pendingStop = null;
+    /** Dashboard ids already given to the buffer (and the cursor the run started from): handed to a re-mint so a replay is dropped. */
+    seenIds = [];
+    connectionState = "reconnecting";
+    stoppedReason = null;
+    lastInventoryError = null;
+    /** DX-4882: whether the connected plan's inventory has been read in this run (a session on no plan has none to read). */
+    inventoryRead = false;
+    lastActivityAt = 0;
+    heartbeat = null;
+    reporter = null;
+    /** DX-5415: the chain of every reporter stop still storing held finals (a suspend's and a transcript switch's); null when none is pending. Never rejects (see `chainSettling`). */
+    settling = null;
+    /** DX-5415: set by `close()` (the server's shutdown) and never cleared: a call paused across the close, or made after it, answers empty and starts nothing. */
+    closed = false;
+    digest = new DigestHold((event) => this.accept(event));
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** The one entry point: see the module docblock for the contract. */
+    async wait(args, signal) {
+        // Parsed first: a cursor this server did not issue is refused before it changes anything.
+        const cursor = args.cursor === null ? null : parseCursor(args.cursor);
+        // DX-4233: a request already cancelled (a plugin reload) touches nothing and starts nothing.
+        if (signal?.aborted || this.closed)
+            return { events: [] };
+        // DX-5415: a suspend still storing the old collector's held finals ends before this call starts a new one (bounded inside).
+        if (this.settling !== null) {
+            await this.settling;
+            if (signal?.aborted || this.closed)
+                return { events: [] };
+        }
+        // DX-4233: one wait at a time; the older call answers empty so its caller is never left hanging.
+        this.supersedeWaiter();
+        // DX-4233: a plan move starts clean (the very first call has no last plan; after a suspend the last plan is still known, and `dropPlanScoped` already ran).
+        if (this.lastPlanId !== undefined && args.planId !== this.lastPlanId) {
+            this.startClean();
+            this.rereadInventory(args.planId);
+        }
+        this.lastPlanId = args.planId;
+        if (cursor !== null) {
+            // DX-4233: a fresh relay (a restarted server) continues the caller's sequence and remembers the ids it was handed; a
+            // running one is already past both.
+            this.seq = Math.max(this.seq, cursor.seq); // DX-4233: max, never `=`: a stale cursor (a plugin reload) must not reuse a buffered seq
+            this.recentIds = boundedIds([...cursor.ids, ...this.recentIds]);
+            // What the caller delivered precedes every record still buffered, so each of their cursors carries it (a dropped
+            // plan-scoped record's ids were taken out of them, and the caller's own delivered ids go back in).
+            this.buffer = this.buffer.map((r) => ({ ...r, recent: boundedIds([...cursor.ids, ...r.recent]) }));
+        }
+        this.touch();
+        this.ensureReporter(args.transcriptPath);
+        // DX-5415 / DX-4233: a transcript switch's settle rides `settling` (the chain a suspend uses), so every call paused on it resumes in call order and the older one cannot overwrite the newer call's waiter.
+        if (this.settling !== null) {
+            await this.settling;
+            // The pause let a close() or a cancel through; a close already let go of the stream, heartbeat and reporter, so none is started again.
+            if (signal?.aborted || this.closed)
+                return { events: [] };
+        }
+        this.buffer = this.buffer.filter((r) => !acknowledged(r.seq, cursor));
+        if (this.pendingStop !== null) {
+            const stopped = this.pendingStop;
+            this.pendingStop = null;
+            return { stopped };
+        }
+        // DX-4233: a server holding no key answers a stop without calling the dashboard (a dispatch always holds its env key, so it never takes this branch).
+        if (this.deps.auth() === null) {
+            return { stopped: this.stopRecord("credential_unavailable", "this session holds no dashboard key") };
+        }
+        if (this.run === null)
+            this.start(cursor);
+        if (this.buffer.length > 0)
+            return this.answer();
+        // DX-5415 / DX-4233: supersede where the waiter is installed, not only before the pauses, so an older call that resumed late cannot orphan the waiter beneath it. Calls resume in call order because a settle (capped at FINAL_SETTLE_BOUND_MS) ends before the idle window (HEARTBEAT_ACTIVITY_WINDOW_MS) can chain a second one; a wall-clock jump can break that order, costing the newer caller one early empty answer, never a second waiter.
+        this.supersedeWaiter();
+        return new Promise((resolve) => {
+            const onAbort = () => this.supersedeWaiter();
+            signal?.addEventListener("abort", onAbort, { once: true });
+            const waiter = {
+                settle: resolve,
+                timer: setTimeout(() => {
+                    this.waiter = null;
+                    this.finishCall(waiter, { events: [] });
+                }, args.timeoutMs),
+                detach: () => signal?.removeEventListener("abort", onAbort),
+            };
+            this.waiter = waiter;
+        });
+    }
+    /** Stop everything: the pending call, the stream, the heartbeat, the transcript tailer. For the server's shutdown. */
+    close() {
+        this.closed = true;
+        this.supersedeWaiter();
+        return this.suspend();
+    }
+    // ---------------------------------------------------------------------------------------------------------------- calls
+    finishCall(waiter, answer) {
+        clearTimeout(waiter.timer);
+        waiter.detach();
+        this.lastActivityAt = this.deps.now();
+        waiter.settle(answer);
+    }
+    /** The pending call, if any, answers empty at once (a newer call replaced it, or its request went away). */
+    supersedeWaiter() {
+        const waiter = this.waiter;
+        if (waiter === null)
+            return;
+        this.waiter = null;
+        this.finishCall(waiter, { events: [] });
+    }
+    /** Everything buffered, each record with the cursor to store once it is delivered. */
+    answer() {
+        return { events: this.buffer.map(({ seq, recent, text, urgent, acks }) => ({ cursor: formatCursor({ seq, ids: recent }), text, urgent, acks })) };
+    }
+    // ------------------------------------------------------------------------------------------------------------ the buffer
+    /**
+     * A record the session should now be told: given the next seq, buffered for the caller, and the pending call answers with it.
+     * A replayed dashboard event never reaches here twice: the listener's duplicate guard (seeded from the cursor) drops it first.
+     */
+    accept(event) {
+        // DX-4233: the seq is given at arrival and never reused, so a record the dashboard publishes late is just the next one.
+        const own = event.ids ?? (event.id === null ? [] : [event.id]);
+        this.recentIds = boundedIds([...this.recentIds, ...own]);
+        for (const id of own) {
+            this.seenIds.push(id);
+            if (this.seenIds.length > DELIVERED_ID_MEMORY)
+                this.seenIds.shift();
+        }
+        this.seq += 1;
+        this.buffer.push({ seq: this.seq, own, recent: [...this.recentIds], text: event.text, scope: event.scope ?? "plan", urgent: event.urgent, acks: event.acks });
+        const waiter = this.waiter;
+        if (waiter === null)
+            return;
+        this.waiter = null;
+        this.finishCall(waiter, this.answer());
+    }
+    // ---------------------------------------------------------------------------------------------------- lifecycle and health
+    /**
+     * DX-4233: drop the plan-scoped records, keeping the session-scoped ones. The ids of what is dropped leave the cursors of what
+     * stays (and the remembered ids): delivering a kept record must not claim an event that was dropped undelivered, or a
+     * restart would resume past it and the dashboard would never replay it.
+     */
+    dropPlanScoped() {
+        const dropped = new Set(this.buffer.filter((r) => r.scope === "plan").flatMap((r) => r.own));
+        this.buffer = this.buffer
+            .filter((r) => r.scope === "session")
+            .map((r) => ({ ...r, recent: r.recent.filter((id) => !dropped.has(id)) }));
+        this.recentIds = this.recentIds.filter((id) => !dropped.has(id));
+        // DX-4233: `seenIds` (the listener's duplicate guard for a re-mint on the SAME run) deliberately keeps them. A plan move's
+        // dropped events belong to a plan the session left, and the dashboard replays only the session's current plan, so nothing
+        // legitimate is replayed into the guard; and the gap, which does need them replayed, ends the run, so `start` builds a fresh `seenIds` from the next call's cursor.
+    }
+    /** Whether the last call named a plan (not `null` = no plan, not `undefined` = no call yet). */
+    onAPlan() {
+        return typeof this.lastPlanId === "number";
+    }
+    /**
+     * DX-4882 / DX-6157: the inventory read no longer describes the session: the plan changed, or a person's Create gave the session an agent (and a plan) after a read refused 403
+     * agent_needed. On no plan there is nothing to read (and nothing to report as unavailable); on a plan, a live run reads it now (a run that is not live reads it when it starts).
+     */
+    rereadInventory(planId) {
+        this.inventoryRead = false;
+        this.lastInventoryError = null;
+        const run = this.run;
+        const auth = this.deps.auth();
+        if (planId === null || run === null || auth === null)
+            return;
+        void this.readInventory(run, auth, { ...this.deps, signal: run.abort.signal });
+    }
+    /** The inventory is a property of the credential and the plan: read best effort, never a gate; a failed read is reported on the heartbeat (`inventory: unavailable`) and tried again at the next re-mint. */
+    async readInventory(run, auth, http) {
+        const inventory = await fetchPlanInventory(auth, http);
+        if (!this.current(run))
+            return;
+        this.inventoryRead = inventory.kind === "ok";
+        this.lastInventoryError = inventory.kind === "ok" ? null : inventory.detail;
+    }
+    /** The session moved to another plan: drop what was buffered or held for the plan it left; session-scoped records stay. */
+    startClean() {
+        this.dropPlanScoped();
+        this.digest.reset();
+    }
+    /** Creates the heartbeat reporter on the first call; a later call's transcript path (a resumed session) is handed to it. */
+    ensureReporter(transcriptPath) {
+        if (this.reporter !== null) {
+            const switching = this.reporter.useTranscript(transcriptPath);
+            if (switching !== null)
+                this.chainSettling(switching);
+            return;
+        }
+        this.reporter = new HeartbeatReporter({
+            auth: () => {
+                const auth = this.deps.auth();
+                if (auth === null)
+                    throw new Error("plan_events_wait: this server holds no dashboard key to heartbeat with");
+                return auth;
+            },
+            http: this.deps,
+            makeStatsWatcher: this.deps.makeStatsWatcher,
+            now: this.deps.now,
+            connection: () => heartbeatConnection(this.connectionState, this.stoppedReason, this.lastInventoryError),
+            streaming: () => this.connectionState === "streaming",
+            // `origin: null` skips the agent/machine hold: the notice reaches the session at once. It is about the session, not a plan.
+            announce: (text, source) => this.digest.route({ type: "event", id: null, text, origin: null, scope: "session", urgent: isUrgent({ source }), acks: [] }),
+            forceReconnect: () => this.run?.forceReconnect?.(),
+        }, transcriptPath ?? null);
+    }
+    /**
+     * DX-5415: the one settle chain: the last settle and `stopping` both finish before it clears itself.
+     * `stopping` never rejects (a reporter's stop settles its own failures), so `settling` never rejects and
+     * every waiter on it resumes; do not add a swallowing fallback here.
+     */
+    chainSettling(stopping) {
+        const settling = Promise.all([this.settling, stopping]).then(() => {
+            if (this.settling === settling)
+                this.settling = null;
+        });
+        this.settling = settling;
+    }
+    /** Mark the relay in use and make sure the heartbeat is scheduled. */
+    touch() {
+        this.lastActivityAt = this.deps.now();
+        this.heartbeat ??= this.deps.scheduleInterval(() => this.heartbeatTick(), HEARTBEAT_INTERVAL_MS);
+    }
+    heartbeatTick() {
+        // DX-4233: a pending call keeps the relay alive however long it waits; only a gap with no call at all suspends it.
+        if (this.waiter === null && this.deps.now() - this.lastActivityAt > HEARTBEAT_ACTIVITY_WINDOW_MS) {
+            // Nobody is reading this session's events any more: stop heartbeating (the dashboard then reads the listener not
+            // healthy) and let go of the stream. The next call starts it again from its cursor; the dashboard replays what it missed.
+            void this.suspend();
+            return;
+        }
+        const auth = this.deps.auth();
+        if (auth === null)
+            return;
+        this.touchControlFiles(auth.sessionId);
+        this.reporter?.tick();
+    }
+    /**
+     * DX-4993 / DX-6692: a live relay keeps its session's control files (compaction, clear) out of the weekly pruning (`SessionControlFiles.touch`); a failure is reported to stderr, never
+     * ends the heartbeat.
+     */
+    touchControlFiles(sessionId) {
+        for (const kind of [this.compactionKind(), this.clearKind()]) {
+            try {
+                kind.files.touch(sessionId);
+            }
+            catch (err) {
+                process.stderr.write(`plan_events_wait: the ${kind.what} file could not be kept alive: ${err instanceof Error ? err.message : String(err)}\n`);
+            }
+        }
+    }
+    /**
+     * Let go of everything the relay holds for a caller: the stream, the heartbeat, the digest, and the plan-scoped records.
+     * What was held for a digest was never marked delivered, so the dashboard's replay (after the caller's cursor) returns it to
+     * whoever calls next. Session-scoped records stay (the dashboard never replays them), and so does the sequence, so a cursor
+     * stays valid across the gap; the delivered ids come back with the next call's cursor.
+     */
+    suspend() {
+        this.heartbeat?.stop();
+        this.heartbeat = null;
+        this.run?.abort.abort();
+        this.run = null;
+        // DX-5415: the reporter's stop settles its collector's held sub-agent finals first; callers that can wait (shutdown, the next call) do.
+        const stopping = this.reporter?.stop() ?? null;
+        if (stopping !== null)
+            this.chainSettling(stopping);
+        this.reporter = null;
+        this.digest.reset();
+        this.dropPlanScoped();
+        // DX-4233: `dropPlanScoped` already took the undelivered records' ids out of `recentIds`, so the dashboard replays them; what
+        // stays there was delivered. `seenIds` is reassigned by `start`, and a plan move after the gap is dropped by `dropPlanScoped`
+        // above, so neither is reset here.
+        this.pendingStop = null;
+        this.connectionState = "reconnecting";
+        this.stoppedReason = null;
+        this.lastInventoryError = null;
+        return this.settling ?? Promise.resolve();
+    }
+    // ------------------------------------------------------------------------------------------------- the mint / stream loop
+    start(cursor) {
+        // The listener's duplicate guard starts with every event the caller was handed and everything still buffered: the dashboard
+        // replays its 30 s overlap before the highest of them, so a replayed one is dropped and a never-delivered one is delivered.
+        this.seenIds = capResumeIds([...(cursor?.ids ?? []), ...this.buffer.flatMap((r) => r.own)]);
+        this.stoppedReason = null;
+        this.inventoryRead = false;
+        const run = { abort: new AbortController(), forceReconnect: null };
+        this.run = run;
+        void this.loop(run).catch((err) => {
+            // A bug, not a stream outcome: say so out loud, and answer it like any terminal outcome rather than idle silently.
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`plan_events_wait: the event relay failed: ${message}\n`);
+            this.terminal(run, "relay_failed", message);
+        });
+    }
+    /** DX-4993: the compaction control's file, ask line and fault wording. */
+    compactionKind() {
+        return { files: this.deps.compactionFiles, fileOf, askLine: formatCompactionAskLine, askSource: { source: "compaction_ask" }, what: "compaction control", faultEffect: "so its compaction gate cannot work" };
+    }
+    /** DX-6692: the clear control's file, ask line and fault wording. */
+    clearKind() {
+        return { files: this.deps.clearFiles, fileOf: clearFileOf, askLine: formatClearAskLine, askSource: { source: "clear_ask" }, what: "clear control", faultEffect: "so the ready loop cannot see an agreed clear" };
+    }
+    /**
+     * DX-4993 / DX-6692 - a control (compaction, clear) arrived: show the agent an ask it has not been shown, and write the file the plugin reads. A control with a new ask (`ask.at`) is
+     * shown once: the file remembers which, so a reconnect, a restart of this server or a repeat of the same frame shows nothing twice. A file that cannot be read is replaced and reported on
+     * stderr only (DX-6156); a file that cannot be written is a line to the agent (a fault: the plugin cannot act on the control), never silence.
+     */
+    applyControl(control, kind) {
+        const auth = this.deps.auth();
+        if (auth === null)
+            return;
+        // DX-4993: a file that cannot be read is no memory of what was shown, never a reason not to write: the write below replaces it (otherwise the same fault repeats
+        // at every frame and the plugin never gets a readable control).
+        // DX-6156: a repaired file is internal only (one stderr line, after the write succeeds); the agent hears of it only through the fault line when the replacing write fails, below.
+        let askedAt = null;
+        let unreadable = null;
+        try {
+            askedAt = kind.files.read(auth.sessionId)?.askedAt ?? null;
+        }
+        catch (err) {
+            unreadable = err instanceof Error ? err.message : String(err);
+        }
+        try {
+            const ask = (control?.ask ?? null);
+            const show = ask !== null && ask.at !== askedAt;
+            kind.files.write(auth.sessionId, kind.fileOf(control, ask === null ? null : show ? ask.at : askedAt, auth.sessionId));
+            if (unreadable !== null)
+                process.stderr.write(`plan_events_wait: the ${kind.what} file of session ${auth.sessionId} could not be read (${unreadable}); it was replaced\n`);
+            if (show) {
+                this.digest.route({ type: "event", id: null, text: kind.askLine(ask), origin: null, urgent: isUrgent(kind.askSource), acks: [], scope: "session" });
+            }
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            this.digest.route({ type: "event", id: null, text: `${LINE_PREFIX} the ${kind.what} could not be kept for this session (${detail}), ${kind.faultEffect}`, origin: null, urgent: isUrgent({ source: "fault" }), acks: [], scope: "session" });
+        }
+    }
+    current(run) {
+        return this.run === run && !run.abort.signal.aborted;
+    }
+    stopRecord(reason, detail) {
+        return { reason, detail, fix: fixForStop(reason) };
+    }
+    /** A terminal outcome: the pending call (or else the next) answers `{stopped}`; the loop ends. */
+    terminal(run, reason, detail) {
+        // DX-4233: only the run that is still current may end the relay; a superseded or closed run ending late is ignored.
+        if (!this.current(run))
+            return;
+        this.digest.cancel();
+        this.run = null;
+        this.connectionState = "stopped";
+        this.stoppedReason = reason;
+        const stopped = this.stopRecord(reason, detail);
+        const waiter = this.waiter;
+        if (waiter === null) {
+            this.pendingStop = stopped;
+            return;
+        }
+        this.waiter = null;
+        this.finishCall(waiter, { stopped });
+    }
+    async loop(run) {
+        const sleep = (ms) => this.deps.sleep(ms, run.abort.signal);
+        // The mint and the inventory read end with the run, so a closed relay leaves no request in flight.
+        const http = { ...this.deps, signal: run.abort.signal };
+        let backoff = INITIAL_BACKOFF_MS;
+        let refusedInRow = 0;
+        for (;;) {
+            if (!this.current(run))
+                return;
+            this.connectionState = "reconnecting";
+            this.reporter?.resetFailureStreak();
+            run.forceReconnect = null;
+            const auth = this.deps.auth();
+            if (auth === null)
+                return this.terminal(run, "credential_unavailable", "this session holds no dashboard key");
+            const minted = await mintTicket(auth, http);
+            if (!this.current(run))
+                return;
+            if (minted.kind === "terminal")
+                return this.terminal(run, minted.reason, minted.detail);
+            if (minted.kind === "transient") {
+                await sleep(backoff);
+                backoff = Math.min(MAX_BACKOFF_MS, backoff * 2);
+                continue;
+            }
+            // DX-4882: only a session on a plan has an inventory to read.
+            if (!this.inventoryRead && this.onAPlan()) {
+                await this.readInventory(run, auth, http);
+                if (!this.current(run))
+                    return;
+            }
+            backoff = INITIAL_BACKOFF_MS;
+            const attempt = { stopped: null, emitted: false };
+            const startedAt = this.deps.now();
+            await runListener({
+                streamUrl: minted.streamUrl,
+                ticket: minted.ticket,
+                leaseMs: minted.leaseMs,
+                resumeIds: capResumeIds([...this.seenIds, ...this.digest.heldIds()]),
+            }, {
+                fetch: this.deps.fetch,
+                sleep,
+                now: this.deps.now,
+                readIdleTimeoutMs: this.deps.readIdleTimeoutMs,
+                onAgentCreated: (created) => {
+                    this.deps.onAgentCreated(created);
+                    this.rereadInventory(created.plan === null ? null : created.plan.id);
+                },
+                signal: run.abort.signal,
+                write: (output) => {
+                    if (!this.current(run))
+                        return;
+                    if (output.type === "stopped") {
+                        attempt.stopped = output;
+                        return;
+                    }
+                    attempt.emitted = true;
+                    if (output.type === "compaction") {
+                        this.applyControl(output.control, this.compactionKind());
+                        return;
+                    }
+                    if (output.type === "clear") {
+                        this.applyControl(output.control, this.clearKind());
+                        return;
+                    }
+                    this.digest.route(output);
+                },
+                onState: (state) => {
+                    if (!this.current(run))
+                        return;
+                    this.connectionState = state;
+                    // DX-5088: the heartbeat failure streak is per stream; a drop ends it, so a quick re-open never inherits the old count.
+                    if (state !== "streaming")
+                        this.reporter?.resetFailureStreak();
+                    // Report `streaming` now, not up to a beat later: the session reads healthy as soon as it is.
+                    if (state === "streaming" && this.deps.auth() !== null)
+                        this.reporter?.tick();
+                },
+                onConnectionAttempt: (abort) => {
+                    run.forceReconnect = abort;
+                },
+            });
+            if (!this.current(run))
+                return;
+            const stopped = attempt.stopped;
+            // DX-4233: the listener always ends with a stop record; its absence is a bug, answered as `relay_failed` by `start`'s catch.
+            if (stopped === null)
+                throw new Error("the stream reader ended without a stop record");
+            if (stopped.reason === "lease_expired") {
+                refusedInRow = 0;
+                continue;
+            }
+            if (stopped.reason === "refused") {
+                const provedHealthy = attempt.emitted || this.deps.now() - startedAt >= HEALTHY_CONNECTION_MS;
+                refusedInRow = provedHealthy ? 1 : refusedInRow + 1;
+                if (refusedInRow >= MAX_REFUSED_TICKETS_IN_A_ROW) {
+                    return this.terminal(run, "refused", `${stopped.detail} (a freshly minted ticket was refused ${refusedInRow} times in a row)`);
+                }
+                continue;
+            }
+            return this.terminal(run, stopped.reason, stopped.detail);
+        }
+    }
+}

package/dist/plan-events-tool.js

@@ -0,0 +1,9 @@
+import { checkedTranscriptPath } from "./session-stats.js";
+/**
+ * DX-4233 - the body of the `plan_events_wait` tool: the transcript path is checked (a refusal names it), then the relay waits,
+ * and a cancelled request (`signal`, the SDK's `extra.signal`) drops the pending wait. A malformed cursor is refused by the relay.
+ */
+export function servePlanEventsWait(relay, args, signal) {
+    const transcriptPath = args.transcript_path === undefined ? undefined : checkedTranscriptPath(args.transcript_path, "plan_events_wait transcript_path");
+    return relay.wait({ planId: args.plan_id, cursor: args.cursor, timeoutMs: args.timeout_ms, transcriptPath }, signal);
+}

package/dist/plugin-publish.js

@@ -0,0 +1,38 @@
+/**
+ * DX-5237 (DX-4679 section 6) - the `plugin_publish` flow: build a card-type plugin project with its own `npm run build`, archive its source,
+ * take a screenshot, and upload all of it as a revision of one of the team's plugins (created on the first publish).
+ *
+ * The build, the archive and the upload are `@danxbot/plugin-sdk/publish`, the same code the `danx-plugin publish` CLI runs; this module adds
+ * what only an agent's tool has: the dashboard client it already holds (its credential, trace and session headers) as the transport, and the
+ * screenshot: the built plugin's own render on the dashboard's `/plugin-preview` page (`plugin-screenshot.ts`, DX-5256). No browser, a dashboard
+ * without that page or a failed render publishes WITHOUT a screenshot and says why in the result (`none: <reason>`), the same stated degraded mode as `mini_app_publish`.
+ *
+ * ORDER, so a failure leaves as little behind as it can: the arguments (a blank note is refused here, before the build), then the build (a failed build uploads nothing), the archive, the
+ * screenshot, and only then the upload. The dashboard is the only validator; its refusal comes back verbatim with the step it refused.
+ */
+import path from "node:path";
+import { archiveSource, assertNote, buildPlugin, uploadRevision, withScreenshot } from "@danxbot/plugin-sdk/publish";
+import { capturePluginRender } from "./plugin-screenshot.js";
+/** The agent's authenticated dashboard client as the publish flow's transport. */
+function clientTransport(client) {
+    return { request: ({ method, path: route, query, body }) => client.request({ method, path: route, basePath: "", query, body }) };
+}
+export async function pluginPublish(client, args, deps) {
+    assertNote(args.note);
+    const projectDir = path.resolve(deps.cwd, args.dir);
+    const built = await buildPlugin(projectDir);
+    const source = await archiveSource(projectDir);
+    const shot = await capturePluginRender(built, deps.baseUrl, { rootAbs: projectDir, cwd: deps.cwd });
+    const toUpload = shot.png_base64 === null ? built : withScreenshot(built, Buffer.from(shot.png_base64, "base64"));
+    const result = await uploadRevision(clientTransport(client), {
+        plugin: args.plugin,
+        name: args.name,
+        note: args.note,
+        built: toUpload,
+        source,
+        dashboardUrl: deps.baseUrl,
+    });
+    if (!result.ok)
+        return { ok: false, status: result.status, body: result.body, plugin: args.plugin, step: result.step };
+    return { ok: true, status: result.status, body: { ...result.body, screenshot: shot.screenshot } };
+}