@cortexkit/opencode-magic-context 0.18.0 → 0.20.0

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;
 }

package/src/shared/stable-json.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, test } from "bun:test";
+import { stableStringify } from "./stable-json";
+
+describe("stableStringify", () => {
+    test("primitive values match JSON.stringify", () => {
+        expect(stableStringify("hello")).toBe('"hello"');
+        expect(stableStringify(42)).toBe("42");
+        expect(stableStringify(true)).toBe("true");
+        expect(stableStringify(false)).toBe("false");
+        expect(stableStringify(null)).toBe("null");
+    });
+
+    test("undefined renders as literal string", () => {
+        expect(stableStringify(undefined)).toBe("undefined");
+    });
+
+    test("object keys sort by code-point order, not locale", () => {
+        // 'Z' (0x5a) sorts before 'a' (0x61) by code-point.
+        // localeCompare would sort 'a' before 'Z' in many locales.
+        // We want code-point semantics.
+        const input = { Z: 1, a: 2 };
+        expect(stableStringify(input)).toBe('{"Z":1,"a":2}');
+    });
+
+    test("nested objects sort recursively", () => {
+        const input = { b: { y: 1, x: 2 }, a: { z: 3, w: 4 } };
+        expect(stableStringify(input)).toBe('{"a":{"w":4,"z":3},"b":{"x":2,"y":1}}');
+    });
+
+    test("arrays preserve order", () => {
+        const input = [3, 1, 2];
+        expect(stableStringify(input)).toBe("[3,1,2]");
+    });
+
+    test("arrays of objects sort keys per element", () => {
+        const input = [
+            { b: 1, a: 2 },
+            { d: 3, c: 4 },
+        ];
+        expect(stableStringify(input)).toBe('[{"a":2,"b":1},{"c":4,"d":3}]');
+    });
+
+    test("identical objects with different key insertion order produce same string", () => {
+        const a = { foo: 1, bar: 2 };
+        const b = { bar: 2, foo: 1 };
+        expect(stableStringify(a)).toBe(stableStringify(b));
+    });
+
+    test("circular references render as marker, do not throw", () => {
+        const a: Record<string, unknown> = { x: 1 };
+        a.self = a;
+        expect(stableStringify(a)).toBe('{"self":"[Circular]","x":1}');
+    });
+
+    test("mixed cycle through array does not crash", () => {
+        const arr: unknown[] = [];
+        arr.push(arr);
+        expect(stableStringify(arr)).toBe('["[Circular]"]');
+    });
+
+    test("empty object and array", () => {
+        expect(stableStringify({})).toBe("{}");
+        expect(stableStringify([])).toBe("[]");
+    });
+
+    test("special string characters JSON-escaped in keys", () => {
+        const input = { 'with "quotes"': 1 };
+        expect(stableStringify(input)).toBe('{"with \\"quotes\\"":1}');
+    });
+
+    test("Unicode key sort by code-point, not by collation", () => {
+        // 'ä' (U+00E4) sorts AFTER 'z' (U+007A) by code-point.
+        // localeCompare in many locales would put 'ä' near 'a'.
+        const input = { z: 1, ä: 2 };
+        const result = stableStringify(input);
+        expect(result).toBe('{"z":1,"ä":2}');
+    });
+
+    test("deterministic across multiple calls", () => {
+        const input = { c: 3, a: 1, b: 2 };
+        const first = stableStringify(input);
+        const second = stableStringify(input);
+        const third = stableStringify(input);
+        expect(first).toBe(second);
+        expect(second).toBe(third);
+    });
+});

package/src/shared/stable-json.ts

