@retaw106/mmc-oc 0.0.0-stage → 1.2.2

package/src/shared/rpc-client.ts

@@ -0,0 +1,218 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+    isPidAlive,
+    legacyRpcPortFilePath,
+    parseRpcPortFile,
+    type RpcPortFileRecord,
+    rpcPortDir,
+} from "./rpc-utils";
+
+const MAX_RETRIES = 10;
+const RETRY_DELAY_MS = 500;
+const REQUEST_TIMEOUT_MS = 5000;
+const MAX_RERESOLVE_ATTEMPTS = 3;
+const NON_RETRYABLE_RPC_ERROR = Symbol("nonRetryableRpcError");
+type NonRetryableRpcError = Error & { [NON_RETRYABLE_RPC_ERROR]: true };
+
+export class MagicContextRpcClient {
+    private port: number | null = null;
+    private token: string | null = null;
+    private instanceId: string | null = null;
+    private portDir: string;
+    private legacyPortFilePath: string;
+    private healthChecked = false;
+
+    constructor(storageDir: string, directory: string) {
+        this.portDir = rpcPortDir(storageDir, directory);
+        this.legacyPortFilePath = legacyRpcPortFilePath(storageDir, directory);
+    }
+
+    /** Call an RPC method. Retries port resolution if the server isn't ready yet. */
+    async call<T = Record<string, unknown>>(
+        method: string,
+        params: Record<string, unknown> = {},
+    ): Promise<T> {
+        let lastError: unknown = null;
+
+        for (let attempt = 0; attempt < MAX_RERESOLVE_ATTEMPTS; attempt++) {
+            const port = await this.resolvePort();
+            if (!port) {
+                lastError = new Error("Magic Context RPC server not available");
+                this.reset();
+                continue;
+            }
+
+            try {
+                const response = await this.fetchWithTimeout(
+                    `http://127.0.0.1:${port}/rpc/${method}`,
+                    {
+                        method: "POST",
+                        headers: {
+                            "Content-Type": "application/json",
+                            // The server requires this per-process token on all
+                            // non-health calls; read from the same port file used
+                            // for discovery. Older servers wrote no token — send
+                            // nothing then (they also require nothing).
+                            ...(this.token ? { Authorization: `Bearer ${this.token}` } : {}),
+                        },
+                        body: JSON.stringify(params),
+                    },
+                );
+
+                if (!response.ok) {
+                    const text = await response.text();
+                    const error = new Error(`RPC ${method} failed (${response.status}): ${text}`);
+                    if (response.status === 401 || response.status >= 500) {
+                        lastError = error;
+                        this.reset();
+                        continue;
+                    }
+                    (error as NonRetryableRpcError)[NON_RETRYABLE_RPC_ERROR] = true;
+                    throw error;
+                }
+
+                return (await response.json()) as T;
+            } catch (err) {
+                if (isNonRetryableRpcError(err)) {
+                    throw err;
+                }
+                lastError = err;
+                this.reset();
+            }
+        }
+
+        if (lastError instanceof Error) {
+            throw lastError;
+        }
+        throw new Error("Magic Context RPC server not available");
+    }
+
+    /** Check if the RPC server is reachable. */
+    async isAvailable(): Promise<boolean> {
+        try {
+            const port = await this.resolvePort();
+            return port !== null;
+        } catch {
+            return false;
+        }
+    }
+
+    /** Resolve the live server's port + bearer token (for opening the WS push
+     *  channel). Reuses the same health-checked port-file discovery as `call`,
+     *  so the WS client and the HTTP client always agree on which server instance
+     *  (and token) to use. Returns null when no live server is found. */
+    async resolveEndpoint(): Promise<{
+        port: number;
+        token: string | null;
+        instanceId: string | null;
+    } | null> {
+        try {
+            // The socket owns reconnect backoff, so endpoint discovery performs one
+            // filesystem/health pass instead of nesting the HTTP client's retries.
+            const port = await this.resolvePort(1);
+            if (port === null) return null;
+            return { port, token: this.token, instanceId: this.instanceId };
+        } catch {
+            return null;
+        }
+    }
+
+    private async resolvePort(maxAttempts = MAX_RETRIES): Promise<number | null> {
+        if (this.port && this.healthChecked) {
+            return this.port;
+        }
+
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            for (const record of this.readPortFiles()) {
+                if (!(await this.healthCheck(record))) continue;
+                this.port = record.port;
+                this.token = record.token ?? null;
+                this.instanceId = record.instance_id ?? null;
+                this.healthChecked = true;
+                return record.port;
+            }
+
+            this.reset();
+            if (attempt < maxAttempts - 1) {
+                await new Promise((resolve) => setTimeout(resolve, RETRY_DELAY_MS));
+            }
+        }
+
+        return null;
+    }
+
+    private readPortFiles(): RpcPortFileRecord[] {
+        const records: RpcPortFileRecord[] = [];
+
+        try {
+            for (const entry of readdirSync(this.portDir)) {
+                if (!entry.startsWith("port-") || !entry.endsWith(".json")) continue;
+                const record = parseRpcPortFile(readFileSync(join(this.portDir, entry), "utf-8"));
+                // A denied liveness probe still leaves this as a candidate; the
+                // mandatory health check below confirms whether its RPC server is reachable.
+                if (!record || isPidAlive(record.pid) === "dead") continue;
+                records.push(record);
+            }
+        } catch {
+            // Directory may not exist yet. Fall back to the legacy file below.
+        }
+
+        try {
+            const legacy = parseRpcPortFile(readFileSync(this.legacyPortFilePath, "utf-8"));
+            if (legacy && (!legacy.pid || isPidAlive(legacy.pid) !== "dead")) records.push(legacy);
+        } catch {
+            // Legacy discovery is optional.
+        }
+
+        // A TUI and its server plugin normally share a process. Prefer that exact
+        // process before considering another live OpenCode instance for the project.
+        records.sort((a, b) => {
+            const aLocal = a.pid === process.pid ? 1 : 0;
+            const bLocal = b.pid === process.pid ? 1 : 0;
+            return bLocal - aLocal || b.started_at - a.started_at;
+        });
+        return records;
+    }
+
+    private async healthCheck(record: RpcPortFileRecord): Promise<boolean> {
+        try {
+            const response = await this.fetchWithTimeout(`http://127.0.0.1:${record.port}/health`, {
+                method: "GET",
+            });
+            if (!response.ok) return false;
+            const body = (await response.json()) as { pid?: unknown; instance_id?: unknown };
+            if (body.pid !== record.pid) return false;
+            // v0.32 health responses predate instance ids. A missing id is the
+            // one-release discovery bridge; an id that is present must still match.
+            return (
+                body.instance_id === undefined ||
+                record.instance_id === undefined ||
+                body.instance_id === record.instance_id
+            );
+        } catch {
+            return false;
+        }
+    }
+
+    private async fetchWithTimeout(url: string, options: RequestInit): Promise<Response> {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        try {
+            return await fetch(url, { ...options, signal: controller.signal });
+        } finally {
+            clearTimeout(timeout);
+        }
+    }
+
+    reset(): void {
+        this.port = null;
+        this.token = null;
+        this.instanceId = null;
+        this.healthChecked = false;
+    }
+}
+
+function isNonRetryableRpcError(err: unknown): err is NonRetryableRpcError {
+    return typeof err === "object" && err !== null && NON_RETRYABLE_RPC_ERROR in err;
+}

