@cortexkit/opencode-magic-context 0.17.2 → 0.19.0

package/src/shared/resolve-fallbacks.ts

@@ -0,0 +1,76 @@
+import { getAgentFallbackModels } from "./model-requirements";
+
+/**
+ * Resolve the final fallback model list to attempt for an OpenCode subagent
+ * call.
+ *
+ * Policy (decided 2026-05-10):
+ *   - If user configured explicit `fallback_models` in their magic-context.jsonc
+ *     for this agent: use ONLY those. Respects user intent, no surprise
+ *     providers.
+ *   - If user did NOT configure any: fall back to the plugin's builtin
+ *     provider-agnostic chain (`AGENT_MODEL_REQUIREMENTS`).
+ *
+ * The returned list does NOT include the primary model — it's the ordered
+ * list of *alternates* to try after the primary fails. Each entry is
+ * "provider/modelID" form.
+ *
+ * Duplicates and empty strings are filtered. Entries that don't match the
+ * "provider/modelID" shape (must contain a "/" with non-empty parts) are
+ * also dropped — defensive guard against malformed user config.
+ */
+export function resolveFallbackChain(
+    agentName: string,
+    userFallbacks: readonly string[] | string | undefined,
+): string[] {
+    const userList = normalizeUserFallbacks(userFallbacks);
+
+    if (userList.length > 0) {
+        return dedupe(userList.filter(isValidModelSpec));
+    }
+
+    const builtin = getAgentFallbackModels(agentName);
+    if (!builtin || builtin.length === 0) return [];
+    return dedupe(builtin.filter(isValidModelSpec));
+}
+
+function normalizeUserFallbacks(userFallbacks: readonly string[] | string | undefined): string[] {
+    if (!userFallbacks) return [];
+    if (typeof userFallbacks === "string") {
+        const trimmed = userFallbacks.trim();
+        return trimmed ? [trimmed] : [];
+    }
+    return userFallbacks.map((s) => s.trim()).filter((s) => s.length > 0);
+}
+
+function isValidModelSpec(spec: string): boolean {
+    const slash = spec.indexOf("/");
+    return slash > 0 && slash < spec.length - 1;
+}
+
+function dedupe(list: string[]): string[] {
+    const seen = new Set<string>();
+    const out: string[] = [];
+    for (const item of list) {
+        if (seen.has(item)) continue;
+        seen.add(item);
+        out.push(item);
+    }
+    return out;
+}
+
+/**
+ * Parse a "provider/modelID" string into the OpenCode `model` object shape.
+ * Returns null on invalid input.
+ *
+ * Note: only splits on the FIRST "/" — modelID can legitimately contain slashes
+ * (e.g. `lemonade/GLM-4.7-Flash-GGUF/main`).
+ */
+export function parseProviderModel(spec: string): { providerID: string; modelID: string } | null {
+    const slash = spec.indexOf("/");
+    if (slash < 1 || slash >= spec.length - 1) return null;
+    return {
+        providerID: spec.slice(0, slash).trim(),
+        modelID: spec.slice(slash + 1).trim(),
+    };
+}

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

