@cortexkit/opencode-magic-context 0.15.6 → 0.16.0

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/rpc-notifications.ts

@@ -14,7 +14,11 @@ export interface RpcNotification {
 }
 
 let queue: RpcNotification[] = [];
-let tuiConnected = false;
+// Timestamp of last drain — used to detect if TUI is actively polling.
+// The TUI polls every 500ms; we consider it connected if it polled within
+// the last 3 seconds (6× the poll interval, tolerates transient delays).
+let lastDrainAt = 0;
+const TUI_CONNECTED_WINDOW_MS = 3_000;
 
 /** Push a notification for TUI to pick up via polling. */
 export function pushNotification(
@@ -30,15 +34,17 @@ export function pushNotification(
 }
 
 /** Drain and return all pending notifications atomically.
- *  Also marks TUI as connected since only TUI polls this. */
+ *  Updates lastDrainAt so isTuiConnected() reflects recent activity. */
 export function drainNotifications(): RpcNotification[] {
-    tuiConnected = true;
+    lastDrainAt = Date.now();
     const result = queue;
     queue = [];
     return result;
 }
 
-/** Whether a TUI client has connected and is polling for notifications. */
+/** Whether a TUI client is actively polling for notifications.
+ *  Returns true only if the TUI has drained within the last 3 seconds.
+ *  This prevents stale-connected state after TUI closes or disconnects. */
 export function isTuiConnected(): boolean {
-    return tuiConnected;
+    return lastDrainAt > 0 && Date.now() - lastDrainAt < TUI_CONNECTED_WINDOW_MS;
 }

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,91 @@
+/**
+ * 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`.
+ */
+
+// 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";
+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 DatabaseImpl = isBun ? sqliteModule.Database : sqliteModule.default;
+
+/**
+ * Database constructor compatible with both bun:sqlite and better-sqlite3.
+ *
+ * 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.
+ */
+import type BetterSqlite3 from "better-sqlite3";
+
+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/subagent-runner.ts

@@ -0,0 +1,206 @@
+/**
+ * Cross-harness subagent runner abstraction.
+ *
+ * Magic Context spawns three kinds of subagents — historian, dreamer, sidekick —
+ * each as a child "session" with its own model/prompt/tools. OpenCode and Pi
+ * have very different APIs for this:
+ *
+ *   - OpenCode: `client.session.create({parentID}) → client.session.prompt() →
+ *     client.session.messages() → client.session.delete()`. The plugin runs
+ *     in-process with the OpenCode server and uses its SDK client directly.
+ *
+ *   - Pi: no in-process child-session API. Instead `pi --print --mode=json`
+ *     spawns a non-interactive subprocess that emits structured JSON events
+ *     and exits when the agent loop finishes. Sessions are JSONL files on
+ *     disk, optionally addressed via `--session <path>`.
+ *
+ * The runner interface below normalizes both into the same shape so the
+ * actual subagent business logic (historian XML parsing, dreamer task loop,
+ * sidekick augmentation) can stay harness-agnostic. Each harness ships its
+ * own runner implementation; agents take a `SubagentRunner` as a dep instead
+ * of reaching for `client.session.*` directly.
+ *
+ * Step 5a (this commit) defines the contract and ships `PiSubagentRunner`.
+ * Step 5b will refactor the OpenCode-side spawn paths in
+ * `compartment-runner-historian.ts`, `dreamer/runner.ts`, and
+ * `sidekick/agent.ts` onto an `OpenCodeSubagentRunner` so both harnesses
+ * share the agent business logic instead of duplicating it. Until 5b lands,
+ * OpenCode keeps its existing direct `client.session.*` calls untouched —
+ * the runner contract is purely additive on the OpenCode side.
+ */
+
+/**
+ * Configuration for one subagent invocation.
+ *
+ * Mirrors the union of OpenCode's `session.create` + `session.prompt` body
+ * fields and Pi's `--print` CLI flags, picking the shared subset that all
+ * three subagent kinds (historian, dreamer, sidekick) actually use today.
+ *
+ * Fields:
+ * - `agent`: harness-specific agent name. OpenCode looks this up in its
+ *   agent registry (`HISTORIAN_AGENT`, `DREAMER_AGENT`, `SIDEKICK_AGENT`).
+ *   Pi has no concept of "agent name" beyond config, so this is ignored
+ *   on the Pi side and used only by `OpenCodeSubagentRunner`.
+ * - `systemPrompt`: full system prompt for this child run. Replaces (not
+ *   appends to) any harness-default system prompt.
+ * - `userMessage`: the single user-turn prompt. Subagent runs are always
+ *   one-shot — no multi-turn conversation in the child.
+ * - `model`: provider/model identifier in the canonical "provider/model"
+ *   shape (e.g. "anthropic/claude-sonnet-4-7"). Each runner is responsible
+ *   for translating to its harness's native model selection.
+ * - `fallbackModels`: ordered list of models to try if `model` fails. Both
+ *   harnesses retry on transient model failures.
+ * - `timeoutMs`: hard cap on the child run. The runner aborts the child on
+ *   exceeding this and returns `{ ok: false, reason: "timeout" }`.
+ * - `cwd`: working directory for the child. OpenCode uses this for
+ *   `query.directory`; Pi uses it as the spawn cwd so that `--cwd`-aware
+ *   tools see the right project root.
+ * - `signal`: optional AbortSignal so callers can cancel an in-flight run
+ *   (used by dreamer's lease-renewal-aborts-on-loss path).
+ */
+export interface SubagentRunOptions {
+    agent: string;
+    systemPrompt: string;
+    userMessage: string;
+    model?: string | undefined;
+    fallbackModels?: readonly string[];
+    timeoutMs?: number | undefined;
+    cwd?: string | undefined;
+    signal?: AbortSignal | undefined;
+    /**
+     * Pi only: explicit thinking level, passed as `--thinking <level>` to the
+     * Pi subprocess. OpenCode ignores this field — thinking/reasoning is
+     * controlled via `variant` in the OpenCode agent config instead.
+     *
+     * Required when the configured historian/dreamer model supports reasoning
+     * (e.g. github-copilot/gpt-5.4) because Pi's own default resolution may
+     * pick a value the provider rejects. Set to "off" to disable thinking for
+     * speed (local models), or "medium"/"high" for better quality.
+     */
+    thinkingLevel?: string | undefined;
+
+    /**
+     * Optional progress callback. The runner invokes it for milestone events
+     * during the run: spawn, first event received, terminal stop reason
+     * detected, child exit. Used by historian/dreamer/sidekick to write
+     * lifecycle entries to the magic-context.log without polluting the
+     * normal stdout stream.
+     *
+     * Implementations must be non-throwing and fast — they're called on the
+     * runner's hot path. Errors are swallowed.
+     */
+    onProgress?: (event: SubagentProgressEvent) => void;
+}
+
+/**
+ * Progress events emitted by a runner during a run. Distinct from the final
+ * `SubagentRunResult` — these are mid-run milestones plus (optionally) every
+ * raw event the underlying harness emits, so callers can write a complete
+ * trace to the log when diagnosing hangs.
+ *
+ * Categories:
+ * - `spawned` / `child_exit` / `stderr` — process lifecycle.
+ * - `first_event` — convenience: first event received from the child, useful
+ *   for measuring auth/network warmup time.
+ * - `terminal` — runner detected the final assistant turn (Pi: assistant
+ *   message_end with terminal stopReason and no toolCall; OpenCode: SDK
+ *   `agent_end` equivalent).
+ * - `raw_event` — every parsed event from the harness's structured output
+ *   stream (Pi NDJSON / OpenCode SDK events). Emitted unconditionally so
+ *   debug logs can capture the full timeline. The `event` payload is
+ *   harness-shaped — callers should treat it as `unknown` and log it raw.
+ */
+export type SubagentProgressEvent =
+    | { type: "spawned"; argv: readonly string[]; pid: number | undefined }
+    | { type: "first_event"; eventType: string; ms: number }
+    | {
+          type: "raw_event";
+          eventType: string | undefined;
+          event: unknown;
+          ms: number;
+      }
+    | {
+          type: "terminal";
+          stopReason: string | undefined;
+          textLength: number;
+          hasToolCall: boolean;
+          ms: number;
+      }
+    | { type: "stderr"; chunk: string }
+    | { type: "child_exit"; code: number | null; signal: string | null; ms: number };
+
+/**
+ * Result of one subagent invocation.
+ *
+ * The runner contract is "fail soft": transient errors, timeouts, model
+ * failures, and aborts all surface as `{ ok: false, reason }` with a
+ * machine-readable reason and a human-readable message. Throwing is
+ * reserved for programmer errors (bad arguments, missing dependencies)
+ * that the agent code couldn't have caused.
+ *
+ * Fields:
+ * - `ok`: true iff the child produced a final assistant message.
+ * - `assistantText`: concatenated text content from the final assistant
+ *   message, with leading/trailing whitespace trimmed. Empty string if the
+ *   child finished but produced no text (rare — usually means the model
+ *   only emitted tool calls and we didn't follow up).
+ * - `reason`: failure category, one of:
+ *     - `"timeout"`: hit `timeoutMs` before the child finished
+ *     - `"abort"`: caller's `signal` was triggered
+ *     - `"model_failed"`: every configured model + fallback returned an error
+ *     - `"spawn_failed"`: subprocess couldn't start (Pi only — binary missing,
+ *       permission denied, etc.)
+ *     - `"non_zero_exit"`: child exited unsuccessfully before a final answer
+ *     - `"no_assistant"`: child completed without a final assistant message
+ *     - `"parse_failed"`: child emitted output we couldn't parse (Pi only —
+ *       JSON malformed or unexpected event ordering)
+ * - `error`: human-readable detail; safe to log, may include stack info.
+ * - `durationMs`: wall-clock time from runner-call to runner-return.
+ * - `meta`: optional harness-specific debug payload. Currently unused; left
+ *   here so the OpenCode runner can surface the child session ID for log
+ *   correlation when Step 5b lands.
+ */
+export type SubagentRunResult =
+    | {
+          ok: true;
+          assistantText: string;
+          durationMs: number;
+          meta?: Record<string, unknown>;
+      }
+    | {
+          ok: false;
+          reason:
+              | "timeout"
+              | "abort"
+              | "model_failed"
+              | "spawn_failed"
+              | "non_zero_exit"
+              | "no_assistant"
+              | "parse_failed";
+          error: string;
+          durationMs: number;
+          meta?: Record<string, unknown>;
+      };
+
+/**
+ * Abstract runner contract.
+ *
+ * Each harness ships a single instance — the OpenCode plugin wires
+ * `OpenCodeSubagentRunner` and the Pi plugin wires `PiSubagentRunner` in
+ * its `extension` boot path. Agent code (historian, dreamer, sidekick)
+ * receives the runner as a dep and never reaches for harness-specific
+ * client APIs directly.
+ */
+export interface SubagentRunner {
+    /** Human-readable harness name, for logging (`"opencode"` or `"pi"`). */
+    readonly harness: string;
+
+    /**
+     * Run one subagent invocation to completion.
+     *
+     * Always resolves with a `SubagentRunResult` — never throws for
+     * runtime/transport/model failures. Throwing is reserved for caller
+     * misuse (e.g. missing required option fields).
+     */
+    run(options: SubagentRunOptions): Promise<SubagentRunResult>;
+}