@wolfx/opencode-magic-context 0.28.0 → 0.30.3

package/package.json

@@ -1,79 +1,80 @@
 {
-	"name": "@wolfx/opencode-magic-context",
-	"version": "0.28.0",
-	"type": "module",
-	"description": "OpenCode plugin for Magic Context — cross-session memory and context management",
-	"main": "dist/index.js",
-	"types": "dist/index.d.ts",
-	"author": "ualtinok",
-	"license": "MIT",
-	"keywords": [
-		"opencode",
-		"plugin",
-		"context",
-		"memory",
-		"ai",
-		"llm",
-		"prompt-caching",
-		"session-history"
-	],
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/cortexkit/magic-context",
-		"directory": "packages/plugin"
-	},
-	"files": [
-		"dist",
-		"src/tui",
-		"src/shared",
-		"README.md"
-	],
-	"scripts": {
-		"build": "bun build src/index.ts --outdir dist --target node --format esm --external @opencode-ai/plugin --external bun:sqlite --external node:sqlite && tsc --emitDeclarationOnly",
-		"typecheck": "tsc --noEmit && tsc -p tsconfig.scripts.json",
-		"test": "bun test",
-		"lint": "biome check .",
-		"lint:fix": "biome check --write .",
-		"format": "biome format --write .",
-		"format:check": "biome format .",
-		"clean": "rm -rf dist",
-		"prepublishOnly": "bun run build"
-	},
-	"dependencies": {
-		"@jitl/quickjs-singlefile-cjs-release-asyncify": "0.32.0",
-		"@opencode-ai/plugin": "^1.15.13",
-		"@opencode-ai/sdk": "^1.15.13",
-		"@opentui/core": "^0.4.2",
-		"@opentui/solid": "^0.4.2",
-		"ai-tokenizer": "^1.0.6",
-		"comment-json": "^4.2.5",
-		"quickjs-emscripten": "^0.32.0",
-		"solid-js": "1.9.12",
-		"zod": "^4.1.8"
-	},
-	"devDependencies": {
-		"@biomejs/biome": "^2.4.7",
-		"@types/better-sqlite3": "^7.6.13",
-		"@types/bun": "^1.3.10",
-		"@types/node": "^22.0.0",
-		"bun-types": "^1.3.10",
-		"typescript": "^5.8.0"
-	},
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
-		},
-		"./tui": {
-			"types": "./src/tui/index.tsx",
-			"import": "./src/tui/index.tsx"
-		}
-	},
-	"oc-plugin": [
-		"server",
-		"tui"
-	],
-	"peerDependencies": {
-		"@opencode-ai/plugin": ">=1.15.0"
-	}
+  "name": "@wolfx/opencode-magic-context",
+  "version": "0.30.3",
+  "type": "module",
+  "description": "OpenCode plugin for Magic Context — cross-session memory and context management",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "author": "ualtinok",
+  "license": "MIT",
+  "keywords": [
+    "opencode",
+    "plugin",
+    "context",
+    "memory",
+    "ai",
+    "llm",
+    "prompt-caching",
+    "session-history"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cortexkit/magic-context",
+    "directory": "packages/plugin"
+  },
+  "files": [
+    "dist",
+    "src/tui",
+    "src/shared",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build src/index.ts --outdir dist --target node --format esm --external @opencode-ai/plugin --external @huggingface/transformers --external onnxruntime-web --external bun:sqlite --external node:sqlite && tsc --emitDeclarationOnly",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.scripts.json",
+    "test": "bun test",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "format:check": "biome format .",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@huggingface/transformers": "^4.1.0",
+    "@jitl/quickjs-singlefile-cjs-release-asyncify": "0.32.0",
+    "@opencode-ai/plugin": "^1.17.11",
+    "@opencode-ai/sdk": "^1.17.11",
+    "@opentui/core": "^0.4.2",
+    "@opentui/solid": "^0.4.2",
+    "ai-tokenizer": "^1.0.6",
+    "comment-json": "^5.0.0",
+    "quickjs-emscripten": "^0.32.0",
+    "solid-js": "1.9.12",
+    "zod": "^4.1.8"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.1",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/bun": "^1.3.10",
+    "@types/node": "^22.20.0",
+    "bun-types": "^1.3.10",
+    "typescript": "^5.8.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tui": {
+      "types": "./src/tui/index.tsx",
+      "import": "./src/tui/index.tsx"
+    }
+  },
+  "oc-plugin": [
+    "server",
+    "tui"
+  ],
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.15.0"
+  }
 }