package/src/shared/rpc-notifications.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, test } from "bun:test";
+import {
+    drainNotifications,
+    isTuiConnected,
+    type NotificationSink,
+    pushNotification,
+    registerNotificationSink,
+} from "./rpc-notifications";
+
+describe("rpc notifications", () => {
+    test("keeps messages queued until the client acks their id", () => {
+        const initial = drainNotifications(Number.MAX_SAFE_INTEGER);
+        expect(initial).toEqual([]);
+
+        pushNotification("one", { ok: true }, "ses_1");
+        const firstPoll = drainNotifications();
+        expect(firstPoll).toHaveLength(1);
+        expect(firstPoll[0].type).toBe("one");
+
+        const retryPoll = drainNotifications();
+        expect(retryPoll.map((m) => m.id)).toEqual(firstPoll.map((m) => m.id));
+
+        const lastReceivedId = Math.max(...firstPoll.map((m) => m.id));
+        expect(drainNotifications(lastReceivedId)).toEqual([]);
+    });
+
+    test("scopes drain to the requesting session; other sessions' items survive", () => {
+        // drain everything left from prior tests
+        drainNotifications(Number.MAX_SAFE_INTEGER);
+
+        pushNotification("for-a", { action: "show-upgrade-dialog" }, "ses_A");
+        pushNotification("for-b", { action: "show-upgrade-dialog" }, "ses_B");
+        pushNotification("global", { action: "show-status-dialog" });
+
+        // Session A sees only its own item + the global one, never ses_B's.
+        const aPoll = drainNotifications(0, "ses_A");
+        expect(aPoll.map((m) => m.type).sort()).toEqual(["for-a", "global"]);
+
+        // Acking session A must NOT prune session B's still-unseen notification.
+        const ackId = Math.max(...aPoll.map((m) => m.id));
+        drainNotifications(ackId, "ses_A");
+        const bPoll = drainNotifications(0, "ses_B");
+        expect(bPoll.map((m) => m.type)).toContain("for-b");
+    });
+
+    test("session-less drain (legacy client) still receives all items", () => {
+        drainNotifications(Number.MAX_SAFE_INTEGER);
+        pushNotification("x", { ok: true }, "ses_1");
+        pushNotification("y", { ok: true }, "ses_2");
+        const poll = drainNotifications(0);
+        expect(poll.map((m) => m.type).sort()).toEqual(["x", "y"]);
+    });
+
+    test("isTuiConnected reflects live WS sinks per-session", () => {
+        // No sinks → nothing connected.
+        expect(isTuiConnected("ses_anything")).toBe(false);
+        expect(isTuiConnected()).toBe(false);
+
+        // A live sink scoped to session A marks ONLY A connected (so B's producers
+        // don't misroute B's /mmc-status / upgrade reminder to the dialog path and
+        // lose it in an unrelated TUI), and the global query is also "connected".
+        const unregister = registerNotificationSink({ sessionId: "ses_A", send: () => {} });
+        expect(isTuiConnected("ses_A")).toBe(true);
+        expect(isTuiConnected("ses_B")).toBe(false);
+        expect(isTuiConnected()).toBe(true);
+
+        // Closing the socket removes the sink → disconnected again.
+        unregister();
+        expect(isTuiConnected("ses_A")).toBe(false);
+        expect(isTuiConnected()).toBe(false);
+    });
+
+    test("a modern session-less sink is global-only", () => {
+        const received: string[] = [];
+        const unregister = registerNotificationSink({
+            sessionId: undefined,
+            protocol: 2,
+            send: (notification) => received.push(notification.type),
+        });
+        expect(isTuiConnected("ses_whatever")).toBe(false);
+        expect(isTuiConnected()).toBe(true);
+
+        pushNotification("scoped", { ok: true }, "ses_whatever");
+        pushNotification("global", { ok: true });
+        expect(received).toEqual(["global"]);
+        unregister();
+    });
+
+    test("a legacy session-less sink retains broad compatibility", () => {
+        const unregister = registerNotificationSink({ sessionId: undefined, send: () => {} });
+        expect(isTuiConnected("ses_whatever")).toBe(true);
+        unregister();
+    });
+
+    test("pushNotification fans out live to a matching sink and skips a foreign session", () => {
+        drainNotifications(Number.MAX_SAFE_INTEGER);
+        const received: string[] = [];
+        const sink: NotificationSink = {
+            sessionId: "ses_live",
+            send: (n) => received.push(n.type),
+        };
+        const unregister = registerNotificationSink(sink);
+
+        pushNotification("for-live", { action: "show-status-dialog" }, "ses_live");
+        pushNotification("for-other", { action: "show-status-dialog" }, "ses_other");
+        pushNotification("global", { action: "show-status-dialog" });
+
+        // The sink sees its own session + global, never the foreign session.
+        expect(received.sort()).toEqual(["for-live", "global"]);
+        unregister();
+    });
+
+    test("a dead sink (throwing send) does not block delivery to other sinks", () => {
+        drainNotifications(Number.MAX_SAFE_INTEGER);
+        const live: string[] = [];
+        const unregDead = registerNotificationSink({
+            sessionId: undefined,
+            send: () => {
+                throw new Error("socket dead");
+            },
+        });
+        const unregLive = registerNotificationSink({
+            sessionId: undefined,
+            send: (n) => live.push(n.type),
+        });
+        // Must not throw, and the live sink still receives it.
+        expect(() => pushNotification("resilient", { ok: true })).not.toThrow();
+        expect(live).toEqual(["resilient"]);
+        unregDead();
+        unregLive();
+    });
+
+    test("queue-cap eviction is session-fair: a noisy session cannot evict another session's newest unseen item", () => {
+        drainNotifications(Number.MAX_SAFE_INTEGER);
+        pushNotification("quiet-dialog", { action: "show-upgrade-dialog" }, "ses_quiet");
+        for (let i = 0; i < 200; i += 1) {
+            pushNotification("noise", { i }, "ses_noisy");
+        }
+        const quietPoll = drainNotifications(0, "ses_quiet");
+        expect(quietPoll.some((m) => m.type === "quiet-dialog")).toBe(true);
+        expect(drainNotifications(0)).toHaveLength(100);
+    });
+
+    test("queue cap remains global across more than one hundred sessions", () => {
+        drainNotifications(Number.MAX_SAFE_INTEGER);
+        for (let i = 0; i < 250; i += 1) {
+            pushNotification("one-per-session", { i }, `ses_${i}`);
+        }
+        expect(drainNotifications(0)).toHaveLength(100);
+    });
+});

