n2n-nexus 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.7.0] - 2026-10-20
+
+### Added
+
+- Session discovery with `list_sessions` and `update_session`: each MCP connection has a distinct session ID, a display name, optional project association, an incoming-message policy and heartbeat-based presence. Connections sharing an instance ID have separate inboxes.
+- Direct messages through `send_message(to, replyTo?, ttlMs?)`, plus `read_inbox`, `get_message` and `acknowledge_message`. Receipts distinguish accepted, fetched, acknowledged, replied, refused and expired messages. Unacknowledged fetched messages remain retrievable, and replies link back to the original message.
+
+### Changed
+
+- MCP adapters register their connection identity and maintain it with heartbeats. Stable instance IDs continue to identify legacy shared-message cursors and meeting permissions.
+- Updated compatible runtime and development dependencies, including Zod, ESLint, typescript-eslint, Vitest and Lefthook.
+
+### Fixed
+
+- Strategy migration now records completion and preserves conflicting documents, preventing later user documents from being mistaken for legacy data and deleted on restart.
+- Interrupted HTTP responses now reject the pending request instead of leaving connection attempts, tool calls or shutdown waiting indefinitely.
+- Malformed Host headers and request URLs return HTTP 400 without terminating the daemon; existing browser and Host restrictions remain in effect.
+- Concurrent attempts to rename one project to different destinations no longer both report success or record a rename that did not happen.
+- MCP adapters can connect to IPv6 daemon endpoints without treating the address brackets as part of a DNS hostname.
+- Task expiry preserves timestamp milliseconds so maintenance does not fail tasks before their TTL has elapsed.
+
+### Upgrade notes
+
+- Upgrade the daemon first, then restart the MCP adapters on 0.7.0. New adapters require the daemon's session registration endpoints before executing tools. Existing meeting and global-message operations remain available with the upgraded daemon.
+- Inboxes are per MCP connection. Host chats sharing one connection share its inbox, and restarting the adapter creates a new session rather than inheriting the previous inbox.
+- Incoming messages require an explicit `read_inbox` call; this release does not automatically wake models. Online presence indicates a recent heartbeat, fetching does not prove processing, and acknowledgement confirms receipt rather than completion of work.
+
 ## [0.6.0] - 2026-10-16
 
 ### Added

package/README.md

