n2n-nexus 0.4.2 → 0.7.0

package/build/server/nexus.js

@@ -1,97 +1,293 @@
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { NexusClient } from "../client/nexus-client.js";
+import { randomUUID } from "node:crypto";
+import { CLIENT_INFO_META_KEY, ProtocolError, ProtocolErrorCode, Server, } from "@modelcontextprotocol/server";
+import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { NexusClient, NexusToolError, NexusTransportError } from "../client/nexus-client.js";
 import { pkg } from "../config/index.js";
+import { resolveInstanceId } from "./instance-id.js";
 const RETRY_INTERVAL_MS = 3000;
+const HEARTBEAT_INTERVAL_MS = 20_000;
+/** How long the first tools/list waits for the startup daemon fetch before answering with what it has. */
+const INITIAL_LIST_WAIT_MS = 1000;
 const SERVICE_NAME = "n2n-nexus";
+/**
+ * MCP adapter in front of the daemon, with one addressable session per connection.
+ *
+ * Served through the v2 SDK's serveStdio entry, which answers both
+ * protocol eras on one connection: 2026-07-28 clients (per-request `_meta`
+ * envelope, `server/discover`, `subscriptions/listen`) and 2025-era clients
+ * (`initialize` handshake).
+ */
 export class NexusServer {
-    server;
+    server = null;
+    handle = null;
     client;
-    instanceId;
     cachedTools = [];
     retryTimer = null;
+    /** True while a reconnect loop is active (waiting or attempting). */
+    retrying = false;
+    retryIntervalMs;
+    heartbeatIntervalMs;
+    sessionId = randomUUID();
+    instanceId;
+    workspace = process.cwd();
+    heartbeatTimer = null;
+    registration = null;
+    registrationAttempted = false;
+    shutdownPromise = null;
     connected = false;
-    constructor() {
+    stopped = false;
+    /**
+     * First client name seen on this stdio connection. clientInfo is only a
+     * SHOULD per request under 2026-07-28, so a request without it must not
+     * fall back to a different instance id than its siblings.
+     */
+    clientName;
+    /** The first daemon fetch, started once serving has begun. */
+    initialFetch = null;
+    constructor(options = {}) {
         const endpoint = process.env.NEXUS_ENDPOINT || "http://127.0.0.1:5688";
-        const instanceId = process.env.NEXUS_INSTANCE_ID ||
-            process.argv.find((_, i) => process.argv[i - 1] === "--id") ||
-            `mcp-${Math.random().toString(36).slice(2, 6)}`;
-        this.instanceId = instanceId;
-        this.client = new NexusClient({ endpoint, timeoutMs: 5000 });
-        this.server = new Server({ name: SERVICE_NAME, version: pkg.version }, { capabilities: { tools: { listChanged: true } } });
-        this.setupHandlers();
+        this.retryIntervalMs = options.retryIntervalMs ?? RETRY_INTERVAL_MS;
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
+        this.client = new NexusClient({ endpoint, timeoutMs: options.requestTimeoutMs ?? 5000 });
     }
-    setupHandlers() {
-        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
-            tools: this.cachedTools
-        }));
-        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    /** Builds the MCP server instance serveStdio pins for the connection. */
+    buildServer() {
+        const server = new Server({ name: SERVICE_NAME, version: pkg.version }, { capabilities: { tools: { listChanged: true } } });
+        server.setRequestHandler("tools/list", async (_request, ctx) => {
+            this.identifyClient(ctx.mcpReq.envelope, server);
+            // Give a local daemon a moment so the first list is complete; never block on a hung one.
+            if (!this.connected && this.initialFetch) {
+                await Promise.race([this.initialFetch, new Promise((r) => setTimeout(r, INITIAL_LIST_WAIT_MS))]);
+            }
+            if (this.connected) {
+                try {
+                    await this.registerSession();
+                }
+                catch (e) {
+                    if (e instanceof NexusTransportError)
+                        await this.daemonUnavailable();
+                    else
+                        throw e;
+                }
+            }
+            return { tools: this.cachedTools };
+        });
+        server.setRequestHandler("tools/call", async (request, ctx) => {
+            this.identifyClient(ctx.mcpReq.envelope, server);
             if (!this.connected) {
                 return {
                     content: [{ type: "text", text: "Daemon is not ready yet. Please wait a moment and retry." }],
                     isError: true
                 };
             }
+            // Unknown tool is a protocol error (JSON-RPC -32602), not a tool execution error.
+            const unknownTool = () => new ProtocolError(ProtocolErrorCode.InvalidParams, `Unknown tool: ${request.params.name}`);
+            if (!this.cachedTools.some((t) => t.name === request.params.name))
+                throw unknownTool();
+            let callingTool = false;
             try {
-                const result = await this.client.callTool(request.params.name, request.params.arguments, this.instanceId);
+                await this.registerSession();
+                if (this.stopped)
+                    throw new NexusTransportError("MCP connection is closed");
+                callingTool = true;
+                const result = await this.client.callTool(request.params.name, request.params.arguments, this.instanceId, this.sessionId);
+                // Every daemon result is a JSON object, so it goes out as structuredContent
+                // (data tools also publish an outputSchema for it; write tools do not). The
+                // JSON text keeps clients that only read content working (the spec's
+                // backwards-compatibility advice).
                 return {
-                    content: [{
-                            type: "text",
-                            text: typeof result === "string" ? result : JSON.stringify(result, null, 2)
-                        }]
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                    structuredContent: result
                 };
             }
             catch (e) {
                 const message = e instanceof Error ? e.message : String(e);
-                // Daemon went away — start retry loop
-                if (this.connected) {
-                    this.connected = false;
-                    this.cachedTools = [];
-                    await this.server.sendToolListChanged();
-                    this.scheduleRetry();
+                // The daemon dropped the tool since the list was fetched: resync so tools/list stops offering it.
+                if (callingTool && e instanceof NexusToolError && e.status === 404) {
+                    await this.refreshTools();
+                    throw unknownTool();
                 }
+                if (!(e instanceof NexusTransportError)) {
+                    // The daemon answered; the tool itself failed. Keep the tool list.
+                    return { content: [{ type: "text", text: message }], isError: true };
+                }
+                // Daemon went away — drop the tool list and start the retry loop
+                await this.daemonUnavailable();
                 return {
                     content: [{ type: "text", text: `Daemon unavailable: ${message}. Reconnecting...` }],
                     isError: true
                 };
             }
         });
+        this.server = server;
+        return server;
+    }
+    identifyClient(meta, server) {
+        if (this.instanceId)
+            return;
+        const envelope = meta;
+        this.clientName = envelope?.[CLIENT_INFO_META_KEY]?.name
+            ?? server.getClientVersion()?.name;
+        this.instanceId = resolveInstanceId(process.env, process.argv, this.workspace, this.clientName);
+    }
+    async daemonUnavailable() {
+        if (this.connected) {
+            this.connected = false;
+            this.cachedTools = [];
+            await this.notifyToolsChanged();
+        }
+        this.scheduleRetry();
+    }
+    /** Coalesce requests so heartbeats and tool calls cannot stack registrations. */
+    registerSession() {
+        if (this.stopped || !this.instanceId)
+            return Promise.resolve();
+        if (this.registration)
+            return this.registration;
+        this.registrationAttempted = true;
+        this.registration = this.client.registerSession({
+            sessionId: this.sessionId, instanceId: this.instanceId,
+            clientName: this.clientName, workspace: this.workspace
+        }).finally(() => {
+            this.registration = null;
+            this.scheduleHeartbeat();
+        });
+        return this.registration;
+    }
+    scheduleHeartbeat() {
+        if (this.stopped || this.heartbeatTimer)
+            return;
+        this.heartbeatTimer = setTimeout(async () => {
+            this.heartbeatTimer = null;
+            try {
+                await this.registerSession();
+            }
+            catch (e) {
+                if (e instanceof NexusTransportError)
+                    await this.daemonUnavailable();
+            }
+        }, this.heartbeatIntervalMs);
+    }
+    /** Delivered unsolicited on 2025-era connections and via subscriptions/listen on 2026-07-28 ones. */
+    async notifyToolsChanged() {
+        await this.server?.sendToolListChanged().catch(() => { });
+    }
+    /** Re-fetch the daemon's tool list; notify the client if it changed. */
+    async refreshTools() {
+        try {
+            const tools = await this.client.fetchTools();
+            const before = JSON.stringify(this.cachedTools);
+            this.cachedTools = tools;
+            if (JSON.stringify(tools) !== before)
+                await this.notifyToolsChanged();
+        }
+        catch {
+            // Transport trouble is handled by the next call; keep the current list.
+        }
     }
     async tryConnect() {
         try {
             const tools = await this.client.fetchTools();
+            if (this.stopped)
+                return false;
+            if (this.instanceId)
+                await this.registerSession();
+            if (this.stopped)
+                return false;
+            // JSON Schema produced by the daemon; the SDK models it as JSON values.
             this.cachedTools = tools;
             this.connected = true;
             console.error(`[n2n-nexus] Connected to daemon. ${tools.length} tools loaded.`);
-            await this.server.sendToolListChanged();
+            await this.notifyToolsChanged();
             return true;
         }
         catch {
             return false;
         }
     }
+    stopRetry() {
+        this.retrying = false;
+        if (this.retryTimer) {
+            clearTimeout(this.retryTimer);
+            this.retryTimer = null;
+        }
+    }
+    /** Stop reconnecting and close the MCP connection. Safe to call more than once. */
+    shutdown() {
+        if (this.shutdownPromise)
+            return this.shutdownPromise;
+        this.stopped = true;
+        this.stopRetry();
+        if (this.heartbeatTimer)
+            clearTimeout(this.heartbeatTimer);
+        this.heartbeatTimer = null;
+        this.shutdownPromise = (async () => {
+            await this.registration?.catch(() => { });
+            if (this.registrationAttempted && this.instanceId) {
+                await this.client.disconnectSession(this.sessionId, this.instanceId).catch(() => { });
+            }
+            await this.handle?.close().catch(() => { });
+        })();
+        return this.shutdownPromise;
+    }
+    /**
+     * Reconnect loop. Each attempt is scheduled only after the previous one
+     * finished, so a daemon that hangs (attempt longer than the interval)
+     * never accumulates concurrent requests.
+     */
     scheduleRetry() {
-        if (this.retryTimer)
+        if (this.retrying || this.stopped)
             return;
+        this.retrying = true;
         const endpoint = process.env.NEXUS_ENDPOINT || "http://127.0.0.1:5688";
-        this.retryTimer = setInterval(async () => {
-            console.error(`[n2n-nexus] Waiting for daemon at ${endpoint}...`);
-            const ok = await this.tryConnect();
-            if (ok && this.retryTimer) {
-                clearInterval(this.retryTimer);
-                this.retryTimer = null;
-            }
-        }, RETRY_INTERVAL_MS);
+        const next = () => {
+            this.retryTimer = setTimeout(async () => {
+                console.error(`[n2n-nexus] Waiting for daemon at ${endpoint}...`);
+                const ok = await this.tryConnect();
+                if (!this.retrying)
+                    return; // stopped while the attempt was in flight
+                // A tools/call may have lost the daemon again while this attempt was still
+                // notifying the client; only stop if the connection is still up.
+                if (ok && this.connected)
+                    this.stopRetry();
+                else
+                    next();
+            }, this.retryIntervalMs);
+        };
+        next();
     }
-    async run() {
-        const transport = new StdioServerTransport();
-        await this.server.connect(transport);
-        // Try to connect immediately; if not ready, start retry loop
-        const ok = await this.tryConnect();
-        if (!ok) {
+    /**
+     * Serve MCP. Per the stdio transport spec the server should exit when its
+     * input closes; without that the reconnect timer would keep the adapter
+     * alive after the IDE went away.
+     */
+    async run(options = {}) {
+        const stdio = !options.transport;
+        const input = options.input ?? (stdio ? process.stdin : undefined);
+        const onExit = options.onExit ?? (() => process.exit(0));
+        if (input) {
+            const exit = () => { void this.shutdown().then(onExit); };
+            input.once("end", exit);
+            input.once("close", exit);
+        }
+        // Serve first so discover/initialize are answered even when the daemon hangs;
+        // tools/list briefly waits for this fetch (2026-07-28 clients only hear
+        // list_changed if they subscribe).
+        const transport = options.transport ?? new StdioServerTransport();
+        this.handle = serveStdio(() => this.buildServer(), {
+            transport,
+            onerror: (err) => console.error("[n2n-nexus] MCP transport error:", err.message)
+        });
+        const onclose = transport.onclose;
+        transport.onclose = () => {
+            onclose?.();
+            void this.shutdown();
+        };
+        this.initialFetch = this.tryConnect();
+        const ok = await this.initialFetch;
+        if (!ok && !this.stopped) {
             const endpoint = process.env.NEXUS_ENDPOINT || "http://127.0.0.1:5688";
-            console.error(`[n2n-nexus] Daemon not available at ${endpoint}. Will retry every ${RETRY_INTERVAL_MS / 1000}s...`);
+            console.error(`[n2n-nexus] Daemon not available at ${endpoint}. Will retry every ${this.retryIntervalMs / 1000}s...`);
             this.scheduleRetry();
         }
     }

package/build/storage/direct-messages.js

@@ -0,0 +1,89 @@
+import { randomUUID } from "node:crypto";
+import { SessionStore } from "./sessions.js";
+import { getDatabase } from "./sqlite.js";
+export const DEFAULT_MESSAGE_TTL_MS = 24 * 60 * 60 * 1000;
+function toMessage(row) {
+    return {
+        messageId: row.message_id, from: row.from_session_id, to: row.to_session_id,
+        text: row.text, category: row.category ?? undefined, replyTo: row.reply_to, status: row.status,
+        createdAt: row.created_at, expiresAt: row.expires_at, fetchedAt: row.fetched_at,
+        acknowledgedAt: row.acknowledged_at, repliedAt: row.replied_at, reason: row.reason
+    };
+}
+function expire(now) {
+    getDatabase().prepare("UPDATE direct_messages SET status = 'expired', reason = 'Message TTL elapsed' WHERE status IN ('accepted', 'fetched') AND expires_at <= ?")
+        .run(new Date(now).toISOString());
+}
+export class DirectMessageStore {
+    static send(fromSessionId, input, now = Date.now()) {
+        SessionStore.require(fromSessionId);
+        const ttlMs = input.ttlMs ?? DEFAULT_MESSAGE_TTL_MS;
+        if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0)
+            throw new Error("ttlMs must be a positive integer");
+        const db = getDatabase();
+        expire(now);
+        return db.transaction(() => {
+            const recipient = SessionStore.require(input.to);
+            if (input.replyTo) {
+                const original = this.get(input.replyTo, fromSessionId, now);
+                if (original.to !== fromSessionId || original.from !== input.to)
+                    throw new Error("Reply must target the original sender");
+                if (!["fetched", "acknowledged", "replied"].includes(original.status))
+                    throw new Error(`Cannot reply to a message with status ${original.status}`);
+            }
+            const messageId = randomUUID();
+            const timestamp = new Date(now).toISOString();
+            const status = recipient.inbound === "refuse" ? "refused" : "accepted";
+            db.prepare("INSERT INTO direct_messages (message_id, from_session_id, to_session_id, text, category, reply_to, status, created_at, expires_at, reason) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)")
+                .run(messageId, fromSessionId, input.to, input.message, input.category ?? null, input.replyTo ?? null, status, timestamp, new Date(now + ttlMs).toISOString(), status === "refused" ? "Recipient refuses incoming messages" : null);
+            if (input.replyTo && status === "accepted") {
+                db.prepare("UPDATE direct_messages SET status = 'replied', replied_at = COALESCE(replied_at, ?) WHERE message_id = ?")
+                    .run(timestamp, input.replyTo);
+            }
+            return this.get(messageId, fromSessionId, now);
+        })();
+    }
+    static readInbox(sessionId, count, now = Date.now()) {
+        SessionStore.require(sessionId);
+        const db = getDatabase();
+        return db.transaction(() => {
+            expire(now);
+            const rows = db.prepare("SELECT * FROM direct_messages WHERE to_session_id = ? AND status IN ('accepted', 'fetched') ORDER BY created_at ASC, rowid ASC LIMIT ?")
+                .all(sessionId, count);
+            const timestamp = new Date(now).toISOString();
+            const update = db.prepare("UPDATE direct_messages SET status = 'fetched', fetched_at = ? WHERE message_id = ? AND status = 'accepted'");
+            return rows.map(row => {
+                if (row.status === "accepted") {
+                    update.run(timestamp, row.message_id);
+                    row.status = "fetched";
+                    row.fetched_at = timestamp;
+                }
+                return toMessage(row);
+            });
+        })();
+    }
+    static get(messageId, actorSessionId, now = Date.now()) {
+        expire(now);
+        const row = getDatabase().prepare("SELECT * FROM direct_messages WHERE message_id = ? AND (from_session_id = ? OR to_session_id = ?)")
+            .get(messageId, actorSessionId, actorSessionId);
+        if (!row)
+            throw new Error("Message not found for this session");
+        return toMessage(row);
+    }
+    static acknowledge(messageId, recipientSessionId, outcome, now = Date.now()) {
+        const db = getDatabase();
+        expire(now);
+        return db.transaction(() => {
+            const message = this.get(messageId, recipientSessionId, now);
+            if (message.to !== recipientSessionId)
+                throw new Error("Only the recipient can acknowledge a message");
+            if (message.status === outcome)
+                return message;
+            if (message.status !== "fetched")
+                throw new Error(`Cannot ${outcome === "acknowledged" ? "acknowledge" : "refuse"} a message with status ${message.status}`);
+            db.prepare("UPDATE direct_messages SET status = ?, acknowledged_at = ?, reason = ? WHERE message_id = ?")
+                .run(outcome, outcome === "acknowledged" ? new Date(now).toISOString() : null, outcome === "refused" ? "Recipient refused message" : null, messageId);
+            return this.get(messageId, recipientSessionId, now);
+        })();
+    }
+}

package/build/storage/docs.js

@@ -1,6 +1,7 @@
 import { promises as fs } from "node:fs";
 import { NexusPaths } from "./paths.js";
 import { FILE_ENCODING } from "../constants.js";
+import { toDict, writeFileAtomic, writeJsonAtomic } from "./fs-utils.js";
 export class DocStorage {
     static async ensureDirectory() {
         await fs.mkdir(NexusPaths.docsDir(), { recursive: true });
@@ -8,7 +9,7 @@ export class DocStorage {
             await fs.access(NexusPaths.docsIndexFile);
         }
         catch {
-            await fs.writeFile(NexusPaths.docsIndexFile, JSON.stringify({}, null, 2), FILE_ENCODING);
+            await writeJsonAtomic(NexusPaths.docsIndexFile, {});
         }
     }
     static async readIndex() {
@@ -17,26 +18,32 @@ export class DocStorage {
             const raw = await fs.readFile(NexusPaths.docsIndexFile, FILE_ENCODING);
             const parsed = JSON.parse(raw);
             if (parsed && typeof parsed === "object")
-                return parsed;
+                return toDict(Object.entries(parsed));
         }
         catch {
             // fall through
         }
-        return {};
+        return toDict();
     }
     static async writeIndex(index) {
         await this.ensureDirectory();
-        await fs.writeFile(NexusPaths.docsIndexFile, JSON.stringify(index, null, 2), FILE_ENCODING);
+        await writeJsonAtomic(NexusPaths.docsIndexFile, index);
     }
     static async init() {
         await this.ensureDirectory();
+    }
+    /** The master strategy document (global/blueprint.md). */
+    static async getBlueprint() {
         try {
-            await fs.access(NexusPaths.globalBlueprint);
+            return await fs.readFile(NexusPaths.globalBlueprint, FILE_ENCODING);
         }
         catch {
-            await fs.writeFile(NexusPaths.globalBlueprint, "# Global Collaboration Blueprint\n\nShared meeting space.", FILE_ENCODING);
+            return "";
         }
     }
+    static async saveBlueprint(content) {
+        await writeFileAtomic(NexusPaths.globalBlueprint, content);
+    }
     static async listDocs() {
         await this.ensureDirectory();
         return this.readIndex();
@@ -55,7 +62,7 @@ export class DocStorage {
         await this.ensureDirectory();
         const index = await this.readIndex();
         const filePath = NexusPaths.docFile(docId);
-        await fs.writeFile(filePath, content, FILE_ENCODING);
+        await writeFileAtomic(filePath, content);
         index[docId] = {
             title,
             lastUpdated: new Date().toISOString(),

package/build/storage/events.js

@@ -0,0 +1,31 @@
+import { getDatabase } from "./sqlite.js";
+function toEvent(row) {
+    return {
+        id: row.id,
+        timestamp: row.timestamp,
+        actor: row.actor,
+        action: row.action,
+        target: row.target ?? undefined,
+        detail: row.detail ? JSON.parse(row.detail) : undefined
+    };
+}
+/**
+ * Structured audit trail of state changes made through the daemon
+ * (project synced, meeting ended, ...). Kept separate from the chat
+ * streams so assistants can read conversation and activity independently.
+ */
+export class EventStore {
+    static record(actor, action, target, detail) {
+        const timestamp = new Date().toISOString();
+        const result = getDatabase().prepare("INSERT INTO events (timestamp, actor, action, target, detail) VALUES (?, ?, ?, ?, ?)").run(timestamp, actor, action, target ?? null, detail ? JSON.stringify(detail) : null);
+        return { id: Number(result.lastInsertRowid), timestamp, actor, action, target, detail };
+    }
+    /** Newest events first. `action` filters by exact action name or a `prefix.` */
+    static list(limit, action) {
+        const db = getDatabase();
+        const rows = (action
+            ? db.prepare("SELECT * FROM events WHERE action = ? OR action LIKE ? ORDER BY id DESC LIMIT ?").all(action, `${action}.%`, limit)
+            : db.prepare("SELECT * FROM events ORDER BY id DESC LIMIT ?").all(limit));
+        return rows.map(toEvent);
+    }
+}

package/build/storage/fs-utils.js

@@ -0,0 +1,42 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { AsyncMutex } from "../utils/async-mutex.js";
+import { FILE_ENCODING } from "../constants.js";
+/**
+ * Serializes every file-store write inside the daemon. HTTP requests are
+ * handled concurrently, so read-modify-write sequences on registry.json,
+ * manifests and the docs index must be queued behind one lock.
+ */
+export const fileWriteLock = new AsyncMutex();
+/**
+ * Write to a temp file in the same directory, then rename over the target so
+ * readers never observe a partially written file.
+ */
+export async function writeFileAtomic(filePath, data) {
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    const tmp = path.join(dir, `.${path.basename(filePath)}.${process.pid}.${Math.random().toString(36).slice(2, 8)}.tmp`);
+    try {
+        await fs.writeFile(tmp, data, typeof data === "string" ? FILE_ENCODING : undefined);
+        await fs.rename(tmp, filePath);
+    }
+    catch (e) {
+        await fs.rm(tmp, { force: true }).catch(() => { });
+        throw e;
+    }
+}
+/**
+ * Copy entries into an object without a prototype. Registry and index maps
+ * are keyed by user-supplied ids; on a plain object ids such as
+ * "constructor" or "__proto__" hit Object.prototype on lookup or rewrite the
+ * prototype on assignment.
+ */
+export function toDict(entries = []) {
+    const dict = Object.create(null);
+    for (const [k, v] of entries)
+        dict[k] = v;
+    return dict;
+}
+export function writeJsonAtomic(filePath, value) {
+    return writeFileAtomic(filePath, JSON.stringify(value, null, 2));
+}

package/build/storage/global-messages.js

@@ -0,0 +1,44 @@
+import { getDatabase } from "./sqlite.js";
+function toMessage(row) {
+    return { id: row.id, from: row.sender, text: row.text, category: row.category ?? undefined, timestamp: row.timestamp };
+}
+/**
+ * Global (non-meeting) chat stream, stored in SQLite so appends are cheap,
+ * concurrent-safe and addressable by id for per-instance unread cursors.
+ */
+export class GlobalMessageStore {
+    static addMessage(from, text, category) {
+        const db = getDatabase();
+        const timestamp = new Date().toISOString();
+        const result = db.prepare("INSERT INTO global_messages (sender, text, category, timestamp) VALUES (?, ?, ?, ?)").run(from, text, category ?? null, timestamp);
+        return { id: Number(result.lastInsertRowid), from, text, category, timestamp };
+    }
+    /** Messages this instance has not read yet, oldest first; advances the cursor. */
+    static readUnread(instanceId, count) {
+        const db = getDatabase();
+        const cursor = db.prepare("SELECT last_read_id FROM read_cursors WHERE instance_id = ? AND context_type = 'global' AND context_id = 'global'").get(instanceId);
+        const lastReadId = cursor?.last_read_id ?? 0;
+        const rows = db.prepare("SELECT id, sender, text, category, timestamp FROM global_messages WHERE id > ? ORDER BY id ASC LIMIT ?").all(lastReadId, count);
+        if (rows.length > 0) {
+            db.prepare("INSERT OR REPLACE INTO read_cursors (instance_id, context_type, context_id, last_read_id, updated_at) VALUES (?, 'global', 'global', ?, ?)").run(instanceId, rows[rows.length - 1].id, new Date().toISOString());
+        }
+        return rows.map(toMessage);
+    }
+    /** Most recent messages regardless of cursor, oldest first. */
+    static recent(count) {
+        const rows = getDatabase().prepare("SELECT id, sender, text, category, timestamp FROM global_messages ORDER BY id DESC LIMIT ?").all(count);
+        return rows.reverse().map(toMessage);
+    }
+    static count() {
+        return getDatabase().prepare("SELECT COUNT(*) AS n FROM global_messages").get().n;
+    }
+    /** Delete the oldest `count` messages. */
+    static pruneOldest(count) {
+        if (count <= 0)
+            return 0;
+        return getDatabase().prepare("DELETE FROM global_messages WHERE id IN (SELECT id FROM global_messages ORDER BY id ASC LIMIT ?)").run(count).changes;
+    }
+    static clear() {
+        return getDatabase().prepare("DELETE FROM global_messages").run().changes;
+    }
+}