@@ -0,0 +1,161 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { MagicContextRpcClient } from "./rpc-client";
+import { rpcPortFilePath } from "./rpc-utils";
+
+interface TestServer {
+    port: number;
+    close: () => Promise<void>;
+}
+
+const tempDirs: string[] = [];
+let servers: TestServer[] = [];
+
+afterEach(async () => {
+    for (const server of servers.splice(0)) {
+        await server.close();
+    }
+    for (const dir of tempDirs.splice(0)) {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+
+function makeTempDir(): string {
+    const dir = mkdtempSync(join(tmpdir(), "mc-rpc-client-"));
+    tempDirs.push(dir);
+    return dir;
+}
+
+function writePortFile(storageDir: string, directory: string, port: number): void {
+    const portFile = rpcPortFilePath(storageDir, directory);
+    mkdirSync(dirname(portFile), { recursive: true });
+    writeFileSync(
+        portFile,
+        JSON.stringify({ port, pid: process.pid, started_at: Date.now() }),
+        "utf-8",
+    );
+}
+
+function writePortFileForPid(
+    storageDir: string,
+    directory: string,
+    port: number,
+    pid: number,
+    startedAt: number,
+): void {
+    const portFile = rpcPortFilePath(storageDir, directory, pid);
+    mkdirSync(dirname(portFile), { recursive: true });
+    writeFileSync(portFile, JSON.stringify({ port, pid, started_at: startedAt }), "utf-8");
+}
+
+async function startRpcServer(handler: (method: string) => Response | object): Promise<TestServer> {
+    const server = createServer(async (req, res) => {
+        if (req.method === "GET" && req.url === "/health") {
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ ok: true }));
+            return;
+        }
+
+        if (req.method === "POST" && req.url?.startsWith("/rpc/")) {
+            const method = req.url.slice("/rpc/".length);
+            const result = handler(method);
+            if (result instanceof Response) {
+                res.writeHead(result.status, { "Content-Type": "application/json" });
+                res.end(await result.text());
+                return;
+            }
+            res.writeHead(200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify(result));
+            return;
+        }
+
+        res.writeHead(404);
+        res.end("Not Found");
+    });
+
+    await new Promise<void>((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const addr = server.address();
+    if (!addr || typeof addr === "string") throw new Error("failed to bind test server");
+
+    const testServer = {
+        port: addr.port,
+        close: () =>
+            new Promise<void>((resolve, reject) => {
+                server.close((err) => (err ? reject(err) : resolve()));
+            }),
+    };
+    servers.push(testServer);
+    return testServer;
+}
+
+async function closeServer(server: TestServer): Promise<void> {
+    servers = servers.filter((s) => s !== server);
+    await server.close();
+}
+
+describe("MagicContextRpcClient", () => {
+    test("re-reads the port file after the cached server restarts on a new port", async () => {
+        const storageDir = makeTempDir();
+        const directory = "/repo";
+        const client = new MagicContextRpcClient(storageDir, directory);
+
+        const first = await startRpcServer(() => ({ value: "first" }));
+        writePortFile(storageDir, directory, first.port);
+        expect(await client.call<{ value: string }>("value")).toEqual({ value: "first" });
+
+        await closeServer(first);
+        const second = await startRpcServer(() => ({ value: "second" }));
+        writePortFile(storageDir, directory, second.port);
+
+        expect(await client.call<{ value: string }>("value")).toEqual({ value: "second" });
+    });
+
+    test("gives up when the port file points at a dead server", async () => {
+        const storageDir = makeTempDir();
+        const directory = "/repo";
+        const dead = await startRpcServer(() => ({ ok: true }));
+        const port = dead.port;
+        await closeServer(dead);
+        writePortFile(storageDir, directory, port);
+
+        const client = new MagicContextRpcClient(storageDir, directory);
+        await expect(client.call("value")).rejects.toThrow(
+            "Magic Context RPC server not available",
+        );
+    }, 20_000);
+
+    test("re-resolves and retries transient 5xx responses", async () => {
+        const storageDir = makeTempDir();
+        const directory = "/repo";
+        let calls = 0;
+        const server = await startRpcServer(() => {
+            calls++;
+            if (calls === 1) {
+                return new Response(JSON.stringify({ error: "warming up" }), { status: 503 });
+            }
+            return { value: "ok" };
+        });
+        writePortFile(storageDir, directory, server.port);
+
+        const client = new MagicContextRpcClient(storageDir, directory);
+        expect(await client.call<{ value: string }>("value")).toEqual({ value: "ok" });
+        expect(calls).toBe(2);
+    });
+
+    test("ignores newer stale pid files and discovers the latest live instance", async () => {
+        const storageDir = makeTempDir();
+        const directory = "/repo";
+        const live = await startRpcServer(() => ({ value: "live" }));
+        writePortFileForPid(storageDir, directory, 65535, 999_999_999, Date.now() + 10_000);
+        writePortFileForPid(storageDir, directory, live.port, process.pid, Date.now());
+
+        const client = new MagicContextRpcClient(storageDir, directory);
+        expect(await client.call<{ value: string }>("value")).toEqual({ value: "live" });
+    });
+});

package/src/shared/rpc-client.ts

@@ -1,17 +1,29 @@
-import { readFileSync } from "node:fs";
-import { rpcPortFilePath } from "./rpc-utils";
+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 portFilePath: string;
+    private portDir: string;
+    private legacyPortFilePath: string;
     private healthChecked = false;
 
     constructor(storageDir: string, directory: string) {
-        this.portFilePath = rpcPortFilePath(storageDir, directory);
+        this.portDir = rpcPortDir(storageDir, directory);
+        this.legacyPortFilePath = legacyRpcPortFilePath(storageDir, directory);
     }
 
     /** Call an RPC method. Retries port resolution if the server isn't ready yet. */
@@ -19,23 +31,52 @@ export class MagicContextRpcClient {
         method: string,
         params: Record<string, unknown> = {},
     ): Promise<T> {
-        const port = await this.resolvePort();
-        if (!port) {
-            throw new Error("Magic Context RPC server not available");
-        }
+        let lastError: unknown = null;
 
-        const response = await this.fetchWithTimeout(`http://127.0.0.1:${port}/rpc/${method}`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify(params),
-        });
+        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" },
+                        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 >= 500) {
+                        lastError = error;
+                        this.reset();
+                        continue;
+                    }
+                    (error as NonRetryableRpcError)[NON_RETRYABLE_RPC_ERROR] = true;
+                    throw error;
+                }
 
