@cortexkit/opencode-magic-context 0.24.0 → 0.25.0

package/src/shared/tag-transcript.ts

@@ -611,7 +611,7 @@ function tagToolPart(args: TagToolPartArgs): void {
         args.part.setText(tagged);
     }
 
-    args.targets.set(tagId, buildToolTarget(args.part, args.message));
+    args.targets.set(tagId, buildToolTarget(args.part, args.message, tagId));
 }
 
 function setToolContentOrText(part: TranscriptPart, content: string): boolean {
@@ -679,10 +679,11 @@ function buildAggregateTarget(tagId: number, occurrences: ToolOccurrence[]): Tag
             return any ? "removed" : "absent";
         },
         truncate(): "truncated" | "absent" {
-            // Truncate BOTH halves. For tool_use, this typically truncates
-            // the args; for tool_result, the output. The sentinel string
-            // matches OpenCode's truncate sentinel exactly.
-            const sentinel = "[truncated]";
+            // Skeleton-drop: replace BOTH halves' content with the one
+            // canonical `[dropped §N§]` placeholder (byte-identical to a full
+            // drop and to OpenCode). Frozen by the dropMode column → replays
+            // the same string every pass. The tool_use call survives intact.
+            const sentinel = `[dropped \u00a7${tagId}\u00a7]`;
             let any = false;
             for (const occ of occurrences) {
                 if (setToolContentOrText(occ.part, sentinel)) {
@@ -739,16 +740,17 @@ function buildTextTarget(
 }
 
 /**
- * TagTarget for a tag-eligible tool part. Tool parts get full-drop
- * (replace with `[dropped §N§]`) or truncated-drop (replace with
- * `[truncated]`) treatment from `applyFlushedStatuses` based on the
- * stored `drop_mode` column. We expose both via the standard target
- * surface; replaceWithSentinel is the canonical mutation, with
- * truncated-drop using the "[truncated]" string.
+ * TagTarget for a tag-eligible tool part. Tool parts get full-drop or
+ * skeleton-drop treatment from `applyFlushedStatuses` based on the stored
+ * `drop_mode` column. Both render the SAME canonical `[dropped §N§]`
+ * placeholder — full-drop replaces the whole pair, skeleton-drop keeps the
+ * tool_use call and replaces only its output. One placeholder string,
+ * byte-identical across passes and across harnesses.
  */
 function buildToolTarget(
     part: TranscriptPart,
     message: { info: { id?: string; role: string } },
+    tagId: number,
 ): TagTarget {
     return {
         setContent(content: string): boolean {
@@ -765,15 +767,15 @@ function buildToolTarget(
             // For Pi the current Transcript contract treats both
             // invocation and result parts symmetrically — both expose
             // setText / setToolOutput.
-            const replaced = part.replaceWithSentinel(`[dropped \u00a7${part.id ?? "?"}\u00a7]`);
+            const replaced = part.replaceWithSentinel(`[dropped \u00a7${tagId}\u00a7]`);
             return replaced ? "removed" : "absent";
         },
         truncate(): "truncated" | "absent" {
-            // Truncate the tool output to a fixed sentinel string. Done
-            // via setToolOutput so the underlying tool_result content
-            // gets the truncation; falls back to setText for cases
-            // where the part type doesn't support setToolOutput.
-            const ok = setToolContentOrText(part, "[truncated]");
+            // Skeleton-drop: replace the tool output with the one canonical
+            // `[dropped §N§]` placeholder (byte-identical to a full drop and to
+            // OpenCode). Frozen by the dropMode column, so it replays the same
+            // string every pass. The tool_use call itself survives intact.
+            const ok = setToolContentOrText(part, `[dropped \u00a7${tagId}\u00a7]`);
             return ok ? "truncated" : "absent";
         },
         message: {

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

@@ -0,0 +1,210 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parse } from "comment-json";
+import {
+    computeEffectiveOrder,
+    DEFAULT_PREFS,
+    DEFAULT_SLOT_ORDER,
+    getTuiPreferencesFile,
+    PLUGIN_KEY,
+    queueTuiPreferenceUpdate,
+    readTuiPreferencesFile,
+    resolveMagicContextPrefs,
+    TUI_PREFS_FILE_ENV,
+} from "./tui-preferences";
+
+let dir: string;
+let file: string;
+const savedEnv: Record<string, string | undefined> = {};
+const ENV_KEYS = [TUI_PREFS_FILE_ENV, "OPENCODE_CONFIG_DIR", "XDG_CONFIG_HOME"];
+
+beforeEach(async () => {
+    for (const key of ENV_KEYS) savedEnv[key] = process.env[key];
+    dir = await mkdtemp(join(tmpdir(), "mc-tui-prefs-test-"));
+    file = join(dir, "tui-preferences.jsonc");
+    process.env[TUI_PREFS_FILE_ENV] = file;
+});
+
+afterEach(async () => {
+    for (const key of ENV_KEYS) {
+        if (savedEnv[key] === undefined) delete process.env[key];
+        else process.env[key] = savedEnv[key];
+    }
+    await rm(dir, { recursive: true, force: true });
+});
+
+describe("getTuiPreferencesFile", () => {
+    test("env override wins", () => {
+        expect(getTuiPreferencesFile()).toBe(file);
+    });
+
+    test("falls back to OPENCODE_CONFIG_DIR then XDG then ~/.config", () => {
+        delete process.env[TUI_PREFS_FILE_ENV];
+        process.env.OPENCODE_CONFIG_DIR = "/tmp/cfgdir";
+        expect(getTuiPreferencesFile()).toBe("/tmp/cfgdir/tui-preferences.jsonc");
+        delete process.env.OPENCODE_CONFIG_DIR;
+        process.env.XDG_CONFIG_HOME = "/tmp/xdg";
+        expect(getTuiPreferencesFile()).toBe("/tmp/xdg/opencode/tui-preferences.jsonc");
+    });
+});
+
+describe("readTuiPreferencesFile (tolerant)", () => {
+    test("missing file → {}", async () => {
+        expect(await readTuiPreferencesFile()).toEqual({});
+    });
+
+    test("malformed JSON → {}", async () => {
+        await writeFile(file, "{ this is not json ", "utf8");
+        expect(await readTuiPreferencesFile()).toEqual({});
+    });
+
+    test("non-object root → {}", async () => {
+        await writeFile(file, "[1, 2, 3]", "utf8");
+        expect(await readTuiPreferencesFile()).toEqual({});
+    });
+
+    test("jsonc with comments + trailing comma parses", async () => {
+        await writeFile(
+            file,
+            `{
+  // a comment
+  "magic-context": { "order": 205, },
+}`,
+            "utf8",
+        );
+        const root = await readTuiPreferencesFile();
+        expect(resolveMagicContextPrefs(root).order).toBe(205);
+    });
+});
+
+describe("resolveMagicContextPrefs (per-key validation)", () => {
+    test("missing key → full defaults clone", () => {
+        expect(resolveMagicContextPrefs({})).toEqual(DEFAULT_PREFS);
+        // clone, not the shared object
+        expect(resolveMagicContextPrefs({})).not.toBe(DEFAULT_PREFS);
+    });
+
+    test("one bad value never poisons the rest", () => {
+        const prefs = resolveMagicContextPrefs({
+            "magic-context": {
+                order: "nope",
+                rememberCollapsed: 1,
+                collapsed: true,
+                sections: { historian: false, memory: "bad" },
+            },
+        });
+        expect(prefs.order).toBe(DEFAULT_SLOT_ORDER); // bad → default
+        expect(prefs.rememberCollapsed).toBe(true); // bad → default true
+        expect(prefs.collapsed).toBe(true); // valid bool preserved
+        expect(prefs.sections.historian).toBe(false); // valid bool preserved
+        expect(prefs.sections.memory).toBe(true); // bad → default true
+    });
+
+    test("order clamps to -10000..10000", () => {
+        expect(resolveMagicContextPrefs({ "magic-context": { order: 99999 } }).order).toBe(10000);
+        expect(resolveMagicContextPrefs({ "magic-context": { order: -99999 } }).order).toBe(-10000);
+    });
+
+    test("collapsed non-boolean → null (seed from startCollapsed)", () => {
+        expect(resolveMagicContextPrefs({ "magic-context": {} }).collapsed).toBeNull();
+    });
+
+    test("header label clamps length, empty → default", () => {
+        expect(
+            resolveMagicContextPrefs({ "magic-context": { header: { label: "" } } }).header.label,
+        ).toBe(DEFAULT_PREFS.header.label);
+        expect(
+            resolveMagicContextPrefs({
+                "magic-context": { header: { label: "x".repeat(50) } },
+            }).header.label.length,
+        ).toBe(24);
+    });
+});
+
+describe("computeEffectiveOrder (cross-plugin convention)", () => {
+    test("default when key missing", () => {
+        expect(computeEffectiveOrder({}, PLUGIN_KEY, DEFAULT_SLOT_ORDER)).toBe(DEFAULT_SLOT_ORDER);
+    });
+
+    test("explicit order clamped", () => {
+        expect(computeEffectiveOrder({ "magic-context": { order: 250 } }, PLUGIN_KEY, 200)).toBe(
+            250,
+        );
+    });
+
+    test("forceToTop sorts below FORCE_TOP_BASE by key position", () => {
+        const root = { aft: { forceToTop: true }, "magic-context": { forceToTop: true } };
+        expect(computeEffectiveOrder(root, "aft", 200)).toBe(-100000 + 0);
+        expect(computeEffectiveOrder(root, "magic-context", 200)).toBe(-100000 + 1);
+        // forced always beats any manual order (clamped band is strictly above)
+        expect(computeEffectiveOrder(root, "aft", 200)).toBeLessThan(-10000);
+    });
+});
+
+describe("write path — comment-json full round-trip", () => {
+    test("persists a nested key and reads back", async () => {
+        await queueTuiPreferenceUpdate(PLUGIN_KEY, ["collapsed"], true);
+        const prefs = resolveMagicContextPrefs(await readTuiPreferencesFile());
+        expect(prefs.collapsed).toBe(true);
+    });
+
+    test("seeds the file from the template when absent", async () => {
+        await queueTuiPreferenceUpdate(PLUGIN_KEY, ["order"], 205);
+        const text = await readFile(file, "utf8");
+        expect(text).toContain("Shared preferences for OpenCode TUI plugins");
+        expect(resolveMagicContextPrefs(await readTuiPreferencesFile()).order).toBe(205);
+    });
+
+    test("INTEROP: a sibling plugin's values AND comments survive MC writing only its key", async () => {
+        // A shared file owned partly by anthropic-auth, with comments and an
+        // appearance block MC knows nothing about. MC must touch ONLY its key.
+        await writeFile(
+            file,
+            `{
+  // anthropic-auth section — DO NOT lose this BLOCK comment
+  "anthropic-auth": {
+    "order": 160,
+    "header": { "label": "CLAUDE" },
+    // bar appearance knobs MC has no schema for
+    "appearance": { "barWidth": 10, "barFilledChar": "#" },
+    "pollMs": 2000 // INLINE trailing comment — must survive too
+  },
+  "magic-context": { "order": 200 }
+}
+`,
+            "utf8",
+        );
+
+        await queueTuiPreferenceUpdate(PLUGIN_KEY, ["collapsed"], true);
+
+        const text = await readFile(file, "utf8");
+        // sibling comments preserved — BOTH block and inline trailing
+        // (comment-json round-trips both faithfully; enforce the guarantee).
+        expect(text).toContain("anthropic-auth section — DO NOT lose this BLOCK comment");
+        expect(text).toContain("bar appearance knobs MC has no schema for");
+        expect(text).toContain("INLINE trailing comment — must survive too");
+
+        // sibling VALUES intact (incl. nested keys MC has no schema for)
+        const root = parse(text) as Record<string, Record<string, unknown>>;
+        const aa = root["anthropic-auth"] as Record<string, unknown>;
+        expect(aa.order).toBe(160);
+        expect((aa.header as Record<string, unknown>).label).toBe("CLAUDE");
+        const appearance = aa.appearance as Record<string, unknown>;
+        expect(appearance.barWidth).toBe(10);
+        expect(appearance.barFilledChar).toBe("#");
+
+        // MC's own change landed
+        expect(resolveMagicContextPrefs(root).collapsed).toBe(true);
+        expect(resolveMagicContextPrefs(root).order).toBe(200);
+    });
+
+    test("malformed existing file → write is a no-op, sibling content untouched", async () => {
+        const broken = `{ "anthropic-auth": { "order": 160 } broken `;
+        await writeFile(file, broken, "utf8");
+        await queueTuiPreferenceUpdate(PLUGIN_KEY, ["collapsed"], true);
+        // unchanged — we never clobber a file we can't safely parse
+        expect(await readFile(file, "utf8")).toBe(broken);
+    });
+});

package/src/shared/tui-preferences.ts

@@ -0,0 +1,303 @@
+import { readFileSync, watch } from "node:fs";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { parse, stringify } from "comment-json";
+
+// Shared preferences file for OpenCode TUI plugins. One top-level key per plugin
+// (short, non-integer-like name, e.g. "magic-context"). The file is OPTIONAL:
+// every reader falls back to defaults when it is missing or malformed.
+//
+// Cross-plugin convention (anthropic-auth / aft / magic-context all mirror it):
+//   - same file name + env override + lookup order,
+//   - byte-identical `computeEffectiveOrder` so the three sort consistently,
+//   - a coordinated default-order ladder (anthropic-auth 160, AFT 180, MC 200).
+//
+// MC uses `comment-json` (already a dep, Bun-safe) for the WRITE path — a full
+// parse → mutate-one-key → stringify round-trip that preserves comments and
+// sibling plugins' keys. (anthropic-auth uses jsonc-parser's surgical `modify`;
+// AFT and MC use comment-json. Both are interop-safe as long as a sibling key's
+// values AND comments survive — asserted by the interop test.)
+
+export const TUI_PREFS_FILE_ENV = "OPENCODE_TUI_PREFERENCES_FILE";
+const FILE_NAME = "tui-preferences.jsonc";
+
+export function getTuiPreferencesFile(): string {
+    const override = process.env[TUI_PREFS_FILE_ENV];
+    if (override) return override;
+    const configDir =
+        process.env.OPENCODE_CONFIG_DIR ||
+        join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "opencode");
+    return join(configDir, FILE_NAME);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// Tolerant read: a missing file, parse error, or non-object root all resolve to
+// {} so the sidebar never crashes on hand-edited content. Never throws.
+export async function readTuiPreferencesFile(): Promise<Record<string, unknown>> {
+    try {
+        const raw = await readFile(getTuiPreferencesFile(), "utf8");
+        if (raw.trim() === "") return {};
+        const root: unknown = parse(raw);
+        return isRecord(root) ? (root as Record<string, unknown>) : {};
+    } catch {
+        return {};
+    }
+}
+
+// Synchronous tolerant read — used once at slot mount to seed the initial
+// collapse state and effective order WITHOUT a frame of async flicker (the
+// sidebar must render at its final width/collapse on the very first paint).
+// Same tolerance contract as the async reader. Never throws.
+export function readTuiPreferencesFileSync(): Record<string, unknown> {
+    try {
+        const raw = readFileSync(getTuiPreferencesFile(), "utf8");
+        if (raw.trim() === "") return {};
+        const root: unknown = parse(raw);
+        return isRecord(root) ? (root as Record<string, unknown>) : {};
+    } catch {
+        return {};
+    }
+}
+
+export const PLUGIN_KEY = "magic-context";
+export const DEFAULT_SLOT_ORDER = 200;
+
+export interface MagicContextTuiPrefs {
+    forceToTop: boolean;
+    order: number;
+    startCollapsed: boolean;
+    rememberCollapsed: boolean;
+    // null = never persisted; seed the UI from `startCollapsed` instead.
+    collapsed: boolean | null;
+    header: {
+        label: string;
+    };
+    sections: {
+        historian: boolean;
+        memory: boolean;
+        status: boolean;
+        dreamer: boolean;
+        stats: boolean;
+    };
+}
+
+export type TuiSections = MagicContextTuiPrefs["sections"];
+
+export const DEFAULT_PREFS: MagicContextTuiPrefs = {
+    forceToTop: false,
+    order: DEFAULT_SLOT_ORDER,
+    startCollapsed: false,
+    rememberCollapsed: true,
+    collapsed: null,
+    header: { label: "Magic Context" },
+    sections: {
+        historian: true,
+        memory: true,
+        status: true,
+        dreamer: true,
+        stats: true,
+    },
+};
+
+function bool(value: unknown, fallback: boolean): boolean {
+    return typeof value === "boolean" ? value : fallback;
+}
+
+function int(value: unknown, fallback: number, min: number, max: number): number {
+    if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+    return Math.min(Math.max(Math.round(value), min), max);
+}
+
+function label(value: unknown, fallback: string, maxLength: number): string {
+    if (typeof value !== "string" || value.length === 0) return fallback;
+    return value.slice(0, maxLength);
+}
+
+// Per-key validation: every value is independently clamped/defaulted so one bad
+// entry never poisons the rest. Never throws. A missing/non-object MC key →
+// full defaults clone.
+export function resolveMagicContextPrefs(root: Record<string, unknown>): MagicContextTuiPrefs {
+    const entry = root[PLUGIN_KEY];
+    if (!isRecord(entry)) return structuredClone(DEFAULT_PREFS);
+
+    const d = DEFAULT_PREFS;
+    const header = isRecord(entry.header) ? entry.header : {};
+    const sections = isRecord(entry.sections) ? entry.sections : {};
+
+    return {
+        forceToTop: bool(entry.forceToTop, d.forceToTop),
+        order: int(entry.order, d.order, -10000, 10000),
+        startCollapsed: bool(entry.startCollapsed, d.startCollapsed),
+        rememberCollapsed: bool(entry.rememberCollapsed, d.rememberCollapsed),
+        collapsed: typeof entry.collapsed === "boolean" ? entry.collapsed : null,
+        header: {
+            label: label(header.label, d.header.label, 24),
+        },
+        sections: {
+            historian: bool(sections.historian, d.sections.historian),
+            memory: bool(sections.memory, d.sections.memory),
+            status: bool(sections.status, d.sections.status),
+            dreamer: bool(sections.dreamer, d.sections.dreamer),
+            stats: bool(sections.stats, d.sections.stats),
+        },
+    };
+}
+
+const FORCE_TOP_BASE = -100000;
+
+// Shared forceToTop convention — MUST stay byte-identical across anthropic-auth,
+// AFT, and magic-context or the three sort inconsistently against each other.
+// Forced plugins sort below FORCE_TOP_BASE, ordered among themselves by their
+// top-level key's position in the file, so users reprioritize by reordering
+// keys. The user-facing `order` knob clamps to -10000..10000, strictly above the
+// forced band, so a manual order can never beat forceToTop. Host slots render
+// ascending by order; OpenCode's built-ins occupy 100-500.
+//
+// Key-naming requirement: plugin keys must be non-integer-like short names (e.g.
+// "magic-context"). JS object key iteration hoists integer-like keys ("0", "42")
+// ahead of string keys, which would skew the indexOf-based ordering of forced
+// plugins. The shared convention requires non-numeric names.
+export function computeEffectiveOrder(
+    root: Record<string, unknown>,
+    pluginKey: string,
+    defaultOrder: number,
+): number {
+    const entry = root[pluginKey];
+    if (!isRecord(entry)) return defaultOrder;
+    if (entry.forceToTop === true) {
+        return FORCE_TOP_BASE + Object.keys(root).indexOf(pluginKey);
+    }
+    return int(entry.order, defaultOrder, -10000, 10000);
+}
+
+const TEMPLATE = `// Shared preferences for OpenCode TUI plugins.
+// One top-level key per plugin (short name). See each plugin's README for its
+// supported settings. This file is safe to hand-edit; plugins update individual
+// keys and preserve the rest (values and comments).
+{}
+`;
+
+type JsonValue = string | number | boolean | null;
+
+// Set a nested path on a comment-json root, creating intermediate plain objects
+// as needed. Mutating an existing leaf preserves its comments; sibling keys are
+// untouched. Returns false when the path is blocked by a non-object value.
+function setDeep(root: Record<string, unknown>, path: string[], value: JsonValue): boolean {
+    let node: Record<string, unknown> = root;
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const key = path[i];
+        const child = node[key];
+        if (child === undefined || child === null) {
+            node[key] = {};
+        } else if (!isRecord(child)) {
+            return false;
+        }
+        node = node[key] as Record<string, unknown>;
+    }
+    node[path[path.length - 1]] = value;
+    return true;
+}
+
+async function writePreference(pluginKey: string, path: string[], value: JsonValue): Promise<void> {
+    const file = getTuiPreferencesFile();
+    await mkdir(dirname(file), { recursive: true });
+    let text: string;
+    try {
+        text = await readFile(file, "utf8");
+    } catch {
+        text = "";
+    }
+    if (text.trim() === "") text = TEMPLATE;
+
+    let root: unknown;
+    try {
+        root = parse(text);
+    } catch {
+        // The shared file is currently malformed. Skip the write rather than
+        // clobber sibling plugins' keys — the user fixes the file, persistence
+        // resumes. (Collapse just won't survive restart until then.)
+        return;
+    }
+    if (!isRecord(root)) root = {};
+    if (!setDeep(root as Record<string, unknown>, [pluginKey, ...path], value)) {
+        return;
+    }
+
+    const next = `${stringify(root, null, 2)}\n`;
+    const tmp = `${file}.${process.pid}.tmp`;
+    await writeFile(tmp, next, "utf8");
+    await rename(tmp, file);
+}
+
+let writeChain: Promise<void> = Promise.resolve();
+
+// Writes are serialized on a promise chain: each update re-reads the file,
+// applies a comment-preserving edit to one property, and replaces the file
+// atomically (temp + rename in the same directory — the only safe cross-process
+// swap). Best-effort by design; preferences are never worth crashing the TUI.
+export function queueTuiPreferenceUpdate(
+    pluginKey: string,
+    path: string[],
+    value: JsonValue,
+): Promise<void> {
+    writeChain = writeChain.then(() => writePreference(pluginKey, path, value)).catch(() => {});
+    return writeChain;
+}
+
+const WATCH_DEBOUNCE_MS = 150;
+
+// Watches the DIRECTORY, not the file: editors and our own atomic writes replace
+// the file via rename, which kills file-level watchers.
+//
+// Two-stage filtering: (1) a cheap filename pre-filter on the prefs name or our
+// `.tmp`; (2) inside the debounce, re-read and compare against last-seen content
+// — the authority. Some platforms (macOS FSEvents, some inotify backends)
+// misattribute a sibling rename to the real filename, so a name filter alone
+// still produces strays; the content compare is robust against that, coalesced
+// events, and mtime granularity.
+//
+// Returns a disposer; never throws.
+export function watchTuiPreferences(onChange: () => void): () => void {
+    const file = getTuiPreferencesFile();
+    const name = basename(file);
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    let lastSeen: string | null = null;
+    // Seed asynchronously; a real change before the seed resolves still wins
+    // because the debounce re-reads fresh and compares against `lastSeen` (null
+    // → does not match → fires).
+    void readFile(file, "utf8")
+        .then((text) => {
+            if (lastSeen === null) lastSeen = text;
+        })
+        .catch(() => {});
+    try {
+        const watcher = watch(dirname(file), (_event, filename) => {
+            const isOurs =
+                filename === name ||
+                (filename?.startsWith(`${name}.`) && filename.endsWith(".tmp"));
+            if (filename != null && !isOurs) return;
+            if (timer) clearTimeout(timer);
+            timer = setTimeout(() => {
+                timer = null;
+                void readFile(file, "utf8")
+                    .catch(() => null)
+                    .then((text) => {
+                        if (text === null) return;
+                        if (text === lastSeen) return;
+                        lastSeen = text;
+                        onChange();
+                    });
+            }, WATCH_DEBOUNCE_MS);
+        });
+        return () => {
+            if (timer) clearTimeout(timer);
+            watcher.close();
+        };
+    } catch {
+        return () => {};
+    }
+}

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

@@ -5,9 +5,14 @@
 import os from "node:os";
 import path from "node:path";
 import { MagicContextRpcClient } from "../../shared/rpc-client";
-import type { RpcNotificationMessage, SidebarSnapshot, StatusDetail } from "../../shared/rpc-types";
+import type {
+    EmbedDetail,
+    RpcNotificationMessage,
+    SidebarSnapshot,
+    StatusDetail,
+} from "../../shared/rpc-types";
 
-export type { SidebarSnapshot, StatusDetail };
+export type { EmbedDetail, SidebarSnapshot, StatusDetail };
 
 let rpcClient: MagicContextRpcClient | null = null;
 let rpcGeneration = 0;
@@ -218,6 +223,33 @@ export async function loadStatusDetail(
     }
 }
 
+const EMPTY_EMBED_DETAIL: EmbedDetail = {
+    enabled: false,
+    model: "off",
+    provider: "off",
+    session: { embedded: 0, total: 0 },
+    memories: { embedded: 0, total: 0 },
+    commits: { embedded: 0, total: 0, gitEnabled: false },
+    statusText: "Embedding is off (no provider configured).",
+};
+
+/** Fetch embedding coverage status for `/ctx-embed` via RPC. */
+export async function loadEmbedDetail(sessionId: string, directory: string): Promise<EmbedDetail> {
+    if (!rpcClient) return EMPTY_EMBED_DETAIL;
+    try {
+        const result = await rpcClient.call<EmbedDetail>("embed-detail", {
+            sessionId,
+            directory,
+        });
+        if ((result as unknown as Record<string, unknown>).error) {
+            return EMPTY_EMBED_DETAIL;
+        }
+        return result;
+    } catch {
+        return EMPTY_EMBED_DETAIL;
+    }
+}
+
 /** Get compartment count via RPC. */
 export async function getCompartmentCount(sessionId: string): Promise<number> {
     if (!rpcClient) return 0;