@wolfx/opencode-magic-context 0.21.8-patch.1

package/dist/tui/data/context-db.d.ts

@@ -0,0 +1,36 @@
+import type { SidebarSnapshot, StatusDetail } from "../../shared/rpc-types";
+export type { SidebarSnapshot, StatusDetail };
+/** Initialize the RPC client. Call once on TUI startup. */
+export declare function initRpcClient(directory: string): void;
+/** Clean up the RPC client. */
+export declare function closeRpc(): void;
+/** Fetch sidebar snapshot from the server via RPC. */
+export declare function loadSidebarSnapshot(sessionId: string, directory: string): Promise<SidebarSnapshot>;
+/** Fetch full status detail from the server via RPC. */
+export declare function loadStatusDetail(sessionId: string, directory: string, modelKey?: string): Promise<StatusDetail>;
+/** Get compartment count via RPC. */
+export declare function getCompartmentCount(sessionId: string): Promise<number>;
+/** Send recomp request to server via RPC. */
+export declare function requestRecomp(sessionId: string): Promise<boolean>;
+export interface TuiMessage {
+    type: string;
+    payload: Record<string, unknown>;
+    sessionId?: string;
+}
+/**
+ * Fetch the current startup announcement from the server, if any.
+ * Returns `{show: false}` when there's nothing to announce or when the
+ * configured ANNOUNCEMENT_VERSION has already been dismissed.
+ */
+export interface AnnouncementResponse {
+    show: boolean;
+    version?: string;
+    features?: string[];
+    footer?: string;
+}
+export declare function getAnnouncement(): Promise<AnnouncementResponse>;
+/** Mark the current ANNOUNCEMENT_VERSION as dismissed on the server. */
+export declare function markAnnounced(): Promise<boolean>;
+/** Poll for pending server→TUI notifications via RPC. */
+export declare function consumeTuiMessages(): Promise<TuiMessage[]>;
+//# sourceMappingURL=context-db.d.ts.map

package/dist/tui/data/context-db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-db.d.ts","sourceRoot":"","sources":["../../../src/tui/data/context-db.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAA0B,eAAe,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEpG,YAAY,EAAE,eAAe,EAAE,YAAY,EAAE,CAAC;AAc9C,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAGrD;AAED,+BAA+B;AAC/B,wBAAgB,QAAQ,IAAI,IAAI,CAI/B;AA0FD,sDAAsD;AACtD,wBAAsB,mBAAmB,CACrC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAClB,OAAO,CAAC,eAAe,CAAC,CA4B1B;AAED,wDAAwD;AACxD,wBAAsB,gBAAgB,CAClC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,MAAM,GAClB,OAAO,CAAC,YAAY,CAAC,CA4CvB;AAED,qCAAqC;AACrC,wBAAsB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ5E;AAED,6CAA6C;AAC7C,wBAAsB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQvE;AAED,MAAM,WAAW,UAAU;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,eAAe,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAkBrE;AAED,wEAAwE;AACxE,wBAAsB,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,CAQtD;AAED,yDAAyD;AACzD,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC,CAqBhE"}

package/package.json

