@cortexkit/opencode-magic-context 0.15.7 → 0.16.0

package/src/shared/transcript-opencode.ts

@@ -0,0 +1,259 @@
+/**
+ * OpenCode adapter for the harness-agnostic transcript interface.
+ *
+ * This is a thin proxy over OpenCode's `MessageLike[]` (i.e. `{ info,
+ * parts: unknown[] }[]`) — it does NOT copy data. Mutations through
+ * `setText`/`setToolOutput`/`replaceWithSentinel` write directly into
+ * the source `parts[]` arrays, exactly as the existing OpenCode-only
+ * transform code does today. `commit()` is a no-op because OpenCode's
+ * AI SDK reads `parts[]` back from the same array we mutated.
+ *
+ * This module is the boundary that lets the rest of the transform code
+ * (which moves to use the Transcript interface in 4b.2) work both for
+ * OpenCode and Pi without branching on harness type. By the end of 4b
+ * the only OpenCode-aware code in the plugin is this file plus
+ * `messages-transform.ts`.
+ *
+ * ## Mutation contract recap
+ *
+ * Magic Context's transform mutates message parts in three ways:
+ *
+ *  1. **Tag prefix injection** — prepends `§N§ ` to text parts and
+ *     tool result outputs. Repeated tagging is idempotent because
+ *     `prependTag` strips any existing prefix first.
+ *
+ *  2. **Sentinel replacement** — when a queued drop fires, the part is
+ *     replaced with a `[dropped §N§]` or `[truncated §N§]` placeholder.
+ *     The original tag number is preserved so the agent's mental
+ *     model of "what was here" survives.
+ *
+ *  3. **Structural noise stripping** — `step-start`/`step-finish`
+ *     wrappers and similar structural metadata are replaced with empty
+ *     sentinel parts so they don't consume tag numbers or get tagged
+ *     themselves.
+ *
+ * The OpenCode adapter implements (1) and (2) by editing `part.text` /
+ * `part.state.output` in place. For (3), structural parts surface as
+ * `kind: "structural"` so callers can filter them out. Adapter does NOT
+ * itself perform stripping — that's the transform pipeline's job, called
+ * after the adapter wraps the messages.
+ *
+ * Step 4b.1 ships the adapter alone. The existing OpenCode transform
+ * code keeps using `MessageLike[]` directly until 4b.2 migrates the
+ * tagging+drops layer to use Transcript instances.
+ */
+
+import { isRecord } from "./record-type-guard";
+import type {
+    Transcript,
+    TranscriptMessage,
+    TranscriptPart,
+    TranscriptPartKind,
+} from "./transcript";
+
+/**
+ * The OpenCode `MessageLike` shape. Re-declared here to avoid a circular
+ * import with `tag-messages.ts` (which lives in the magic-context hooks
+ * tree and depends on storage). Keeping a local minimal type also makes
+ * the adapter trivially unit-testable without booting OpenCode SDK
+ * types.
+ *
+ * MUST stay structurally compatible with `tag-messages.ts MessageLike` —
+ * if that file's MessageLike adds a required field, this one needs to
+ * add it too. The build will fail loudly if the shapes diverge.
+ */
+export interface OpenCodeMessageLike {
+    info: { id?: string; role?: string; sessionID?: string };
+    parts: unknown[];
+}
+
+/**
+ * Wrap an existing `MessageLike[]` as a Transcript. Zero copies — every
+ * `TranscriptPart` returned proxies the matching entry in the source
+ * `parts` array, and mutations are reflected immediately.
+ */
+export function createOpenCodeTranscript(messages: OpenCodeMessageLike[]): Transcript {
+    const transcriptMessages: TranscriptMessage[] = messages.map((message) => ({
+        info: {
+            id: message.info.id,
+            role: message.info.role ?? "unknown",
+            sessionId: message.info.sessionID,
+        },
+        // `parts` is a getter so newly-replaced sentinels inside the
+        // underlying array are surfaced on the next read. Cheap; allocs
+        // one wrapper per part per access. Adapter callers iterate
+        // `messages` once per pass so the cost is O(parts) per pass —
+        // same as before the adapter existed.
+        get parts(): TranscriptPart[] {
+            return message.parts.map((part, index) => createOpenCodePart(message, index, part));
+        },
+    }));
+
+    return {
+        messages: transcriptMessages,
+        harness: "opencode",
+        // OpenCode reads parts back from the same `parts[]` array we
+        // mutated, so there's nothing to flush. Adapters that buffer
+        // mutations (Pi) override this.
+        commit(): void {
+            /* no-op for OpenCode */
+        },
+    };
+}
+
+/**
+ * Construct a TranscriptPart proxy over a single OpenCode part.
+ *
+ * Held by `parts` getter calls only; never cached because the underlying
+ * `parts[]` array can be mutated in place (sentinel replacement) and
+ * cached proxies would point at stale data. The constructor cost is
+ * trivial — small object literal, no allocations beyond the closure.
+ */
+function createOpenCodePart(
+    parent: OpenCodeMessageLike,
+    index: number,
+    rawPart: unknown,
+): TranscriptPart {
+    const kind = classifyOpenCodePart(rawPart);
+    const id = extractPartId(rawPart);
+
+    return {
+        kind,
+        id,
+        getText(): string | undefined {
+            return readOpenCodePartText(rawPart);
+        },
+        setText(newText: string): boolean {
+            return writeOpenCodePartText(rawPart, newText);
+        },
+        setToolOutput(newText: string): boolean {
+            return writeOpenCodeToolOutput(rawPart, newText);
+        },
+        getToolMetadata(): { toolName: string | undefined; inputByteSize: number } {
+            return readOpenCodeToolMetadata(rawPart);
+        },
+        replaceWithSentinel(sentinelText: string): boolean {
+            // Build a synthetic text part that carries the sentinel as
+            // its content. Subsequent passes see this as a normal text
+            // part with kind="text" — but the existing tagging code is
+            // idempotent and won't double-tag a part that already has
+            // the right prefix, so re-processing is safe.
+            //
+            // We DON'T preserve the original part type. Sentinels are
+            // always text — that's the contract the existing
+            // apply-operations code expects.
+            const sentinelPart = { type: "text", text: sentinelText };
+            parent.parts[index] = sentinelPart;
+            return true;
+        },
+    };
+}
+
+/** Classify part kind based on `type` field. Falls back to "unknown". */
+function classifyOpenCodePart(part: unknown): TranscriptPartKind {
+    if (!isRecord(part)) return "unknown";
+    const type = part.type;
+    if (typeof type !== "string") return "unknown";
+    switch (type) {
+        case "text":
+            return "text";
+        case "reasoning":
+            return "thinking";
+        case "tool":
+            return "tool_use";
+        case "file":
+            return "file";
+        case "image":
+            return "image";
+        case "step-start":
+        case "step-finish":
+            return "structural";
+        default:
+            return "unknown";
+    }
+}
+
+/**
+ * Extract a stable per-part identifier when present. Used by the dropped-
+ * placeholder watermark to track which sentinels are already replayed
+ * across passes.
+ */
+function extractPartId(part: unknown): string | undefined {
+    if (!isRecord(part)) return undefined;
+    if (typeof part.id === "string" && part.id.length > 0) return part.id;
+    if (typeof part.callID === "string" && part.callID.length > 0) return part.callID;
+    return undefined;
+}
+
+function readOpenCodePartText(part: unknown): string | undefined {
+    if (!isRecord(part)) return undefined;
+    if (typeof part.text === "string") return part.text;
+    if (typeof part.thinking === "string") return part.thinking;
+    if (part.type === "tool") {
+        const state = isRecord(part.state) ? part.state : null;
+        const output = state && typeof state.output === "string" ? state.output : "";
+        return output;
+    }
+    return undefined;
+}
+
+function writeOpenCodePartText(part: unknown, newText: string): boolean {
+    if (!isRecord(part)) return false;
+    const writable = part as Record<string, unknown>;
+    if (typeof writable.text === "string") {
+        if (writable.text === newText) return false;
+        writable.text = newText;
+        return true;
+    }
+    if (typeof writable.thinking === "string") {
+        if (writable.thinking === newText) return false;
+        writable.thinking = newText;
+        return true;
+    }
+    return false;
+}
+
+function writeOpenCodeToolOutput(part: unknown, newText: string): boolean {
+    if (!isRecord(part)) return false;
+    if (part.type !== "tool") return false;
+    const state = isRecord(part.state) ? (part.state as Record<string, unknown>) : null;
+    if (!state) return false;
+    if (typeof state.output !== "string") return false;
+    if (state.output === newText) return false;
+    state.output = newText;
+    return true;
+}
+
+function readOpenCodeToolMetadata(part: unknown): {
+    toolName: string | undefined;
+    inputByteSize: number;
+} {
+    if (!isRecord(part)) return { toolName: undefined, inputByteSize: 0 };
+    if (part.type !== "tool") return { toolName: undefined, inputByteSize: 0 };
+
+    // OpenCode parts use `tool` as the tool name field; some legacy
+    // shapes use `toolName` or `name`. Match all three for forward
+    // compatibility with shape evolution.
+    const toolName =
+        typeof part.tool === "string"
+            ? part.tool
+            : typeof part.toolName === "string"
+              ? part.toolName
+              : typeof part.name === "string"
+                ? part.name
+                : undefined;
+
+    const state = isRecord(part.state) ? part.state : null;
+    const input = state?.input ?? part.args ?? part.input;
+
+    let inputByteSize = 0;
+    if (input !== undefined && input !== null) {
+        try {
+            inputByteSize = JSON.stringify(input).length;
+        } catch {
+            inputByteSize = 0;
+        }
+    }
+
+    return { toolName, inputByteSize };
+}

