@wolfx/opencode-magic-context 0.21.8-patch.1

package/src/shared/rpc-utils.ts

@@ -0,0 +1,72 @@
+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.
+ */
+export function projectHash(directory: string): string {
+    const normalized = directory.replace(/\/+$/, "");
+    return createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+}
+
+/** 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/session-messages-bounded.test.ts

@@ -0,0 +1,112 @@
+/// <reference types="bun-types" />
+
+// Regression guard: every `client.session.messages(...)` call in plugin code
+// must include `limit` in its `query`. Without `limit`, OpenCode's legacy
+// messages endpoint hydrates the ENTIRE session into RAM — catastrophic on
+// huge sessions (10k+ messages) which is exactly when Magic Context shines.
+//
+// Background: the plugin only ever needs the latest assistant message of a
+// helper subagent (historian / dreamer / sidekick / key-files / user-memory)
+// or a bounded tail of the active session (conflict-warning cleanup). Both
+// fit comfortably in `limit: 50` with massive headroom.
+//
+// If you add a new `session.messages(...)` call, this test fails until you
+// include a `limit` in the query. The test does a static source-text scan
+// so it catches the issue at lint-time without runtime mocking overhead.
+
+import { describe, expect, it } from "bun:test";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const PLUGIN_SRC = join(__dirname, "..", "..", "src");
+
+/** Recursively walk a directory and return paths of all `.ts` files
+ *  excluding `.test.ts`, `.gen.ts`, and node_modules. */
+function walkSourceFiles(dir: string, out: string[] = []): string[] {
+    for (const entry of readdirSync(dir)) {
+        if (entry === "node_modules" || entry === "dist") continue;
+        const full = join(dir, entry);
+        const s = statSync(full);
+        if (s.isDirectory()) {
+            walkSourceFiles(full, out);
+        } else if (
+            s.isFile() &&
+            entry.endsWith(".ts") &&
+            !entry.endsWith(".test.ts") &&
+            !entry.endsWith(".gen.ts")
+        ) {
+            out.push(full);
+        }
+    }
+    return out;
+}
+
+/** Find call expressions matching `session.messages(...)` and return the
+ *  source text of each call (from "session.messages(" to its matching ")"). */
+function findSessionMessagesCalls(source: string): string[] {
+    const calls: string[] = [];
+    const needle = "session.messages(";
+    let i = 0;
+    while (true) {
+        const idx = source.indexOf(needle, i);
+        if (idx === -1) break;
+        // Skip comments — if the line starts with `*` or `//` we ignore.
+        const lineStart = source.lastIndexOf("\n", idx) + 1;
+        const linePrefix = source.slice(lineStart, idx).trimStart();
+        if (linePrefix.startsWith("//") || linePrefix.startsWith("*")) {
+            i = idx + needle.length;
+            continue;
+        }
+        // Walk forward to find the matching closing paren, respecting
+        // brace/bracket/paren nesting.
+        let depth = 1;
+        let j = idx + needle.length;
+        while (j < source.length && depth > 0) {
+            const ch = source[j];
+            if (ch === "(" || ch === "{" || ch === "[") depth++;
+            else if (ch === ")" || ch === "}" || ch === "]") depth--;
+            j++;
+        }
+        if (depth === 0) {
+            calls.push(source.slice(idx, j));
+        }
+        i = j;
+    }
+    return calls;
+}
+
+describe("session.messages() callsites must include query.limit", () => {
+    const files = walkSourceFiles(PLUGIN_SRC);
+    const violations: Array<{ file: string; callText: string }> = [];
+
+    for (const file of files) {
+        // Skip the regression test itself
+        if (file.endsWith("session-messages-bounded.test.ts")) continue;
+        const source = readFileSync(file, "utf-8");
+        const calls = findSessionMessagesCalls(source);
+        for (const call of calls) {
+            // The call text spans from "session.messages(" to the closing
+            // ")". A correct call must mention `limit` (the SDK key) somewhere
+            // inside that span — typically `query: { ..., limit: N }`.
+            if (!/\blimit\b/.test(call)) {
+                violations.push({ file: file.replace(PLUGIN_SRC, "<plugin>/src"), callText: call });
+            }
+        }
+    }
+
+    it("has no unbounded session.messages() calls in plugin code", () => {
+        if (violations.length > 0) {
+            const report = violations
+                .map(
+                    (v) =>
+                        `\n  in ${v.file}:\n    ${v.callText.replace(/\n/g, "\n    ").slice(0, 300)}`,
+                )
+                .join("\n");
+            throw new Error(
+                `Found ${violations.length} unbounded session.messages() call(s). ` +
+                    `Add \`limit: 50\` (or appropriate bound) to query.${report}`,
+            );
+        }
+        expect(violations).toEqual([]);
+    });
+});