@@ -0,0 +1,80 @@
+{
+	"name": "@wolfx/opencode-magic-context",
+	"version": "0.21.8-patch.1",
+	"type": "module",
+	"description": "OpenCode plugin for Magic Context — cross-session memory and context management",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"author": "ualtinok",
+	"license": "MIT",
+	"keywords": [
+		"opencode",
+		"plugin",
+		"context",
+		"memory",
+		"ai",
+		"llm",
+		"prompt-caching",
+		"session-history"
+	],
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/cortexkit/magic-context",
+		"directory": "packages/plugin"
+	},
+	"files": [
+		"dist",
+		"src/tui",
+		"src/shared",
+		"README.md"
+	],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+	"scripts": {
+		"build": "bun build src/index.ts --outdir dist --target node --format esm --external @opencode-ai/plugin --external @huggingface/transformers --external onnxruntime-web --external better-sqlite3 --external bun:sqlite && tsc --emitDeclarationOnly",
+		"typecheck": "tsc --noEmit && tsc -p tsconfig.scripts.json",
+		"test": "bun test",
+		"lint": "biome check .",
+		"lint:fix": "biome check --write .",
+		"format": "biome format --write .",
+		"format:check": "biome format .",
+		"clean": "rm -rf dist",
+		"prepublishOnly": "bun run build"
+	},
+	"dependencies": {
+		"@huggingface/transformers": "^4.1.0",
+		"@opencode-ai/plugin": "^1.14.39",
+		"@opencode-ai/sdk": "^1.14.39",
+		"ai-tokenizer": "^1.0.6",
+		"better-sqlite3": "^12.9.0",
+		"comment-json": "^4.2.5",
+		"nanotar": "^0.3.0",
+		"zod": "^4.1.8"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.4.7",
+		"@types/better-sqlite3": "^7.6.13",
+		"@types/node": "^22.0.0",
+		"bun-types": "^1.3.10",
+		"typescript": "^5.8.0"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./tui": {
+			"types": "./src/tui/index.tsx",
+			"import": "./src/tui/index.tsx"
+		}
+	},
+	"oc-plugin": [
+		"server",
+		"tui"
+	],
+	"peerDependencies": {
+		"@opencode-ai/plugin": ">=1.14.0"
+	}
+}

package/src/shared/announcement.test.ts

@@ -0,0 +1,143 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+/**
+ * `announcement.ts` reads/writes a single `last_announced_version` file under
+ * `getMagicContextStorageDir()`. The behavior we test:
+ *   1. `markAnnouncementSeen` then `readLastAnnouncedVersion` round-trips
+ *   2. `shouldShowAnnouncement` returns false after a matching mark
+ *   3. `shouldShowAnnouncement` returns true after a non-matching mark
+ *   4. Empty-version inputs are no-ops (don't crash, don't write garbage)
+ *
+ * We isolate writes by pointing `XDG_DATA_HOME` at a temp dir before requiring
+ * the module fresh per test, since the module captures the storage path at
+ * import time via `getMagicContextStorageDir()`.
+ */
+
+let tmpRoot = "";
+let originalXdg: string | undefined;
+
+beforeEach(() => {
+    tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "mc-announcement-test-"));
+    originalXdg = process.env.XDG_DATA_HOME;
+    process.env.XDG_DATA_HOME = tmpRoot;
+});
+
+afterEach(() => {
+    if (originalXdg === undefined) {
+        delete process.env.XDG_DATA_HOME;
+    } else {
+        process.env.XDG_DATA_HOME = originalXdg;
+    }
+    try {
+        fs.rmSync(tmpRoot, { recursive: true, force: true });
+    } catch {
+        // best-effort
+    }
+});
+
+describe("announcement state persistence", () => {
+    test("round-trips a dismissed version through the file", async () => {
+        // Fresh import after XDG override so the module captures the temp path
+        const mod = await import(`./announcement?t=${Date.now()}-rt`);
+        const { readLastAnnouncedVersion, markAnnouncementSeen } = mod;
+
+        expect(readLastAnnouncedVersion()).toBe("");
+
+        markAnnouncementSeen("9.9.9");
+        expect(readLastAnnouncedVersion()).toBe("9.9.9");
+
+        markAnnouncementSeen("9.9.10");
+        expect(readLastAnnouncedVersion()).toBe("9.9.10");
+    });
+
+    test("ignores empty / zero-length version marks", async () => {
+        const mod = await import(`./announcement?t=${Date.now()}-empty`);
+        const { readLastAnnouncedVersion, markAnnouncementSeen } = mod;
+
+        markAnnouncementSeen("");
+        expect(readLastAnnouncedVersion()).toBe("");
+    });
+
+    test("creates the storage directory if it does not exist", async () => {
+        const mod = await import(`./announcement?t=${Date.now()}-mkdir`);
+        const { markAnnouncementSeen } = mod;
+
+        // Storage dir lives under tmpRoot + cortexkit/magic-context — does not
+        // exist yet at the start of the test
+        const expectedDir = path.join(tmpRoot, "cortexkit", "magic-context");
+        expect(fs.existsSync(expectedDir)).toBe(false);
+
+        markAnnouncementSeen("0.21.7");
+
+        expect(fs.existsSync(expectedDir)).toBe(true);
+        expect(fs.readFileSync(path.join(expectedDir, "last_announced_version"), "utf-8")).toBe(
+            "0.21.7",
+        );
+    });
+
+    test("trims whitespace from stored version on read", async () => {
+        const mod = await import(`./announcement?t=${Date.now()}-trim`);
+        const { readLastAnnouncedVersion } = mod;
+
+        const dir = path.join(tmpRoot, "cortexkit", "magic-context");
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, "last_announced_version"), "  1.2.3  \n");
+
+        expect(readLastAnnouncedVersion()).toBe("1.2.3");
+    });
+});
+
+describe("shouldShowAnnouncement gating", () => {
+    test("returns false when the live version is already marked", async () => {
+        const mod = await import(`./announcement?t=${Date.now()}-match`);
+        const {
+            ANNOUNCEMENT_VERSION,
+            ANNOUNCEMENT_FEATURES,
+            markAnnouncementSeen,
+            shouldShowAnnouncement,
+        } = mod;
+
+        // Skip the test if announcements are currently disabled (empty constants)
+        // — the gate's empty-input behavior is covered separately below.
+        if (!ANNOUNCEMENT_VERSION || ANNOUNCEMENT_FEATURES.length === 0) {
+            return;
+        }
+
+        markAnnouncementSeen(ANNOUNCEMENT_VERSION);
+        expect(shouldShowAnnouncement()).toBe(false);
+    });
+
+    test("returns true when the live version was never marked", async () => {
+        const mod = await import(`./announcement?t=${Date.now()}-none`);
+        const { ANNOUNCEMENT_VERSION, ANNOUNCEMENT_FEATURES, shouldShowAnnouncement } = mod;
+
+        if (!ANNOUNCEMENT_VERSION || ANNOUNCEMENT_FEATURES.length === 0) {
+            // When empty, the gate is always false regardless of state
+            expect(shouldShowAnnouncement()).toBe(false);
+            return;
+        }
+
+        // No mark has been written in this fresh tmpRoot, so the gate is open
+        expect(shouldShowAnnouncement()).toBe(true);
+    });
+
+    test("returns true when a different (older) version is marked", async () => {
+        const mod = await import(`./announcement?t=${Date.now()}-older`);
+        const {
+            ANNOUNCEMENT_VERSION,
+            ANNOUNCEMENT_FEATURES,
+            markAnnouncementSeen,
+            shouldShowAnnouncement,
+        } = mod;
+
+        if (!ANNOUNCEMENT_VERSION || ANNOUNCEMENT_FEATURES.length === 0) {
+            return;
+        }
+
+        markAnnouncementSeen("0.0.0-pre-historic");
+        expect(shouldShowAnnouncement()).toBe(true);
+    });
+});