package/src/shared/rpc-notifications.ts

@@ -0,0 +1,222 @@
+/**
+ * In-memory notification queue for server→TUI push.
+ * Replaces SQLite plugin_messages table.
+ *
+ * Also tracks whether a TUI client is actively connected (polling).
+ * The server plugin cannot use `process.env.OPENCODE_CLIENT` to detect TUI
+ * because the server runs in a separate process from the TUI client.
+ */
+
+export interface RpcNotification {
+    id: number;
+    type: string;
+    payload: Record<string, unknown>;
+    sessionId?: string;
+}
+
+let queue: RpcNotification[] = [];
+let nextNotificationId = 1;
+
+/**
+ * A connected TUI notification sink — one per authenticated WebSocket. The RPC
+ * server registers a sink when a TUI socket authenticates (hello) and removes
+ * it on close. `send` is sink-agnostic (the server owns the actual WS socket)
+ * so this module stays free of Bun/WS types.
+ */
+export interface NotificationSink {
+    /** The TUI's active session at connect time (its hello scope). */
+    sessionId?: string;
+    /** Protocol 2 clients use strict session scoping; absent means legacy behavior. */
+    protocol?: number;
+    /** Deliver one notification over this sink's live socket. */
+    send: (notification: RpcNotification) => void;
+}
+
+// Live sinks replace the old poll-drain-timestamp inference. "TUI connected for
+// a session" is now exact socket liveness — accurate and immediate — instead of
+// "did a 500ms poll drain within the last 3s". Per-session scoping still matters:
+// one process can serve MANY sessions (a TUI on session A plus an OpenCode
+// Desktop opened on session B for the same project, whose newer RPC server this
+// TUI's port discovery then selects). Each sink carries ITS session, so a
+// B-scoped producer (`/mmc-status`, upgrade reminder) only sees B's TUI as
+// connected and routes its dialog there, never to A.
+const sinks = new Set<NotificationSink>();
+
+/** Register a live TUI sink. Returns an unregister fn (call on socket close). */
+export function registerNotificationSink(sink: NotificationSink): () => void {
+    sinks.add(sink);
+    return () => {
+        sinks.delete(sink);
+    };
+}
+
+/** Whether a notification may be delivered to a sink. Protocol 2 makes a
+ * session-less socket global-only; legacy sockets retain broad compatibility. */
+function notificationMatchesSink(notification: RpcNotification, sink: NotificationSink): boolean {
+    if (notification.sessionId === undefined) return true;
+    if (sink.sessionId !== undefined) return notification.sessionId === sink.sessionId;
+    return sink.protocol !== 2;
+}
+
+/** Push a notification to the TUI. Fans out to any live WS sink immediately and
+ *  also enqueues it so a TUI that is momentarily disconnected (reconnecting, or
+ *  not yet connected) still receives it on its next hello via the backlog drain.
+ *  At-least-once: a live push that the socket drops is re-delivered from the
+ *  queue on reconnect (pruned only when the client acknowledges it). */
+export function pushNotification(
+    type: string,
+    payload: Record<string, unknown>,
+    sessionId?: string,
+): void {
+    const notification: RpcNotification = { id: nextNotificationId++, type, payload, sessionId };
+    queue.push(notification);
+    // Fan out to every live sink this notification is scoped to. A delivery throw
+    // (dead socket mid-send) must not block other sinks or the caller.
+    for (const sink of sinks) {
+        if (!notificationMatchesSink(notification, sink)) continue;
+        try {
+            sink.send(notification);
+        } catch {
+            // Socket died between liveness check and send; the close handler will
+            // unregister it, and the queue backlog re-delivers on reconnect.
+        }
+    }
+    // Keep a strict global bound. Reserve the newest item for at most 25 recently
+    // active scopes, then evict the oldest unreserved item. This protects a quiet
+    // session from one noisy peer without allowing one item per session to grow
+    // the queue without limit.
+    if (queue.length > 100) {
+        const reservedIds = new Set<number>();
+        const reservedScopes = new Set<string>();
+        for (let i = queue.length - 1; i >= 0 && reservedScopes.size < 25; i -= 1) {
+            const candidate = queue[i];
+            const scope = candidate.sessionId ?? "\0global";
+            if (reservedScopes.has(scope)) continue;
+            reservedScopes.add(scope);
+            reservedIds.add(candidate.id);
+        }
+        const evictionIndex = queue.findIndex((candidate) => !reservedIds.has(candidate.id));
+        queue.splice(evictionIndex >= 0 ? evictionIndex : 0, 1);
+    }
+}
+
+export function acknowledgeNotifications(ids: readonly number[]): void {
+    const acknowledged = new Set(ids.filter((id) => Number.isSafeInteger(id) && id > 0));
+    if (acknowledged.size === 0) return;
+    // Exact removal preserves an earlier notification when a later handler finishes
+    // first or the earlier handler declines to consume its notification.
+    queue = queue.filter((notification) => !acknowledged.has(notification.id));
+}
+
+/** Reset process-local state to simulate a fresh server module in protocol tests. */
+export function __resetNotificationStateForTests(): void {
+    queue = [];
+    nextNotificationId = 1;
+    sinks.clear();
+}
+
+export interface DrainNotificationsOptions {
+    /**
+     * Cursor for global notifications when a session-scoped client sends separate
+     * session and global watermarks.
+     */
+    globalLastReceivedId?: number;
+    /** Ack/drain only the named session, not global notifications. */
+    sessionOnly?: boolean;
+    /** Ack/drain only session-less global notifications. */
+    globalOnly?: boolean;
+}
+
+function cursor(value: number | undefined): number {
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : 0;
+}
+
+/** Return pending notifications after pruning only the scopes the client acked.
+ *
+ *  Session-scoped and global notifications have independent cursors. A TUI can
+ *  switch from session A to session B after handling a high id in A; that high
+ *  watermark must never prune B's lower, still-unseen ids. Global notifications
+ *  are also tracked separately so a global dialog does not become a session
+ *  watermark. Legacy callers that omit options keep the original single-cursor
+ *  behavior.
+ *
+ *  Delivery is at-least-once (non-destructive return + prune-on-ack): a returned
+ *  notification stays queued until an exact acknowledgement or a legacy cursor
+ *  removes it, so a dropped WS socket re-delivers unhandled backlog on reconnect. */
+export function drainNotifications(
+    lastReceivedId = 0,
+    sessionId?: string,
+    options: DrainNotificationsOptions = {},
+): RpcNotification[] {
+    const sessionCursor = cursor(lastReceivedId);
+
+    if (options.globalOnly) {
+        queue = queue.filter(
+            (notification) =>
+                notification.sessionId !== undefined || notification.id > sessionCursor,
+        );
+        return queue.filter(
+            (notification) =>
+                notification.sessionId === undefined && notification.id > sessionCursor,
+        );
+    }
+
+    if (options.sessionOnly) {
+        if (sessionId === undefined) return [];
+        queue = queue.filter(
+            (notification) =>
+                notification.sessionId !== sessionId || notification.id > sessionCursor,
+        );
+        return queue.filter(
+            (notification) =>
+                notification.sessionId === sessionId && notification.id > sessionCursor,
+        );
+    }
+
+    if (sessionId !== undefined && options.globalLastReceivedId !== undefined) {
+        const globalCursor = cursor(options.globalLastReceivedId);
+        queue = queue.filter((notification) => {
+            if (notification.sessionId === undefined) return notification.id > globalCursor;
+            if (notification.sessionId === sessionId) return notification.id > sessionCursor;
+            return true;
+        });
+        return queue.filter((notification) => {
+            if (notification.sessionId === undefined) return notification.id > globalCursor;
+            return notification.sessionId === sessionId && notification.id > sessionCursor;
+        });
+    }
+
+    const matchesClient = (notification: RpcNotification): boolean =>
+        sessionId === undefined ||
+        notification.sessionId === undefined ||
+        notification.sessionId === sessionId;
+    if (sessionCursor > 0) {
+        // Legacy single-cursor mode prunes the scopes this client can see. New WS
+        // clients pass dual cursors above so cross-session watermarks stay isolated.
+        queue = queue.filter(
+            (notification) => !(notification.id <= sessionCursor && matchesClient(notification)),
+        );
+    }
+    return queue.filter(
+        (notification) => notification.id > sessionCursor && matchesClient(notification),
+    );
+}
+
+/** Whether a TUI client is connected via a live notification socket.
+ *  Now exact socket liveness (a registered WS sink), not a poll-drain timestamp.
+ *
+ *  Pass `sessionId` (preferred) to ask whether a TUI is connected FOR THAT
+ *  SESSION — this is what producers (`/mmc-status`, `/mmc-recomp`, the upgrade
+ *  reminder) must use to decide dialog-vs-message, so a TUI on a different
+ *  session in the same process does not misroute their delivery. A modern
+ *  session-less sink is global-only; a legacy sink retains broad compatibility.
+ *  Omit `sessionId` only for callers with no session context. */
+export function isTuiConnected(sessionId?: string): boolean {
+    if (sinks.size === 0) return false;
+    if (sessionId === undefined) return true;
+    for (const sink of sinks) {
+        if (sink.sessionId === sessionId) return true;
+        if (sink.sessionId === undefined && sink.protocol !== 2) return true;
+    }
+    return false;
+}