package/src/shared/sqlite-helpers.ts

@@ -0,0 +1,27 @@
+/**
+ * Cross-runtime helpers that smooth over the small bun:sqlite ↔ better-sqlite3
+ * API differences without leaking either library into call sites.
+ */
+
+import type { Database } from "./sqlite";
+
+/**
+ * Close a database, ignoring errors.
+ *
+ * bun:sqlite supports `db.close(throwOnError = false)`. better-sqlite3 has
+ * only `db.close()` and throws on already-closed databases. This helper
+ * mirrors the bun "swallow errors" semantics for both runtimes — useful in
+ * test teardown and `finally` blocks where the caller doesn't care whether
+ * the close succeeded.
+ */
+export function closeQuietly(db: Database | null | undefined): void {
+    if (!db) return;
+    // Just attempt close and swallow errors. bun:sqlite has no `open` property,
+    // and better-sqlite3 throws TypeError on already-closed databases — both
+    // are handled by the bare try/catch.
+    try {
+        db.close();
+    } catch {
+        // intentional: caller wants quiet close
+    }
+}

package/src/shared/sqlite.ts

@@ -0,0 +1,134 @@
+/**
+ * SQLite chokepoint — runtime-detected backend selection.
+ *
+ * The same shipped plugin artifact must run under two different runtimes:
+ *   - Bun (current OpenCode releases) → uses `bun:sqlite` (built-in, fast)
+ *   - Node (OpenCode beta + future Pi plugin) → uses `better-sqlite3`
+ *
+ * Bun cannot load `better-sqlite3` (oven-sh/bun#4290), and Node has no
+ * `bun:sqlite` module. Static imports of either would crash at parse time
+ * in the wrong runtime, so we use dynamic imports gated by runtime detection.
+ *
+ * The Function-constructor wrapper around `import()` defeats bundler static
+ * analysis — without it, esbuild/bun build would try to resolve both modules
+ * during the bundle step, including the one that doesn't exist in the build
+ * runtime.
+ *
+ * Both libraries expose ~95% API parity:
+ *   - new Database(path, { readonly?: boolean })
+ *   - db.prepare(sql).run/get/all
+ *   - db.exec(multistatement)
+ *   - db.transaction(fn) → wrapped function
+ *   - db.close()
+ *
+ * The 5% that differs (db.query, db.run, db.close(boolean), Database.open)
+ * is either rewritten to common-subset patterns or hidden behind the helpers
+ * in `./sqlite-helpers.ts`.
+ */
+
+// Type import only — better-sqlite3's runtime is loaded dynamically below.
+// @types/better-sqlite3 has richer definitions than @types/bun's bun:sqlite
+// types, and bun:sqlite is a structural superset for the API surface we use,
+// so calls typed against BetterSqlite3 work under both runtimes at runtime.
+import type BetterSqlite3 from "better-sqlite3";
+
+// Detect Bun via process.versions.bun. Both globalThis.Bun and
+// process.versions.bun are set by the Bun runtime, but process.versions
+// is a lower-level surface less likely to be sandboxed by host runtimes
+// (e.g. Electron in OpenCode desktop apps that re-expose a Bun-flavored
+// environment). Real Node and Electron never set this field.
+const isBun = typeof process !== "undefined" && typeof process.versions?.bun === "string";
+
+// IMPORTANT: bundler-evading dynamic imports.
+//
+// We can't write `await import("better-sqlite3")` directly because esbuild/bun
+// would try to resolve both modules at build time, and one of them won't exist
+// in the build runtime (bun:sqlite is missing in Node, better-sqlite3 isn't
+// shipped in Bun-only environments). Earlier versions used
+// `new Function("p", "return import(p)")("modname")` to defeat static
+// analysis, but that breaks Pi's vm-based extension loader: a Function
+// constructed at runtime has no module record, so `import()` inside it has
+// no referrer module and Node throws "A dynamic import callback was not
+// specified".
+//
+// The /* @vite-ignore */ + variable indirection pattern hides the specifier
+// from static analyzers while keeping a real referrer module for the
+// dynamic import — Pi's loader, esbuild, and bun build all accept it.
+const bunSpec = "bun:" + "sqlite";
+const betterSpec = "better-" + "sqlite3";
+
+// Under Electron, the npm-installed better-sqlite3 binary has the wrong ABI
+// (it's a Node prebuild but Electron embeds a different NODE_MODULE_VERSION).
+// resolveBetterSqliteNativeBinding() detects this and downloads + caches the
+// matching Electron prebuild, then returns its absolute path so we can pass
+// it to better-sqlite3 via the `nativeBinding` constructor option (a
+// documented public API). Returns null outside Electron OR when the on-disk
+// binary already matches the runtime ABI — in those cases the default
+// bindings() lookup just works.
+const electronNativeBinding = isBun
+    ? null
+    : await (async () => {
+          const mod = await import("./native-binding");
+          return mod.resolveBetterSqliteNativeBinding();
+      })();
+
+const sqliteModule = isBun
+    ? await import(/* @vite-ignore */ bunSpec)
+    : await import(/* @vite-ignore */ betterSpec);
+
+// Different export shapes between the two libraries:
+//   - bun:sqlite     → named export `Database`
+//   - better-sqlite3 → default export
+const RawDatabaseImpl = isBun ? sqliteModule.Database : sqliteModule.default;
+
+// When we resolved a non-default Electron-compatible native binding above,
+// transparently inject it into every `new Database(...)` call. This is the
+// public `nativeBinding` constructor option that better-sqlite3 ships
+// specifically for cross-runtime extension scenarios — it makes
+// better-sqlite3 `require()` the binary at the supplied path directly,
+// bypassing the default bindings() resolver.
+//
+// Subclassing keeps the call sites untouched: existing
+// `new Database(filename, { readonly: true })` invocations work as-is.
+// Callers can still override `nativeBinding` explicitly if they need to.
+//
+// The TypeScript type intentionally references @types/better-sqlite3 because
+// its definitions are richer than @types/bun's bun:sqlite types and bun:sqlite
+// is a structural superset for the API surface we use. Calls written against
+// this type work correctly under both runtimes at runtime.
+//
+// @types/better-sqlite3 uses `export = Database` (CommonJS interop), which
+// surfaces in TypeScript as `import Database = require("better-sqlite3")`.
+// We capture the DatabaseConstructor type from the namespace re-export.
+const DatabaseImpl: typeof BetterSqlite3 =
+    electronNativeBinding == null
+        ? (RawDatabaseImpl as typeof BetterSqlite3)
+        : (class DatabaseWithElectronBinding extends (RawDatabaseImpl as typeof BetterSqlite3) {
+              constructor(filename?: string | Buffer, options?: BetterSqlite3.Options) {
+                  // Type narrowing: the surrounding ternary already proved
+                  // electronNativeBinding is non-null in this branch, but
+                  // TypeScript can't follow that across the class boundary.
+                  const fallback = electronNativeBinding as string;
+                  super(filename, {
+                      ...options,
+                      nativeBinding: options?.nativeBinding ?? fallback,
+                  });
+              }
+          } as typeof BetterSqlite3);
+
+export const Database: typeof BetterSqlite3 = DatabaseImpl;
+
+/** Instance type alias used by helpers and storage modules. */
+export type Database = BetterSqlite3.Database;
+
+/**
+ * Statement instance type used for WeakMap caches throughout the codebase.
+ *
+ * We deliberately use the variadic Statement<unknown[], unknown> shape rather
+ * than `ReturnType<Database["prepare"]>` because the latter resolves through
+ * a conditional return type in @types/better-sqlite3 that confuses TypeScript
+ * about how many arguments .run/.get/.all accept. With this explicit type,
+ * cached statements accept any number of bind args (matching bun:sqlite's
+ * historical behavior in this codebase).
+ */
+export type Statement = BetterSqlite3.Statement<unknown[], unknown>;

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(",")}}`;
+}