package/src/shared/announcement.ts

@@ -0,0 +1,97 @@
+/**
+ * Release-notes startup announcement shared by OpenCode plugin and Pi plugin.
+ *
+ * Bump `ANNOUNCEMENT_VERSION` and populate `ANNOUNCEMENT_FEATURES` *only* when a
+ * release ships user-facing news worth surfacing once at startup. Patch releases
+ * with no user-visible changes should leave both untouched — that way a user who
+ * already dismissed the dialog for the current `ANNOUNCEMENT_VERSION` won't see
+ * it again on the next bugfix bump.
+ *
+ * The persisted state is a single line of text (`last_announced_version`) under
+ * `getMagicContextStorageDir()`. OpenCode and Pi share the same file because
+ * they share the same storage root — so dismissing in one harness suppresses
+ * the dialog in the other for the same announcement.
+ *
+ * Leave both empty (`""` and `[]`) to skip the dialog entirely.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getMagicContextStorageDir } from "./data-path";
+
+/**
+ * Bump only when there are user-visible changes worth a startup dialog.
+ * Does NOT need to match the published package version.
+ */
+export const ANNOUNCEMENT_VERSION = "0.21.7";
+
+/**
+ * Short, user-facing bullet strings. Keep each line ~80 chars or shorter so the
+ * TUI dialog renders cleanly without horizontal scroll on a typical terminal.
+ */
+export const ANNOUNCEMENT_FEATURES: ReadonlyArray<string> = [
+    "Pi parity sweep: 44 audit findings fixed, including a critical SHIP-BLOCKER where /ctx-flush did not drain the pending Pi compaction queue.",
+    "Pi historian recovery fix: empty/no-op historian returns now clear emergency recovery so sessions cannot loop forever at 95%.",
+    "trimPiMessagesToBoundary now sweeps non-contiguous tool-result orphans, fixing provider 400s after compaction in long Pi sessions.",
+    "Hidden subagent tool isolation: historian, dreamer, and sidekick can no longer spawn subagents or run unsafe tools.",
+    "TUI sidebar and /ctx-status header now show execute threshold inline: '47.5% / 65%' on the left, '475K / 1.0M' on the right.",
+    "doctor --issue now caps GitHub issue bodies at ~60KB with a dedicated 'Recent errors' section so reports stay submittable.",
+];
+
+/**
+ * Persistent footer rendered below the version-specific bullets in every
+ * announcement. Stays in place across releases so users always see the Discord
+ * invite without us needing to repeat it in `ANNOUNCEMENT_FEATURES` each time.
+ *
+ * Leave empty (`""`) to suppress the footer.
+ */
+export const ANNOUNCEMENT_FOOTER = "Join us on Discord: https://discord.gg/F2uWxjGnU";
+
+const STATE_FILENAME = "last_announced_version";
+
+function getStateFilePath(): string {
+    return path.join(getMagicContextStorageDir(), STATE_FILENAME);
+}
+
+/**
+ * Read the most recently dismissed announcement version, or `""` if none.
+ *
+ * Best-effort: any read failure returns `""` (which forces the announcement to
+ * re-show). The cost of a spurious second dialog is much smaller than the cost
+ * of suppressing a real announcement due to a transient FS error.
+ */
+export function readLastAnnouncedVersion(): string {
+    try {
+        const file = getStateFilePath();
+        if (!fs.existsSync(file)) return "";
+        return fs.readFileSync(file, "utf-8").trim();
+    } catch {
+        return "";
+    }
+}
+
+/**
+ * Persist `version` as the most recently dismissed announcement. Best-effort:
+ * write failures are swallowed so dialog-confirm flows never throw on storage
+ * errors. Worst case the user sees the same dialog once more on next startup.
+ */
+export function markAnnouncementSeen(version: string): void {
+    if (!version) return;
+    try {
+        const dir = getMagicContextStorageDir();
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(getStateFilePath(), version);
+    } catch {
+        // best-effort
+    }
+}
+
+/**
+ * True when the configured `ANNOUNCEMENT_VERSION` has not yet been dismissed
+ * AND there is at least one feature to show. Used by both the TUI dialog path
+ * and the Desktop ignored-message fallback.
+ */
+export function shouldShowAnnouncement(): boolean {
+    if (!ANNOUNCEMENT_VERSION || ANNOUNCEMENT_FEATURES.length === 0) return false;
+    return readLastAnnouncedVersion() !== ANNOUNCEMENT_VERSION;
+}

