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

package/src/shared/error-message.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "bun:test";
+import { describeError, getErrorMessage } from "./error-message";
+
+describe("describeError", () => {
+    it("extracts name and message from standard Error", () => {
+        const err = new TypeError("boom");
+        const desc = describeError(err);
+        expect(desc.name).toBe("TypeError");
+        expect(desc.message).toBe("boom");
+        expect(desc.brief).toContain("TypeError");
+        expect(desc.brief).toContain('message="boom"');
+    });
+
+    it("surfaces class name when message is empty (NotFoundError case)", () => {
+        class NotFoundError extends Error {
+            constructor() {
+                super("");
+                this.name = "NotFoundError";
+            }
+        }
+        const err = new NotFoundError();
+        const desc = describeError(err);
+        expect(desc.name).toBe("NotFoundError");
+        expect(desc.message).toBe("");
+        // brief must still carry a useful signal even with empty message
+        expect(desc.brief).toContain("NotFoundError");
+    });
+
+    it("falls back to constructor.name when .name is missing", () => {
+        // Simulate an SDK-shaped object where .name is an empty string
+        const err = Object.assign(new Error("x"), { name: "" });
+        const desc = describeError(err);
+        // Falls back to constructor.name ("Error")
+        expect(desc.name).toBe("Error");
+    });
+
+    it("extracts status/code fields from HTTP-style errors", () => {
+        const err = Object.assign(new Error("not found"), {
+            status: 404,
+            code: "ENOTFOUND",
+        });
+        const desc = describeError(err);
+        expect(desc.status).toBe("404");
+        expect(desc.code).toBe("ENOTFOUND");
+        expect(desc.brief).toContain("status=404");
+        expect(desc.brief).toContain("code=ENOTFOUND");
+    });
+
+    it("captures first stack frames in stackHead", () => {
+        const err = new Error("with stack");
+        const desc = describeError(err);
+        expect(desc.stackHead).toBeDefined();
+        expect(desc.stackHead?.length).toBeGreaterThan(0);
+    });
+
+    it("handles non-Error thrown values", () => {
+        const desc = describeError("plain string");
+        expect(desc.brief).toContain("plain string");
+        expect(desc.stringForm).toContain("plain string");
+    });
+
+    it("handles objects without .message", () => {
+        const desc = describeError({ name: "WeirdError" });
+        expect(desc.name).toBe("WeirdError");
+        expect(desc.message).toBe("");
+        expect(desc.brief).toContain("WeirdError");
+    });
+
+    it("handles undefined/null", () => {
+        expect(describeError(undefined).brief).toBeTruthy();
+        expect(describeError(null).brief).toBeTruthy();
+    });
+
+    it("surfaces cause name when present", () => {
+        const cause = new TypeError("inner");
+        const outer = new Error("outer");
+        (outer as unknown as { cause: unknown }).cause = cause;
+        const desc = describeError(outer);
+        expect(desc.causeName).toBe("TypeError");
+        expect(desc.brief).toContain("cause=TypeError");
+    });
+
+    it("clips very long messages in brief", () => {
+        const long = "x".repeat(1000);
+        const err = new Error(long);
+        const desc = describeError(err);
+        expect(desc.brief.length).toBeLessThan(500);
+    });
+
+    it("getErrorMessage still works as before", () => {
+        expect(getErrorMessage(new Error("foo"))).toBe("foo");
+        expect(getErrorMessage("bar")).toBe("bar");
+    });
+});

package/src/shared/error-message.ts