package/src/shared/transcript.ts

@@ -0,0 +1,226 @@
+/**
+ * Harness-agnostic transcript interface.
+ *
+ * Magic Context's transform pipeline operates on messages in a specific
+ * shape: ordered messages with role-tagged parts (text, tool, reasoning,
+ * tool_result, image), where tagging, sentinel stripping, and queued-drop
+ * application MUTATE part content in-place. OpenCode's plugin transform
+ * receives a `{ info, parts: unknown[] }[]` array and the AI SDK reads
+ * those mutations directly. Pi's `pi.on("context", ...)` event delivers a
+ * `AgentMessage[]` and accepts a fully-replaced array as the result.
+ *
+ * Rather than building a bidirectional `MessageLike[] ↔ AgentMessage[]`
+ * adapter (Oracle's rejected Q1 alternative — too much round-trip
+ * complexity, double-conversion bugs), this module defines a small
+ * adapter contract that:
+ *
+ *   1. Exposes ordered messages with a *uniform* part-level mutation
+ *      surface, regardless of underlying shape.
+ *   2. Is owned by the harness — OpenCode's adapter mutates `parts[]`
+ *      directly (zero copies), Pi's adapter rebuilds an `AgentMessage[]`
+ *      from the mutated transcript only at commit time.
+ *   3. Lets the shared transform code (tagging, stripping, drops)
+ *      operate on `TranscriptPart` interface instances without caring
+ *      whether they're wrapping `Part` from `@opencode-ai/sdk` or
+ *      `TextContent | ToolCall | ThinkingContent` from `@mariozechner/pi-ai`.
+ *
+ * What this interface deliberately does NOT do:
+ *
+ * - **No data round-trip.** The transcript is a *view* over harness data;
+ *   it doesn't define a third canonical message shape. There's no JSON
+ *   serialization, no normalization to a common DTO. Round-trip-free
+ *   adapters are 10x simpler and faster.
+ *
+ * - **No mutation semantics divergence.** Both adapters expose the same
+ *   in-place mutation API (`setText`, `setOutput`, `replaceWithSentinel`).
+ *   Whether mutation flushes to the source array immediately (OpenCode)
+ *   or accumulates until `commit()` (Pi) is the adapter's concern.
+ *
+ * - **No session-storage abstraction.** Compartment storage, ordinals,
+ *   raw-history reads — those live in feature modules, not here. The
+ *   transcript only models the *current turn's* live message buffer.
+ *
+ * Step 4b.1 ships ONLY the interface and OpenCode adapter migration.
+ * Pi adapter implementation lands in 4b.2 alongside the Pi context-event
+ * wire-up, since the two are co-designed (the Pi adapter has to satisfy
+ * the same operations the tagging code calls). 4b.3 wires the Pi
+ * compartment trigger and historian invocation. 4b.4 nudges + auto-search.
+ */
+
+/** Categorical kind of a transcript part, useful for filter predicates. */
+export type TranscriptPartKind =
+    | "text"
+    | "thinking"
+    | "tool_use"
+    | "tool_result"
+    | "image"
+    | "file"
+    | "structural"
+    | "unknown";
+
+/**
+ * A single content fragment within a transcript message.
+ *
+ * The interface is intentionally narrow: it exposes the operations Magic
+ * Context's transform code performs (read kind, read text, mutate text,
+ * mutate tool output, drop, replace with sentinel) and nothing more. Each
+ * harness adapter implements these against its native part type.
+ *
+ * IMPORTANT: implementations are stateful proxies over the live source
+ * data. Calling `setText("...")` on an OpenCode part mutates the
+ * underlying `Part.text`; calling it on a Pi part flips a dirty flag and
+ * the adapter's `commit()` rebuilds the affected `AgentMessage`. Either
+ * way, the transcript code reads back consistent values via `getText()`.
+ */
+export interface TranscriptPart {
+    /** Discriminator for filter logic. Stable across mutations. */
+    readonly kind: TranscriptPartKind;
+
+    /**
+     * Best-effort identifier for cross-pass tracking. May be:
+     * - OpenCode part ID (e.g. "prt_..."), stable across passes.
+     * - Pi tool-call ID for tool_use/tool_result parts.
+     * - undefined for synthetic/structural parts.
+     *
+     * Pure parts without a stable ID return undefined and are tracked
+     * positionally within their containing message instead.
+     */
+    readonly id: string | undefined;
+
+    /**
+     * The user-/agent-visible text payload, if this part has one. Returns
+     * undefined for parts that have no text representation (image, file,
+     * structural-only). For thinking parts returns the thinking text. For
+     * tool_use returns the JSON-stringified arguments (so size accounting
+     * reflects what the model sees). For tool_result returns the
+     * concatenated text content of the result.
+     */
+    getText(): string | undefined;
+
+    /**
+     * Replace the visible text payload. Applies only to text and thinking
+     * parts; throws for kinds where mutation isn't meaningful (the caller
+     * should check `kind` first).
+     *
+     * Returns true if the underlying source data actually changed (so
+     * deduplication helpers can short-circuit). Returns false when the
+     * new text equals the existing text byte-for-byte.
+     */
+    setText(newText: string): boolean;
+
+    /**
+     * For tool_result parts: replace the text content of the result.
+     * For tool_use parts: replace JSON-serialized arguments.
+     * For everything else: throws — caller should check `kind` first.
+     */
+    setToolOutput(newText: string): boolean;
+
+    /**
+     * Tool-specific metadata exposed for tagging/drop accounting:
+     * - toolName: tool identifier (e.g. "bash", "ctx_search"). undefined
+     *   for non-tool parts.
+     * - inputByteSize: serialized argument size; used by historian
+     *   pressure projection to estimate post-drop savings.
+     *
+     * For non-tool parts both fields are undefined.
+     */
+    getToolMetadata(): { toolName: string | undefined; inputByteSize: number };
+
+    /**
+     * Replace this part with a sentinel placeholder. Sentinels look like
+     * `[dropped §N§]` or `[truncated §N§]` and survive cache-busting
+     * cycles by carrying their original tag number. Used by the
+     * apply-operations flow when a queued drop fires.
+     *
+     * Implementations replace the part *in place* in the parent message's
+     * part array. The replaced part's `kind` shifts to "structural" so
+     * subsequent transform passes don't double-process it.
+     *
+     * Returns true on success; returns false if the part can't be
+     * replaced (e.g. it's already a sentinel, or it's an image part).
+     */
+    replaceWithSentinel(sentinelText: string): boolean;
+}
+
+/**
+ * A single message in the transcript, exposing role + ordered parts.
+ *
+ * Lifetime: a TranscriptMessage is valid only within a single transform
+ * pass. Adapters do not guarantee identity across passes — callers must
+ * use `info.id` for cross-pass correlation, never the message reference.
+ */
+export interface TranscriptMessage {
+    /**
+     * Lightweight metadata exposed for tagging, sentinel persistence, and
+     * cross-pass correlation. Adapters fill these from harness-native
+     * fields:
+     *
+     * - id: provider-stable message ID (OpenCode `msg_...`, Pi entryId).
+     * - role: "user" | "assistant" | "system" | "tool" | other custom roles.
+     * - sessionId: session identifier, used to scope DB writes.
+     *
+     * IMPORTANT for Pi: Pi's `ToolResultMessage` has role "toolResult"
+     * which the OpenCode-derived transform code expects to NOT be present
+     * (OpenCode folds tool results into the next user message's parts).
+     * The Pi adapter therefore exposes tool-result messages as parts of a
+     * synthetic "user" message in the transcript view, even though the
+     * underlying Pi storage has them as separate top-level entries. This
+     * is the *only* shape normalization the adapter performs.
+     */
+    readonly info: { id?: string; role: string; sessionId?: string };
+
+    /** Ordered parts. Same ordering invariants as the underlying source. */
+    readonly parts: TranscriptPart[];
+}
+
+/**
+ * Adapter contract: everything the transform pipeline calls on a
+ * harness-specific transcript implementation.
+ *
+ * Adapters are owned by the harness adapter layer (OpenCode's
+ * messages-transform.ts, Pi's context-event handler). The shared
+ * transform code receives a Transcript and operates only through this
+ * interface — it never imports from `@opencode-ai/sdk` or
+ * `@mariozechner/pi-ai`.
+ */
+export interface Transcript {
+    /** Ordered messages in the current pass. */
+    readonly messages: TranscriptMessage[];
+
+    /**
+     * Adapter identification. Useful for:
+     * - Logging (`magic-context[opencode]` vs `magic-context[pi]`).
+     * - Per-harness behaviors gated at adapter level (e.g. opencode-only
+     *   compaction marker injection).
+     * - Test assertions confirming the right adapter ran.
+     */
+    readonly harness: "opencode" | "pi";
+
+    /**
+     * Commit accumulated mutations to the underlying source array.
+     *
+     * For OpenCode: no-op — parts are mutated directly in `Part.text`/
+     * `Part.state.output` and OpenCode reads them back from the same
+     * array, so changes are already visible.
+     *
+     * For Pi: rebuilds a new `AgentMessage[]` from the dirty messages
+     * and stores it on the adapter so `pi.on("context", ...)` can return
+     * `{ messages }` to Pi. Idempotent: calling twice is safe.
+     *
+     * Always called exactly once per pass, after the transform pipeline
+     * finishes. Adapters that don't need it implement it as a no-op.
+     */
+    commit(): void;
+}
+
+/**
+ * Sentinel marker for transcript parts that should be ignored by all
+ * downstream transform stages (tagging, drops, indexing). Adapters set
+ * this on parts that exist only as structural artifacts (e.g. OpenCode's
+ * `step-start`/`step-finish`).
+ *
+ * Exported so harness adapters can stamp it on synthetic parts they
+ * create internally and so test fixtures can construct synthetic
+ * transcripts without needing real OpenCode/Pi structures.
+ */
+export const STRUCTURAL_SENTINEL_KIND: TranscriptPartKind = "structural";

