@cortexkit/opencode-magic-context 0.32.0 → 0.32.1

package/src/shared/rpc-server.ts

@@ -13,6 +13,7 @@ import { dirname } from "node:path";
 import type { Server, ServerWebSocket } from "bun";
 import { log } from "./logger";
 import {
+    acknowledgeNotifications,
     drainNotifications,
     type NotificationSink,
     registerNotificationSink,
@@ -57,8 +58,12 @@ function bearerToken(req: Request): string {
     return typeof auth === "string" ? auth.replace(/^Bearer\s+/i, "") : "";
 }
 
-function websocketToken(req: Request, url: URL): string {
-    return bearerToken(req) || url.searchParams.get("token") || "";
+function websocketToken(req: Request): string {
+    const headerToken = bearerToken(req);
+    if (headerToken) return headerToken;
+    // v0.32 TUI clients put the token in the upgrade URL. Keep this fallback only
+    // for the v0.32→v0.32.1 skew window; remove it when v0.32 clients are unsupported.
+    return new URL(req.url).searchParams.get("token") ?? "";
 }
 
 /**
@@ -242,7 +247,7 @@ export class MagicContextRpcServer {
         // WebSocket upgrade — the persistent push channel. Authenticate before
         // `srv.upgrade` so an unauthorized request never becomes a live socket.
         if (url.pathname === "/ws") {
-            if (!tokensMatch(websocketToken(req, url), this.token)) {
+            if (!tokensMatch(websocketToken(req), this.token)) {
                 return new Response("Unauthorized", { status: 401 });
             }
             const ok = srv.upgrade(req, { data: { authed: false } });
@@ -253,7 +258,7 @@ export class MagicContextRpcServer {
         // No wildcard CORS: the only legitimate client is the in-process TUI
         // client, not a browser origin.
         if (req.method === "GET" && url.pathname === "/health") {
-            return json({ ok: true, pid: process.pid });
+            return json({ ok: true, pid: process.pid, instance_id: this.instanceId });
         }
 
         if (req.method !== "POST" || !url.pathname.startsWith("/rpc/")) {
@@ -293,8 +298,8 @@ export class MagicContextRpcServer {
         }
     }
 
-    /** WS message handler: hello (auth + sink registration + backlog drain) and
-     *  ack (cursor advance → queue prune). All other messages are ignored. */
+    /** WS message handler: hello (auth + sink registration + backlog delivery) and
+     *  ack (exact removal or legacy cursor pruning). All other messages are ignored. */
     private handleWsMessage(ws: ServerWebSocket<WsData>, raw: string | Buffer): void {
         let msg: {
             type?: string;
@@ -303,6 +308,10 @@ export class MagicContextRpcServer {
             lastReceivedId?: number;
             globalLastReceivedId?: number;
             ackScope?: string;
+            protocol?: number;
+            instanceId?: string;
+            ids?: unknown;
+            cursor?: number;
         };
         try {
             msg = JSON.parse(typeof raw === "string" ? raw : raw.toString("utf8"));
@@ -336,6 +345,7 @@ export class MagicContextRpcServer {
             // Register a live sink so future pushes reach this socket immediately.
             const sink: NotificationSink = {
                 sessionId: ws.data.sessionId,
+                protocol: msg.protocol,
                 send: (notification) => {
                     ws.send(JSON.stringify({ type: "notification", notification }));
                 },
@@ -343,40 +353,66 @@ export class MagicContextRpcServer {
             ws.data.unregister = registerNotificationSink(sink);
             this.sockets.add(ws);
 
-            // Deliver any backlog the client hasn't seen (at-least-once). Modern
-            // clients send separate session and global cursors; keeping those
-            // watermarks independent prevents a high id in one session from pruning
-            // lower unseen notifications in another session.
-            const lastReceivedId = Number(msg.lastReceivedId ?? 0);
-            const sessionCursor = Number.isFinite(lastReceivedId) ? lastReceivedId : 0;
-            const hasGlobalCursor = typeof msg.globalLastReceivedId === "number";
-            const globalLastReceivedId = hasGlobalCursor
-                ? Number.isFinite(msg.globalLastReceivedId)
-                    ? msg.globalLastReceivedId
-                    : 0
-                : 0;
-            const backlog =
-                ws.data.sessionId === undefined && hasGlobalCursor
-                    ? drainNotifications(globalLastReceivedId, undefined, { globalOnly: true })
-                    : drainNotifications(
-                          sessionCursor,
-                          ws.data.sessionId,
-                          hasGlobalCursor
-                              ? { globalLastReceivedId: globalLastReceivedId }
-                              : undefined,
-                      );
+            const usesExactAcknowledgements = msg.protocol === 2;
+            // The epoch arrives before backlog frames so the client can discard
+            // cursors and deduplication entries from a replaced server first.
+            ws.send(
+                JSON.stringify({
+                    type: "hello-ack",
+                    protocol: 2,
+                    instanceId: this.instanceId,
+                }),
+            );
+
+            let backlog: ReturnType<typeof drainNotifications>;
+            if (usesExactAcknowledgements) {
+                // Protocol 2 never treats a high handled id as proof that lower ids
+                // were consumed. Exact acknowledgements are the only destructive
+                // operation, so declined or interrupted dialogs survive reconnects.
+                backlog =
+                    ws.data.sessionId === undefined
+                        ? drainNotifications(0, undefined, { globalOnly: true })
+                        : drainNotifications(0, ws.data.sessionId, {
+                              globalLastReceivedId: 0,
+                          });
+            } else {
+                // Legacy clients use independent session and global watermarks.
+                const lastReceivedId = Number(msg.lastReceivedId ?? 0);
+                const sessionCursor = Number.isFinite(lastReceivedId) ? lastReceivedId : 0;
+                const hasGlobalCursor = typeof msg.globalLastReceivedId === "number";
+                const globalLastReceivedId = hasGlobalCursor
+                    ? Number.isFinite(msg.globalLastReceivedId)
+                        ? msg.globalLastReceivedId
+                        : 0
+                    : 0;
+                backlog =
+                    ws.data.sessionId === undefined && hasGlobalCursor
+                        ? drainNotifications(globalLastReceivedId, undefined, { globalOnly: true })
+                        : drainNotifications(
+                              sessionCursor,
+                              ws.data.sessionId,
+                              hasGlobalCursor
+                                  ? { globalLastReceivedId: globalLastReceivedId }
+                                  : undefined,
+                          );
+            }
             for (const notification of backlog) {
                 ws.send(JSON.stringify({ type: "notification", notification }));
             }
-            ws.send(JSON.stringify({ type: "hello-ack" }));
             return;
         }
 
         if (msg.type === "ack") {
-            // Advance only the cursor scope the client handled. Acking session A
-            // must not prune session B, and acking a global notification must not
-            // become a session watermark. Cheap, event-driven queue cleanup.
-            const lastReceivedId = Number(msg.lastReceivedId ?? 0);
+            if (Array.isArray(msg.ids)) {
+                acknowledgeNotifications(
+                    msg.ids.filter((id): id is number => typeof id === "number"),
+                );
+                return;
+            }
+
+            // Keep watermark acknowledgements during the one-release skew window.
+            // Scope isolation remains mandatory for these legacy messages.
+            const lastReceivedId = Number(msg.cursor ?? msg.lastReceivedId ?? 0);
             if (Number.isFinite(lastReceivedId) && lastReceivedId > 0) {
                 if (msg.ackScope === "global") {
                     drainNotifications(lastReceivedId, undefined, { globalOnly: true });

package/src/shared/sqlite.ts

@@ -137,11 +137,15 @@ function buildNodeSqliteDatabaseClass(DatabaseSync: any): typeof BetterSqlite3 {
         transaction<F extends (...args: any[]) => any>(fn: F): F {
             // biome-ignore lint/suspicious/noExplicitAny: faithful pass-through of this/args to fn.
             const self = this as any;
-            const wrapped = function (this: unknown, ...args: unknown[]): unknown {
+            const execute = (
+                mode: "" | "DEFERRED" | "IMMEDIATE" | "EXCLUSIVE",
+                receiver: unknown,
+                args: unknown[],
+            ) => {
                 const nested = self.isTransaction === true;
-                self.exec(nested ? `SAVEPOINT ${SAVEPOINT}` : "BEGIN");
+                self.exec(nested ? `SAVEPOINT ${SAVEPOINT}` : `BEGIN${mode ? ` ${mode}` : ""}`);
                 try {
-                    const result = fn.apply(this, args);
+                    const result = fn.apply(receiver, args);
                     self.exec(nested ? `RELEASE ${SAVEPOINT}` : "COMMIT");
                     return result;
                 } catch (error) {
@@ -157,6 +161,21 @@ function buildNodeSqliteDatabaseClass(DatabaseSync: any): typeof BetterSqlite3 {
                     throw error;
                 }
             };
+            const wrapped = function (this: unknown, ...args: unknown[]): unknown {
+                return execute("", this, args);
+            };
+            wrapped.default = function (this: unknown, ...args: unknown[]): unknown {
+                return execute("", this, args);
+            };
+            wrapped.deferred = function (this: unknown, ...args: unknown[]): unknown {
+                return execute("DEFERRED", this, args);
+            };
+            wrapped.immediate = function (this: unknown, ...args: unknown[]): unknown {
+                return execute("IMMEDIATE", this, args);
+            };
+            wrapped.exclusive = function (this: unknown, ...args: unknown[]): unknown {
+                return execute("EXCLUSIVE", this, args);
+            };
             return wrapped as unknown as F;
         }
     }

package/src/shared/tui-config.test.ts

@@ -4,11 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 
 const roots: string[] = [];
-const prevConfigDir = process.env.OPENCODE_CONFIG_DIR;
-
 afterEach(() => {
-    if (prevConfigDir === undefined) delete process.env.OPENCODE_CONFIG_DIR;
-    else process.env.OPENCODE_CONFIG_DIR = prevConfigDir;
     for (const root of roots.splice(0)) {
         rmSync(root, { recursive: true, force: true });
     }
@@ -18,7 +14,6 @@ describe("ensureTuiPluginEntry", () => {
     it("preserves tuple dev-path plugin entry and does not add @latest", async () => {
         const root = mkdtempSync(join(tmpdir(), "mc-tui-"));
         roots.push(root);
-        process.env.OPENCODE_CONFIG_DIR = root;
         const devPath = "/Work/magic-context/packages/plugin";
         const tuiPath = join(root, "tui.json");
         writeFileSync(
@@ -27,7 +22,7 @@ describe("ensureTuiPluginEntry", () => {
         );
 
         const { ensureTuiPluginEntry } = await import("./tui-config");
-        const changed = ensureTuiPluginEntry();
+        const changed = ensureTuiPluginEntry({ configDir: root });
         expect(changed).toBe(false);
         const parsed = JSON.parse(readFileSync(tuiPath, "utf-8")) as { plugin: unknown[] };
         expect(parsed.plugin).toHaveLength(2);
@@ -40,7 +35,6 @@ describe("ensureTuiPluginEntry", () => {
     it("upgrades bare npm name to @latest while preserving tuple options", async () => {
         const root = mkdtempSync(join(tmpdir(), "mc-tui-npm-"));
         roots.push(root);
-        process.env.OPENCODE_CONFIG_DIR = root;
         const tuiPath = join(root, "tui.json");
         writeFileSync(
             tuiPath,
@@ -54,7 +48,7 @@ describe("ensureTuiPluginEntry", () => {
         );
 
         const { ensureTuiPluginEntry } = await import("./tui-config");
-        expect(ensureTuiPluginEntry()).toBe(true);
+        expect(ensureTuiPluginEntry({ configDir: root })).toBe(true);
         const parsed = JSON.parse(readFileSync(tuiPath, "utf-8")) as { plugin: unknown[] };
         const entry = parsed.plugin[0] as unknown[];
         expect(entry[0]).toBe("@cortexkit/opencode-magic-context@latest");
@@ -64,10 +58,9 @@ describe("ensureTuiPluginEntry", () => {
     it("creates tui.jsonc (not tui.json) on a fresh install", async () => {
         const root = mkdtempSync(join(tmpdir(), "mc-tui-fresh-"));
         roots.push(root);
-        process.env.OPENCODE_CONFIG_DIR = root;
 
         const { ensureTuiPluginEntry } = await import("./tui-config");
-        expect(ensureTuiPluginEntry()).toBe(true);
+        expect(ensureTuiPluginEntry({ configDir: root })).toBe(true);
 
         // The new file must be tui.jsonc so a tui.json stub never ends up
         // sitting next to a tui.jsonc the user writes later (#176).
@@ -82,7 +75,6 @@ describe("ensureTuiPluginEntry", () => {
     it("writes into the existing tui.jsonc when both files exist", async () => {
         const root = mkdtempSync(join(tmpdir(), "mc-tui-both-"));
         roots.push(root);
-        process.env.OPENCODE_CONFIG_DIR = root;
         // A real user config in tui.jsonc plus a leftover empty tui.json.
         writeFileSync(
             join(root, "tui.jsonc"),
@@ -91,7 +83,7 @@ describe("ensureTuiPluginEntry", () => {
         writeFileSync(join(root, "tui.json"), "{}\n");
 
         const { ensureTuiPluginEntry } = await import("./tui-config");
-        expect(ensureTuiPluginEntry()).toBe(true);
+        expect(ensureTuiPluginEntry({ configDir: root })).toBe(true);
 
         // The plugin entry must land in tui.jsonc (higher precedence), and the
         // user's keybinds must survive; tui.json must be left untouched.

package/src/shared/tui-config.ts

@@ -62,8 +62,8 @@ function writeTuiConfigAtomic(configPath: string, config: Record<string, unknown
     renameSync(tmpPath, configPath);
 }
 
-function resolveTuiConfigPath(): string {
-    const configDir = getOpenCodeConfigPaths({ binary: "opencode" }).configDir;
+function resolveTuiConfigPath(configDirOverride?: string): string {
+    const configDir = configDirOverride ?? getOpenCodeConfigPaths({ binary: "opencode" }).configDir;
     const jsoncPath = join(configDir, "tui.jsonc");
     const jsonPath = join(configDir, "tui.json");
 
@@ -80,12 +80,12 @@ function resolveTuiConfigPath(): string {
 }
 
 /**
- * Ensure tui.json has the magic-context TUI plugin entry.
- * Creates tui.json if it doesn't exist. Silently skips if already present.
+ * Ensure the selected TUI config has the magic-context plugin entry.
+ * Creates tui.jsonc if neither TUI config exists. Silently skips if already present.
  */
-export function ensureTuiPluginEntry(): boolean {
+export function ensureTuiPluginEntry(options: { configDir?: string } = {}): boolean {
     try {
-        const configPath = resolveTuiConfigPath();
+        const configPath = resolveTuiConfigPath(options.configDir);
 
         let config: Record<string, unknown> = {};
         if (existsSync(configPath)) {

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

@@ -0,0 +1,113 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MagicContextRpcServer } from "../../shared/rpc-server";
+import type { SidebarSnapshot } from "../../shared/rpc-types";
+import { closeRpc, getCompartmentCount, initRpcClient, loadSidebarSnapshot } from "./context-db";
+
+const originalXdgDataHome = process.env.XDG_DATA_HOME;
+const tempDirs: string[] = [];
+const servers: MagicContextRpcServer[] = [];
+
+afterEach(() => {
+    closeRpc();
+    for (const server of servers.splice(0)) server.stop();
+    for (const dir of tempDirs.splice(0)) {
+        rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
+    }
+    if (originalXdgDataHome === undefined) delete process.env.XDG_DATA_HOME;
+    else process.env.XDG_DATA_HOME = originalXdgDataHome;
+});
+
+function makeDataHome(): string {
+    const dir = mkdtempSync(join(tmpdir(), "mc-context-db-"));
+    tempDirs.push(dir);
+    process.env.XDG_DATA_HOME = dir;
+    return dir;
+}
+
+function snapshot(sessionId: string, inputTokens: number): SidebarSnapshot {
+    return {
+        sessionId,
+        usagePercentage: inputTokens > 0 ? 25 : 0,
+        inputTokens,
+        contextLimit: 1000,
+        systemPromptTokens: 0,
+        compartmentCount: inputTokens > 0 ? 2 : 0,
+        memoryCount: 0,
+        memoryBlockCount: 0,
+        pendingOpsCount: 0,
+        historianRunning: false,
+        compartmentInProgress: false,
+        sessionNoteCount: 0,
+        readySmartNoteCount: 0,
+        cacheTtl: "5m",
+        lastDreamerRunAt: null,
+        projectIdentity: null,
+        compartmentTokens: 0,
+        factTokens: 0,
+        memoryTokens: 0,
+        docsTokens: 0,
+        profileTokens: 0,
+        conversationTokens: inputTokens,
+        toolCallTokens: 0,
+        toolDefinitionTokens: 0,
+        executeThreshold: 65,
+        newWorkTokens: null,
+        totalInputTokens: inputTokens,
+    };
+}
+
+async function startServer(
+    dataHome: string,
+    directory: string,
+    sidebar: () => Record<string, unknown>,
+): Promise<MagicContextRpcServer> {
+    const server = new MagicContextRpcServer(
+        join(dataHome, "cortexkit", "magic-context"),
+        directory,
+    );
+    server.handle("sidebar-snapshot", async () => sidebar());
+    await server.start();
+    servers.push(server);
+    return server;
+}
+
+describe("TUI context RPC data", () => {
+    test("uses an unexpired sticky snapshot only for failed responses", async () => {
+        const dataHome = makeDataHome();
+        const directory = "/repo-sticky";
+        const sessionId = "ses_sticky";
+        let response: Record<string, unknown> = snapshot(sessionId, 250) as unknown as Record<
+            string,
+            unknown
+        >;
+        await startServer(dataHome, directory, () => response);
+        initRpcClient(directory);
+
+        expect((await loadSidebarSnapshot(sessionId, directory)).inputTokens).toBe(250);
+        response = { error: "database busy" };
+        expect((await loadSidebarSnapshot(sessionId, directory)).inputTokens).toBe(250);
+
+        response = snapshot(sessionId, 0) as unknown as Record<string, unknown>;
+        expect((await loadSidebarSnapshot(sessionId, directory)).inputTokens).toBe(0);
+        response = { error: "database busy again" };
+        expect((await loadSidebarSnapshot(sessionId, directory)).inputTokens).toBe(0);
+    });
+
+    test("distinguishes a real zero compartment count from an RPC failure", async () => {
+        const dataHome = makeDataHome();
+        const directory = "/repo-count";
+        const server = await startServer(dataHome, directory, () => ({}));
+        server.handle("compartment-count", async () => ({ count: 0 }));
+        initRpcClient(directory);
+
+        expect(await getCompartmentCount("ses_zero")).toEqual({ ok: true, count: 0 });
+        server.handle("compartment-count", async () => {
+            throw new Error("database unavailable");
+        });
+        const failed = await getCompartmentCount("ses_zero");
+        expect(failed.ok).toBe(false);
+    });
+});

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

@@ -102,7 +102,13 @@ const STICKY_MAX_ENTRIES = 100;
 const stickySidebarCache = new Map<string, CachedSnapshot>();
 
 function rememberSidebarSnapshot(snapshot: SidebarSnapshot): void {
-    if (!snapshot.sessionId || snapshot.inputTokens <= 0) return;
+    if (!snapshot.sessionId) return;
+    if (snapshot.inputTokens <= 0) {
+        // A successful zero is authoritative (new/deleted/reverted session) and
+        // must prevent a later transport failure from resurrecting old values.
+        stickySidebarCache.delete(snapshot.sessionId);
+        return;
+    }
     // LRU-style bound: drop the oldest entry once we hit the cap. With a
     // 5-min TTL most stale entries time out naturally; this just prevents
     // unbounded growth across many session switches in a long TUI session.
@@ -126,19 +132,9 @@ 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,
@@ -152,9 +148,11 @@ export async function loadSidebarSnapshot(
             directory,
         });
         if ((result as unknown as Record<string, unknown>).error) {
+            // Snapshot-build errors are explicit failure envelopes, equivalent to
+            // a transport failure: retain the last known-good client snapshot.
             return recallSidebarSnapshot(sessionId, empty);
         }
-        // Trust successful server responses. The server has its own sticky
+        // Trust successful server responses, including authoritative zeroes. The server has its own sticky
         // sidebar cache (`sidebar-snapshot-cache.ts`) that handles transient
         // zero-token windows by hybriding cached breakdown values into a
         // fresh snapshot, AND clears that cache on `session.deleted`. If the
@@ -249,14 +247,23 @@ export async function loadEmbedDetail(sessionId: string, directory: string): Pro
     }
 }
 
-/** Get compartment count via RPC. */
-export async function getCompartmentCount(sessionId: string): Promise<number> {
-    if (!rpcClient) return 0;
+export type CompartmentCountResult = { ok: true; count: number } | { ok: false; error: string };
+
+/** Get compartment count without making transport failure look like a real zero. */
+export async function getCompartmentCount(sessionId: string): Promise<CompartmentCountResult> {
+    if (!rpcClient) return { ok: false, error: "RPC client is not initialized" };
     try {
-        const result = await rpcClient.call<{ count: number }>("compartment-count", { sessionId });
-        return result.count ?? 0;
-    } catch {
-        return 0;
+        const result = await rpcClient.call<{ count?: number; error?: string }>(
+            "compartment-count",
+            { sessionId },
+        );
+        if (typeof result.error === "string") return { ok: false, error: result.error };
+        if (typeof result.count !== "number" || !Number.isFinite(result.count)) {
+            return { ok: false, error: "Invalid compartment count response" };
+        }
+        return { ok: true, count: result.count };
+    } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) };
     }
 }