pi-mega-compact 0.4.5 → 0.4.7

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

@@ -0,0 +1,328 @@
+/**
+ * mega-compact.extension.test.ts — end-to-end drive of the REAL extension
+ * entry (extensions/mega-compact.ts) through a faithful mock pi.
+ *
+ * This is the closest we get to "a live pi session" without a model: it
+ * loads the compiled extension, captures its event/command handlers, and
+ * fires them with mock ctx objects — proving the three compact layers
+ * (auto-trigger -> compactSession) AND the three recall entries all
+ * route through the real code, not just the unit-tested src/ modules.
+ *
+ * Uses a per-test isolated state dir (process.env.MEGACOMPACT_STATE_DIR)
+ * so concurrent node --test runs do not collide on disk.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const baseTmp = mkdtempSync(join(tmpdir(), "mc-ext-"));
+let counter = 0;
+/** Build a mock pi + ctx and load the extension into them. */
+function harness(opts = {}) {
+    const stateDir = join(baseTmp, `run-${counter++}`);
+    process.env.MEGACOMPACT_STATE_DIR = stateDir;
+    process.env.MEGACOMPACT_DEBUG = "true";
+    // Low threshold so the auto-trigger gate trips on our small mock context.
+    // Tier tests opt out (keepTier/keepThreshold) so they can drive the real
+    // tier resolution instead of the forced 50-token threshold.
+    if (!opts.keepThreshold)
+        process.env.MEGACOMPACT_THRESHOLD_TOKENS = "50";
+    if (!opts.keepTier)
+        delete process.env.MEGACOMPACT_TIER;
+    process.env.MEGACOMPACT_FAST_GATE_PCT = "1";
+    const handlers = {};
+    const commands = {};
+    const appended = [];
+    let statusKey;
+    let statusText;
+    const notifies = [];
+    // Minimal AgentMessage factory for the session we project into the extension.
+    function msg(role, text, toolName) {
+        if (role === "assistant" && toolName) {
+            return { role: "assistant", content: [{ type: "toolCall", name: toolName, id: "c1", arguments: {} }], api: "anthropic-messages", provider: "anthropic", model: "m", usage: { inputTokens: 1, outputTokens: 1, cacheReadTokens: 0, cacheWriteTokens: 0 }, stopReason: "tool_use", timestamp: 0 };
+        }
+        if (role === "toolResult" && toolName) {
+            return { role: "toolResult", toolCallId: "c1", toolName, content: [{ type: "text", text }], isError: false, timestamp: 0 };
+        }
+        return { role: "user", content: text, timestamp: 0 };
+    }
+    const session = [
+        msg("user", "read src/vec.ts and understand the index"),
+        msg("assistant", "ok", "Read"),
+        msg("user", "edit src/vec.ts to add a cosine helper"),
+        msg("assistant", "ok", "Edit"),
+        msg("user", "now fix the dedupe bug in store.ts"),
+        msg("assistant", "ok", "Edit"),
+        msg("user", "actually we should add recall sorting too"),
+        msg("assistant", "ok", "Edit"),
+    ];
+    // Mirror the REAL SessionManager: getEntries() returns SessionEntry objects,
+    // which the extension projects to messages via the SDK's
+    // sessionEntryToContextMessages(entry). The harness must use the same shape
+    // (type:"message" with a .message) or recentUserQuery() silently queries "".
+    const toEntry = (m, i) => ({
+        type: "message",
+        id: `e${i}`,
+        parentId: null,
+        timestamp: String(i),
+        message: m,
+    });
+    const sessionManager = {
+        getSessionId: () => "sess_ext_001",
+        getEntries: () => session.map(toEntry),
+    };
+    function makeCtx(over = {}) {
+        return {
+            ui: {
+                setStatus: (k, t) => { statusKey = k; statusText = t; },
+                notify: (s) => notifies.push(s),
+                select: () => { },
+                confirm: async () => true,
+                input: async () => "",
+                setWidget: () => { },
+            },
+            mode: "tui",
+            hasUI: true,
+            cwd: stateDir,
+            sessionManager,
+            modelRegistry: {},
+            model: undefined,
+            isIdle: () => true,
+            isProjectTrusted: () => true,
+            signal: undefined,
+            abort: () => { },
+            hasPendingMessages: () => false,
+            shutdown: () => { },
+            getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }),
+            compact: () => { },
+            getSystemPrompt: () => "system base",
+            ...over,
+        };
+    }
+    const pi = {
+        on: (ev, h) => { handlers[ev] = h; },
+        registerCommand: (name, opts) => { commands[name] = opts; },
+        registerTool: () => { },
+        registerShortcut: () => { },
+        registerFlag: () => { },
+        getFlag: () => undefined,
+        registerMessageRenderer: () => { },
+        registerEntryRenderer: () => { },
+        sendMessage: (_m) => { },
+        sendUserMessage: () => { },
+        appendEntry: (t, d) => appended.push({ t, d }),
+        setSessionName: () => { },
+        getSessionName: () => undefined,
+        setLabel: () => { },
+        exec: async () => ({ stdout: "", stderr: "", code: 0 }),
+        getActiveTools: () => [],
+        getAllTools: () => [],
+        setActiveTools: () => { },
+        getCommands: () => [],
+        setModel: async () => false,
+        getThinkingLevel: () => "off",
+        setThinkingLevel: () => { },
+    };
+    // Import the compiled extension (same dist/extensions dir as this test).
+    const mod = require("./mega-compact.js");
+    mod.default(pi);
+    return {
+        stateDir, handlers, commands, appended, get status() { return { statusKey, statusText }; }, notifies,
+        fire: (ev, event, ctx) => handlers[ev](event, ctx),
+        ctx: makeCtx,
+        session,
+    };
+}
+test("auto-trigger: past threshold persists a chkpt and drops context", async () => {
+    const h = harness();
+    const messages = h.session;
+    const ctx = h.ctx({ getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }) });
+    const res = await h.fire("context", { type: "context", messages }, ctx);
+    // L1->L4 ran: a checkpoint was persisted to the SQLite store + a marker entry written.
+    const { listCheckpoints } = await import("../src/store/sqlite.js");
+    assert.ok(listCheckpoints("sess_ext_001", h.stateDir).length > 0, "checkpoint persisted to local vector db");
+    assert.equal(h.appended.some((a) => a.t === "mega-compact-marker"), true, "marker sentinel appended");
+    // Context dropped (the compacted range was trimmed).
+    assert.ok(res && Array.isArray(res.messages), "context handler returns filtered messages");
+    assert.ok(res.messages.length < messages.length, "outgoing context shrank");
+});
+test("session_before_compact cancels once we've persisted", async () => {
+    const h = harness();
+    const ctx = h.ctx();
+    // First fire the auto-trigger so a checkpoint is persisted this session.
+    await h.fire("context", { type: "context", messages: h.session }, h.ctx({ getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }) }));
+    // Now pi tries to compact natively — we must cancel (no double-compact).
+    const res = await h.fire("session_before_compact", { type: "session_before_compact", reason: "overflow", willRetry: true, preparation: {}, signal: undefined }, ctx);
+    assert.deepEqual(res, { cancel: true });
+});
+test("session_before_compact does NOT cancel when nothing persisted", async () => {
+    const h = harness();
+    const ctx = h.ctx();
+    // Do NOT fire context first; this session has no checkpoint.
+    const res = await h.fire("session_before_compact", { type: "session_before_compact", reason: "threshold", willRetry: false, preparation: {}, signal: undefined }, ctx);
+    assert.deepEqual(res, {});
+});
+test("resume auto-inline stages recall into the system prompt", async () => {
+    const h = harness();
+    // Seed a checkpoint first (simulate a prior session that compacted).
+    await h.fire("context", { type: "context", messages: h.session }, h.ctx({ getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }) }));
+    // Fresh resume: session_start with reason "resume".
+    const ctx = h.ctx();
+    await h.fire("session_start", { type: "session_start", reason: "resume", previousSessionFile: undefined }, ctx);
+    // The next before_agent_start must prepend the recalled block.
+    const res = await h.fire("before_agent_start", { type: "before_agent_start", prompt: "base system", images: undefined, systemPrompt: "base system", systemPromptOptions: {} }, ctx);
+    assert.ok(res && typeof res.systemPrompt === "string", "before_agent_start returns a systemPrompt");
+    assert.ok(res.systemPrompt.includes("Recalled context"), "recalled block injected into system prompt");
+});
+test("/recall-context reports and stages the top checkpoint", async () => {
+    const h = harness();
+    await h.fire("context", { type: "context", messages: h.session }, h.ctx({ getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }) }));
+    const ctx = h.ctx();
+    await h.commands["mega-recall"].handler("dedupe bug store.ts", ctx);
+    assert.ok(h.notifies.some((n) => n.includes("recall staged")), "command reports staged checkpoints");
+    assert.ok(h.notifies.some((n) => n.includes("chkpt_")), "command names the checkpoint");
+});
+test("/megacompact-status reports live store stats", async () => {
+    const h = harness();
+    await h.fire("context", { type: "context", messages: h.session }, h.ctx({ getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }) }));
+    const ctx = h.ctx({ getContextUsage: () => ({ tokens: 50000, contextWindow: 200000, percent: 25 }) });
+    await h.commands["mega-status"].handler("", ctx);
+    assert.ok(h.notifies.some((n) => n.includes("store:") && n.includes("chkpt")), "status shows checkpoint count");
+});
+// ---- Named compaction tiers -------------------------------------------------
+// low=50k, medium=100k, high=200k, ultra=1M, mega=10M. Driven through the REAL
+// loadConfig()/status path by setting MEGACOMPACT_TIER before loading the ext.
+const TIER_CASES = [
+    ["low", 50_000],
+    ["medium", 100_000],
+    ["high", 200_000],
+    ["ultra", 1_000_000],
+    ["mega", 10_000_000],
+];
+for (const [tier, threshold] of TIER_CASES) {
+    test(`tier "${tier}" resolves to a ${threshold}-token threshold`, async () => {
+        // Keep tier + keep threshold UNSET so the tier (not an explicit number)
+        // drives the threshold. harness() would otherwise reset the threshold.
+        delete process.env.MEGACOMPACT_THRESHOLD_TOKENS;
+        process.env.MEGACOMPACT_TIER = tier;
+        const h = harness({ keepTier: true, keepThreshold: true });
+        const ctx = h.ctx({ getContextUsage: () => ({ tokens: 1, contextWindow: 2_000_000, percent: 0.01 }) });
+        await h.commands["mega-status"].handler("", ctx);
+        delete process.env.MEGACOMPACT_TIER;
+        assert.ok(h.notifies.some((n) => n.includes(`tier=${tier}`) && n.includes(`threshold=${threshold}`)), `status should report tier=${tier} threshold=${threshold}`);
+    });
+}
+test("explicit MEGACOMPACT_THRESHOLD_TOKENS overrides the tier", async () => {
+    process.env.MEGACOMPACT_TIER = "mega";
+    process.env.MEGACOMPACT_THRESHOLD_TOKENS = "777";
+    const h = harness({ keepTier: true, keepThreshold: true });
+    const ctx = h.ctx({ getContextUsage: () => ({ tokens: 1, contextWindow: 2_000_000, percent: 0.01 }) });
+    await h.commands["mega-status"].handler("", ctx);
+    delete process.env.MEGACOMPACT_TIER;
+    assert.ok(h.notifies.some((n) => n.includes("tier=custom") && n.includes("threshold=777")), "explicit threshold wins over tier (tier=custom)");
+});
+// ---- /dashboard commands ----------------------------------------------------
+test("/dashboard-status reports no server when pid file missing", async () => {
+    const h = harness();
+    const ctx = h.ctx();
+    await h.commands["mega-dashboard-status"].handler("", ctx);
+    assert.ok(h.notifies.some((n) => n.includes("not running")), "reports no server running");
+});
+test("/dashboard-stop reports no server when pid file missing", async () => {
+    const h = harness();
+    const ctx = h.ctx();
+    await h.commands["mega-dashboard-stop"].handler("", ctx);
+    assert.ok(h.notifies.some((n) => n.includes("no dashboard server running")), "reports no server");
+});
+test("/dashboard skips server spawn when already running", async () => {
+    const h = harness();
+    const confirms = [];
+    // Set up a fake HTTP server at a random port
+    const { createServer } = await import("node:http");
+    const server = createServer((_req, res) => {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ updatedAt: new Date().toISOString(), tier: "test", version: 1, config: {}, session: {}, context: {}, trigger: {}, store: {} }));
+    });
+    await new Promise((r) => server.listen(0, "127.0.0.1", r));
+    const addr = server.address();
+    const { join: j } = await import("node:path");
+    const { writeFileSync: wf } = await import("node:fs");
+    wf(j(h.stateDir, "port.pid"), JSON.stringify({ port: addr.port, pid: process.pid }));
+    const ctx = h.ctx({
+        ui: {
+            setStatus: () => { },
+            notify: (s) => { h.notifies.push(s); },
+            select: () => { },
+            confirm: async () => { confirms.push(true); return true; },
+            input: async () => "",
+        },
+    });
+    await h.commands["mega-dashboard"].handler("", ctx);
+    assert.ok(h.notifies.some((n) => n.includes("already running")), "reports already running");
+    assert.ok(confirms.length > 0, "confirm dialog was shown");
+    await new Promise((r) => server.close(() => r()));
+});
+test("/dashboard-status reports running after dashboard start", async () => {
+    const h = harness();
+    // Write a fake port.pid with a real port (use a server we control)
+    const { createServer } = await import("node:http");
+    const { join: j } = await import("node:path");
+    const { writeFileSync: wf } = await import("node:fs");
+    const server = createServer((_req, res) => {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ updatedAt: new Date().toISOString(), tier: "test" }));
+    });
+    await new Promise((r) => server.listen(0, "127.0.0.1", r));
+    const addr = server.address();
+    wf(j(h.stateDir, "port.pid"), JSON.stringify({ port: addr.port, pid: process.pid }));
+    const ctx = h.ctx();
+    await h.commands["mega-dashboard-status"].handler("", ctx);
+    assert.ok(h.notifies.some((n) => n.includes("running") && n.includes(String(addr.port))), "reports running with port");
+    await new Promise((r) => server.close(() => r()));
+});
+test("state snapshot writes dashboard.json after compaction", async () => {
+    const h = harness();
+    const ctx = h.ctx({ getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }) });
+    // Fire auto-trigger compaction (context event above 80% threshold)
+    await h.fire("context", { type: "context", messages: h.session }, ctx);
+    const { existsSync: ex, readFileSync: rf } = await import("node:fs");
+    const { join: j } = await import("node:path");
+    const snapPath = j(h.stateDir, "dashboard.json");
+    assert.ok(ex(snapPath), "dashboard.json written after compaction");
+    const snap = JSON.parse(rf(snapPath, "utf-8"));
+    // Item B: the honest token model is wired — the original dropped region was
+    // captured (originalTokens > 0), and the saved amount never exceeds the
+    // original (saved = max(0, original − stored) ≤ original). For this tiny
+    // harness session the summary can be ≥ the region, so saved may be 0; the
+    // positive "saved > 0" case with a large region is covered by the
+    // vectorStore unit tests.
+    assert.ok(snap.store.originalTokens > 0, "snapshot.store.originalTokens captured after compaction");
+    assert.ok(snap.store.originalTokens >= snap.store.tokensSaved, "model invariant: original region >= tokens saved");
+    // Item A: crew (live agent) block is present in the dashboard snapshot.
+    assert.ok(snap.crew && typeof snap.crew.activeAgents === "number", "snapshot.crew.activeAgents present");
+});
+test("events.log receives compaction events", async () => {
+    const h = harness();
+    const ctx = h.ctx({ getContextUsage: () => ({ tokens: 200000, contextWindow: 200000, percent: 100 }) });
+    // Fire auto-trigger compaction twice (first fires compaction, second also fires)
+    await h.fire("context", { type: "context", messages: h.session }, ctx);
+    const { readFileSync: rf, existsSync: ex } = await import("node:fs");
+    const { join: j } = await import("node:path");
+    const logPath = j(h.stateDir, "events.log");
+    if (ex(logPath)) {
+        const content = rf(logPath, "utf-8").trim();
+        // At minimum, we expect at least one event logged
+        assert.ok(content.length > 0, "events.log is non-empty after compaction");
+    }
+    else {
+        // events.log may not exist if the DashboardEmitter path differs from stateDir;
+        // verify dashboard.json was written (proves the post-compact path executed)
+        assert.ok(ex(j(h.stateDir, "dashboard.json")), "dashboard.json proves post-compact ran");
+    }
+});
+test("cleanup", () => {
+    rmSync(baseTmp, { recursive: true, force: true });
+});

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