package/src/shared/tui-config.ts

@@ -12,6 +12,29 @@ import { getOpenCodeConfigPaths } from "./opencode-config-dir";
 const PLUGIN_NAME = "@cortexkit/opencode-magic-context";
 const PLUGIN_ENTRY = `${PLUGIN_NAME}@latest`;
 
+/**
+ * Detect whether a tui.json plugin entry already references magic-context, in
+ * any form. Covers:
+ *   - Bare npm name: "@cortexkit/opencode-magic-context"
+ *   - Versioned npm: "@cortexkit/opencode-magic-context@latest" / "@0.15.7" / etc.
+ *   - Local dev directory path (absolute or relative): ".../magic-context"
+ *     or ".../magic-context/packages/plugin"
+ *   - file:// URLs pointing at the same paths
+ *   - Tarball paths ending in opencode-magic-context-*.tgz
+ *
+ * Without the path/URL detection, doctor/setup auto-injection adds the npm
+ * @latest entry on top of an existing dev path, double-loading the plugin.
+ */
+function isMagicContextEntry(entry: string): boolean {
+    if (!entry) return false;
+    if (entry === PLUGIN_NAME) return true;
+    if (entry.startsWith(`${PLUGIN_NAME}@`)) return true;
+    // Local directory paths: match anywhere in the string so the setup pattern
+    // (dir-only, dir + /packages/plugin, file:// + either) all qualify.
+    if (entry.includes("opencode-magic-context")) return true;
+    return false;
+}
+
 function resolveTuiConfigPath(): string {
     const configDir = getOpenCodeConfigPaths({ binary: "opencode" }).configDir;
     const jsoncPath = join(configDir, "tui.jsonc");
@@ -40,20 +63,23 @@ export function ensureTuiPluginEntry(): boolean {
             ? config.plugin.filter((p): p is string => typeof p === "string")
             : [];
 
-        const existingIdx = plugins.findIndex(
-            (p) => p === PLUGIN_NAME || p.startsWith(`${PLUGIN_NAME}@`),
-        );
+        const existingIdx = plugins.findIndex(isMagicContextEntry);
         if (existingIdx >= 0) {
-            if (plugins[existingIdx] === PLUGIN_ENTRY) {
+            const existing = plugins[existingIdx];
+            if (existing === PLUGIN_ENTRY) {
                 return false; // Already @latest
             }
-            // Only upgrade versionless entries (bare package name) to @latest.
-            // Pinned versions (e.g. @0.8.10) are left as-is — user chose them intentionally.
-            const existing = plugins[existingIdx];
+            // Only upgrade the bare versionless npm name to @latest.
+            // Pinned versions (e.g. @0.8.10), local dev paths
+            // (~/Work/OSS/magic-context/packages/plugin), and
+            // file:// URLs are all left as-is — the user chose them
+            // intentionally and overwriting their dev-loop entry would
+            // either double-load the plugin (npm + dev) or replace
+            // their working directory pointer.
             if (existing === PLUGIN_NAME) {
                 plugins[existingIdx] = PLUGIN_ENTRY;
             } else {
-                return false; // Pinned version — don't touch
+                return false;
             }
         } else {
             plugins.push(PLUGIN_ENTRY);

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

@@ -12,8 +12,12 @@ export type { SidebarSnapshot, StatusDetail };
 let rpcClient: MagicContextRpcClient | null = null;
 
 function getStorageDir(): string {
+    // Plugin v0.16+ uses the shared cortexkit/magic-context path so OpenCode
+    // and Pi can share state. The TUI just needs to point its RPC client at
+    // the same storage directory the server plugin uses for the lock-file
+    // discovery convention.
     const dataDir = process.env.XDG_DATA_HOME ?? path.join(os.homedir(), ".local", "share");
-    return path.join(dataDir, "opencode", "storage", "plugin", "magic-context");
+    return path.join(dataDir, "cortexkit", "magic-context");
 }
 
 /** Initialize the RPC client. Call once on TUI startup. */