package/src/shared/assistant-message-extractor.ts

@@ -0,0 +1,74 @@
+type MessageTime = { created?: number };
+
+type MessageInfo = {
+    role?: string;
+    time?: MessageTime;
+};
+
+type MessagePart = {
+    type?: string;
+    text?: string;
+};
+
+type SessionMessage = {
+    info?: MessageInfo;
+    parts?: unknown;
+};
+
+import { isRecord } from "./record-type-guard";
+
+function asSessionMessage(value: unknown): SessionMessage | null {
+    if (!isRecord(value)) return null;
+    const info = value.info;
+    const parts = value.parts;
+    return {
+        info: isRecord(info)
+            ? {
+                  role: typeof info.role === "string" ? info.role : undefined,
+                  time: isRecord(info.time)
+                      ? {
+                            created:
+                                typeof info.time.created === "number"
+                                    ? info.time.created
+                                    : undefined,
+                        }
+                      : undefined,
+              }
+            : undefined,
+        parts,
+    };
+}
+
+function getCreatedTime(message: SessionMessage): number {
+    return message.info?.time?.created ?? 0;
+}
+
+function getTextParts(message: SessionMessage): MessagePart[] {
+    if (!Array.isArray(message.parts)) return [];
+    return message.parts
+        .filter((part): part is Record<string, unknown> => isRecord(part))
+        .map((part) => ({
+            type: typeof part.type === "string" ? part.type : undefined,
+            text: typeof part.text === "string" ? part.text : undefined,
+        }))
+        .filter((part) => part.type === "text" && Boolean(part.text));
+}
+
+export function extractLatestAssistantText(messages: unknown): string | null {
+    if (!Array.isArray(messages) || messages.length === 0) return null;
+
+    const assistantMessages = messages
+        .map(asSessionMessage)
+        .filter((message): message is SessionMessage => message !== null)
+        .filter((message) => message.info?.role === "assistant")
+        .sort((a, b) => getCreatedTime(b) - getCreatedTime(a));
+
+    const latest = assistantMessages[0];
+    if (!latest) return null;
+
+    return (
+        getTextParts(latest)
+            .map((part) => part.text)
+            .join("\n") || null
+    );
+}