-        if (!response.ok) {
-            const text = await response.text();
-            throw new Error(`RPC ${method} failed (${response.status}): ${text}`);
+                return (await response.json()) as T;
+            } catch (err) {
+                if (isNonRetryableRpcError(err)) {
+                    throw err;
+                }
+                lastError = err;
+                this.reset();
+            }
         }
 
-        return (await response.json()) as T;
+        if (lastError instanceof Error) {
+            throw lastError;
+        }
+        throw new Error("Magic Context RPC server not available");
     }
 
     /** Check if the RPC server is reachable. */
@@ -83,13 +124,28 @@ export class MagicContextRpcClient {
     }
 
     private readPortFile(): number | null {
+        const records: RpcPortFileRecord[] = [];
+
         try {
-            const content = readFileSync(this.portFilePath, "utf-8").trim();
-            const port = Number.parseInt(content, 10);
-            if (Number.isNaN(port) || port <= 0 || port > 65535) {
-                return null;
+            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"));
+                if (!record || !isPidAlive(record.pid)) continue;
+                records.push(record);
             }
-            return port;
+        } catch {
+            // Directory may not exist yet. Fall back to the legacy file below.
+        }
+
+        if (records.length > 0) {
+            records.sort((a, b) => b.started_at - a.started_at);
+            return records[0].port;
+        }
+
+        try {
+            const record = parseRpcPortFile(readFileSync(this.legacyPortFilePath, "utf-8"));
+            if (record?.pid && !isPidAlive(record.pid)) return null;
+            return record?.port ?? null;
         } catch {
             return null;
         }
@@ -121,3 +177,7 @@ export class MagicContextRpcClient {
         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,20 @@
+import { describe, expect, test } from "bun:test";
+import { drainNotifications, pushNotification } 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([]);
+    });
+});

package/src/shared/rpc-notifications.ts

@@ -8,12 +8,14 @@
  */
 
 export interface RpcNotification {
+    id: number;
     type: string;
     payload: Record<string, unknown>;
     sessionId?: string;
 }
 
 let queue: RpcNotification[] = [];
+let nextNotificationId = 1;
 // Timestamp of last drain — used to detect if TUI is actively polling.
 // The TUI polls every 500ms; we consider it connected if it polled within
 // the last 3 seconds (6× the poll interval, tolerates transient delays).
@@ -26,20 +28,21 @@ export function pushNotification(
     payload: Record<string, unknown>,
     sessionId?: string,
 ): void {
-    queue.push({ type, payload, sessionId });
+    queue.push({ id: nextNotificationId++, type, payload, sessionId });
     // Cap queue size to prevent unbounded growth if TUI is not polling
     if (queue.length > 100) {
         queue = queue.slice(-50);
     }
 }
 
-/** Drain and return all pending notifications atomically.
+/** Return pending notifications after acking the client's last received id.
  *  Updates lastDrainAt so isTuiConnected() reflects recent activity. */
