@cortexkit/opencode-magic-context 0.15.7 → 0.16.0

package/dist/plugin/hooks/create-session-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-session-hooks.d.ts","sourceRoot":"","sources":["../../../src/plugin/hooks/create-session-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAU7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACrC,GAAG,EAAE,aAAa,CAAC;IACnB,YAAY,EAAE,wBAAwB,CAAC;IACvC,gBAAgB,EAAE,gBAAgB,CAAC;CACtC;;;;;;qBAmDu0E,CAAC;;;;;;;;;;;;qBAAqd,CAAC;mBAAyB,CAAC;iBAAuB,CAAC;iBAAuB,CAAC;0BAAc,CAAC;uBAAiB,CAAC;;;;;;0BAAi+mB,CAAC;;;;;;EAD32sB"}
+{"version":3,"file":"create-session-hooks.d.ts","sourceRoot":"","sources":["../../../src/plugin/hooks/create-session-hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAU7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,8CAA8C,CAAC;AACrF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAE9C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACrC,GAAG,EAAE,aAAa,CAAC;IACnB,YAAY,EAAE,wBAAwB,CAAC;IACvC,gBAAgB,EAAE,gBAAgB,CAAC;CACtC;;;;;;qBAmD04E,CAAC;;;;;;;;;;;;qBAAkZ,CAAC;mBAAyB,CAAC;iBAAuB,CAAC;iBAAuB,CAAC;0BAAc,CAAC;uBAAiB,CAAC;;;;;;0BAAy7nB,CAAC;;;;;;EADn0tB"}

package/dist/plugin/messages-transform.d.ts

@@ -9,7 +9,7 @@ type MessagesTransformOutput = {
  * Top-level transform wrapper. Catches errors so OpenCode's prompt loop
  * always proceeds — without this guard, a transient DB contention event can
  * crash the user's turn through OpenCode's Effect pipeline. See issue #23:
- * https://github.com/cortexkit/opencode-magic-context/issues/23
+ * https://github.com/cortexkit/magic-context/issues/23
  *
  * Error handling is tiered:
  *

package/dist/plugin/rpc-handlers.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Server-side RPC handlers. Queries the server's own SQLite DB
+ * and returns typed responses for TUI consumption.
+ */
 import type { MagicContextConfig } from "../config/schema/magic-context";
 import type { LiveSessionState } from "../hooks/magic-context/live-session-state";
 import type { MagicContextRpcServer } from "../shared/rpc-server";

package/dist/plugin/rpc-handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rpc-handlers.d.ts","sourceRoot":"","sources":["../../src/plugin/rpc-handlers.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAMzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAQlF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAkflE;;GAEG;AACH,wBAAgB,mBAAmB,CAC/B,SAAS,EAAE,qBAAqB,EAChC,IAAI,EAAE;IACF,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,gBAAgB,EAAE,gBAAgB,CAAC;CACtC,GACF,IAAI,CA8HN"}
+{"version":3,"file":"rpc-handlers.d.ts","sourceRoot":"","sources":["../../src/plugin/rpc-handlers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAMzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAQlF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAkflE;;GAEG;AACH,wBAAgB,mBAAmB,CAC/B,SAAS,EAAE,qBAAqB,EAChC,IAAI,EAAE;IACF,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;IAChB,gBAAgB,EAAE,gBAAgB,CAAC;CACtC,GACF,IAAI,CA8HN"}

package/dist/plugin/tool-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../src/plugin/tool-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAqB1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACrC,GAAG,EAAE,aAAa,CAAC;IACnB,YAAY,EAAE,wBAAwB,CAAC;CAC1C,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAsFjC"}
+{"version":3,"file":"tool-registry.d.ts","sourceRoot":"","sources":["../../src/plugin/tool-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,WAAW,CAAC;AAqB1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACrC,GAAG,EAAE,aAAa,CAAC;IACnB,YAAY,EAAE,wBAAwB,CAAC;CAC1C,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CA8GjC"}

package/dist/shared/conflict-detector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conflict-detector.d.ts","sourceRoot":"","sources":["../../src/shared/conflict-detector.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,cAAc;IAC3B,8CAA8C;IAC9C,WAAW,EAAE,OAAO,CAAC;IACrB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2DAA2D;IAC3D,SAAS,EAAE;QACP,cAAc,EAAE,OAAO,CAAC;QACxB,eAAe,EAAE,OAAO,CAAC;QACzB,SAAS,EAAE,OAAO,CAAC;QACnB,uBAAuB,EAAE,OAAO,CAAC;QACjC,uBAAuB,EAAE,OAAO,CAAC;QACjC,oBAAoB,EAAE,OAAO,CAAC;KACjC,CAAC;CACL;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAyDjE;AAuPD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAWlE"}
+{"version":3,"file":"conflict-detector.d.ts","sourceRoot":"","sources":["../../src/shared/conflict-detector.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,cAAc;IAC3B,8CAA8C;IAC9C,WAAW,EAAE,OAAO,CAAC;IACrB,+CAA+C;IAC/C,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,2DAA2D;IAC3D,SAAS,EAAE;QACP,cAAc,EAAE,OAAO,CAAC;QACxB,eAAe,EAAE,OAAO,CAAC;QACzB,SAAS,EAAE,OAAO,CAAC;QACnB,uBAAuB,EAAE,OAAO,CAAC;QACjC,uBAAuB,EAAE,OAAO,CAAC;QACjC,oBAAoB,EAAE,OAAO,CAAC;KACjC,CAAC;CACL;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,CAyDjE;AAsQD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAWlE"}

package/dist/shared/data-path.d.ts

@@ -1,5 +1,27 @@
 export declare function getDataDir(): string;
 export declare function getOpenCodeStorageDir(): string;
+/**
+ * Resolve the shared magic-context storage directory.
+ *
+ * Magic-context's own data (compartments, facts, memories, embeddings, dream
+ * runs, notes, etc.) lives at this path regardless of which harness loaded the
+ * plugin (OpenCode or Pi). This enables:
+ *   - Shared project memories across harnesses
+ *   - Shared embedding cache
+ *   - Shared Dreamer runs (one per project per machine)
+ *   - Future cross-harness session migration
+ *
+ * Layout: <XDG_DATA_HOME>/cortexkit/magic-context/
+ */
+export declare function getMagicContextStorageDir(): string;
+/**
+ * Legacy magic-context storage directory used by the OpenCode plugin before the
+ * shared cortexkit path. Used only for one-time migration of existing data into
+ * the new shared location. The legacy directory is left in place after copy so
+ * users can roll back if needed; manual cleanup is safe after one stable
+ * release.
+ */
+export declare function getLegacyOpenCodeMagicContextStorageDir(): string;
 /**
  * Resolve OpenCode's cache base directory.
  *

package/dist/shared/data-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"data-path.d.ts","sourceRoot":"","sources":["../../src/shared/data-path.ts"],"names":[],"mappings":"AAGA,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C"}
+{"version":3,"file":"data-path.d.ts","sourceRoot":"","sources":["../../src/shared/data-path.ts"],"names":[],"mappings":"AAGA,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED;;;;;;GAMG;AACH,wBAAgB,uCAAuC,IAAI,MAAM,CAEhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C"}

package/dist/shared/harness.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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";
+/**
+ * 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 declare function setHarness(value: HarnessId): void;
+/**
+ * Get the current harness identifier. Used by storage modules when
+ * INSERTing session-scoped rows so each row is correctly attributed.
+ */
+export declare function getHarness(): HarnessId;
+/**
+ * Test-only helper to reset harness state between test cases. Do NOT call
+ * from production code paths.
+ */
+export declare function _resetHarnessForTesting(): void;
+//# sourceMappingURL=harness.d.ts.map

package/dist/shared/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../../src/shared/harness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,IAAI,CAAC;AAK1C;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAQjD;AAED;;;GAGG;AACH,wBAAgB,UAAU,IAAI,SAAS,CAEtC;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAG9C"}

package/dist/shared/rpc-notifications.d.ts

@@ -14,8 +14,10 @@ export interface RpcNotification {
 /** Push a notification for TUI to pick up via polling. */
 export declare function pushNotification(type: string, payload: Record<string, unknown>, sessionId?: string): void;
 /** 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 declare function drainNotifications(): RpcNotification[];
-/** 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 declare function isTuiConnected(): boolean;
 //# sourceMappingURL=rpc-notifications.d.ts.map

package/dist/shared/rpc-notifications.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rpc-notifications.d.ts","sourceRoot":"","sources":["../../src/shared/rpc-notifications.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAKD,0DAA0D;AAC1D,wBAAgB,gBAAgB,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,SAAS,CAAC,EAAE,MAAM,GACnB,IAAI,CAMN;AAED;6DAC6D;AAC7D,wBAAgB,kBAAkB,IAAI,eAAe,EAAE,CAKtD;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,IAAI,OAAO,CAExC"}
+{"version":3,"file":"rpc-notifications.d.ts","sourceRoot":"","sources":["../../src/shared/rpc-notifications.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,eAAe;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AASD,0DAA0D;AAC1D,wBAAgB,gBAAgB,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,SAAS,CAAC,EAAE,MAAM,GACnB,IAAI,CAMN;AAED;wEACwE;AACxE,wBAAgB,kBAAkB,IAAI,eAAe,EAAE,CAKtD;AAED;;2EAE2E;AAC3E,wBAAgB,cAAc,IAAI,OAAO,CAExC"}

package/dist/shared/sqlite-helpers.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare function closeQuietly(db: Database | null | undefined): void;
+//# sourceMappingURL=sqlite-helpers.d.ts.map

package/dist/shared/sqlite-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-helpers.d.ts","sourceRoot":"","sources":["../../src/shared/sqlite-helpers.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAUlE"}

package/dist/shared/sqlite.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 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`.
+ */
+/**
+ * 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 declare const Database: typeof BetterSqlite3;
+/** 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>;
+//# sourceMappingURL=sqlite.d.ts.map

package/dist/shared/sqlite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.d.ts","sourceRoot":"","sources":["../../src/shared/sqlite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAmCH;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,aAAa,MAAM,gBAAgB,CAAC;AAEhD,eAAO,MAAM,QAAQ,EAAE,OAAO,aAA4B,CAAC;AAE3D,+DAA+D;AAC/D,MAAM,MAAM,QAAQ,GAAG,aAAa,CAAC,QAAQ,CAAC;AAE9C;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,aAAa,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,OAAO,CAAC,CAAC"}

package/dist/shared/subagent-runner.d.ts

@@ -0,0 +1,202 @@
+/**
+ * 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>;
+}
+//# sourceMappingURL=subagent-runner.d.ts.map

package/dist/shared/subagent-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-runner.d.ts","sourceRoot":"","sources":["../../src/shared/subagent-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,WAAW,kBAAkB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACjC;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAEnC;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,qBAAqB,GAC3B;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACrE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACtD;IACI,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;CACd,GACD;IACI,IAAI,EAAE,UAAU,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;CACd,GACD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACjC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,MAAM,iBAAiB,GACvB;IACI,EAAE,EAAE,IAAI,CAAC;IACT,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,GACD;IACI,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EACA,SAAS,GACT,OAAO,GACP,cAAc,GACd,cAAc,GACd,eAAe,GACf,cAAc,GACd,cAAc,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,CAAC;AAER;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC3B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;;;OAMG;IACH,GAAG,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CAChE"}

package/dist/shared/tag-transcript.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Harness-agnostic tagging over the Transcript interface.
+ *
+ * This is a deliberately minimal alternative to the OpenCode-specific
+ * `tag-messages.ts` that operates on `MessageLike[]`. The OpenCode flow
+ * carries 380+ lines of accumulated complexity:
+ *
+ *   - source-content persistence (for cross-pass detag/restore behavior),
+ *   - tool-call indexing across separate "tool" and "tool_result" parts,
+ *   - reasoning-byte tracking for historian projection,
+ *   - file-part stable IDs,
+ *   - existing-tag resolver with content-id fallback.
+ *
+ * Most of that is OpenCode-specific (cache stability across multi-pass
+ * transforms, AI SDK part-id semantics, file part shapes). Pi's
+ * `pi.on("context", ...)` fires once per LLM call with a complete
+ * `AgentMessage[]`, so we can use a simpler tagging contract:
+ *
+ *   1. Walk the transcript in order.
+ *   2. For each tag-eligible part (text, tool_use, tool_result), assign
+ *      a tag number via the shared `Tagger`.
+ *   3. Inject `§N§ ` prefix into the visible text (unless skipped).
+ *   4. Build a `TagTarget` so `applyPendingOperations` from
+ *      `apply-operations.ts` can replace this part with a sentinel when
+ *      a queued drop fires.
+ *
+ * Tool drops aggregate by call_id across both invocation and result
+ * occurrences (mirrors OpenCode tag-messages.ts:196-220). When a drop
+ * fires for a tool tag, BOTH the assistant `toolCall`/`tool_use` part
+ * and the user `toolResult`/`tool_result` part are mutated together so
+ * the LLM sees consistent dropped state. Without this aggregation:
+ *
+ *   - Tool tag byte_size reflects only the args (~58 bytes for a `read`)
+ *     because the FIRST occurrence (invocation) is tagged first and
+ *     `assignTag` short-circuits the SECOND occurrence (result, ~4KB)
+ *     to the same tag without updating byte_size.
+ *   - Drops touch only the second occurrence (last write wins on
+ *     `targets.set`), leaving the first in original form.
+ *
+ * Reuses unchanged from the OpenCode path:
+ *
+ *   - `Tagger` (DB-backed counter + assignment store).
+ *   - `applyPendingOperations` (operates on `Map<number, TagTarget>`).
+ *   - `applyFlushedStatuses` (same).
+ *   - Tag prefix primitives (`prependTag`, `stripTagPrefix`, `byteSize`).
+ */
+import type { ContextDatabase } from "../features/magic-context/storage";
+import type { Tagger } from "../features/magic-context/tagger";
+import type { TagTarget } from "../hooks/magic-context/tag-messages";
+import type { Transcript } from "./transcript";
+export interface TagTranscriptOptions {
+    /**
+     * When true, skip injecting `§N§` prefix into visible text. Tags
+     * still get assigned in the DB so historian/drops can reference
+     * them; the agent just doesn't see the markers. Used when
+     * `ctx_reduce_enabled: false` (agent has no `ctx_reduce` tool to
+     * act on the markers). Cache-safe because skip behavior is
+     * consistent across passes.
+     */
+    skipPrefixInjection?: boolean;
+}
+export interface TagTranscriptResult {
+    targets: Map<number, TagTarget>;
+}
+export declare function tagTranscript(sessionId: string, transcript: Transcript, tagger: Tagger, db: ContextDatabase, options?: TagTranscriptOptions): TagTranscriptResult;
+//# sourceMappingURL=tag-transcript.d.ts.map

package/dist/shared/tag-transcript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-transcript.d.ts","sourceRoot":"","sources":["../../src/shared/tag-transcript.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAGzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAC;AAM/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AACrE,OAAO,KAAK,EAAE,UAAU,EAAkB,MAAM,cAAc,CAAC;AAE/D,MAAM,WAAW,oBAAoB;IACjC;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,MAAM,WAAW,mBAAmB;IAChC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACnC;AAyDD,wBAAgB,aAAa,CACzB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,eAAe,EACnB,OAAO,GAAE,oBAAyB,GACnC,mBAAmB,CA+JrB"}

package/dist/shared/transcript-opencode.d.ts

@@ -0,0 +1,71 @@
+/**
+ * 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 type { Transcript } 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 declare function createOpenCodeTranscript(messages: OpenCodeMessageLike[]): Transcript;
+//# sourceMappingURL=transcript-opencode.d.ts.map

package/dist/shared/transcript-opencode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript-opencode.d.ts","sourceRoot":"","sources":["../../src/shared/transcript-opencode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAGH,OAAO,KAAK,EACR,UAAU,EAIb,MAAM,cAAc,CAAC;AAEtB;;;;;;;;;;GAUG;AACH,MAAM,WAAW,mBAAmB;IAChC,IAAI,EAAE;QAAE,EAAE,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,KAAK,EAAE,OAAO,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,mBAAmB,EAAE,GAAG,UAAU,CA2BpF"}