@@ -61,7 +61,7 @@ n2n-nexus gives AI assistants a shared coordination workspace. A long-running lo
 ```
 
 - **Daemon is the source of truth**: start it once and keep it running.
-- **MCP adapters are stateless**: each IDE starts an adapter through `npx`, then forwards tool calls to the daemon.
+- **MCP adapters hold connection identity only**: each IDE starts an adapter through `npx`, then forwards tool calls to the daemon, which stores the session directory and inboxes.
 - **Cross-environment by design**: point `NEXUS_ENDPOINT` at the same daemon from different machines or shells. The daemon binds to localhost by default; use `--host 0.0.0.0` only on a trusted network.
 
 ## 🚀 Quick start
@@ -103,18 +103,21 @@ The adapter can start before the daemon. It loads the daemon tool list once the
 
 ## 🛠️ Toolset
 
-The daemon exposes 26 tools, grouped by purpose:
+The daemon exposes 31 tools, grouped by purpose:
 
 | Group | Tools | Purpose |
 | --- | --- | --- |
 | **Topology** | `get_global_topology` | Read the project list or a detailed per-project subgraph. |
 | **Projects & assets** | `search_projects`, `get_project`, `update_project`, `rename_project`, `sync_project_assets`, `upload_project_asset` | Find, read, update, and rename projects; sync manifests and internal docs; upload binary assets. |
 | **Global docs** | `list_global_docs`, `get_global_doc`, `sync_global_doc`, `get_global_strategy`, `update_global_strategy` | List, read, create and update shared global documents and the master strategy document. |
-| **Messaging** | `send_message`, `read_messages`, `list_events` | Post and read meeting and global messages; read the structured activity log. |
+| **Messaging** | `send_message`, `read_messages`, `list_events` | Send direct, meeting or global messages; read shared messages and the activity log. |
+| **Sessions and inboxes** | `list_sessions`, `update_session`, `read_inbox`, `get_message`, `acknowledge_message` | Discover connections, receive direct messages, and inspect explicit receipts and replies. |
 | **Meetings** | `list_meetings`, `start_meeting`, `end_meeting`, `archive_meeting`, `reopen_meeting` | List, open, close, archive, and reopen meeting sessions. |
 | **Tasks** | `create_task`, `get_task`, `list_tasks`, `cancel_task` | Create and track tasks that assistants manage themselves. |
 | **Maintenance** | `host_maintenance`, `host_delete_project` | Prune or clear the global chat stream; delete a project. |
 
+Direct inboxes are per MCP connection and require explicit reads; messages do not automatically wake models. Chats sharing one connection share its inbox. Receipt states distinguish storage, fetching, acknowledgement and replies; acknowledgement does not mean the requested work is complete. See the [assistant workflow](docs/ASSISTANT_GUIDE.md#direct-conversations).
+
 See [Tools reference](./docs/TOOLS_REFERENCE.md) for parameter schemas and call examples.
 
 ## 💾 Data storage

package/build/client/nexus-client.js

@@ -35,12 +35,8 @@ export class NexusClient {
         const payload = body !== undefined ? JSON.stringify(body) : undefined;
         const transport = url.protocol === "https:" ? https : http;
         return new Promise((resolve, reject) => {
-            const req = transport.request({
+            const req = transport.request(url, {
                 method,
-                protocol: url.protocol,
-                hostname: url.hostname,
-                port: url.port,
-                path: `${url.pathname}${url.search}`,
                 headers: {
                     "Content-Type": "application/json",
                     ...(payload ? { "Content-Length": Buffer.byteLength(payload) } : {})
@@ -48,6 +44,11 @@ export class NexusClient {
                 timeout: this.timeoutMs
             }, (res) => {
                 let data = "";
+                const interrupted = () => reject(new NexusTransportError("Response from daemon ended before completion"));
+                res.on("aborted", interrupted);
+                res.on("error", (error) => reject(new NexusTransportError(error.message)));
+                res.on("close", () => { if (!res.complete)
+                    interrupted(); });
                 res.on("data", chunk => { data += chunk; });
                 res.on("end", () => {
                     let parsed;
@@ -78,8 +79,14 @@ export class NexusClient {
         const res = await this.request("GET", "/api/tools");
         return res.tools;
     }
-    async callTool(name, args, instanceId) {
-        const res = await this.request("POST", "/api/tools/call", { tool: name, args: args || {}, instanceId: instanceId || "unknown" });
+    async registerSession(session) {
+        await this.request("POST", "/api/sessions/register", session);
+    }
+    async disconnectSession(sessionId, instanceId) {
+        await this.request("POST", "/api/sessions/disconnect", { sessionId, instanceId });
+    }
+    async callTool(name, args, instanceId, sessionId) {
+        const res = await this.request("POST", "/api/tools/call", { tool: name, args: args || {}, instanceId: instanceId || "unknown", ...(sessionId ? { sessionId } : {}) });
         if (!res.ok)
             throw new NexusToolError(res.error || "Tool call failed", 200);
         return res.result;

package/build/daemon/server.js

@@ -4,13 +4,15 @@ import { URL } from "node:url";
 import { StorageManager } from "../storage/index.js";
 import { SqliteMeetingStore } from "../storage/sqlite-meeting.js";
 import { GlobalMessageStore } from "../storage/global-messages.js";
+import { SessionStore } from "../storage/sessions.js";
+import { DirectMessageStore } from "../storage/direct-messages.js";
 import { EventStore } from "../storage/events.js";
 import { runMigrations } from "../storage/migrations.js";
 import { createTask, updateTask, getTask, listTasks, cancelTask } from "../storage/tasks.js";
 import { MAX_BODY_BYTES } from "../constants.js";
 import { ADDRESS_LIMIT_FACTOR, RateLimiter, rateLimitFromEnv } from "./rate-limit.js";
 import { ResultContractError, finalizeResult } from "./tool-outputs.js";
-import { TOOL_DEFINITIONS, isToolName, parseToolArgs, taskUpdateSchema, ToolValidationError } from "./tools.js";
+import { TOOL_DEFINITIONS, isToolName, parseToolArgs, taskUpdateSchema, sessionRegistrationSchema, sessionDisconnectSchema, ToolValidationError } from "./tools.js";
 import { z } from "zod";
 // ---------------------------------------------------------------------------
 // Storage bootstrap
@@ -77,7 +79,20 @@ async function toolGetProject(args) {
         ? { manifest, internalDocs: await StorageManager.getProjectDocs(args.projectId) }
         : { manifest };
 }
-async function toolSendMessage(args, instanceId) {
+function requireSession(sessionId, instanceId) {
+    if (!sessionId)
+        throw new Error("A registered sessionId is required");
+    return SessionStore.require(sessionId, instanceId);
+}
+async function toolSendMessage(args, instanceId, sessionId) {
+    if (args.to !== undefined) {
+        const sender = requireSession(sessionId, instanceId);
+        const saved = DirectMessageStore.send(sender.sessionId, { ...args, to: args.to });
+        return {
+            ok: true, sentTo: "session", messageId: saved.messageId, status: saved.status,
+            to: saved.to, replyTo: saved.replyTo, message: `Direct message ${saved.status}.`
+        };
+    }
     const meetingId = args.meetingId ?? SqliteMeetingStore.getActiveMeetingId();
     if (meetingId) {
         const msg = {
@@ -208,8 +223,32 @@ async function toolHostDeleteProject(args, instanceId) {
 // ---------------------------------------------------------------------------
 // Tool dispatcher
 // ---------------------------------------------------------------------------
-async function dispatchTool(name, rawArgs, instanceId) {
+async function dispatchTool(name, rawArgs, instanceId, sessionId) {
     switch (name) {
+        case "list_sessions": {
+            const args = parseToolArgs(name, rawArgs);
+            const self = sessionId ? requireSession(sessionId, instanceId) : null;
+            const sessions = SessionStore.list(args);
+            return { self, sessions, count: sessions.length };
+        }
+        case "update_session": {
+            const args = parseToolArgs(name, rawArgs);
+            return { session: SessionStore.update(requireSession(sessionId, instanceId).sessionId, args) };
+        }
+        case "read_inbox": {
+            const args = parseToolArgs(name, rawArgs);
+            const self = requireSession(sessionId, instanceId);
+            const messages = DirectMessageStore.readInbox(self.sessionId, args.count);
+            return { sessionId: self.sessionId, messages, count: messages.length };
+        }
+        case "get_message": {
+            const args = parseToolArgs(name, rawArgs);
+            return { message: DirectMessageStore.get(args.messageId, requireSession(sessionId, instanceId).sessionId) };
+        }
+        case "acknowledge_message": {
+            const args = parseToolArgs(name, rawArgs);
+            return { message: DirectMessageStore.acknowledge(args.messageId, requireSession(sessionId, instanceId).sessionId, args.outcome) };
+        }
         case "sync_project_assets": return toolSyncProjectAssets(parseToolArgs(name, rawArgs), instanceId);
         case "upload_project_asset": return toolUploadAsset(parseToolArgs(name, rawArgs), instanceId);
         case "update_project": return toolUpdateProject(parseToolArgs(name, rawArgs), instanceId);
@@ -217,7 +256,7 @@ async function dispatchTool(name, rawArgs, instanceId) {
         case "search_projects": return toolSearchProjects(parseToolArgs(name, rawArgs));
         case "get_global_topology": return toolGetGlobalTopology(parseToolArgs(name, rawArgs));
         case "get_project": return toolGetProject(parseToolArgs(name, rawArgs));
-        case "send_message": return toolSendMessage(parseToolArgs(name, rawArgs), instanceId);
+        case "send_message": return toolSendMessage(parseToolArgs(name, rawArgs), instanceId, sessionId);
         case "read_messages": return toolReadMessages(parseToolArgs(name, rawArgs), instanceId);
         case "list_events": return toolListEvents(parseToolArgs(name, rawArgs));
         case "get_global_strategy":
@@ -271,9 +310,9 @@ function rateLimited(retryAfterSec, scope) {
  * Run a tool for an HTTP request. Validation failures and handler rejections
  * are the caller's fault and surface as 400, not as daemon errors.
  */
-async function callTool(name, args, instanceId) {
+async function callTool(name, args, instanceId, sessionId) {
     try {
-        return finalizeResult(name, await dispatchTool(name, args, instanceId));
+        return finalizeResult(name, await dispatchTool(name, args, instanceId, sessionId));
     }
     catch (e) {
         if (e instanceof HttpError)
@@ -291,6 +330,9 @@ const UNKNOWN_INSTANCE = "unknown";
 function actor(body) {
     return typeof body.instanceId === "string" && body.instanceId ? body.instanceId : UNKNOWN_INSTANCE;
 }
+function sessionActor(body) {
+    return z.string().min(1).optional().parse(body.sessionId);
+}
 /** Query-string parameters as tool arguments; `numeric` names are converted to numbers. */
 function queryArgs(url, numeric) {
     const args = {};
@@ -401,20 +443,27 @@ export async function createDaemonServer(options) {
      * Requests that name no instance ("unknown") are only limited per address:
      * pooling them in one shared bucket let any client exhaust it for all others.
      */
-    const call = (name, args, instanceId) => {
+    const call = (name, args, instanceId, sessionId) => {
         if (instanceId !== UNKNOWN_INSTANCE) {
             const wait = instanceLimiter.take(`instance:${instanceId}`);
             if (wait)
                 throw rateLimited(wait, `instance '${instanceId}'`);
         }
-        return callTool(name, args, instanceId);
+        return callTool(name, args, instanceId, sessionId);
     };
     const server = http.createServer(async (req, res) => {
         const method = req.method || "GET";
-        const url = new URL(req.url || "/", `http://${req.headers.host || "127.0.0.1"}`);
-        const path = url.pathname;
         const parseBody = (r) => parseRequestBody(r, maxBodyBytes);
         try {
+            let url;
+            try {
+                url = new URL(req.url || "/", `http://${req.headers.host || "127.0.0.1"}`);
+            }
+            catch {
+                req.resume();
+                throw new HttpError(400, "Invalid request URL or Host header");
+            }
+            const path = url.pathname;
             const guard = rejectBrowserRequest(req, allowedHosts);
             if (guard) {
                 req.resume();
@@ -438,23 +487,44 @@ export async function createDaemonServer(options) {
             if (method === "GET" && path === "/api/tools") {
                 return jsonResponse(res, 200, { tools: TOOL_DEFINITIONS });
             }
+            if (method === "POST" && path === "/api/sessions/register") {
+                const input = sessionRegistrationSchema.parse(await parseBody(req));
+                let session;
+                try {
+                    session = SessionStore.register(input);
+                }
+                catch (e) {
+                    throw new HttpError(400, e instanceof Error ? e.message : String(e));
+                }
+                return jsonResponse(res, 200, { ok: true, session });
+            }
+            if (method === "POST" && path === "/api/sessions/disconnect") {
+                const input = sessionDisconnectSchema.parse(await parseBody(req));
+                try {
+                    SessionStore.disconnect(input.sessionId, input.instanceId);
+                }
+                catch (e) {
+                    throw new HttpError(400, e instanceof Error ? e.message : String(e));
+                }
+                return jsonResponse(res, 200, { ok: true });
+            }
             // Tool call dispatcher  ← core endpoint
             if (method === "POST" && path === "/api/tools/call") {
                 const body = await parseBody(req);
                 const toolName = body.tool;
                 const args = (body.args || {});
-                const instanceId = body.instanceId || UNKNOWN_INSTANCE;
+                const instanceId = actor(body);
                 if (!toolName)
                     return jsonResponse(res, 400, { ok: false, error: "tool is required" });
                 if (!isToolName(toolName)) {
                     return jsonResponse(res, 404, { ok: false, error: `Unknown tool: '${toolName}'` });
                 }
-                return jsonResponse(res, 200, { ok: true, result: await call(toolName, args, instanceId) });
+                return jsonResponse(res, 200, { ok: true, result: await call(toolName, args, instanceId, sessionActor(body)) });
             }
             // Messages
             if (method === "POST" && path === "/api/messages/send") {
                 const body = await parseBody(req);
-                return jsonResponse(res, 200, await call("send_message", body, actor(body)));
+                return jsonResponse(res, 200, await call("send_message", body, actor(body), sessionActor(body)));
             }
             if (method === "GET" && path === "/api/messages/unread") {
                 const result = await call("read_messages", queryArgs(url, ["count"]), url.searchParams.get("instanceId") || UNKNOWN_INSTANCE);

package/build/daemon/tool-outputs.js

@@ -12,6 +12,20 @@ import { TASK_STATUSES } from "../storage/tasks.js";
  * 2025-era clients require.
  */
 const ack = { ok: z.literal(true), message: z.string() };
+const sessionSchema = z.object({
+    sessionId: z.string(), instanceId: z.string(), name: z.string(),
+    clientName: z.string(), workspace: z.string(), projectId: z.string().nullable(),
+    inbound: z.enum(["accept", "refuse"]), reception: z.literal("pull"),
+    online: z.boolean(), createdAt: z.string(), lastSeenAt: z.string()
+});
+const deliveryStatus = z.enum(["accepted", "fetched", "acknowledged", "replied", "refused", "expired"]);
+const directMessageSchema = z.object({
+    messageId: z.string(), from: z.string(), to: z.string(), text: z.string(),
+    category: z.enum(MESSAGE_CATEGORIES).optional(), replyTo: z.string().nullable(),
+    status: deliveryStatus, createdAt: z.string(), expiresAt: z.string(),
+    fetchedAt: z.string().nullable(), acknowledgedAt: z.string().nullable(),
+    repliedAt: z.string().nullable(), reason: z.string().nullable()
+});
 const messageSchema = z.object({
     id: z.number().int().optional(),
     from: z.string(),
@@ -80,11 +94,19 @@ export const TOOL_OUTPUT_SCHEMAS = {
         manifest: storedManifest,
         internalDocs: z.string().optional()
     }),
+    list_sessions: z.object({ self: sessionSchema.nullable(), sessions: z.array(sessionSchema), count: z.number().int() }),
+    update_session: z.object({ session: sessionSchema }),
+    read_inbox: z.object({ sessionId: z.string(), messages: z.array(directMessageSchema), count: z.number().int() }),
+    get_message: z.object({ message: directMessageSchema }),
+    acknowledge_message: z.object({ message: directMessageSchema }),
     send_message: z.object({
         ...ack,
-        sentTo: z.enum(["meeting", "global"]),
+        sentTo: z.enum(["meeting", "global", "session"]),
         meetingId: z.string().optional(),
-        messageId: z.number().int().optional()
+        messageId: z.union([z.number().int(), z.string()]).optional(),
+        status: deliveryStatus.optional(),
+        to: z.string().optional(),
+        replyTo: z.string().nullable().optional()
     }),
     read_messages: z.object({
         source: z.enum(["meeting", "global"]),

package/build/daemon/tools.js

@@ -62,9 +62,28 @@ export const TOOL_SCHEMAS = {
         includeDocs: z.boolean().default(true).describe("Also return the internal docs (Markdown)")
     }),
     // Messaging
+    list_sessions: z.object({
+        onlineOnly: z.boolean().default(true),
+        projectId: projectIdSchema.optional(),
+        limit: positiveInt(500).default(100)
+    }),
+    update_session: z.object({
+        name: z.string().min(1).optional(),
+        projectId: projectIdSchema.nullable().optional(),
+        inbound: z.enum(["accept", "refuse"]).optional()
+    }),
+    read_inbox: z.object({ count: positiveInt(500).default(10) }),
+    get_message: z.object({ messageId: z.string().min(1) }),
+    acknowledge_message: z.object({
+        messageId: z.string().min(1),
+        outcome: z.enum(["acknowledged", "refused"]).default("acknowledged")
+    }),
     send_message: z.object({
         message: z.string().min(1),
         category: z.enum(MESSAGE_CATEGORIES).optional(),
+        to: z.string().min(1).optional().describe("Exact sessionId from list_sessions; mutually exclusive with meetingId"),
+        replyTo: z.string().min(1).optional().describe("Direct message being answered; requires to = original sender"),
+        ttlMs: positiveInt(Number.MAX_SAFE_INTEGER).optional().describe("Direct-message expiry in milliseconds; defaults to 24 hours"),
         meetingId: z.string().min(1).optional().describe("Target meeting. Defaults to the active meeting, or global chat when none is active.")
     }),
     read_messages: z.object({
@@ -123,7 +142,12 @@ const TOOL_DESCRIPTIONS = {
     search_projects: "Search project registry by name or description.",
     get_global_topology: "Default: project list + stats. With projectId: detailed subgraph.",
     get_project: "Read a project's full manifest and, by default, its internal docs.",
-    send_message: "Post a message. Goes to meetingId if given, else to the active meeting, else to global chat.",
+    list_sessions: "Discover MCP connections and your own session. Online means a recent connection heartbeat, not model readiness. Delivery is pull-only.",
+    update_session: "Set your session name, project association or incoming-message policy. Refusing also rejects pending inbox messages.",
+    read_inbox: "Fetch your pending direct messages, oldest first. Unacknowledged messages remain retrievable; fetching does not confirm processing.",
+    get_message: "Read a direct message and its receipt status; only the sender and recipient may query it.",
+    acknowledge_message: "Explicitly acknowledge or refuse a fetched direct message. Acknowledgement confirms receipt, not completed work.",
+    send_message: "Send directly to an exact sessionId using to, optionally replying with replyTo. Otherwise post to meetingId, the active meeting, or global chat. Direct accepted means stored, not read or a woken model.",
     read_messages: "Read messages this instance has not read yet (cursor advances automatically). Global chat by default; pass meetingId for a meeting.",
     list_events: "Activity log: structured records of state changes (project.sync, project.rename, meeting.end, ...), newest first.",
     get_global_strategy: "Read the master strategy document (global/blueprint.md).",
@@ -153,6 +177,11 @@ const TOOL_TITLES = {
     get_global_topology: "Project Topology",
     get_project: "Read Project",
     send_message: "Send Message",
+    list_sessions: "List Sessions",
+    update_session: "Update My Session",
+    read_inbox: "Read My Inbox",
+    get_message: "Read Message Receipt",
+    acknowledge_message: "Acknowledge Message",
     read_messages: "Read Messages",
     list_events: "Activity Log",
     get_global_strategy: "Read Strategy",
@@ -188,7 +217,12 @@ const TOOL_ANNOTATIONS = {
     search_projects: readOnly,
     get_global_topology: readOnly,
     get_project: readOnly,
-    send_message: write(false, false),
+    send_message: write(true, false), // a direct reply also updates the original message's receipt
+    list_sessions: readOnly,
+    update_session: write(true, true),
+    read_inbox: write(false, true),
+    get_message: readOnly,
+    acknowledge_message: write(true, true),
     read_messages: write(false, false), // only advances this instance's own unread cursor (bookkeeping, not shared data)
     list_events: readOnly,
     get_global_strategy: readOnly,
@@ -233,7 +267,7 @@ export const TOOL_NAMES = Object.keys(TOOL_SCHEMAS);
  */
 const PUBLISHED_OUTPUT_SCHEMAS = new Set([
     "search_projects", "get_global_topology", "get_project",
-    "read_messages", "list_events",
+    "read_messages", "list_events", "list_sessions", "update_session", "read_inbox", "get_message", "acknowledge_message",
     "get_global_strategy", "list_global_docs", "get_global_doc",
     "list_meetings", "get_task", "list_tasks"
 ]);
@@ -259,8 +293,24 @@ export function parseToolArgs(name, args) {
     const result = TOOL_SCHEMAS[name].safeParse(args ?? {});
     if (!result.success)
         throw new ToolValidationError(name, z.prettifyError(result.error));
+    if (name === "send_message") {
+        const message = result.data;
+        if (message.to !== undefined && message.meetingId !== undefined) {
+            throw new ToolValidationError(name, "to and meetingId are mutually exclusive");
+        }
+        if (message.to === undefined && (message.replyTo !== undefined || message.ttlMs !== undefined)) {
+            throw new ToolValidationError(name, "replyTo and ttlMs require a direct recipient (to)");
+        }
+    }
     return result.data;
 }
+export const sessionRegistrationSchema = z.object({
+    sessionId: z.string().min(1),
+    instanceId: z.string().min(1),
+    clientName: z.string().optional(),
+    workspace: z.string().optional()
+});
+export const sessionDisconnectSchema = sessionRegistrationSchema.pick({ sessionId: true, instanceId: true });
 /** Schema for POST /api/tasks/:id/update (not an MCP tool). */
 export const taskUpdateSchema = z.object({
     status: z.enum(TASK_STATUSES).optional(),

package/build/server/nexus.js

@@ -1,14 +1,16 @@
+import { randomUUID } from "node:crypto";
 import { CLIENT_INFO_META_KEY, ProtocolError, ProtocolErrorCode, Server, } from "@modelcontextprotocol/server";
-import { serveStdio } from "@modelcontextprotocol/server/stdio";
+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";
 /**
- * Stateless MCP adapter in front of the daemon.
+ * 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`
@@ -24,6 +26,14 @@ export class NexusServer {
     /** 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;
     stopped = false;
     /**
@@ -37,19 +47,33 @@ export class NexusServer {
     constructor(options = {}) {
         const endpoint = process.env.NEXUS_ENDPOINT || "http://127.0.0.1:5688";
         this.retryIntervalMs = options.retryIntervalMs ?? RETRY_INTERVAL_MS;
+        this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? HEARTBEAT_INTERVAL_MS;
         this.client = new NexusClient({ endpoint, timeoutMs: options.requestTimeoutMs ?? 5000 });
     }
     /** 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 () => {
+        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." }],
@@ -60,13 +84,13 @@ export class NexusServer {
             const unknownTool = () => new ProtocolError(ProtocolErrorCode.InvalidParams, `Unknown tool: ${request.params.name}`);
             if (!this.cachedTools.some((t) => t.name === request.params.name))
                 throw unknownTool();
-            // 2026-07-28 clients identify themselves per request; 2025-era clients did so in initialize.
-            const envelope = ctx.mcpReq.envelope;
-            this.clientName ??= envelope?.[CLIENT_INFO_META_KEY]?.name
-                ?? server.getClientVersion()?.name;
-            const instanceId = resolveInstanceId(process.env, process.argv, process.cwd(), this.clientName);
+            let callingTool = false;
             try {
-                const result = await this.client.callTool(request.params.name, request.params.arguments, 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
@@ -79,7 +103,7 @@ export class NexusServer {
             catch (e) {
                 const message = e instanceof Error ? e.message : String(e);
                 // The daemon dropped the tool since the list was fetched: resync so tools/list stops offering it.
-                if (e instanceof NexusToolError && e.status === 404) {
+                if (callingTool && e instanceof NexusToolError && e.status === 404) {
                     await this.refreshTools();
                     throw unknownTool();
                 }
@@ -88,12 +112,7 @@ export class NexusServer {
                     return { content: [{ type: "text", text: message }], isError: true };
                 }
                 // Daemon went away — drop the tool list and start the retry loop
-                if (this.connected) {
-                    this.connected = false;
-                    this.cachedTools = [];
-                    await this.notifyToolsChanged();
-                    this.scheduleRetry();
-                }
+                await this.daemonUnavailable();
                 return {
                     content: [{ type: "text", text: `Daemon unavailable: ${message}. Reconnecting...` }],
                     isError: true
@@ -103,6 +122,52 @@ export class NexusServer {
         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(() => { });
@@ -123,6 +188,12 @@ export class NexusServer {
     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;
@@ -142,12 +213,22 @@ export class NexusServer {
         }
     }
     /** Stop reconnecting and close the MCP connection. Safe to call more than once. */
-    async shutdown() {
-        if (this.stopped)
-            return;
+    shutdown() {
+        if (this.shutdownPromise)
+            return this.shutdownPromise;
         this.stopped = true;
         this.stopRetry();
-        await this.handle?.close().catch(() => { });
+        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
@@ -192,10 +273,16 @@ export class NexusServer {
         // 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: options.transport,
+            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) {

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/index.js

@@ -84,12 +84,15 @@ export class StorageManager {
     }
     static renameProject(oldId, newId) {
         return this.write(async () => {
-            await RegistryStorage.renameProject(oldId, newId);
+            if (!await RegistryStorage.getProjectManifest(oldId))
+                throw new Error(`Project '${oldId}' not found.`);
+            const renamed = await RegistryStorage.renameProject(oldId, newId);
+            if (renamed === 0)
+                throw new Error(`Project '${oldId}' could not be renamed.`);
             try {
                 const result = await ProjectStorage.renameProject(oldId, newId);
-                if (result === 0) {
-                    await RegistryStorage.renameProject(newId, oldId);
-                }
+                if (result === 0)
+                    throw new Error(`Project '${oldId}' could not be renamed.`);
                 return result;
             }
             catch (error) {

package/build/storage/migrations.js

@@ -9,8 +9,7 @@ import { MESSAGE_CATEGORIES } from "../types.js";
 import { FILE_ENCODING } from "../constants.js";
 /**
  * One-time upgrades of data written by earlier releases. Each step is
- * idempotent: it runs only while the legacy artifact is present and the
- * new location is still empty, then renames the artifact out of the way.
+ * idempotent: migrated artifacts are retired or completion is persisted.
  */
 /** 0.5.0 kept the global chat in global/discussion.json; import it into SQLite. */
 export async function importLegacyDiscussion() {
@@ -55,23 +54,31 @@ export async function importLegacyDiscussion() {
 }
 /** Title 0.5.0's update_global_strategy gave the doc it wrote; a user doc with another title is left alone. */
 export const LEGACY_STRATEGY_TITLE = "Global Collaboration Strategy";
+const LEGACY_STRATEGY_MIGRATION = "migration:legacy_strategy";
 /**
  * 0.5.0's update_global_strategy saved the strategy as the global doc
  * "strategy"; it now lives in global/blueprint.md. Move it there unless the
- * blueprint has already been written.
+ * blueprint has already been written. Record completion even when there
+ * is nothing to move, so later user documents cannot become legacy data.
  */
 export async function importLegacyStrategy() {
-    const docs = await DocStorage.listDocs();
-    if (docs.strategy?.title !== LEGACY_STRATEGY_TITLE)
+    const db = getDatabase();
+    if (db.prepare("SELECT 1 FROM meeting_state WHERE key = ?").get(LEGACY_STRATEGY_MIGRATION))
         return false;
-    const legacy = await DocStorage.getDoc("strategy");
-    const current = await DocStorage.getBlueprint();
-    if (legacy && (!current || current === BLUEPRINT_PLACEHOLDER)) {
-        await DocStorage.saveBlueprint(legacy);
+    const docs = await DocStorage.listDocs();
+    let moved = false;
+    if (docs.strategy?.title === LEGACY_STRATEGY_TITLE) {
+        const legacy = await DocStorage.getDoc("strategy");
+        const current = await DocStorage.getBlueprint();
+        if (legacy && (!current || current === BLUEPRINT_PLACEHOLDER)) {
+            await DocStorage.saveBlueprint(legacy);
+            await DocStorage.deleteDoc("strategy");
+            moved = true;
+            console.error("[n2n-nexus] Moved legacy global doc 'strategy' into global/blueprint.md");
+        }
     }
-    await DocStorage.deleteDoc("strategy");
-    console.error("[n2n-nexus] Moved legacy global doc 'strategy' into global/blueprint.md");
-    return true;
+    db.prepare("INSERT INTO meeting_state (key, value) VALUES (?, ?)").run(LEGACY_STRATEGY_MIGRATION, "complete");
+    return moved;
 }
 export async function runMigrations() {
     await importLegacyDiscussion();

package/build/storage/sessions.js

@@ -0,0 +1,77 @@
+import { getDatabase } from "./sqlite.js";
+export const SESSION_LEASE_MS = 60_000;
+function toSession(row, now) {
+    return {
+        sessionId: row.session_id, instanceId: row.instance_id, name: row.name,
+        clientName: row.client_name, workspace: row.workspace, projectId: row.project_id,
+        inbound: row.inbound, reception: "pull",
+        online: row.connected === 1 && now - Date.parse(row.last_seen_at) < SESSION_LEASE_MS,
+        createdAt: row.created_at, lastSeenAt: row.last_seen_at
+    };
+}
+export class SessionStore {
+    static register(input, now = Date.now()) {
+        const db = getDatabase();
+        return db.transaction(() => {
+            const existing = this.get(input.sessionId, now);
+            if (existing && existing.instanceId !== input.instanceId)
+                throw new Error("Session belongs to another instance");
+            const timestamp = new Date(now).toISOString();
+            if (existing) {
+                db.prepare("UPDATE sessions SET client_name = ?, workspace = ?, connected = 1, last_seen_at = ? WHERE session_id = ?")
+                    .run(input.clientName ?? existing.clientName, input.workspace ?? existing.workspace, timestamp, input.sessionId);
+            }
+            else {
+                db.prepare("INSERT INTO sessions (session_id, instance_id, name, client_name, workspace, created_at, last_seen_at) VALUES (?, ?, ?, ?, ?, ?, ?)")
+                    .run(input.sessionId, input.instanceId, `session-${input.sessionId.slice(0, 8)}`, input.clientName ?? "", input.workspace ?? "", timestamp, timestamp);
+            }
+            return this.get(input.sessionId, now);
+        })();
+    }
+    static get(sessionId, now = Date.now()) {
+        const row = getDatabase().prepare("SELECT * FROM sessions WHERE session_id = ?").get(sessionId);
+        return row ? toSession(row, now) : null;
+    }
+    static require(sessionId, instanceId) {
+        const session = this.get(sessionId);
+        if (!session)
+            throw new Error(`Unknown session: ${sessionId}`);
+        if (instanceId !== undefined && session.instanceId !== instanceId)
+            throw new Error("Session belongs to another instance");
+        return session;
+    }
+    static list(options = {}, now = Date.now()) {
+        const clauses = [];
+        const params = [];
+        if (options.projectId !== undefined) {
+            clauses.push("project_id = ?");
+            params.push(options.projectId);
+        }
+        if (options.onlineOnly) {
+            clauses.push("connected = 1 AND last_seen_at > ?");
+            params.push(new Date(now - SESSION_LEASE_MS).toISOString());
+        }
+        const rows = getDatabase().prepare(`SELECT * FROM sessions ${clauses.length ? `WHERE ${clauses.join(" AND ")}` : ""} ORDER BY last_seen_at DESC, rowid DESC LIMIT ?`)
+            .all(...params, options.limit ?? 100);
+        return rows.map(row => toSession(row, now));
+    }
+    static update(sessionId, changes, now = Date.now()) {
+        const db = getDatabase();
+        return db.transaction(() => {
+            const existing = this.require(sessionId);
+            db.prepare("UPDATE sessions SET name = ?, project_id = ?, inbound = ? WHERE session_id = ?")
+                .run(changes.name ?? existing.name, changes.projectId === undefined ? existing.projectId : changes.projectId, changes.inbound ?? existing.inbound, sessionId);
+            if (changes.inbound === "refuse") {
+                db.prepare("UPDATE direct_messages SET status = 'expired', reason = 'Message TTL elapsed' WHERE to_session_id = ? AND status IN ('accepted', 'fetched') AND expires_at <= ?")
+                    .run(sessionId, new Date(now).toISOString());
+                db.prepare("UPDATE direct_messages SET status = 'refused', reason = 'recipient_refused' WHERE to_session_id = ? AND status IN ('accepted', 'fetched')")
+                    .run(sessionId);
+            }
+            return this.get(sessionId, now);
+        })();
+    }
+    static disconnect(sessionId, instanceId) {
+        this.require(sessionId, instanceId);
+        getDatabase().prepare("UPDATE sessions SET connected = 0 WHERE session_id = ?").run(sessionId);
+    }
+}

package/build/storage/sqlite.js

@@ -98,6 +98,38 @@ CREATE TABLE IF NOT EXISTS read_cursors (
     updated_at TEXT,
     PRIMARY KEY (instance_id, context_type, context_id)
 );
+
+-- Live MCP connections have separate identities even within one IDE/project.
+CREATE TABLE IF NOT EXISTS sessions (
+    session_id TEXT PRIMARY KEY,
+    instance_id TEXT NOT NULL,
+    name TEXT NOT NULL,
+    client_name TEXT NOT NULL,
+    workspace TEXT NOT NULL,
+    project_id TEXT,
+    inbound TEXT NOT NULL CHECK(inbound IN ('accept', 'refuse')) DEFAULT 'accept',
+    connected INTEGER NOT NULL DEFAULT 1,
+    created_at TEXT NOT NULL,
+    last_seen_at TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project_id);
+
+CREATE TABLE IF NOT EXISTS direct_messages (
+    message_id TEXT PRIMARY KEY,
+    from_session_id TEXT NOT NULL REFERENCES sessions(session_id),
+    to_session_id TEXT NOT NULL REFERENCES sessions(session_id),
+    text TEXT NOT NULL,
+    category TEXT CHECK(category IN ('MEETING_START', 'PROPOSAL', 'DECISION', 'UPDATE', 'CHAT')),
+    reply_to TEXT REFERENCES direct_messages(message_id),
+    status TEXT NOT NULL CHECK(status IN ('accepted', 'fetched', 'acknowledged', 'replied', 'refused', 'expired')),
+    created_at TEXT NOT NULL,
+    expires_at TEXT NOT NULL,
+    fetched_at TEXT,
+    acknowledged_at TEXT,
+    replied_at TEXT,
+    reason TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_direct_messages_inbox ON direct_messages(to_session_id, status);
 `;
 /**
  * Get the database file path

package/build/storage/tasks.js

@@ -118,7 +118,7 @@ export function expireTasks(now = Date.now()) {
         SET status = 'failed', error_message = 'TTL expired', updated_at = ?
         WHERE status IN ('pending', 'running')
           AND ttl IS NOT NULL
-          AND strftime('%s', created_at) * 1000 + ttl < ?
+          AND ROUND(unixepoch(created_at, 'subsec') * 1000) + ttl < ?
     `).run(new Date(now).toISOString(), now).changes;
 }
 /**

package/docs/ARCHITECTURE.md

@@ -20,16 +20,16 @@
    ▼      ▼      ▼
 MCP-A  MCP-B  MCP-C
 (Win)  (WSL)  (VM)
-Stateless protocol adapter, one per IDE
+Lightweight protocol adapter, one per MCP connection
 ```
 
 ### Core Principles
 
 1. **Daemon is the single source of truth** — all reads/writes, business logic, and tool definitions live in the daemon.
-2. **MCP is a stateless protocol adapter** — no tool definitions, no hardcoded names, no local data.
-3. **Daemon decides tool capability** — MCP fetches `GET /api/tools` at startup; any daemon upgrade is immediately visible to all connected MCPs.
+2. **MCP holds connection identity only** — no hardcoded tool names or local persistent data; sessions and inboxes live in the daemon.
+3. **Daemon decides tool capability** — MCP fetches `GET /api/tools` at startup and reconnect. Session inboxes require both the session-aware adapter and daemon; legacy clients can continue using the existing shared-message APIs.
 4. **No local fallback** — if the daemon is unreachable, the MCP reports an error and retries every 3 s. No split-brain degradation. A tool call the daemon rejects (validation, not found, permission) is returned to the IDE as an error result (`isError: true`) and does not affect the connection; an unknown tool name is a JSON-RPC `-32602` error.
-5. **Plain HTTP between MCP and daemon** — no SSE; AI is request-driven and doesn't need push.
+5. **Plain HTTP between MCP and daemon** — inboxes are pulled explicitly; heartbeats maintain presence but do not wake the model.
 
 ### MCP Startup Flow
 
@@ -51,6 +51,8 @@ Read NEXUS_ENDPOINT (default: http://127.0.0.1:5688)
 
 The adapter's instance ID (read cursors, meeting permissions) uses the first client name seen on the connection, from the request's `io.modelcontextprotocol/clientInfo` (2026-07-28) or from `initialize` (2025 era), unless `NEXUS_INSTANCE_ID` / `--id` pins it.
 
+Each MCP connection also gets a random session ID, registered on its first tool request and refreshed every 20 seconds with a 60-second presence lease. Disconnect marks it offline; an adapter restart creates a new session, so pending messages for the old session are not transferred. Multiple host chats sharing a connection share its inbox. Project association is directory metadata, not an implicit target for project tools. Registration and disconnect use `POST /api/sessions/register` and `POST /api/sessions/disconnect`; direct tools receive session identity outside their model-supplied arguments. This remains a trusted local daemon, not an authentication boundary. See [tool reference](TOOLS_REFERENCE.md#session-directory-and-direct-inboxes).
+
 ---
 
 ## 💾 Data Persistence
@@ -145,7 +147,7 @@ npx n2n-nexus daemon --root ~/.n2n-nexus --port 5688
 ### Tool capability (MCP-facing)
 ```
 GET  /api/tools              Return full tool definition list (JSON Schema)
-POST /api/tools/call         Execute tool call { tool, args, instanceId }
+POST /api/tools/call         Execute tool call { tool, args, instanceId, sessionId? }
 ```
 
 ### System

package/docs/ARCHITECTURE_zh.md

@@ -20,16 +20,16 @@
    ▼      ▼      ▼
 MCP-A  MCP-B  MCP-C
 (Win)  (WSL)  (VM)
-无状态协议适配器，每个 IDE 一个
+轻量协议适配器，每条 MCP 连接一个
 ```
 
 ### 核心原则
 
 1. **Daemon 是唯一的真相来源** — 所有读写、业务逻辑和工具定义都在 daemon 侧。
-2. **MCP 是无状态协议适配器** — 不含工具定义、不含 hardcode 工具名、不存本地数据。
-3. **Daemon 决定工具能力** — MCP 启动时拉取 `GET /api/tools`；daemon 升级新工具后，所有已连接 MCP 立即获得新能力，无需更新。
+2. **MCP 只维护连接身份** — 不含 hardcode 工具名、不存本地持久化数据；会话目录和收件箱在 daemon。
+3. **Daemon 决定工具能力** — MCP 启动和重连时拉取 `GET /api/tools`。个人收件箱需要适配器和 daemon 都支持会话身份；旧客户端仍可使用原有共享消息接口。
 4. **无本地降级** — daemon 不可达时，MCP 每 3 秒重试并报告错误，不做本地 fallback（避免数据分裂）。daemon 拒绝的工具调用（校验失败、不存在、无权限）作为错误结果（`isError: true`）返回给 IDE，不影响连接；未知工具名返回 JSON-RPC `-32602` 错误。
-5. **MCP ↔ Daemon 全部走普通 HTTP** — 不使用 SSE；AI 是请求驱动模型，不需要推送。
+5. **MCP ↔ Daemon 全部走普通 HTTP** — 收件箱由助手主动拉取；心跳只维护在线状态，不唤醒模型。
 
 ### MCP 启动流程
 
@@ -51,6 +51,8 @@ MCP-A  MCP-B  MCP-C
 
 适配器的实例 ID（未读游标、会议权限以它为键）取自该连接上第一次见到的客户端名，来源是请求 `_meta` 中的 `io.modelcontextprotocol/clientInfo`（2026-07-28）或 `initialize`（2025 代），`NEXUS_INSTANCE_ID` / `--id` 可固定。
 
+每条 MCP 连接还会生成随机会话 ID，在首次工具请求时注册，每 20 秒刷新一次心跳，在线租约为 60 秒。断连后标记离线；适配器重启会创建新会话，旧会话的待收消息不会转移。宿主多个聊天共用连接时也共用收件箱。项目关联仅用于目录筛选，不作为项目工具的隐式操作目标。注册和断连分别使用 `POST /api/sessions/register` 与 `POST /api/sessions/disconnect`，工具请求的会话身份放在模型参数之外。系统仍采用可信本地 daemon 边界，这不是身份认证机制。精确契约见[工具参考](TOOLS_REFERENCE.md#session-directory-and-direct-inboxes)。
+
 ---
 
 ## 💾 数据持久化
@@ -113,7 +115,7 @@ n2n-nexus
   │
   ├─ n2n-nexus daemon    用户手动启动一次，持续运行，持有所有数据。
   │
-  └─ n2n-nexus mcp       IDE 通过 npx 自动启动，无状态代理。
+  └─ n2n-nexus mcp       IDE 通过 npx 自动启动，维护连接身份。
 ```
 
 **Daemon**（用户手动启动）：
@@ -145,7 +147,7 @@ npx n2n-nexus daemon --root ~/.n2n-nexus --port 5688
 ### 工具能力（MCP 对接）
 ```
 GET  /api/tools              返回完整工具定义列表（JSON Schema）
-POST /api/tools/call         执行工具调用 { tool, args, instanceId }
+POST /api/tools/call         执行工具调用 { tool, args, instanceId, sessionId? }
 ```
 
 ### 系统

package/docs/ASSISTANT_GUIDE.md

@@ -22,7 +22,7 @@ read_messages(count)            → fetch messages you have not yet read (increm
 
 ### 2. Project IDs
 
-There is no session to set up: every project tool takes the `projectId` it acts on.
+Project operations need no implicit project context: every project tool takes the `projectId` it acts on.
 Project IDs must follow `[prefix]_[name]` format, for example: `web_my-site`, `api_user-auth`, `mcp_nexus`.
 
 ### 3. Write project data
@@ -36,6 +36,15 @@ upload_project_asset(projectId, fileName, base64Content) → upload a binary fil
 
 All write tools run synchronously and return their result directly.
 
+### Direct conversations
+
+1. Call `list_sessions` to find the exact destination `sessionId`; use `update_session` to set your name and project association.
+2. Send `send_message({ to: sessionId, message: "Please review this change" })`. Inspect `status`: accepted means stored, refused means rejected.
+3. The recipient calls `read_inbox`, then `acknowledge_message({ messageId })` to confirm receipt or passes `outcome: "refused"` to decline.
+4. Reply with `send_message({ to: original.from, replyTo: original.messageId, message: "Review result..." })`. The sender can query `get_message({ messageId })` for the original receipt.
+
+Unconfirmed fetched messages can appear again; use their IDs to recognize retries. Acknowledgement does not mean work is complete. The inbox is pull-only: there is no automatic model wakeup. Connection restarts create new session IDs; discover the destination again. See [receipt and session contracts](TOOLS_REFERENCE.md#session-directory-and-direct-inboxes).
+
 ### 4. Messages and collaboration
 
 ```

package/docs/README_zh.md

@@ -31,7 +31,7 @@ n2n-nexus 是一个开源的 Model Context Protocol (MCP) 协同服务器，适
 - AI 助手项目注册表
 - 编码 agent 会议和任务协同
 
-n2n-nexus 面向这些场景设计：共享 daemon 状态、无状态 MCP 适配器、项目感知协作、本地存储和跨环境 IDE 工作流。
+n2n-nexus 面向这些场景设计：共享 daemon 状态、轻量 MCP 适配器、项目感知协作、本地存储和跨环境 IDE 工作流。
 
 ## n2n-nexus 是什么？
 
@@ -66,11 +66,11 @@ n2n-nexus 为 AI 助手提供共享协作空间。不同助手不再只依赖自
        ▼       ▼       ▼
     MCP-A   MCP-B   MCP-C
    (Win)   (WSL)   (SSH/VM)
-  每个 IDE 一个无状态适配器
+  每条 MCP 连接一个轻量适配器
 ```
 
 - **Daemon 是唯一数据源**：启动一次并保持运行。
-- **MCP 适配器无状态**：每个 IDE 通过 `npx` 启动适配器，然后把工具调用转发给 daemon。
+- **MCP 适配器只维护连接身份**：每个 IDE 通过 `npx` 启动适配器，然后把工具调用转发给 daemon；会话目录和收件箱保存在 daemon。
 - **跨环境协作**：通过 `NEXUS_ENDPOINT` 让不同机器或 shell 指向同一个 daemon。daemon 默认只监听本机；只有在可信网络中才使用 `--host 0.0.0.0`。
 
 ## 快速开始
@@ -124,7 +124,10 @@ npx n2n-nexus daemon --port 5688
 
 ### 消息和协作
 
-- `send_message`：发送会议消息或全局消息。
+- `send_message`：向精确会话 ID 发送定向消息，也保留会议消息和全局消息。
+- `list_sessions` / `update_session`：发现连接，设置自己的名称、项目关联和接收策略。
+- `read_inbox` / `acknowledge_message`：取回个人消息并明确确认或拒绝。
+- `get_message`：查询自己发送或接收的消息状态和回复关联。
 - `read_messages`：增量读取未读消息（全局或指定会议）。
 - `list_events`：读取结构化活动日志（项目同步、重命名、会议结束等）。
 - `get_global_strategy`：读取主策略文档。
@@ -133,6 +136,8 @@ npx n2n-nexus daemon --port 5688
 - `get_global_doc`：读取共享文档。
 - `sync_global_doc`：创建或更新共享文档。
 
+每条 MCP 连接有独立会话 ID；多个聊天若共用连接，仍视为一个会话。在线仅表示近期心跳，消息采用主动拉取，不自动唤醒模型。已存储、已取回、已确认和已回复是不同状态，确认收件不等于任务完成。使用流程见[助手指南](ASSISTANT_GUIDE_zh.md)，精确契约见[工具参考](TOOLS_REFERENCE.md#session-directory-and-direct-inboxes)。
+
 ### 会议管理
 
 - `list_meetings`：列出会议（状态、参与者、消息与决策数、摘要）。

package/llms.txt

@@ -1,6 +1,6 @@
 # n2n-nexus
 
-n2n-nexus is a local-first Model Context Protocol (MCP) coordination hub from N2NS Lab for multi-AI assistant collaboration. It uses a long-running local daemon as the source of truth and stateless MCP adapters for IDEs and AI coding assistants.
+n2n-nexus is a local-first Model Context Protocol (MCP) coordination hub from N2NS Lab for multi-AI assistant collaboration. It uses a long-running local daemon as the source of truth and lightweight MCP adapters for IDEs and AI coding assistants. Each MCP connection has a discoverable session identity and a pull-based direct inbox with explicit receipts and reply links; messages do not automatically wake models.
 
 ## Search intent coverage
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "n2n-nexus",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Local-first MCP coordination hub from N2NS Lab for multi-AI assistant collaboration.",
   "main": "build/index.js",
   "type": "module",
@@ -84,17 +84,17 @@
   "dependencies": {
     "@modelcontextprotocol/server": "^2.3.1",
     "better-sqlite3": "^13.0.3",
-    "zod": "^4.6.6"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@modelcontextprotocol/client": "^2.3.1",
     "@types/better-sqlite3": "^9.6.0",
     "@types/node": "^26.6.5",
-    "eslint": "^10.12.0",
-    "lefthook": "^2.2.1",
+    "eslint": "^10.13.0",
+    "lefthook": "^2.2.2",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.71.1",
-    "vitest": "^5.0.3"
+    "typescript-eslint": "^8.72.0",
+    "vitest": "^5.0.5"
   }
 }