package/src/shared/announcement.ts

@@ -37,15 +37,14 @@ import { getMagicContextStorageDir } from "./data-path";
  * Bump only when there are user-visible changes worth a startup dialog.
  * Does NOT need to match the published package version.
  */
-export const ANNOUNCEMENT_VERSION = "0.28.0";
+export const ANNOUNCEMENT_VERSION = "0.30.2";
 
 /**
  * Short, user-facing bullet strings. Keep each line ~80 chars or shorter so the
  * TUI dialog renders cleanly without horizontal scroll on a typical terminal.
  */
 export const ANNOUNCEMENT_FEATURES: ReadonlyArray<string> = [
-    'New \'language\' option: set a top-level 2-letter language code (e.g. "tr" or "es") and Magic Context writes its summaries, memories, and guidance in that language, while keeping all structure (tags, categories, code, paths) in English. User-level only, off by default.',
-    "The ctx_reduce reminder now reflects how much tool output is actually reclaimable, instead of escalating to 'urgent' just because you're near compaction. It also no longer suggests dropping the agent's task list or tiny status outputs.",
+    "Fixed high idle CPU from the TUI sidebar (#200): it now uses a single persistent connection to the plugin instead of polling, so an idle session no longer burns CPU.",
 ];
 
 /**

package/src/shared/commit-detection.test.ts

@@ -0,0 +1,63 @@
+/// <reference types="bun-types" />
+
+import { describe, expect, it } from "bun:test";
+import {
+    COMMIT_HASH_TEST_PATTERN,
+    COMMIT_VERB_PATTERN,
+    createCommitHashExtractPattern,
+    textMentionsRecentCommit,
+} from "./commit-detection";
+
+describe("textMentionsRecentCommit", () => {
+    it("fires on a hash + commit-action verb in the same text", () => {
+        expect(textMentionsRecentCommit("Committed abc1234 with the fix")).toBe(true);
+        expect(textMentionsRecentCommit("merged a1b2c3d into main")).toBe(true);
+        expect(textMentionsRecentCommit("rebased onto feedb4d cleanly")).toBe(true);
+        expect(textMentionsRecentCommit("cherry-picked deadbeef")).toBe(true);
+    });
+
+    it("does NOT fire on a hash alone, or the bare word 'hash'/'sha' + hex", () => {
+        expect(textMentionsRecentCommit("the value is abc1234")).toBe(false);
+        // 'hash'/'sha' are intentionally NOT commit-action verbs (parity contract).
+        expect(textMentionsRecentCommit("hash is abc1234567")).toBe(false);
+        expect(textMentionsRecentCommit("sha abc1234")).toBe(false);
+    });
+
+    it("does NOT fire on a verb alone (no hash)", () => {
+        expect(textMentionsRecentCommit("I will commit later")).toBe(false);
+    });
+
+    it("respects the 7-12 hex length bound", () => {
+        expect(textMentionsRecentCommit("committed abc12")).toBe(false); // too short
+        expect(textMentionsRecentCommit("committed abc1234567890abcdef")).toBe(false); // too long
+    });
+
+    it("does not match commit-ish words that are not commit actions", () => {
+        expect(COMMIT_VERB_PATTERN.test("commitment to abc1234")).toBe(false);
+        expect(COMMIT_VERB_PATTERN.test("a merger of abc1234")).toBe(false);
+    });
+});
+
+describe("shared regex instances are stateless across calls", () => {
+    it("COMMIT_HASH_TEST_PATTERN.test is repeatable (non-global)", () => {
+        expect(COMMIT_HASH_TEST_PATTERN.test("abc1234")).toBe(true);
+        expect(COMMIT_HASH_TEST_PATTERN.test("abc1234")).toBe(true); // no lastIndex drift
+    });
+
+    it("createCommitHashExtractPattern returns a fresh global regex each call", () => {
+        const a = createCommitHashExtractPattern();
+        const b = createCommitHashExtractPattern();
+        expect(a).not.toBe(b);
+        expect(a.global).toBe(true);
+    });
+});
+
+describe("createCommitHashExtractPattern (historian extraction)", () => {
+    it("captures backtick-wrapped and bare hashes, deduped via matchAll", () => {
+        const text = "Committed `abc1234` and def5678, also abc1234 again";
+        const found = [...text.matchAll(createCommitHashExtractPattern())].map((m) =>
+            m[1]?.toLowerCase(),
+        );
+        expect(found).toEqual(["abc1234", "def5678", "abc1234"]);
+    });
+});

package/src/shared/commit-detection.ts

@@ -0,0 +1,53 @@
+// Canonical commit-detection patterns — the SINGLE source of truth shared by:
+//   - the historian commit-cluster trigger + summary hash extraction
+//     (read-session-formatting.ts),
+//   - the OpenCode note-nudge `commit_detected` boundary (tag-messages.ts),
+//   - the Pi note-nudge detector (detect-recent-commit.ts).
+//
+// These three previously each carried their own hash/verb regexes that had
+// drifted (hash length 6 vs 7; verb sets {hash, sha} vs {merge, rebas}). Keeping
+// them here stops that drift: change the patterns once and every site follows.
+//
+// All three sites look for a short git hash AND a commit-related word in the
+// SAME assistant text part — the pairing is what keeps false positives low.
+
+/** A short git hash: 7-12 hex chars (git's default abbreviated hash is 7).
+ *  6 was too loose — more random-hex false positives. */
+const HASH_HEX = "[0-9a-f]{7,12}";
+
+/**
+ * Boolean hash test. Non-global (stateless), so this single instance is safe to
+ * reuse with `.test()` across call sites — only `/g` regexes carry `lastIndex`.
+ */
+export const COMMIT_HASH_TEST_PATTERN = new RegExp(`\\b${HASH_HEX}\\b`, "i");
+
+/**
+ * Commit-ACTION verbs, with common inflections, each fully word-boundary-anchored
+ * (so they don't match e.g. "commitment"/"merger"). Non-global → safe to share.
+ *
+ * Scope decision: this is the commit-action set the OpenCode + Pi note-nudge
+ * detectors used and pin in tests ("commit/cherry-pick/merge/rebase"). It does
+ * NOT include the bare nouns "hash"/"sha" that the historian's old hint regex
+ * carried — a parity test asserts "hash <hex>" alone must NOT count as a commit,
+ * and those nouns only ever gated a cosmetic hash-strip in historian summaries
+ * (never a trigger), so unifying to the action set is behavior-preserving where
+ * it matters.
+ */
+export const COMMIT_VERB_PATTERN =
+    /\b(?:commit(?:ted|ting|s)?|cherry-?pick(?:ed|ing|s)?|merge[ds]?|merging|rebas(?:e|ed|es|ing))\b/i;
+
+/** True when a text part mentions a commit hash in a commit context. Used by the
+ *  OpenCode + Pi note-nudge detectors. */
+export function textMentionsRecentCommit(text: string): boolean {
+    return COMMIT_HASH_TEST_PATTERN.test(text) && COMMIT_VERB_PATTERN.test(text);
+}
+
+/**
+ * Fresh `/g` capturing, backtick-aware hash pattern for the historian's
+ * extract-and-strip path (matchAll + replace). Returned as a NEW instance per
+ * call: a `/g` regex carries `lastIndex`, so handing out a fresh one is
+ * bulletproof against accidental `.exec()` reuse across callers.
+ */
+export function createCommitHashExtractPattern(): RegExp {
+    return new RegExp(`\`?\\b(${HASH_HEX})\\b\`?`, "gi");
+}