package/src/shared/bounded-session-map.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "bun:test";
+import { BoundedSessionMap } from "./bounded-session-map";
+
+describe("BoundedSessionMap", () => {
+    it("rejects non-positive caps", () => {
+        expect(() => new BoundedSessionMap(0)).toThrow();
+        expect(() => new BoundedSessionMap(-5)).toThrow();
+        expect(() => new BoundedSessionMap(Number.NaN)).toThrow();
+    });
+
+    it("stores and retrieves values", () => {
+        const map = new BoundedSessionMap<number>(3);
+        map.set("a", 1);
+        map.set("b", 2);
+        expect(map.get("a")).toBe(1);
+        expect(map.get("b")).toBe(2);
+        expect(map.get("missing")).toBeUndefined();
+        expect(map.size).toBe(2);
+    });
+
+    it("evicts the oldest entry when cap is exceeded", () => {
+        const map = new BoundedSessionMap<string>(3);
+        map.set("a", "alpha");
+        map.set("b", "bravo");
+        map.set("c", "charlie");
+        map.set("d", "delta"); // evicts "a"
+        expect(map.has("a")).toBe(false);
+        expect(map.has("b")).toBe(true);
+        expect(map.has("c")).toBe(true);
+        expect(map.has("d")).toBe(true);
+        expect(map.size).toBe(3);
+    });
+
+    it("treats get() as a touch for LRU ordering", () => {
+        const map = new BoundedSessionMap<string>(3);
+        map.set("a", "alpha");
+        map.set("b", "bravo");
+        map.set("c", "charlie");
+        // Touch "a" — now "b" is the oldest.
+        expect(map.get("a")).toBe("alpha");
+        map.set("d", "delta");
+        expect(map.has("b")).toBe(false);
+        expect(map.has("a")).toBe(true);
+        expect(map.has("c")).toBe(true);
+        expect(map.has("d")).toBe(true);
+    });
+
+    it("peek() does NOT touch recency", () => {
+        const map = new BoundedSessionMap<number>(3);
+        map.set("a", 1);
+        map.set("b", 2);
+        map.set("c", 3);
+        expect(map.peek("a")).toBe(1);
+        // Adding a fourth entry should still evict "a" since peek didn't touch it.
+        map.set("d", 4);
+        expect(map.has("a")).toBe(false);
+    });
+
+    it("set() on existing key refreshes recency without growing size", () => {
+        const map = new BoundedSessionMap<number>(3);
+        map.set("a", 1);
+        map.set("b", 2);
+        map.set("c", 3);
+        map.set("a", 100); // refresh "a" to most-recent with new value
+        expect(map.size).toBe(3);
+        expect(map.get("a")).toBe(100);
+        map.set("d", 4); // evicts "b" (now oldest)
+        expect(map.has("b")).toBe(false);
+        expect(map.has("a")).toBe(true);
+    });
+
+    it("delete() removes entries and returns true when present", () => {
+        const map = new BoundedSessionMap<number>(3);
+        map.set("a", 1);
+        expect(map.delete("a")).toBe(true);
+        expect(map.delete("a")).toBe(false);
+        expect(map.size).toBe(0);
+    });
+
+    it("clear() drops all entries", () => {
+        const map = new BoundedSessionMap<number>(3);
+        map.set("a", 1);
+        map.set("b", 2);
+        map.clear();
+        expect(map.size).toBe(0);
+        expect(map.get("a")).toBeUndefined();
+    });
+
+    it("tolerates cap=1 edge case (every set evicts previous)", () => {
+        const map = new BoundedSessionMap<number>(1);
+        map.set("a", 1);
+        map.set("b", 2);
+        expect(map.has("a")).toBe(false);
+        expect(map.get("b")).toBe(2);
+        expect(map.size).toBe(1);
+    });
+});