@@ -0,0 +1,37 @@
+/**
+ * Process-local deterministic JSON serialization for JSON-like plain
+ * objects. Keys are sorted by code-point order (NOT locale-sensitive).
+ *
+ * Contract:
+ * - Stable for plain objects, arrays, primitives, and `null`.
+ * - `undefined` serialized as the string "undefined".
+ * - Circular references serialized as the string `"[Circular]"`.
+ * - **NOT** a canonical cross-runtime / cross-locale JSON serializer.
+ *   Two different runtimes that disagree on `JSON.stringify` of primitives
+ *   (none known today) would produce different output.
+ *
+ * Used for:
+ * - `tool_definition_measurements` fingerprint hashing
+ * - `pending_compaction_marker_state` CAS comparison
+ *
+ * If a future use case needs true canonical JSON (e.g. cross-process
+ * signing), build a separate utility — do NOT widen this contract.
+ */
+export function stableStringify(value: unknown, seen = new WeakSet<object>()): string {
+    if (value === undefined) return "undefined";
+    if (value === null || typeof value !== "object") return JSON.stringify(value) ?? String(value);
+    if (seen.has(value)) return '"[Circular]"';
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item, seen)).join(",")}]`;
+    }
+    // Code-point sort (NOT localeCompare). Stable across runtimes/locales.
+    const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => {
+        if (a < b) return -1;
+        if (a > b) return 1;
+        return 0;
+    });
+    return `{${entries
+        .map(([key, child]) => `${JSON.stringify(key)}:${stableStringify(child, seen)}`)
+        .join(",")}}`;
+}

package/src/shared/transcript.ts

@@ -22,7 +22,7 @@
  *   3. Lets the shared transform code (tagging, stripping, drops)
  *      operate on `TranscriptPart` interface instances without caring
  *      whether they're wrapping `Part` from `@opencode-ai/sdk` or
- *      `TextContent | ToolCall | ThinkingContent` from `@mariozechner/pi-ai`.
+ *      `TextContent | ToolCall | ThinkingContent` from `@earendil-works/pi-ai`.
  *
  * What this interface deliberately does NOT do:
  *
@@ -181,7 +181,7 @@ export interface TranscriptMessage {
  * messages-transform.ts, Pi's context-event handler). The shared
  * transform code receives a Transcript and operates only through this
  * interface — it never imports from `@opencode-ai/sdk` or
- * `@mariozechner/pi-ai`.
+ * `@earendil-works/pi-ai`.
  */
 export interface Transcript {
     /** Ordered messages in the current pass. */

package/src/tui/data/context-db.ts

@@ -10,6 +10,7 @@ import type { RpcNotificationMessage, SidebarSnapshot, StatusDetail } from "../.
 export type { SidebarSnapshot, StatusDetail };
 
 let rpcClient: MagicContextRpcClient | null = null;
+let lastReceivedNotificationId = 0;
 
 function getStorageDir(): string {
     // Plugin v0.16+ uses the shared cortexkit/magic-context path so OpenCode
@@ -30,6 +31,7 @@ export function initRpcClient(directory: string): void {
 export function closeRpc(): void {
     rpcClient?.reset();
     rpcClient = null;
+    lastReceivedNotificationId = 0;
 }
 
 const EMPTY_SNAPSHOT: SidebarSnapshot = {
@@ -103,9 +105,19 @@ function recallSidebarSnapshot(sessionId: string, fallback: SidebarSnapshot): Si
         stickySidebarCache.delete(sessionId);
         return fallback;
     }
+    if (!hasInFlightEvidence(fallback)) {
+        stickySidebarCache.delete(sessionId);
+        return fallback;
+    }
     return cached.snapshot;
 }
 
+function hasInFlightEvidence(snapshot: SidebarSnapshot): boolean {
+    return (
+        snapshot.compartmentInProgress || snapshot.historianRunning || snapshot.pendingOpsCount > 0
+    );
+}
+
 /** Fetch sidebar snapshot from the server via RPC. */
 export async function loadSidebarSnapshot(
     sessionId: string,
@@ -225,8 +237,15 @@ export async function consumeTuiMessages(): Promise<TuiMessage[]> {
     try {
         const result = await rpcClient.call<{ messages: RpcNotificationMessage[] }>(
             "pending-notifications",
+            { lastReceivedId: lastReceivedNotificationId },
         );
-        return (result.messages ?? []).map((m) => ({
+        const messages = result.messages ?? [];
+        for (const message of messages) {
+            if (message.id > lastReceivedNotificationId) {
+                lastReceivedNotificationId = message.id;
+            }
+        }
+        return messages.map((m) => ({
             type: m.type,
             payload: m.payload,
             sessionId: m.sessionId,