pi-mega-compact 0.21.2 → 0.21.3

package/dist/extensions/dashboard-server/routes-rag-settings-helpers.js

@@ -138,6 +138,7 @@ export const SETTINGS = [
         name: "Three-Way Failback",
         settings: [
             boolDirect("MEGACOMPACT_THREE_WAY_FAILBACK", "Three-Way Failback", "Umbrella for the 3-way failback safety system: TriggerGuard (stages a recall block even when session_start never fires), the live-window ReductionValidator + persisted ThrashGuard (stops ineffective compaction re-fire loops), the 3-source read-only recall vote + same-repo relevance floor, and InjectionConfirm (asserts the staged block reached the message list pi sends). OFF = byte-identical pre-3WF behavior (v0.20.83). Runtime reads envBool(plain key), so this uses the plain-write convention (not _DISABLED).", true),
+            boolDirect("MEGACOMPACT_ITHACUS_BRIDGE", "ithacus Bridge", "Mega↔ithacus bridge: gate the child extension + bridge usage that tie this extension to ithacus's durable compaction. Default ON; OFF (=0/`=false`) is byte-identical to pre-bridge behavior — the bridge is only consulted when this is ON. Positive sprint flag. Runtime reads envBool(plain key), so this uses the plain-write convention (not _DISABLED).", true),
             boolDirect("MEGACOMPACT_RECALL_TAIL_INJECT", "Recall Tail Inject", "Compose the staged recall block as a trailing user message on the context event (tail inject) instead of the legacy system-prompt prepend. Tail mode keeps the cache prefix stable and is the mode InjectionConfirm verifies against ContextEvent.messages; OFF falls back to the legacy prepend path (verified by string-contains). Runtime reads envBool(plain key), so this uses the plain-write convention (not _DISABLED).", true),
         ],
     },

package/dist/extensions/mega-compact-child.js

@@ -0,0 +1,126 @@
+/**
+ * mega-compact-child.ts — minimal extension loaded ONLY into dispatched child
+ * pi subprocesses (spawned by ithacus with a second `-e` flag).
+ *
+ * Design: a child is a FRESH pi process started with `--no-extensions -e <this
+ * file>` (see ithacus-spawn.ts). It does NOT receive the parent's MegaConfig and
+ * is a separate process, so it reads its two control env vars directly and owns
+ * its own bridge. It gives children recall-at-start + compaction-on-shutdown via
+ * the mega-compact bridge, with NO tools and NO console output, so it never
+ * pollutes the child's `--mode json` JSONL stdout that ithacus-spawn parses.
+ *
+ * Per the teammate brief this mirrors ithacus-child-mailbox.ts (default export,
+ * no console, dispose on session_shutdown) but registers ZERO tools — registering
+ * any tool risks a pi duplicate-tool-name hard-fail and children need none.
+ *
+ * PREVENT-PI-004: no network. The bridge is a same-repo relative import over a
+ * local sqlite store; the only I/O is the read-only `git rev-parse` inside
+ * repoStateDir. Nothing to flag.
+ */
+import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
+import { createMegaBridge } from "../src/bridge.js";
+import { repoStateDir } from "./mega-config.js";
+import { STATE_DIR_DEFAULT } from "../src/config.js";
+/** Default-ON env bool: only `=false`/`=0` disables (matches mega-config envBool). */
+function envBool(name, fallback) {
+    const v = process.env[name];
+    if (v == null || v === "")
+        return fallback;
+    return v === "true" || v === "1";
+}
+/** Extract a recall query from a single AgentMessage (string or content blocks). */
+function messageToText(m) {
+    const c = m.content;
+    if (typeof c === "string")
+        return c;
+    if (Array.isArray(c))
+        return c.map((b) => b.text ?? "").join(" ");
+    return "";
+}
+/** Convert a session's AgentMessages into the bridge's lightweight shape. */
+function toBridgeMessages(ctx) {
+    const out = [];
+    try {
+        for (const entry of ctx.sessionManager.getEntries()) {
+            for (const m of sessionEntryToContextMessages(entry)) {
+                if (m.role === "user" || m.role === "assistant") {
+                    out.push({ role: m.role, text: messageToText(m) });
+                }
+            }
+        }
+    }
+    catch {
+        /* non-fatal: a child without a session manager yields no messages */
+    }
+    return out;
+}
+export default function (pi) {
+    // Flag read at LOAD time: a flag-OFF child registers nothing and a flag-ON
+    // child that never fires a hook pays zero cost (bridge is built lazily).
+    if (!envBool("MEGACOMPACT_ITHACUS_BRIDGE", true))
+        return;
+    let bridge;
+    // Build the bridge lazily on first hook fire so cost is opt-in by usage.
+    const getBridge = () => {
+        if (!bridge) {
+            bridge = createMegaBridge({
+                stateDir: repoStateDir(process.cwd(), STATE_DIR_DEFAULT),
+            });
+        }
+        return bridge;
+    };
+    // S52-style recall injection: prepend staged checkpoints + durable memories
+    // to the system prompt, mirroring the main entry's before_agent_start path.
+    // 4th-layer stability guard: an unset/empty sessionId makes recall silently
+    // useless (the openclaw Date.now() gotcha), so skip outright.
+    pi.on("before_agent_start", async (event) => {
+        try {
+            const sessionId = process.env.ITHACUS_MEGA_SESSION_ID;
+            if (!sessionId || sessionId === "")
+                return undefined;
+            // Prefer the event's raw prompt; fall back to a generic query.
+            const query = event.prompt && event.prompt.trim() ? event.prompt.trim() : "";
+            if (query === "")
+                return undefined;
+            const b = getBridge();
+            const cp = b.recallCheckpoints({ sessionId, query, limit: 3 });
+            const mem = await b.recallMemories({ query, limit: 5 });
+            const blocks = [];
+            if (!cp.empty && cp.block)
+                blocks.push(cp.block);
+            if (!mem.empty && mem.block)
+                blocks.push(mem.block);
+            if (blocks.length === 0)
+                return undefined;
+            return { systemPrompt: `${event.systemPrompt ?? ""}\n\n${blocks.join("\n\n")}` };
+        }
+        catch {
+            // layer b: non-fatal — never break the agent loop. No injection.
+            return undefined;
+        }
+    });
+    // Compaction on shutdown: persist the session's messages as a checkpoint.
+    // Best-effort; non-fatal. Releases the sqlite handle via close().
+    // The bridge is constructed lazily here too: a child that only compacts (no
+    // recall fired) still persists its session. Best-effort; non-fatal.
+    pi.on("session_shutdown", async (_event, ctx) => {
+        try {
+            const sessionId = process.env.ITHACUS_MEGA_SESSION_ID;
+            if (!sessionId || sessionId === "")
+                return;
+            const messages = toBridgeMessages(ctx);
+            if (messages.length === 0)
+                return;
+            await getBridge().compact({ sessionId, messages });
+        }
+        catch {
+            /* non-fatal */
+        }
+        finally {
+            if (bridge) {
+                bridge.close();
+                bridge = undefined;
+            }
+        }
+    });
+}