@@ -0,0 +1,115 @@
+export function getErrorMessage(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Produce a rich, safe-to-log description of any thrown value.
+ *
+ * Motivated by SDK errors whose `.message` is empty while `.name`/`toString()`
+ * carry the actual signal (e.g. `NotFoundError` with no message on OpenCode
+ * session-delete races). Using {@link getErrorMessage} alone erases that signal.
+ *
+ * Captures:
+ * - `name` from the Error (defaults to `constructor.name`)
+ * - `message` (may be empty)
+ * - first few stack frames
+ * - `String(error)` so objects and custom toString surfaces are visible
+ * - Common HTTP-shape fields (`status`, `statusCode`, `code`)
+ * - `cause` chain summary (first level only)
+ *
+ * Returns a compact, single-line-friendly string suitable for log lines,
+ * plus a structured object for callers that want individual fields.
+ */
+export interface ErrorDescription {
+    name: string;
+    message: string;
+    status?: string;
+    code?: string;
+    causeName?: string;
+    stackHead?: string;
+    stringForm: string;
+    /** Best short summary for human-readable logs. Never empty. */
+    brief: string;
+}
+
+function readString(value: unknown): string | undefined {
+    if (typeof value === "string" && value.length > 0) return value;
+    if (typeof value === "number") return String(value);
+    return undefined;
+}
+
+function clip(value: string, max: number): string {
+    if (value.length <= max) return value;
+    return `${value.slice(0, max)}…`;
+}
+
+export function describeError(error: unknown): ErrorDescription {
+    const stringForm = clip(safeString(error), 400);
+
+    if (!(error instanceof Error) && !(error && typeof error === "object")) {
+        return {
+            name: typeof error,
+            message: "",
+            stringForm,
+            brief: stringForm || "<empty>",
+        };
+    }
+
+    const obj = error as Record<string, unknown>;
+    const nameFromField = readString(obj.name);
+    const nameFromCtor = error?.constructor?.name;
+    const name = nameFromField ?? nameFromCtor ?? "Error";
+
+    const message = readString(obj.message) ?? "";
+    const status = readString(obj.status) ?? readString(obj.statusCode);
+    const code = readString(obj.code);
+
+    let causeName: string | undefined;
+    const cause = obj.cause;
+    if (cause && typeof cause === "object") {
+        const causeRecord = cause as Record<string, unknown>;
+        causeName =
+            readString(causeRecord.name) ??
+            (cause as { constructor?: { name?: string } }).constructor?.name;
+    }
+
+    const stack = readString(obj.stack);
+    const stackHead = stack
+        ? stack
+              .split("\n")
+              .slice(0, 4)
+              .map((l) => l.trim())
+              .filter((l) => l.length > 0)
+              .join(" | ")
+        : undefined;
+
+    const briefParts: string[] = [];
+    if (name) briefParts.push(name);
+    if (message) briefParts.push(`message="${clip(message, 200)}"`);
+    if (status) briefParts.push(`status=${status}`);
+    if (code) briefParts.push(`code=${code}`);
+    if (causeName) briefParts.push(`cause=${causeName}`);
+    if (!message && stringForm && stringForm !== name) {
+        briefParts.push(`str="${clip(stringForm, 200)}"`);
+    }
+    const brief = briefParts.join(" ") || stringForm || name;
+
+    return {
+        name,
+        message,
+        ...(status ? { status } : {}),
+        ...(code ? { code } : {}),
+        ...(causeName ? { causeName } : {}),
+        ...(stackHead ? { stackHead } : {}),
+        stringForm,
+        brief,
+    };
+}
+
+function safeString(value: unknown): string {
+    try {
+        return String(value);
+    } catch {
+        return "<unstringifiable>";
+    }
+}

package/src/shared/format-bytes.ts

@@ -0,0 +1,5 @@
+export function formatBytes(bytes: number): string {
+    if (bytes < 1024) return `${bytes}B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}

package/src/shared/format-threshold.ts

@@ -0,0 +1,28 @@
+/**
+ * Format an execute-threshold percentage for human-facing display.
+ *
+ * `executeThreshold` in the snapshot is always a percentage number, but it
+ * comes from two very different config paths:
+ *   1. `execute_threshold_percentage` (or its model-keyed variant) — user
+ *      configures an integer like 65 directly. We must render exactly that.
+ *   2. `execute_threshold_tokens` — user configures absolute token cap (e.g.
+ *      128000). The resolver in `event-resolvers.ts` divides that by the
+ *      model's context limit (`(128000 / 907788) * 100`) and the result is
+ *      a long float like `14.099783080260304` that overflows the TUI cell
+ *      (issue #90).
+ *
+ * Behaviour:
+ *   - Integer input (≤0.05 fractional drift) renders without decimals.
+ *   - Anything else is rendered with one decimal digit, which is precise
+ *     enough to convey the configured token budget without smearing across
+ *     two lines in a narrow sidebar.
+ *
+ * Returns the formatted percentage WITHOUT the trailing `%` so callers can
+ * compose richer strings like `47.5% / 65%` consistently.
+ */
+export function formatThresholdPercent(value: number | undefined | null): string {
+    if (typeof value !== "number" || !Number.isFinite(value)) return "—";
+    const rounded = Math.round(value);
+    if (Math.abs(value - rounded) < 0.05) return String(rounded);
+    return value.toFixed(1);
+}

package/src/shared/harness.ts

@@ -0,0 +1,61 @@
+/**
+ * Identifier for the host harness this plugin is running inside.
+ *
+ * Magic Context's SQLite database lives at a vendor-scoped path
+ * (`~/.local/share/cortexkit/magic-context/`) so OpenCode and Pi can share
+ * project memories, embedding cache, dreamer runs, and other project-scoped
+ * state. Session-scoped tables carry a `harness` column populated from this
+ * module so we can disambiguate which harness wrote each session row,
+ * filter by harness in the dashboard, and (eventually) migrate sessions
+ * between harnesses.
+ *
+ * Each plugin entry point sets this once at boot, before any DB write
+ * happens:
+ * - OpenCode plugin: relies on the default ("opencode") — no setHarness call
+ *   needed
+ * - Pi plugin: calls `setHarness("pi")` before opening the database
+ *
+ * NEVER read this from configuration or session state — it is a
+ * boot-time constant per plugin instance. Cross-harness leakage is a
+ * correctness bug, not a feature.
+ */
+export type HarnessId = "opencode" | "pi";
+
+let currentHarness: HarnessId = "opencode";
+let harnessLocked = false;
+
+/**
+ * Set the harness identifier for this plugin instance. Must be called once
+ * at boot before any DB write happens. Subsequent calls with a different
+ * value throw to prevent accidental mid-session swaps that would corrupt
+ * the harness column and break per-harness session scoping.
+ *
+ * Calling with the same value as the current is a no-op (safe to call
+ * defensively).
+ */
+export function setHarness(value: HarnessId): void {
+    if (harnessLocked && currentHarness !== value) {
+        throw new Error(
+            `Magic Context: harness already locked to "${currentHarness}"; cannot change to "${value}"`,
+        );
+    }
+    currentHarness = value;
+    harnessLocked = true;
+}
+
+/**
+ * Get the current harness identifier. Used by storage modules when
+ * INSERTing session-scoped rows so each row is correctly attributed.
+ */
+export function getHarness(): HarnessId {
+    return currentHarness;
+}
+
+/**
+ * Test-only helper to reset harness state between test cases. Do NOT call
+ * from production code paths.
+ */
+export function _resetHarnessForTesting(): void {
+    currentHarness = "opencode";
+    harnessLocked = false;
+}

package/src/shared/index.ts

@@ -0,0 +1,5 @@
+export * from "./logger";
+export * from "./model-requirements";
+export * from "./model-suggestion-retry";
+export * from "./normalize-sdk-response";
+export * from "./resolve-fallbacks";

package/src/shared/internal-initiator-marker.ts

@@ -0,0 +1 @@
+export const OMO_INTERNAL_INITIATOR_MARKER = "<!-- OMO_INTERNAL_INITIATOR -->";

package/src/shared/jsonc-parser.ts

@@ -0,0 +1,138 @@
+import { existsSync, readFileSync } from "node:fs";
+
+export function stripJsonComments(content: string): string {
+    let result = "";
+    let inString = false;
+    let escaped = false;
+    let inLineComment = false;
+    let inBlockComment = false;
+
+    for (let index = 0; index < content.length; index += 1) {
+        const char = content[index];
+        const next = content[index + 1];
+
+        if (inLineComment) {
+            if (char === "\n") {
+                inLineComment = false;
+                result += char;
+            }
+            continue;
+        }
+
+        if (inBlockComment) {
+            if (char === "*" && next === "/") {
+                inBlockComment = false;
+                index += 1;
+            }
+            continue;
+        }
+
+        if (inString) {
+            result += char;
+            if (escaped) {
+                escaped = false;
+            } else if (char === "\\") {
+                escaped = true;
+            } else if (char === '"') {
+                inString = false;
+            }
+            continue;
+        }
+
+        if (char === '"') {
+            inString = true;
+            result += char;
+            continue;
+        }
+
+        if (char === "/" && next === "/") {
+            inLineComment = true;
+            index += 1;
+            continue;
+        }
+
+        if (char === "/" && next === "*") {
+            inBlockComment = true;
+            index += 1;
+            continue;
+        }
+
+        result += char;
+    }
+
+    return result;
+}
+
+function stripTrailingCommas(content: string): string {
+    let result = "";
+    let inString = false;
+    let escaped = false;
+
+    for (let index = 0; index < content.length; index += 1) {
+        const char = content[index];
+
+        if (inString) {
+            result += char;
+            if (escaped) {
+                escaped = false;
+            } else if (char === "\\") {
+                escaped = true;
+            } else if (char === '"') {
+                inString = false;
+            }
+            continue;
+        }
+
+        if (char === '"') {
+            inString = true;
+            result += char;
+            continue;
+        }
+
+        if (char === ",") {
+            let lookahead = index + 1;
+            while (lookahead < content.length && /\s/.test(content[lookahead] ?? "")) {
+                lookahead += 1;
+            }
+            const next = content[lookahead];
+            if (next === "}" || next === "]") {
+                continue;
+            }
+        }
+
+        result += char;
+    }
+
+    return result;
+}
+
+export function parseJsonc<T = unknown>(content: string): T {
+    const normalized = stripTrailingCommas(stripJsonComments(content));
+    return JSON.parse(normalized) as T;
+}
+
+export function readJsoncFile<T = unknown>(filePath: string): T | null {
+    try {
+        return parseJsonc<T>(readFileSync(filePath, "utf-8"));
+    } catch (_error) {
+        return null;
+    }
+}
+
+export function detectConfigFile(basePath: string): {
+    format: "json" | "jsonc" | "none";
+    path: string;
+} {
+    const jsoncPath = `${basePath}.jsonc`;
+    const jsonPath = `${basePath}.json`;
+
+    if (existsSync(jsoncPath)) {
+        return { format: "jsonc", path: jsoncPath };
+    }
+
+    if (existsSync(jsonPath)) {
+        return { format: "json", path: jsonPath };
+    }
+
+    return { format: "none", path: jsoncPath };
+}

package/src/shared/logger.ts

@@ -0,0 +1,94 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getMagicContextLogPath } from "./data-path";
+
+const isTestEnv = process.env.NODE_ENV === "test";
+
+let buffer: string[] = [];
+let flushTimer: ReturnType<typeof setTimeout> | null = null;
+const FLUSH_INTERVAL_MS = 500;
+const BUFFER_SIZE_LIMIT = 50;
+
+// Cache the last log directory we mkdir'd successfully so we only retry the
+// filesystem call when the resolved path actually changes. The path is
+// re-evaluated on every flush because `setHarness("pi")` runs after module
+// load on Pi; we MUST NOT freeze it at import time, or Pi's first flush
+// could land in the OpenCode subtree.
+let lastEnsuredDir: string | null = null;
+
+function ensureDir(filePath: string): void {
+    const dir = path.dirname(filePath);
+    if (dir === lastEnsuredDir) return;
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        lastEnsuredDir = dir;
+    } catch {
+        // Intentional: logging must never throw. If mkdir fails we still
+        // try the append; failure there is also swallowed.
+    }
+}
+
+function flush(): void {
+    if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+    }
+    if (buffer.length === 0) return;
+    const data = buffer.join("");
+    buffer = [];
+    try {
+        const logFile = getMagicContextLogPath();
+        ensureDir(logFile);
+        fs.appendFileSync(logFile, data);
+    } catch {
+        // Intentional: logging must never throw
+    }
+}
+
+function scheduleFlush(): void {
+    if (flushTimer) return;
+    flushTimer = setTimeout(() => {
+        flushTimer = null;
+        flush();
+    }, FLUSH_INTERVAL_MS);
+}
+
+export function log(message: string, data?: unknown): void {
+    if (isTestEnv) return;
+    try {
+        const timestamp = new Date().toISOString();
+        const serialized =
+            data === undefined
+                ? ""
+                : data instanceof Error
+                  ? ` ${data.message}${data.stack ? `\n${data.stack}` : ""}`
+                  : ` ${JSON.stringify(data)}`;
+        buffer.push(`[${timestamp}] ${message}${serialized}\n`);
+        if (buffer.length >= BUFFER_SIZE_LIMIT) {
+            flush();
+        } else {
+            scheduleFlush();
+        }
+    } catch {
+        // Intentional: logging must never throw
+    }
+}
+
+export function sessionLog(sessionId: string, message: string, data?: unknown): void {
+    log(`[magic-context][${sessionId}] ${message}`, data);
+}
+
+/**
+ * Resolve the current log file path. The path is harness-aware (see
+ * {@link getMagicContextLogPath}) and re-evaluated on every call, so callers
+ * who format diagnostic output with this value always see the path the next
+ * flush will actually use.
+ */
+export function getLogFilePath(): string {
+    return getMagicContextLogPath();
+}
+
+// Flush remaining buffer on process exit
+if (!isTestEnv) {
+    process.on("exit", flush);
+}

package/src/shared/model-requirements.ts

@@ -0,0 +1,86 @@
+import { DREAMER_AGENT } from "../agents/dreamer";
+import { HISTORIAN_AGENT, HISTORIAN_EDITOR_AGENT } from "../agents/historian";
+import { SIDEKICK_AGENT } from "../agents/sidekick";
+
+/**
+ * Provider-agnostic fallback chain entry.
+ * Each entry specifies a model and the providers to try in priority order.
+ * Follows oh-my-opencode's FallbackEntry pattern — `opencode` acts as a
+ * catch-all proxy provider and is listed last in most entries.
+ */
+export type FallbackEntry = {
+    providers: string[];
+    model: string;
+    variant?: string;
+};
+
+export type AgentModelRequirement = {
+    fallbackChain: FallbackEntry[];
+};
+
+// Historian: quality matters, single long prompt.
+// Copilot first (request-based pricing, ideal for single-prompt background work).
+const HISTORIAN_FALLBACK_CHAIN: FallbackEntry[] = [
+    { providers: ["github-copilot", "anthropic", "opencode"], model: "claude-sonnet-4-6" },
+    { providers: ["opencode-go"], model: "minimax-m2.7" },
+    {
+        providers: ["zai-coding-plan", "bailian-coding-plan", "opencode-go", "opencode"],
+        model: "glm-5",
+    },
+    { providers: ["openai", "github-copilot", "opencode"], model: "gpt-5.4" },
+    { providers: ["google", "github-copilot", "opencode"], model: "gemini-3.1-pro" },
+];
+
+// Dreamer: runs overnight during idle time, can be slow.
+// Copilot first (request-based pricing). Local models also work well here.
+const DREAMER_FALLBACK_CHAIN: FallbackEntry[] = [
+    { providers: ["github-copilot", "anthropic", "opencode"], model: "claude-sonnet-4-6" },
+    { providers: ["google", "github-copilot", "opencode"], model: "gemini-3-flash" },
+    {
+        providers: ["zai-coding-plan", "bailian-coding-plan", "opencode-go", "opencode"],
+        model: "glm-5",
+    },
+    { providers: ["opencode-go"], model: "minimax-m2.7" },
+    { providers: ["github-copilot", "openai", "opencode"], model: "gpt-5.4-mini" },
+];
+
+// Sidekick: speed is critical — fast inference providers first.
+// No Copilot preference (low token count, request-based pricing doesn't help).
+const SIDEKICK_FALLBACK_CHAIN: FallbackEntry[] = [
+    { providers: ["cerebras"], model: "qwen-3-235b-a22b-instruct-2507" },
+    { providers: ["google", "github-copilot", "opencode"], model: "gemini-3-flash" },
+    { providers: ["openai", "github-copilot", "opencode"], model: "gpt-5.4-mini" },
+    { providers: ["opencode"], model: "gpt-5-nano" },
+];
+
+export const AGENT_MODEL_REQUIREMENTS: Record<string, AgentModelRequirement> = {
+    [HISTORIAN_AGENT]: { fallbackChain: HISTORIAN_FALLBACK_CHAIN },
+    // Editor reuses historian's fallback chain — same input profile (long single prompt).
+    [HISTORIAN_EDITOR_AGENT]: { fallbackChain: HISTORIAN_FALLBACK_CHAIN },
+    [DREAMER_AGENT]: { fallbackChain: DREAMER_FALLBACK_CHAIN },
+    [SIDEKICK_AGENT]: { fallbackChain: SIDEKICK_FALLBACK_CHAIN },
+};
+
+/**
+ * Expand a provider-agnostic fallback chain into a flat `provider/model` list
+ * that OpenCode's agent config accepts as `fallback_models`.
+ */
+export function expandFallbackChain(chain: FallbackEntry[]): string[] {
+    const models: string[] = [];
+    for (const entry of chain) {
+        for (const provider of entry.providers) {
+            models.push(`${provider}/${entry.model}`);
+        }
+    }
+    return models;
+}
+
+/**
+ * Get the expanded fallback_models list for an agent.
+ * Returns undefined if no requirement is defined.
+ */
+export function getAgentFallbackModels(agent: string): string[] | undefined {
+    const requirement = AGENT_MODEL_REQUIREMENTS[agent];
+    if (!requirement) return undefined;
+    return expandFallbackChain(requirement.fallbackChain);
+}