-export function drainNotifications(): RpcNotification[] {
+export function drainNotifications(lastReceivedId = 0): RpcNotification[] {
     lastDrainAt = Date.now();
-    const result = queue;
-    queue = [];
-    return result;
+    if (lastReceivedId > 0) {
+        queue = queue.filter((notification) => notification.id > lastReceivedId);
+    }
+    return [...queue];
 }
 
 /** Whether a TUI client is actively polling for notifications.

package/src/shared/rpc-server.ts

@@ -1,8 +1,15 @@
-import { mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import {
+    mkdirSync,
+    readdirSync,
+    readFileSync,
+    renameSync,
+    unlinkSync,
+    writeFileSync,
+} from "node:fs";
 import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
 import { dirname } from "node:path";
 import { log } from "./logger";
-import { rpcPortFilePath } from "./rpc-utils";
+import { isPidAlive, parseRpcPortFile, rpcPortDir, rpcPortFilePath } from "./rpc-utils";
 
 type RpcHandler = (params: Record<string, unknown>) => Promise<Record<string, unknown>>;
 
@@ -11,9 +18,12 @@ export class MagicContextRpcServer {
     private port = 0;
     private handlers = new Map<string, RpcHandler>();
     private portFilePath: string;
+    private portDir: string;
+    private startedAt = Date.now();
 
     constructor(storageDir: string, directory: string) {
         this.portFilePath = rpcPortFilePath(storageDir, directory);
+        this.portDir = rpcPortDir(storageDir, directory);
     }
 
     /** Register an RPC method handler. */
@@ -40,12 +50,24 @@ export class MagicContextRpcServer {
                 this.port = addr.port;
                 this.server = server;
 
-                // Write port file atomically
+                // Write a per-process port file atomically. Multi-instance
+                // OpenCode is supported: TUI discovery scans all live pid files
+                // and picks the most recent instead of cross-wiring via one
+                // shared project file.
                 try {
+                    this.warnIfOtherLiveInstance();
                     const dir = dirname(this.portFilePath);
                     mkdirSync(dir, { recursive: true });
                     const tmpPath = `${this.portFilePath}.tmp`;
-                    writeFileSync(tmpPath, String(this.port), "utf-8");
+                    writeFileSync(
+                        tmpPath,
+                        JSON.stringify({
+                            port: this.port,
+                            pid: process.pid,
+                            started_at: this.startedAt,
+                        }),
+                        "utf-8",
+                    );
                     renameSync(tmpPath, this.portFilePath);
                     log(`[rpc] server listening on 127.0.0.1:${this.port}`);
                 } catch (err) {
@@ -60,6 +82,22 @@ export class MagicContextRpcServer {
         });
     }
 
+    private warnIfOtherLiveInstance(): void {
+        try {
+            for (const entry of readdirSync(this.portDir)) {
+                if (!entry.startsWith("port-") || !entry.endsWith(".json")) continue;
+                const record = parseRpcPortFile(readFileSync(`${this.portDir}/${entry}`, "utf-8"));
+                if (!record || record.pid === process.pid || !isPidAlive(record.pid)) continue;
+                log(
+                    `[rpc] another Magic Context RPC server is active for this project (pid ${record.pid}, port ${record.port}); starting separate instance on a new port`,
+                );
+                return;
+            }
+        } catch {
+            // No discovery directory yet, or unreadable stale file. Not fatal.
+        }
+    }
+
     /** Stop the server and clean up port file. */
     stop(): void {
         if (this.server) {

package/src/shared/rpc-types.ts

@@ -84,6 +84,7 @@ export interface StatusDetail extends SidebarSnapshot {
 }
 
 export interface RpcNotificationMessage {
+    id: number;
     type: string;
     payload: Record<string, unknown>;
     sessionId?: string;

package/src/shared/rpc-utils.ts

@@ -1,6 +1,12 @@
 import { createHash } from "node:crypto";
 import { join } from "node:path";
 
+export interface RpcPortFileRecord {
+    port: number;
+    pid: number;
+    started_at: number;
+}
+
 /**
  * Stable hash for a project directory — scopes RPC port files per-project
  * so multiple OpenCode instances don't collide.
@@ -10,7 +16,57 @@ export function projectHash(directory: string): string {
     return createHash("sha256").update(normalized).digest("hex").slice(0, 16);
 }
 
-/** Per-project RPC port file path. */
-export function rpcPortFilePath(storageDir: string, directory: string): string {
-    return join(storageDir, "rpc", projectHash(directory), "port");
+/** Directory containing per-process RPC discovery files for a project. */
+export function rpcPortDir(storageDir: string, directory: string): string {
+    return join(storageDir, "rpc", projectHash(directory));
+}
+
+/** Per-process RPC port file path. */
+export function rpcPortFilePath(storageDir: string, directory: string, pid = process.pid): string {
+    return join(rpcPortDir(storageDir, directory), `port-${pid}.json`);
+}
+
+/** Legacy single-port file used by v0.18.0 and earlier. */
+export function legacyRpcPortFilePath(storageDir: string, directory: string): string {
+    return join(rpcPortDir(storageDir, directory), "port");
+}
+
+export function isPidAlive(pid: number): boolean {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (err) {
+        return (err as NodeJS.ErrnoException).code === "EPERM";
+    }
+}
+
+export function parseRpcPortFile(content: string, fallbackPid = 0): RpcPortFileRecord | null {
+    const trimmed = content.trim();
+    if (!trimmed) return null;
+
+    if (trimmed.startsWith("{")) {
+        try {
+            const parsed = JSON.parse(trimmed) as Partial<RpcPortFileRecord>;
+            const port = Number(parsed.port);
+            const pid = Number(parsed.pid);
+            const startedAt = Number(parsed.started_at);
+            if (!isValidPort(port) || !Number.isInteger(pid) || pid <= 0) return null;
+            return {
+                port,
+                pid,
+                started_at: Number.isFinite(startedAt) ? startedAt : 0,
+            };
+        } catch {
+            return null;
+        }
+    }
+
+    const port = Number.parseInt(trimmed, 10);
+    if (!isValidPort(port)) return null;
+    return { port, pid: fallbackPid, started_at: 0 };
+}
+
+function isValidPort(port: number): boolean {
+    return Number.isInteger(port) && port > 0 && port <= 65535;
 }