package/dist/extensions/mega-config.js

@@ -198,6 +198,11 @@ export function loadConfig() {
         // 3WF-1: TriggerGuard — guarantee a staged recall block on every context
         // event even when session_start never fires. Default ON; OFF = byte-identical.
         threeWayFailback: envBool("MEGACOMPACT_THREE_WAY_FAILBACK", true),
+        // Sprint A: Mega↔ithacus bridge — gate the child extension + bridge usage.
+        // Default ON; OFF (=0/`=false`) = byte-identical pre-bridge behavior.
+        // Runtime reads envBool(plain key), mirroring threeWayFailback (plain-write
+        // convention, not _DISABLED).
+        ithacusBridge: envBool("MEGACOMPACT_ITHACUS_BRIDGE", true),
         // 3WF-2: ThrashGuard re-arm budget as a fraction of effectiveThreshold.
         // 0.10 default (10% of the effective threshold) — see mega-config-types.
         // Clamped to [0.01, 0.5]: below 1% the guard is almost never armed (any

package/dist/src/bridge/factory.js

@@ -0,0 +1,181 @@
+/**
+ * bridge/factory.ts — `createMegaBridge(opts)` implementation.
+ *
+ * A thin, pi-agnostic wrapper over the engine's compaction / recall / memory /
+ * fork / vector APIs. Stores are constructed lazily on first use (a consumer
+ * that only calls recallMemories pays no VectorStore cost). Exceptions
+ * propagate from every method except `fork` (catches ForkError by design) and
+ * `close` (swallows best-effort cleanup), so failures surface in tests.
+ */
+import { compactSession } from "../engine.js";
+import { recallAndInline, recallAndInlineAsync, recallMemoriesAndInline, } from "../recall.js";
+import { forkFromConversation, ForkError } from "../fork.js";
+import { createTurnStore } from "../store/turns/index.js";
+import { addMemory } from "../store/sqlite/memories.js";
+import { VectorStore, vectorSearch } from "../vectorStore.js";
+import { repoKey } from "../store/repoKey.js";
+/** Map a RecallInjectResult to the bridge's slimmer result contract. */
+function mapRecallResult(r) {
+    return {
+        block: r.block,
+        report: r.report,
+        hitCount: r.toInject.length,
+        empty: r.empty,
+    };
+}
+/** Map the memoryRecallAndInline tuple result to the bridge contract. */
+function mapMemoryResult(r) {
+    return {
+        block: r.block,
+        report: r.report,
+        hitCount: r.report.length,
+        empty: r.empty,
+    };
+}
+/** Map vectorSearch hits to the cortex result contract. */
+function mapCortexHits(hits, limit) {
+    const top = hits.slice(0, limit);
+    return {
+        results: top.map((h) => ({
+            checkpointId: h.checkpoint.checkpointId,
+            score: h.score,
+            summary: h.checkpoint.summary,
+        })),
+        hitCount: top.length,
+    };
+}
+/**
+ * Create a MegaBridge over a single stateDir.
+ *
+ * The VectorStore and TurnStore are lazy: constructed on first use and cached
+ * in closures. The stateDir is retained for memory recall, which needs it
+ * directly.
+ */
+export function createMegaBridge(opts) {
+    const stateDir = opts.stateDir;
+    let vectorStore;
+    let turnStore;
+    const getVectorStore = () => {
+        if (!vectorStore)
+            vectorStore = new VectorStore({ stateDir });
+        return vectorStore;
+    };
+    const getTurnStore = () => {
+        if (!turnStore)
+            turnStore = createTurnStore({ stateDir });
+        return turnStore;
+    };
+    return {
+        compact(input) {
+            const result = compactSession({
+                sessionId: input.sessionId,
+                messages: input.messages,
+                keepFrom: input.keepFrom,
+                summary: input.summary,
+                keyDecisions: input.keyDecisions,
+                nextSteps: input.nextSteps,
+                filesModified: input.filesModified,
+                compressionPressure: input.compressionPressure,
+            }, getVectorStore());
+            return {
+                skipped: result.skipped,
+                deduped: result.deduped,
+                summary: result.summary,
+                checkpointId: result.checkpointId,
+                tokenEstimate: result.tokenEstimate,
+                originalTokenEstimate: result.originalTokenEstimate,
+                compactedFrom: result.compactedFrom,
+            };
+        },
+        recallCheckpoints(opts) {
+            const recallOpts = {
+                sessionId: opts.sessionId,
+                query: opts.query,
+                limit: opts.limit ?? 3,
+                source: "command",
+                skipInjected: opts.skipInjected,
+                recallMaxTokens: opts.recallMaxTokens,
+            };
+            return mapRecallResult(recallAndInline(recallOpts, getVectorStore()));
+        },
+        async recallMemories(opts) {
+            const memOpts = {
+                query: opts.query,
+                stateDir,
+                limit: opts.limit,
+                minSimilarity: opts.minSimilarity,
+                crossRepo: opts.crossRepo,
+                crossRepoCosine: opts.crossRepoCosine,
+                recallMaxTokens: opts.recallMaxTokens,
+            };
+            const r = await recallMemoriesAndInline(memOpts);
+            return mapMemoryResult(r);
+        },
+        async recallAndInlineAsync(opts) {
+            const recallOpts = {
+                sessionId: opts.sessionId,
+                query: opts.query,
+                limit: opts.limit ?? 3,
+                source: "command",
+                skipInjected: opts.skipInjected,
+                recallMaxTokens: opts.recallMaxTokens,
+            };
+            const r = await recallAndInlineAsync(recallOpts, getVectorStore());
+            return mapRecallResult(r);
+        },
+        fork(opts) {
+            try {
+                const outcome = forkFromConversation(getTurnStore(), opts.parentConversationId, opts.turnIndex);
+                return {
+                    childConversationId: outcome.childConversationId,
+                    checkpointIds: outcome.checkpointIds,
+                    forkTurnIndex: opts.turnIndex,
+                };
+            }
+            catch (e) {
+                if (e instanceof ForkError) {
+                    return { error: e.code };
+                }
+                throw e;
+            }
+        },
+        cortexQuery(opts) {
+            const limit = opts.limit ?? 3;
+            const scope = opts.repo ?? repoKey(stateDir);
+            const hits = vectorSearch(getVectorStore(), scope, opts.query, limit);
+            return mapCortexHits(hits, limit);
+        },
+        addMemory(input) {
+            // repo === null ⇒ stateDir-scoped durable memory (matches recallMemories).
+            return addMemory({
+                kind: input.kind,
+                content: input.content,
+                tags: input.tags,
+                category: input.category,
+            }, null, stateDir);
+        },
+        recordTurn(input) {
+            const turn = {
+                conversationId: input.conversationId,
+                sessionId: input.sessionId,
+                turnIndex: input.turnIndex,
+                role: input.role ?? "assistant",
+                endedAt: input.endedAt ?? Date.now(),
+                ctxTokens: input.ctxTokens,
+                ctxPercent: input.ctxPercent,
+                model: input.model,
+            };
+            getTurnStore().asWriter().appendTurn(turn);
+        },
+        close() {
+            if (turnStore) {
+                try {
+                    turnStore.close();
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+        },
+    };
+}

package/dist/src/bridge/types.js

@@ -0,0 +1,10 @@
+/**
+ * bridge/types.ts — contract types for the bidirectional mega-compact bridge.
+ *
+ * A pi-agnostic, unit-testable adapter surface that wraps the engine's
+ * compaction / recall / memory / fork / vector APIs behind one factory so an
+ * external host (ithacus) can drive them without importing pi-runtime types.
+ * Every type here mirrors a real engine signature (see factory.ts for the
+ * wiring).
+ */
+export {};

package/dist/src/bridge.js

@@ -0,0 +1 @@
+export { createMegaBridge } from "./bridge/factory.js";

package/extensions/dashboard-server/routes-rag-settings-helpers.ts

@@ -305,6 +305,12 @@ export const SETTINGS: ReadonlyArray<SettingGroup> = [
 				"Umbrella for the 3-way failback safety system: TriggerGuard (stages a recall block even when session_start never fires), the live-window ReductionValidator + persisted ThrashGuard (stops ineffective compaction re-fire loops), the 3-source read-only recall vote + same-repo relevance floor, and InjectionConfirm (asserts the staged block reached the message list pi sends). OFF = byte-identical pre-3WF behavior (v0.20.83). Runtime reads envBool(plain key), so this uses the plain-write convention (not _DISABLED).",
 				true,
 			),
+			boolDirect(
+				"MEGACOMPACT_ITHACUS_BRIDGE",
+				"ithacus Bridge",
+				"Mega↔ithacus bridge: gate the child extension + bridge usage that tie this extension to ithacus's durable compaction. Default ON; OFF (=0/`=false`) is byte-identical to pre-bridge behavior — the bridge is only consulted when this is ON. Positive sprint flag. Runtime reads envBool(plain key), so this uses the plain-write convention (not _DISABLED).",
+				true,
+			),
 			boolDirect(
 				"MEGACOMPACT_RECALL_TAIL_INJECT",
 				"Recall Tail Inject",

package/extensions/mega-compact-child.ts

@@ -0,0 +1,129 @@
+/**
+ * mega-compact-child.ts — minimal extension loaded ONLY into dispatched child
+ * pi subprocesses (spawned by ithacus with a second `-e` flag).
+ *
+ * Design: a child is a FRESH pi process started with `--no-extensions -e <this
+ * file>` (see ithacus-spawn.ts). It does NOT receive the parent's MegaConfig and
+ * is a separate process, so it reads its two control env vars directly and owns
+ * its own bridge. It gives children recall-at-start + compaction-on-shutdown via
+ * the mega-compact bridge, with NO tools and NO console output, so it never
+ * pollutes the child's `--mode json` JSONL stdout that ithacus-spawn parses.
+ *
+ * Per the teammate brief this mirrors ithacus-child-mailbox.ts (default export,
+ * no console, dispose on session_shutdown) but registers ZERO tools — registering
+ * any tool risks a pi duplicate-tool-name hard-fail and children need none.
+ *
+ * PREVENT-PI-004: no network. The bridge is a same-repo relative import over a
+ * local sqlite store; the only I/O is the read-only `git rev-parse` inside
+ * repoStateDir. Nothing to flag.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
+import { createMegaBridge } from "../src/bridge.js";
+import type {
+	MegaBridge,
+	BridgeMessage,
+} from "../src/bridge.js";
+import { repoStateDir } from "./mega-config.js";
+import { STATE_DIR_DEFAULT } from "../src/config.js";
+
+/** Default-ON env bool: only `=false`/`=0` disables (matches mega-config envBool). */
+function envBool(name: string, fallback: boolean): boolean {
+	const v = process.env[name];
+	if (v == null || v === "") return fallback;
+	return v === "true" || v === "1";
+}
+
+/** Extract a recall query from a single AgentMessage (string or content blocks). */
+function messageToText(m: { content: unknown }): string {
+	const c = (m as { content: unknown }).content;
+	if (typeof c === "string") return c;
+	if (Array.isArray(c)) return c.map((b: { text?: string }) => b.text ?? "").join(" ");
+	return "";
+}
+
+/** Convert a session's AgentMessages into the bridge's lightweight shape. */
+function toBridgeMessages(ctx: ExtensionContext): BridgeMessage[] {
+	const out: BridgeMessage[] = [];
+	try {
+		for (const entry of ctx.sessionManager.getEntries()) {
+			for (const m of sessionEntryToContextMessages(entry as never)) {
+				if (m.role === "user" || m.role === "assistant") {
+					out.push({ role: m.role, text: messageToText(m) });
+				}
+			}
+		}
+	} catch {
+		/* non-fatal: a child without a session manager yields no messages */
+	}
+	return out;
+}
+
+export default function (pi: ExtensionAPI): void {
+	// Flag read at LOAD time: a flag-OFF child registers nothing and a flag-ON
+	// child that never fires a hook pays zero cost (bridge is built lazily).
+	if (!envBool("MEGACOMPACT_ITHACUS_BRIDGE", true)) return;
+
+	let bridge: MegaBridge | undefined;
+
+	// Build the bridge lazily on first hook fire so cost is opt-in by usage.
+	const getBridge = (): MegaBridge => {
+		if (!bridge) {
+			bridge = createMegaBridge({
+				stateDir: repoStateDir(process.cwd(), STATE_DIR_DEFAULT),
+			});
+		}
+		return bridge;
+	};
+
+	// S52-style recall injection: prepend staged checkpoints + durable memories
+	// to the system prompt, mirroring the main entry's before_agent_start path.
+	// 4th-layer stability guard: an unset/empty sessionId makes recall silently
+	// useless (the openclaw Date.now() gotcha), so skip outright.
+	pi.on("before_agent_start", async (event) => {
+		try {
+			const sessionId = process.env.ITHACUS_MEGA_SESSION_ID;
+			if (!sessionId || sessionId === "") return undefined;
+
+			// Prefer the event's raw prompt; fall back to a generic query.
+			const query = event.prompt && event.prompt.trim() ? event.prompt.trim() : "";
+			if (query === "") return undefined;
+
+			const b = getBridge();
+			const cp = b.recallCheckpoints({ sessionId, query, limit: 3 });
+			const mem = await b.recallMemories({ query, limit: 5 });
+
+			const blocks: string[] = [];
+			if (!cp.empty && cp.block) blocks.push(cp.block);
+			if (!mem.empty && mem.block) blocks.push(mem.block);
+			if (blocks.length === 0) return undefined;
+
+			return { systemPrompt: `${event.systemPrompt ?? ""}\n\n${blocks.join("\n\n")}` };
+		} catch {
+			// layer b: non-fatal — never break the agent loop. No injection.
+			return undefined;
+		}
+	});
+
+	// Compaction on shutdown: persist the session's messages as a checkpoint.
+	// Best-effort; non-fatal. Releases the sqlite handle via close().
+	// The bridge is constructed lazily here too: a child that only compacts (no
+	// recall fired) still persists its session. Best-effort; non-fatal.
+	pi.on("session_shutdown", async (_event, ctx) => {
+		try {
+			const sessionId = process.env.ITHACUS_MEGA_SESSION_ID;
+			if (!sessionId || sessionId === "") return;
+			const messages = toBridgeMessages(ctx);
+			if (messages.length === 0) return;
+			await getBridge().compact({ sessionId, messages });
+		} catch {
+			/* non-fatal */
+		} finally {
+			if (bridge) {
+				bridge.close();
+				bridge = undefined;
+			}
+		}
+	});
+}

package/extensions/mega-config-types.ts

@@ -159,6 +159,11 @@ export interface MegaConfig {
 	 *  to the pre-change OFF state. The single gate lives at the call site
 	 *  (tailResult.ts, config.messageSeparation), not inside buildSeparatedPrompt. */
 	messageSeparation: boolean;
+	/** Sprint A: Mega↔ithacus bridge — gate the child extension + bridge usage
+	 *  that tie this extension to ithacus's durable compaction. Positive sprint
+	 *  flag, default ON; flag-OFF (=0/`=false`) is byte-identical to pre-bridge
+	 *  behavior (the bridge is only consulted when this is ON). */
+	ithacusBridge: boolean;
 	/** P3: Cache-aware striping (PLAN_V2 Phase 3). Inserts stability-ordered
 	 *  cache stripes between summaries and thread. Default OFF. */
 	cacheStriping: boolean;

package/extensions/mega-config.ts

@@ -234,6 +234,11 @@ export function loadConfig(): MegaConfig {
 		// 3WF-1: TriggerGuard — guarantee a staged recall block on every context
 		// event even when session_start never fires. Default ON; OFF = byte-identical.
 		threeWayFailback: envBool("MEGACOMPACT_THREE_WAY_FAILBACK", true),
+		// Sprint A: Mega↔ithacus bridge — gate the child extension + bridge usage.
+		// Default ON; OFF (=0/`=false`) = byte-identical pre-bridge behavior.
+		// Runtime reads envBool(plain key), mirroring threeWayFailback (plain-write
+		// convention, not _DISABLED).
+		ithacusBridge: envBool("MEGACOMPACT_ITHACUS_BRIDGE", true),
 		// 3WF-2: ThrashGuard re-arm budget as a fraction of effectiveThreshold.
 		// 0.10 default (10% of the effective threshold) — see mega-config-types.
 		// Clamped to [0.01, 0.5]: below 1% the guard is almost never armed (any

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.21.2",
+  "version": "0.21.3",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",

package/src/bridge/factory.ts

@@ -0,0 +1,231 @@
+/**
+ * bridge/factory.ts — `createMegaBridge(opts)` implementation.
+ *
+ * A thin, pi-agnostic wrapper over the engine's compaction / recall / memory /
+ * fork / vector APIs. Stores are constructed lazily on first use (a consumer
+ * that only calls recallMemories pays no VectorStore cost). Exceptions
+ * propagate from every method except `fork` (catches ForkError by design) and
+ * `close` (swallows best-effort cleanup), so failures surface in tests.
+ */
+import { compactSession } from "../engine.js";
+import {
+  recallAndInline,
+  recallAndInlineAsync,
+  recallMemoriesAndInline,
+} from "../recall.js";
+import type {
+  RecallInjectOptions,
+  RecallInjectResult,
+  MemoryRecallInjectOptions,
+} from "../recall/types.js";
+import { forkFromConversation, ForkError } from "../fork.js";
+import { createTurnStore } from "../store/turns/index.js";
+import type { TurnStore, TurnEntry } from "../store/turns/types.js";
+import { addMemory } from "../store/sqlite/memories.js";
+import { VectorStore, vectorSearch } from "../vectorStore.js";
+import type { SearchHit } from "../vectorStore.js";
+import { repoKey } from "../store/repoKey.js";
+import type {
+  BridgeOptions,
+  BridgeCompactInput,
+  BridgeCompactResult,
+  BridgeRecallOptions,
+  BridgeRecallResult,
+  BridgeMemoryRecallOptions,
+  BridgeMemoryRecallResult,
+  BridgeForkOptions,
+  BridgeForkResult,
+  BridgeCortexOptions,
+  BridgeCortexResult,
+  BridgeAddMemoryInput,
+  BridgeRecordTurnInput,
+  MegaBridge,
+} from "./types.js";
+
+/** Map a RecallInjectResult to the bridge's slimmer result contract. */
+function mapRecallResult(r: RecallInjectResult): BridgeRecallResult {
+  return {
+    block: r.block,
+    report: r.report,
+    hitCount: r.toInject.length,
+    empty: r.empty,
+  };
+}
+
+/** Map the memoryRecallAndInline tuple result to the bridge contract. */
+function mapMemoryResult(
+  r: { empty: boolean; block: string; report: string[] },
+): BridgeMemoryRecallResult {
+  return {
+    block: r.block,
+    report: r.report,
+    hitCount: r.report.length,
+    empty: r.empty,
+  };
+}
+
+/** Map vectorSearch hits to the cortex result contract. */
+function mapCortexHits(hits: SearchHit[], limit: number): BridgeCortexResult {
+  const top = hits.slice(0, limit);
+  return {
+    results: top.map((h) => ({
+      checkpointId: h.checkpoint.checkpointId,
+      score: h.score,
+      summary: h.checkpoint.summary,
+    })),
+    hitCount: top.length,
+  };
+}
+
+/**
+ * Create a MegaBridge over a single stateDir.
+ *
+ * The VectorStore and TurnStore are lazy: constructed on first use and cached
+ * in closures. The stateDir is retained for memory recall, which needs it
+ * directly.
+ */
+export function createMegaBridge(opts: BridgeOptions): MegaBridge {
+  const stateDir = opts.stateDir;
+  let vectorStore: VectorStore | undefined;
+  let turnStore: TurnStore | undefined;
+
+  const getVectorStore = (): VectorStore => {
+    if (!vectorStore) vectorStore = new VectorStore({ stateDir });
+    return vectorStore;
+  };
+  const getTurnStore = (): TurnStore => {
+    if (!turnStore) turnStore = createTurnStore({ stateDir });
+    return turnStore;
+  };
+
+  return {
+    compact(input: BridgeCompactInput): BridgeCompactResult {
+      const result = compactSession(
+        {
+          sessionId: input.sessionId,
+          messages: input.messages,
+          keepFrom: input.keepFrom,
+          summary: input.summary,
+          keyDecisions: input.keyDecisions,
+          nextSteps: input.nextSteps,
+          filesModified: input.filesModified,
+          compressionPressure: input.compressionPressure,
+        },
+        getVectorStore(),
+      );
+      return {
+        skipped: result.skipped,
+        deduped: result.deduped,
+        summary: result.summary,
+        checkpointId: result.checkpointId,
+        tokenEstimate: result.tokenEstimate,
+        originalTokenEstimate: result.originalTokenEstimate,
+        compactedFrom: result.compactedFrom,
+      };
+    },
+
+    recallCheckpoints(opts: BridgeRecallOptions): BridgeRecallResult {
+      const recallOpts: RecallInjectOptions = {
+        sessionId: opts.sessionId,
+        query: opts.query,
+        limit: opts.limit ?? 3,
+        source: "command",
+        skipInjected: opts.skipInjected,
+        recallMaxTokens: opts.recallMaxTokens,
+      };
+      return mapRecallResult(recallAndInline(recallOpts, getVectorStore()));
+    },
+
+    async recallMemories(opts: BridgeMemoryRecallOptions): Promise<BridgeMemoryRecallResult> {
+      const memOpts: MemoryRecallInjectOptions = {
+        query: opts.query,
+        stateDir,
+        limit: opts.limit,
+        minSimilarity: opts.minSimilarity,
+        crossRepo: opts.crossRepo,
+        crossRepoCosine: opts.crossRepoCosine,
+        recallMaxTokens: opts.recallMaxTokens,
+      };
+      const r = await recallMemoriesAndInline(memOpts);
+      return mapMemoryResult(r);
+    },
+
+    async recallAndInlineAsync(opts: BridgeRecallOptions): Promise<BridgeRecallResult> {
+      const recallOpts: RecallInjectOptions = {
+        sessionId: opts.sessionId,
+        query: opts.query,
+        limit: opts.limit ?? 3,
+        source: "command",
+        skipInjected: opts.skipInjected,
+        recallMaxTokens: opts.recallMaxTokens,
+      };
+      const r = await recallAndInlineAsync(recallOpts, getVectorStore());
+      return mapRecallResult(r);
+    },
+
+    fork(opts: BridgeForkOptions): BridgeForkResult {
+      try {
+        const outcome = forkFromConversation(
+          getTurnStore(),
+          opts.parentConversationId,
+          opts.turnIndex,
+        );
+        return {
+          childConversationId: outcome.childConversationId,
+          checkpointIds: outcome.checkpointIds,
+          forkTurnIndex: opts.turnIndex,
+        };
+      } catch (e) {
+        if (e instanceof ForkError) {
+          return { error: e.code };
+        }
+        throw e;
+      }
+    },
+
+    cortexQuery(opts: BridgeCortexOptions): BridgeCortexResult {
+      const limit = opts.limit ?? 3;
+      const scope = opts.repo ?? repoKey(stateDir);
+      const hits = vectorSearch(getVectorStore(), scope, opts.query, limit);
+      return mapCortexHits(hits, limit);
+    },
+
+    addMemory(input: BridgeAddMemoryInput): number | void {
+      // repo === null ⇒ stateDir-scoped durable memory (matches recallMemories).
+      return addMemory(
+        {
+          kind: input.kind,
+          content: input.content,
+          tags: input.tags,
+          category: input.category,
+        },
+        null,
+        stateDir,
+      );
+    },
+
+    recordTurn(input: BridgeRecordTurnInput): void {
+      const turn: TurnEntry = {
+        conversationId: input.conversationId,
+        sessionId: input.sessionId,
+        turnIndex: input.turnIndex,
+        role: (input.role as TurnEntry["role"]) ?? "assistant",
+        endedAt: input.endedAt ?? Date.now(),
+        ctxTokens: input.ctxTokens,
+        ctxPercent: input.ctxPercent,
+        model: input.model,
+      };
+      getTurnStore().asWriter().appendTurn(turn);
+    },
+
+    close(): void {
+      if (turnStore) {
+        try {
+          turnStore.close();
+        } catch {
+          /* best-effort */
+        }
+      }
+    },
+  };
+}

package/src/bridge/types.ts

@@ -0,0 +1,138 @@
+/**
+ * bridge/types.ts — contract types for the bidirectional mega-compact bridge.
+ *
+ * A pi-agnostic, unit-testable adapter surface that wraps the engine's
+ * compaction / recall / memory / fork / vector APIs behind one factory so an
+ * external host (ithacus) can drive them without importing pi-runtime types.
+ * Every type here mirrors a real engine signature (see factory.ts for the
+ * wiring).
+ */
+
+import type { EngineMessage } from "../types.js";
+
+/** Same shape as the engine's internal message. Identity re-export. */
+export type BridgeMessage = EngineMessage;
+
+/** Bridge construction options. */
+export interface BridgeOptions {
+  stateDir: string;
+}
+
+/** Input to compact a message slice into a checkpoint. */
+export interface BridgeCompactInput {
+  sessionId: string;
+  messages: BridgeMessage[];
+  keepFrom?: number;
+  summary?: string;
+  keyDecisions?: string[];
+  nextSteps?: string[];
+  filesModified?: string[];
+  compressionPressure?: number;
+}
+
+/** Useful subset of CompactResult. */
+export interface BridgeCompactResult {
+  skipped: boolean;
+  deduped: boolean;
+  summary: string;
+  checkpointId?: string;
+  tokenEstimate: number;
+  originalTokenEstimate?: number;
+  compactedFrom?: number;
+}
+
+/** Options for checkpoint recall (per-session). */
+export interface BridgeRecallOptions {
+  sessionId: string;
+  query: string;
+  limit?: number;
+  recallMaxTokens?: number;
+  skipInjected?: boolean;
+}
+
+/** Mapped from RecallInjectResult. */
+export interface BridgeRecallResult {
+  block: string;
+  report: string[];
+  hitCount: number;
+  empty: boolean;
+}
+
+/** Options for durable memory recall (stateDir-scoped, no sessionId). */
+export interface BridgeMemoryRecallOptions {
+  query: string;
+  limit?: number;
+  minSimilarity?: number;
+  crossRepo?: boolean;
+  crossRepoCosine?: number;
+  recallMaxTokens?: number;
+}
+
+export interface BridgeMemoryRecallResult {
+  block: string;
+  report: string[];
+  hitCount: number;
+  empty: boolean;
+}
+
+/** Options to fork a child conversation off a parent turn. */
+export interface BridgeForkOptions {
+  parentConversationId: string;
+  turnIndex: number;
+}
+
+/** Fork result: success variant OR a graceful error variant. */
+export interface BridgeForkSuccess {
+  childConversationId: string;
+  checkpointIds: string[];
+  forkTurnIndex: number;
+}
+export interface BridgeForkError {
+  error: "TURN_NOT_FOUND" | "NO_RECALL";
+}
+export type BridgeForkResult = BridgeForkSuccess | BridgeForkError;
+
+/** Options for a top-k corpus / vector query. */
+export interface BridgeCortexOptions {
+  query: string;
+  limit?: number;
+  repo?: string;
+}
+
+export interface BridgeCortexResult {
+  results: Array<{ checkpointId: string; score: number; summary?: string }>;
+  hitCount: number;
+}
+
+/** Input to persist a durable memory. */
+export interface BridgeAddMemoryInput {
+  content: string;
+  kind?: string;
+  tags?: string[];
+  category?: string;
+}
+
+/** Input to record a turn fact. */
+export interface BridgeRecordTurnInput {
+  conversationId: string;
+  sessionId: string;
+  turnIndex: number;
+  role?: string;
+  endedAt?: number;
+  ctxTokens?: number;
+  ctxPercent?: number;
+  model?: string;
+}
+
+/** The bridge surface exposed to the host. */
+export interface MegaBridge {
+  compact(input: BridgeCompactInput): BridgeCompactResult;
+  recallCheckpoints(opts: BridgeRecallOptions): BridgeRecallResult;
+  recallMemories(opts: BridgeMemoryRecallOptions): Promise<BridgeMemoryRecallResult>;
+  recallAndInlineAsync(opts: BridgeRecallOptions): Promise<BridgeRecallResult>;
+  fork(opts: BridgeForkOptions): BridgeForkResult;
+  cortexQuery(opts: BridgeCortexOptions): BridgeCortexResult;
+  addMemory(input: BridgeAddMemoryInput): number | void;
+  recordTurn(input: BridgeRecordTurnInput): void;
+  close(): void;
+}

package/src/bridge.ts

@@ -0,0 +1,24 @@
+/**
+ * bridge.ts — public barrel for the mega-compact bidirectional bridge.
+ *
+ * Hosts import only this file. The factory and all contracts live under
+ * src/bridge/ (kept thin per the delegate-shell pattern).
+ */
+export type {
+  MegaBridge,
+  BridgeOptions,
+  BridgeMessage,
+  BridgeCompactInput,
+  BridgeCompactResult,
+  BridgeRecallOptions,
+  BridgeRecallResult,
+  BridgeMemoryRecallOptions,
+  BridgeMemoryRecallResult,
+  BridgeForkOptions,
+  BridgeForkResult,
+  BridgeCortexOptions,
+  BridgeCortexResult,
+  BridgeAddMemoryInput,
+  BridgeRecordTurnInput,
+} from "./bridge/types.js";
+export { createMegaBridge } from "./bridge/factory.js";