@@ -0,0 +1,291 @@
+/**
+ * openclaw-mega-compact — OpenClaw plugin adapter for the pi-mega-compact engine.
+ *
+ * Wires the pi-agnostic Trident engine (src/) into OpenClaw's plugin lifecycle:
+ *  - Registers a CompactionProvider that replaces the built-in summarizeInStages.
+ *  - Exposes `mega_status` and `mega_recall` tools for on-demand inspection.
+ *  - Hooks into `before_compaction` / `after_compaction` for diagnostics.
+ *
+ * Design constraints:
+ *  - NO imports from `@earendil-works/pi-coding-agent` or pi-agent-core.
+ *  - The engine core (src/) is pi-agnostic; this file is the sole OpenClaw boundary.
+ *  - No network at runtime — everything is local (stores + extractive summarizer).
+ */
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { compactSession, setDefaultStore, } from "../src/engine.js";
+import { recallAndInline } from "../src/recall.js";
+import { VectorStore } from "../src/vectorStore.js";
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const PLUGIN_ID = "mega-compact";
+const PLUGIN_LABEL = "Mega Compact (Trident)";
+/** Default state directory for vector store persistence. */
+const STATE_DIR = process.env.MEGA_COMPACT_STATE_DIR ?? undefined;
+/** Minimum messages before we bother compacting. */
+const MIN_MESSAGES_FOR_COMPACT = 6;
+// ---------------------------------------------------------------------------
+// Message conversion — OpenClaw unknown[] → EngineMessage[]
+// ---------------------------------------------------------------------------
+/**
+ * Best-effort conversion from OpenClaw's opaque message array to our
+ * EngineMessage shape. OpenClaw messages are typed as `unknown[]` so we
+ * handle whatever shape comes through gracefully.
+ */
+function toEngineMessages(messages) {
+    return messages.map((msg) => {
+        if (!msg || typeof msg !== "object") {
+            // Primitive fallback — treat as custom text.
+            return {
+                role: "custom",
+                text: String(msg ?? ""),
+            };
+        }
+        const m = msg;
+        const role = typeof m.role === "string" ? m.role : "custom";
+        // Normalize role to one of our four engine roles.
+        let engineRole;
+        switch (role) {
+            case "user":
+                engineRole = "user";
+                break;
+            case "assistant":
+                engineRole = "assistant";
+                break;
+            case "tool":
+            case "function":
+                engineRole = "tool";
+                break;
+            default:
+                engineRole = "custom";
+                break;
+        }
+        // Extract text content from common message shapes.
+        const text = typeof m.content === "string"
+            ? m.content
+            : typeof m.text === "string"
+                ? m.text
+                : Array.isArray(m.content)
+                    ? m.content
+                        .filter((part) => part.type === "text" && typeof part.text === "string")
+                        .map((part) => part.text)
+                        .join("\n")
+                    : "";
+        // Preserve tool metadata when present.
+        const toolName = typeof m.name === "string"
+            ? m.name
+            : typeof m.toolName === "string"
+                ? m.toolName
+                : undefined;
+        const input = typeof m.input === "string"
+            ? m.input
+            : typeof m.arguments === "string"
+                ? m.arguments
+                : m.arguments !== undefined
+                    ? JSON.stringify(m.arguments)
+                    : undefined;
+        const output = typeof m.output === "string"
+            ? m.output
+            : engineRole === "tool" && typeof m.content === "string"
+                ? m.content
+                : undefined;
+        return { role: engineRole, text, toolName, input, output };
+    });
+}
+// ---------------------------------------------------------------------------
+// Compaction provider
+// ---------------------------------------------------------------------------
+function createCompactionProvider(store) {
+    return {
+        id: PLUGIN_ID,
+        label: PLUGIN_LABEL,
+        async summarize({ messages, signal, compressionRatio, }) {
+            // Abort check — bail early if the caller cancelled.
+            if (signal?.aborted) {
+                throw new DOMException("Aborted", "AbortError");
+            }
+            const engineMessages = toEngineMessages(messages);
+            // Nothing meaningful to compact.
+            if (engineMessages.length < MIN_MESSAGES_FOR_COMPACT) {
+                return "";
+            }
+            // Map compression ratio → keepFrom boundary.
+            // compressionRatio=0.5 means "compact the oldest 50%".
+            // Default to compacting the oldest half if not specified.
+            const ratio = compressionRatio ?? 0.5;
+            const keepFrom = Math.max(MIN_MESSAGES_FOR_COMPACT, Math.floor(engineMessages.length * (1 - ratio)));
+            // Abort check after conversion (conversion is cheap but check anyway).
+            if (signal?.aborted) {
+                throw new DOMException("Aborted", "AbortError");
+            }
+            const sessionId = `openclaw-${Date.now()}`;
+            const input = {
+                sessionId,
+                messages: engineMessages,
+                keepFrom,
+            };
+            const result = compactSession(input, store);
+            if (result.skipped) {
+                return "";
+            }
+            return result.summary;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Plugin entry
+// ---------------------------------------------------------------------------
+export default definePluginEntry({
+    id: PLUGIN_ID,
+    name: "Mega Compact",
+    description: "Layered, local, vector-backed context compressor (Trident engine) for OpenClaw compaction.",
+    register(api) {
+        const logger = api.logger;
+        // Resolve state directory — prefer plugin config override.
+        const pluginCfg = (api.pluginConfig ?? {});
+        const stateDir = typeof pluginCfg.stateDir === "string" && pluginCfg.stateDir.length > 0
+            ? pluginCfg.stateDir
+            : STATE_DIR;
+        // Initialize vector store.
+        let store;
+        try {
+            store = new VectorStore({ stateDir });
+            setDefaultStore(store);
+            logger.info?.(`${PLUGIN_ID}: vector store initialized (stateDir=${stateDir ?? "default"})`);
+        }
+        catch (err) {
+            logger.error?.(`${PLUGIN_ID}: failed to init vector store:`, err);
+            return; // Hard bail — no point registering if store is broken.
+        }
+        // -----------------------------------------------------------------------
+        // Register compaction provider
+        // -----------------------------------------------------------------------
+        const provider = createCompactionProvider(store);
+        api.registerCompactionProvider(provider);
+        logger.info?.(`${PLUGIN_ID}: registered compaction provider "${provider.id}"`);
+        // -----------------------------------------------------------------------
+        // Hooks — before / after compaction diagnostics
+        // -----------------------------------------------------------------------
+        api.registerHook({
+            event: "before_compaction",
+            handler: async (ctx) => {
+                const msgCount = Array.isArray(ctx?.messages) ? ctx.messages.length : 0;
+                logger.info?.(`${PLUGIN_ID}: before_compaction — ${msgCount} messages in scope`);
+            },
+        });
+        api.registerHook({
+            event: "after_compaction",
+            handler: async (ctx) => {
+                const summaryLen = typeof ctx?.summary === "string" ? ctx.summary.length : 0;
+                logger.info?.(`${PLUGIN_ID}: after_compaction — summary ${summaryLen} chars`);
+            },
+        });
+        // -----------------------------------------------------------------------
+        // Tool: mega_status
+        // -----------------------------------------------------------------------
+        api.registerTool({
+            name: "mega_status",
+            description: "Show the current status of the mega-compact engine: vector store stats, checkpoint count, and recent compaction activity.",
+            parameters: {
+                type: "object",
+                properties: {
+                    sessionId: {
+                        type: "string",
+                        description: "Optional session ID to scope stats to.",
+                    },
+                },
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const sessionId = args?.sessionId ?? "global";
+                try {
+                    const stats = store.stats(sessionId);
+                    const parts = [
+                        `**Mega Compact Status**`,
+                        `Session: ${sessionId}`,
+                        `Checkpoints: ${stats.checkpointCount}`,
+                        `Total tokens saved: ${stats.totalTokenEstimate}`,
+                        `Last checkpoint: ${stats.lastCheckpointId ?? "—"}`,
+                        `Injected count: ${stats.injectedCount}`,
+                        `Dedup hit rate: ${(stats.dedupHitRate * 100).toFixed(0)}%`,
+                    ];
+                    if (stats.lastSummary) {
+                        parts.push(`\nLast summary (truncated):\n  ${stats.lastSummary.slice(0, 120).replace(/\n/g, " ")}…`);
+                    }
+                    return { content: [{ type: "text", text: parts.join("\n") }] };
+                }
+                catch (err) {
+                    return {
+                        content: [{ type: "text", text: `Error reading mega-compact status: ${err}` }],
+                        isError: true,
+                    };
+                }
+            },
+        });
+        // -----------------------------------------------------------------------
+        // Tool: mega_recall
+        // -----------------------------------------------------------------------
+        api.registerTool({
+            name: "mega_recall",
+            description: "Recall and inline relevant context from the mega-compact vector store for the current session.",
+            parameters: {
+                type: "object",
+                properties: {
+                    sessionId: {
+                        type: "string",
+                        description: "Session ID to recall context for.",
+                    },
+                    query: {
+                        type: "string",
+                        description: "Natural language query for relevant context.",
+                    },
+                    limit: {
+                        type: "number",
+                        description: "Max checkpoints to recall (default 3).",
+                    },
+                },
+                required: ["sessionId", "query"],
+                additionalProperties: false,
+            },
+            handler: async (args) => {
+                const { sessionId, query, limit } = args;
+                if (!sessionId || !query) {
+                    return {
+                        content: [{ type: "text", text: "Both `sessionId` and `query` are required." }],
+                        isError: true,
+                    };
+                }
+                try {
+                    const result = recallAndInline({ sessionId, query, limit: limit ?? 3, source: "command", skipInjected: false }, store);
+                    if (result.toInject.length === 0) {
+                        return {
+                            content: [{ type: "text", text: "No relevant context found in the mega-compact store." }],
+                        };
+                    }
+                    const parts = [
+                        `**Recalled ${result.toInject.length} checkpoint(s):**`,
+                        ...result.report,
+                        "",
+                        "---",
+                        result.block,
+                    ];
+                    return { content: [{ type: "text", text: parts.join("\n") }] };
+                }
+                catch (err) {
+                    return {
+                        content: [{ type: "text", text: `Error during mega-recall: ${err}` }],
+                        isError: true,
+                    };
+                }
+            },
+        });
+        // -----------------------------------------------------------------------
+        // Cleanup on shutdown
+        // -----------------------------------------------------------------------
+        api.on("shutdown", () => {
+            logger.info?.(`${PLUGIN_ID}: shutting down — clearing default store`);
+            setDefaultStore(undefined);
+        });
+        logger.info?.(`${PLUGIN_ID}: plugin registered (tools: mega_status, mega_recall)`);
+    },
+});