package/src/shared/data-path.test.ts

@@ -7,6 +7,7 @@ import {
     getCacheDir,
     getDataDir,
     getLegacyOpenCodeMagicContextStorageDir,
+    getMagicContextLogPath,
     getMagicContextStorageDir,
     getOpenCodeCacheDir,
     getOpenCodeStorageDir,
@@ -18,6 +19,7 @@ const savedEnv = {
     XDG_CACHE_HOME: process.env.XDG_CACHE_HOME,
     XDG_DATA_HOME: process.env.XDG_DATA_HOME,
     LOCALAPPDATA: process.env.LOCALAPPDATA,
+    MAGIC_CONTEXT_LOG_PATH: process.env.MAGIC_CONTEXT_LOG_PATH,
 };
 
 describe("data-path", () => {
@@ -25,10 +27,12 @@ describe("data-path", () => {
         process.env.XDG_CACHE_HOME = undefined;
         process.env.XDG_DATA_HOME = undefined;
         process.env.LOCALAPPDATA = undefined;
+        process.env.MAGIC_CONTEXT_LOG_PATH = undefined;
         // Bun's env handling: explicit delete for unset
         delete process.env.XDG_CACHE_HOME;
         delete process.env.XDG_DATA_HOME;
         delete process.env.LOCALAPPDATA;
+        delete process.env.MAGIC_CONTEXT_LOG_PATH;
     });
 
     afterEach(() => {
@@ -37,6 +41,9 @@ describe("data-path", () => {
         if (savedEnv.XDG_DATA_HOME !== undefined)
             process.env.XDG_DATA_HOME = savedEnv.XDG_DATA_HOME;
         if (savedEnv.LOCALAPPDATA !== undefined) process.env.LOCALAPPDATA = savedEnv.LOCALAPPDATA;
+        if (savedEnv.MAGIC_CONTEXT_LOG_PATH !== undefined)
+            process.env.MAGIC_CONTEXT_LOG_PATH = savedEnv.MAGIC_CONTEXT_LOG_PATH;
+        else delete process.env.MAGIC_CONTEXT_LOG_PATH;
     });
 
     test("getCacheDir falls back to <homedir>/.cache when XDG_CACHE_HOME is unset (all platforms)", () => {
@@ -158,6 +165,27 @@ describe("data-path", () => {
             path.join("/some/project/", ".cortexkit", "magic-context"),
         );
     });
+
+    test("getMagicContextLogPath falls back to the harness temp dir when the env override is unset", () => {
+        expect(getMagicContextLogPath("opencode")).toBe(
+            path.join(os.tmpdir(), "opencode", "magic-context", "magic-context.log"),
+        );
+        expect(getMagicContextLogPath("pi")).toBe(
+            path.join(os.tmpdir(), "pi", "magic-context", "magic-context.log"),
+        );
+    });
+
+    test("getMagicContextLogPath honors MAGIC_CONTEXT_LOG_PATH", () => {
+        process.env.MAGIC_CONTEXT_LOG_PATH = "/tmp/custom/magic-context.log";
+        expect(getMagicContextLogPath("pi")).toBe("/tmp/custom/magic-context.log");
+    });
+
+    test("getMagicContextLogPath ignores a blank MAGIC_CONTEXT_LOG_PATH", () => {
+        process.env.MAGIC_CONTEXT_LOG_PATH = "   ";
+        expect(getMagicContextLogPath("pi")).toBe(
+            path.join(os.tmpdir(), "pi", "magic-context", "magic-context.log"),
+        );
+    });
 });
 
 describe("ensureCortexKitArtifactGitignore", () => {

package/src/shared/data-path.ts

@@ -46,6 +46,11 @@ export function getMagicContextTempDir(harness: HarnessId = getHarness()): strin
  * reflected in the next flush.
  */
 export function getMagicContextLogPath(harness: HarnessId = getHarness()): string {
+    // An explicit override wins over the harness temp-dir default, so users on
+    // sandboxed/ephemeral setups (Docker, CI) can point the diagnostic log at a
+    // persistent or shared path. Blank/whitespace is treated as unset.
+    const envPath = process.env.MAGIC_CONTEXT_LOG_PATH?.trim();
+    if (envPath) return envPath;
     return path.join(getMagicContextTempDir(harness), "magic-context.log");
 }
 

package/src/shared/exit-abort-registry.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "bun:test";
+import { registerExitAbort, unregisterExitAbort } from "./exit-abort-registry";
+
+// Captured before any registration so we can isolate the ONE listener the
+// registry installs process-wide (it intentionally never removes it, mirroring
+// production, so the suite must not strip it either).
+const baseline = process.listenerCount("exit");
+
+/** The registry's single 'exit' listener (the first one added past baseline). */
+function registryListener(): () => void {
+    return process.listeners("exit").slice(baseline)[0] as () => void;
+}
+
+describe("exit-abort-registry", () => {
+    it("adds exactly ONE process exit listener no matter how many controllers register", () => {
+        registerExitAbort(new AbortController());
+        registerExitAbort(new AbortController());
+        registerExitAbort(new AbortController());
+        expect(process.listenerCount("exit") - baseline).toBe(1);
+    });
+
+    it("aborts every registered controller when the exit listener fires", () => {
+        const a = new AbortController();
+        const b = new AbortController();
+        registerExitAbort(a);
+        registerExitAbort(b);
+
+        // Invoke the registry's listener directly (emitting 'exit' would end the
+        // test process).
+        registryListener()();
+
+        expect(a.signal.aborted).toBe(true);
+        expect(b.signal.aborted).toBe(true);
+        // Still exactly one listener after firing.
+        expect(process.listenerCount("exit") - baseline).toBe(1);
+    });
+
+    it("does not abort a controller that was unregistered before exit", () => {
+        const keep = new AbortController();
+        const drop = new AbortController();
+        registerExitAbort(keep);
+        registerExitAbort(drop);
+        unregisterExitAbort(drop);
+
+        registryListener()();
+
+        expect(keep.signal.aborted).toBe(true);
+        expect(drop.signal.aborted).toBe(false);
+    });
+});

package/src/shared/exit-abort-registry.ts

@@ -0,0 +1,46 @@
+/**
+ * Process-global registry of AbortControllers to abort on process exit, backed
+ * by a SINGLE `process.once("exit")` listener no matter how many controllers
+ * register.
+ *
+ * Why this exists: the plugin factory runs once per plugin instance, and
+ * OpenCode Desktop loads many instances in one Node process (one per open
+ * project). Registering a `process.once("exit")` per instance added one listener
+ * each, so past Node's default 10-listener cap it logged a
+ * `MaxListenersExceededWarning` ("11 exit listeners added to [process]"). One
+ * module-global listener that fans out to every registered controller keeps the
+ * count at one.
+ */
+
+const controllers = new Set<AbortController>();
+let listenerRegistered = false;
+
+function abortAll(): void {
+    for (const controller of controllers) {
+        try {
+            controller.abort();
+        } catch {
+            // best-effort: the process is exiting anyway
+        }
+    }
+}
+
+/**
+ * Abort `controller` when the process exits. The underlying `process.once("exit")`
+ * listener is installed on the first call only; subsequent calls just add to the
+ * fan-out set.
+ */
+export function registerExitAbort(controller: AbortController): void {
+    controllers.add(controller);
+    if (listenerRegistered) return;
+    listenerRegistered = true;
+    process.once("exit", abortAll);
+}
+
+/**
+ * Stop tracking `controller` (e.g. when its plugin instance is disposed) so the
+ * set doesn't grow without bound as Desktop opens and closes projects.
+ */
+export function unregisterExitAbort(controller: AbortController): void {
+    controllers.delete(controller);
+}

package/src/shared/harness-provider-map.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "bun:test";
+import { piModelRefToCanonical, resolveModelRefForPi } from "./harness-provider-map";
+
+describe("harness-provider-map", () => {
+    describe("resolveModelRefForPi (canonical -> Pi, used when spawning)", () => {
+        it("maps the diverging auth-plugin providers, preserving the model id", () => {
+            expect(resolveModelRefForPi("openai/gpt-5.5")).toBe("openai-codex/gpt-5.5");
+            expect(resolveModelRefForPi("google/antigravity-gemini-3.5-flash")).toBe(
+                "google-antigravity/antigravity-gemini-3.5-flash",
+            );
+        });
+
+        it("leaves anthropic and every other provider unchanged", () => {
+            expect(resolveModelRefForPi("anthropic/claude-opus-4-8")).toBe(
+                "anthropic/claude-opus-4-8",
+            );
+            expect(resolveModelRefForPi("cerebras/gpt-oss-120b")).toBe("cerebras/gpt-oss-120b");
+            expect(resolveModelRefForPi("openrouter/openai/gpt-5.5")).toBe(
+                "openrouter/openai/gpt-5.5",
+            );
+        });
+
+        it("is idempotent: a config already in Pi form still resolves to Pi form", () => {
+            expect(resolveModelRefForPi("openai-codex/gpt-5.5")).toBe("openai-codex/gpt-5.5");
+            expect(resolveModelRefForPi("google-antigravity/antigravity-gemini-3.1-pro")).toBe(
+                "google-antigravity/antigravity-gemini-3.1-pro",
+            );
+        });
+
+        it("preserves model ids that themselves contain slashes", () => {
+            expect(resolveModelRefForPi("openai/some/nested/id")).toBe(
+                "openai-codex/some/nested/id",
+            );
+        });
+
+        it("passes through malformed refs (no slash, empty provider) unchanged", () => {
+            expect(resolveModelRefForPi("gpt-5.5")).toBe("gpt-5.5");
+            expect(resolveModelRefForPi("/gpt-5.5")).toBe("/gpt-5.5");
+            expect(resolveModelRefForPi("")).toBe("");
+        });
+    });
+
+    describe("piModelRefToCanonical (Pi -> canonical, used by Pi setup write)", () => {
+        it("normalizes Pi-native provider ids to the OpenCode form", () => {
+            expect(piModelRefToCanonical("openai-codex/gpt-5.5")).toBe("openai/gpt-5.5");
+            expect(piModelRefToCanonical("google-antigravity/antigravity-gemini-3.5-flash")).toBe(
+                "google/antigravity-gemini-3.5-flash",
+            );
+        });
+
+        it("leaves already-canonical and unmapped providers unchanged", () => {
+            expect(piModelRefToCanonical("anthropic/claude-opus-4-8")).toBe(
+                "anthropic/claude-opus-4-8",
+            );
+            expect(piModelRefToCanonical("openai/gpt-5.5")).toBe("openai/gpt-5.5");
+        });
+
+        it("round-trips with resolveModelRefForPi", () => {
+            const piForm = "openai-codex/gpt-5.5";
+            expect(resolveModelRefForPi(piModelRefToCanonical(piForm))).toBe(piForm);
+        });
+    });
+});

package/src/shared/harness-provider-map.ts

@@ -0,0 +1,56 @@
+/**
+ * Provider-id translation between the canonical (OpenCode) form stored in the
+ * shared magic-context config and Pi's harness-native provider ids.
+ *
+ * OpenCode and Pi now share ONE config, but a few auth-plugin providers were
+ * named differently on each side. The model id AFTER the slash is identical;
+ * only the provider prefix differs:
+ *
+ *   canonical (OpenCode)   Pi
+ *   --------------------   -------------------
+ *   openai/<model>         openai-codex/<model>
+ *   google/<model>         google-antigravity/<model>
+ *   anthropic/<model>      anthropic/<model>      (same; every other provider too)
+ *
+ * Canonical = OpenCode: the config always stores the OpenCode form. Pi
+ * translates at its edges:
+ *   - read:  canonical -> Pi when spawning a configured model (subagent-runner).
+ *   - write: Pi -> canonical in the Pi setup wizard, so a config written from
+ *            the Pi side stays readable by OpenCode.
+ *
+ * OpenCode needs no translation (canonical IS the OpenCode form).
+ */
+
+const CANONICAL_TO_PI_PROVIDER: Record<string, string> = {
+    openai: "openai-codex",
+    google: "google-antigravity",
+};
+
+const PI_TO_CANONICAL_PROVIDER: Record<string, string> = {
+    "openai-codex": "openai",
+    "google-antigravity": "google",
+};
+
+/** Remap only the provider prefix (text before the first "/"), preserving the
+ *  model id verbatim. No "/", empty provider, or unmapped provider -> unchanged. */
+function remapProviderPrefix(ref: string, map: Record<string, string>): string {
+    if (typeof ref !== "string") return ref;
+    const slash = ref.indexOf("/");
+    if (slash <= 0) return ref;
+    const provider = ref.slice(0, slash);
+    const mapped = map[provider];
+    return mapped ? `${mapped}${ref.slice(slash)}` : ref;
+}
+
+/** Pi-native `provider/model` -> canonical (OpenCode). Identity when unmapped.
+ *  Used by the Pi setup wizard so configs it writes stay OpenCode-readable. */
+export function piModelRefToCanonical(ref: string): string {
+    return remapProviderPrefix(ref, PI_TO_CANONICAL_PROVIDER);
+}
+
+/** Canonical (OpenCode) `provider/model` -> Pi-native, for spawning a model on
+ *  Pi. Idempotent: normalizes any Pi-form prefix back to canonical first, so it
+ *  is safe on a config that already holds Pi-form ids (hand-edited or pre-fix). */
+export function resolveModelRefForPi(ref: string): string {
+    return remapProviderPrefix(piModelRefToCanonical(ref), CANONICAL_TO_PI_PROVIDER);
+}

package/src/shared/rpc-client.ts

@@ -97,6 +97,20 @@ export class MagicContextRpcClient {
         }
     }
 
+    /** 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 } | null> {
+        try {
+            const port = await this.resolvePort();
+            if (port === null) return null;
+            return { port, token: this.token };
+        } catch {
+            return null;
+        }
+    }
+
     private async resolvePort(): Promise<number | null> {
         if (this.port && this.healthChecked) {
             return this.port;