package/src/shared/bounded-session-map.ts

@@ -0,0 +1,84 @@
+/**
+ * Bounded LRU map keyed by session id.
+ *
+ * Rationale: magic-context maintains several module-scope Maps that track
+ * per-session state (prepared injection cache, per-message token cache, etc.).
+ * These are cleared on the `session.deleted` event, but sessions that are
+ * never explicitly deleted — because OpenCode crashed, the user force-quit,
+ * the session was archived rather than deleted, or the session simply outlived
+ * the plugin process's interest in it — leak entries for the lifetime of the
+ * plugin process.
+ *
+ * In long-running OpenCode instances with thousands of sessions over time,
+ * an unbounded `Map<sessionId, LargeObject>` can retain tens of megabytes
+ * indefinitely. A session-scoped LRU with a generous cap (e.g. 100) covers
+ * any realistic working-set of active sessions a user actually cares about,
+ * while evicting cold session ids that will either never return or be
+ * rebuilt from durable SQLite state on their next transform pass.
+ *
+ * Implementation notes:
+ * - Built on `Map` which preserves insertion order. On every `set`/`get`
+ *   touch we delete+reinsert to move the key to the tail (most-recent).
+ * - Eviction drops the oldest entry (first in iteration order).
+ * - The cached value type is generic — callers decide what per-session state
+ *   to store. For injection/token state, all three properties of the cached
+ *   object are safe to throw away: they are either recomputable from the
+ *   messages array on the next pass, or reloadable from SQLite.
+ */
+export class BoundedSessionMap<V> {
+    private readonly maxEntries: number;
+    private readonly store = new Map<string, V>();
+
+    constructor(maxEntries: number) {
+        if (!Number.isFinite(maxEntries) || maxEntries < 1) {
+            throw new Error(`BoundedSessionMap: maxEntries must be >= 1, got ${maxEntries}`);
+        }
+        this.maxEntries = maxEntries;
+    }
+
+    get(sessionId: string): V | undefined {
+        const value = this.store.get(sessionId);
+        if (value === undefined) return undefined;
+        // Touch: move to most-recent position.
+        this.store.delete(sessionId);
+        this.store.set(sessionId, value);
+        return value;
+    }
+
+    /**
+     * Peek without touching recency — useful for `has`-style checks that
+     * should not rearrange LRU order. Use sparingly; `get` is the normal
+     * access path.
+     */
+    peek(sessionId: string): V | undefined {
+        return this.store.get(sessionId);
+    }
+
+    has(sessionId: string): boolean {
+        return this.store.has(sessionId);
+    }
+
+    set(sessionId: string, value: V): void {
+        if (this.store.has(sessionId)) {
+            // Refresh recency.
+            this.store.delete(sessionId);
+        } else if (this.store.size >= this.maxEntries) {
+            // Evict oldest entry. Map iteration is insertion-ordered.
+            const oldest = this.store.keys().next().value;
+            if (oldest !== undefined) this.store.delete(oldest);
+        }
+        this.store.set(sessionId, value);
+    }
+
+    delete(sessionId: string): boolean {
+        return this.store.delete(sessionId);
+    }
+
+    clear(): void {
+        this.store.clear();
+    }
+
+    get size(): number {
+        return this.store.size;
+    }
+}