n2n-nexus 0.4.2 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,120 @@
 
 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
+
+- Rate limiting, which the MCP tools specification requires of servers: a token bucket per instance ID (default 20 calls/s, burst 60; `NEXUS_RATE_LIMIT`, `NEXUS_RATE_BURST`, `0` disables) plus one per client address at five times that, since instance IDs are self-declared. Requests without an instance ID (most REST reads) are limited per address only. Over the limit the daemon answers `429` with `Retry-After`; the MCP adapter reports it to the model as a tool error and keeps the connection. `/health` and `GET /api/tools` are exempt.
+
+- Structured tool results: every successful call returns `structuredContent` alongside the JSON text, and the eleven data-returning tools publish an `outputSchema`. Result shapes are zod contracts in `src/daemon/tool-outputs.ts` that type the handlers; a test calls all tools through the adapter for both protocol eras and checks each result against its contract. Publishing schemas for write tools as well would have grown `tools/list` from about 14 KB to 27 KB for a one-line acknowledgement, so they are left out (22 KB with the read schemas).
+
+- A display `title` on every tool (for example "Delete Project"), which MCP clients show instead of the raw tool name.
+
+- MCP tool annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) on every tool, so clients can tell read-only tools from ones that overwrite or delete data and ask the user before the latter.
+
+- `list_meetings` tool and `GET /api/meetings`: list meetings with status, initiator, participants, message and decision counts and summary. Assistants could only reach a meeting whose id they already knew.
+
+- `get_project` tool and `GET /api/projects/:projectId`: read a project's full manifest and internal docs. Assistants could sync them but had no tool to read them back.
+
+- `get_global_strategy`, `list_global_docs` and `get_global_doc` tools. Assistants could write the strategy and shared docs but had no tool to read them back; only the REST API could.
+
+- `list_events` tool and `GET /api/events`: a structured activity log (actor, action, target, detail) of every state change made through the daemon.
+
+### Removed
+
+- `register_session_context` and `POST /api/session/register`. The daemon kept an in-memory "current project" per instance that only `upload_project_asset` used; MCP 2026-07-28 makes protocol sessions go away and recommends passing cross-call state as explicit tool arguments. `upload_project_asset` now takes `projectId` and checks that the project exists.
+
+- Leftovers from the pre-0.5 election architecture and other dead code: unused constants (`PORT_RANGE_*`, `HANDSHAKE_TIMEOUT`, `HEARTBEAT_INTERVAL`), `hasFlag`, `HubConfig`/`ToolContext`/`MeetingState` types, `isSqliteAvailable`, `getTasksByMeeting`, `getActiveTaskCount`, `NexusClient.health`, the never-used `archives/` directory and `tasks.json` path, `suggestedSyncTargets` (parsed a `name@project` instance-id format that no longer exists), the undocumented `NEXUS_PORT` alias of `NEXUS_DAEMON_PORT`, and `migrations/003_add_tasks_table.sql` (the schema lives in `sqlite.ts`). The two `getRootPath` implementations are merged into `config/paths.ts`, so `--root ./relative` and `~` are resolved consistently. `billing` is now preserved on read and patch instead of being dropped.
+
+- JSON meeting-store fallback (`store.ts`, `meetings.ts`) and the `/api/storage/info` endpoint. SQLite is required; the daemon no longer reports a "degraded" storage mode.
+
+### Fixed
+
+- `NEXUS_RATE_BURST` between 0 and 1 made every call fail with 429 forever, and `NEXUS_RATE_BURST=0` silently disabled rate limiting. The burst is now at least 1, and only `NEXUS_RATE_LIMIT=0` disables limiting.
+
+- Manifests written by earlier releases (whose `update_project` stored patches unvalidated) could hold nested relations, endpoints or API specs with missing or extra fields, which made `get_project` and `get_global_topology` fail outputSchema validation on 2026-07-28 clients. Reads now normalize stored manifests: invalid entries are dropped, missing strings become empty, an unknown relation type reads as `related`. The files are not rewritten.
+
+- Result contracts were only enforced by TypeScript, which ignores extra fields on returned variables, so a new field in stored data could reach clients as structuredContent that violates the published `outputSchema`. Every result now passes through its zod contract on the way out: undeclared fields are stripped, and a result that cannot meet the contract becomes a server error.
+
+- If a tool call lost the daemon while a reconnect attempt that had just succeeded was still notifying the client, the attempt then stopped the retry loop although the adapter was disconnected again; every later call answered "Daemon is not ready yet" until the IDE restarted. The loop now stops only if the connection is still up.
+
+- The adapter's reconnect loop used a 3-second `setInterval` while each attempt could take up to the 5-second request timeout, so a hung daemon accumulated overlapping requests. Each attempt is now scheduled only after the previous one finishes.
+
+- `rename_project`, `cancel_task`, `end_meeting`, `archive_meeting` and `reopen_meeting` were annotated `destructiveHint: false`, which MCP reserves for purely additive tools; clients could run them without asking the user. They are now marked destructive.
+
+- When the daemon reported a tool as unknown (for example after an upgrade the adapter did not notice), the adapter returned `-32602` but kept offering the tool in `tools/list`. It now re-fetches the tool list and sends `list_changed` if it differs.
+
+- The adapter fetched the daemon tool list before it began reading stdin. A daemon that accepted connections but never answered held `server/discover` and `initialize` for the 5-second client timeout, long enough for probing clients to misclassify the server as legacy, and delayed exit after stdin closed. The adapter now serves immediately and fetches in the background.
+
+- On 2026-07-28 connections, a request without `io.modelcontextprotocol/clientInfo` (only a SHOULD in the spec) got an instance ID without the IDE name, so one client could appear as two instances with split unread cursors and meeting permissions. The adapter now keeps the first client name seen on the connection.
+
+- Calling a tool the adapter does not know returned a tool result with `isError: true`. The MCP specification classifies an unknown tool as a protocol error; the adapter now answers with JSON-RPC error `-32602` (Invalid Params), also when the daemon reports the tool as unknown.
+
+- The MCP adapter did not exit when the IDE closed its stdin: while the daemon was unreachable the 3-second reconnect timer kept the process alive indefinitely, leaving orphaned adapters. The adapter now shuts down and exits when stdin ends, as the stdio transport specification requires.
+
+- Project and document ids that match `Object.prototype` keys were mishandled: `register_session_context({ projectId: "constructor" })` reported success for a project that did not exist, and a project or doc named `__proto__` was silently lost because assigning it rewrote the map's prototype. The registry and docs index are now prototype-free maps.
+
+- `sync_project_assets` wrote the manifest and the internal docs as two separately locked steps, so a concurrent `host_delete_project` could run between them and leave a project directory on disk that the registry no longer knew about. Both writes now happen in one critical section.
+
+- `npm run build` now clears `build/` first. `tsc` alone left compiled files of deleted sources behind (for example `build/storage/store.js`), and `npm publish` would have shipped them.
+
+- `ttl` on tasks was stored but never enforced and `cleanupTasks` was never scheduled, so the tasks table grew forever. The daemon now runs task maintenance at startup and hourly: pending/running tasks past their TTL are marked `failed` (`TTL expired`) and finished tasks older than 7 days are purged. The `tasks_updated_at` trigger is dropped: it overwrote the ISO 8601 `updated_at` written by `updateTask` with `datetime('now')` in a different format, so age comparisons mixed two timestamp formats.
+
+- `update_global_strategy` wrote `global/docs/strategy.md` while the documentation described `global/blueprint.md` as the master strategy document, and two initializers created `blueprint.md` with different placeholder text. The tool now writes `blueprint.md`; `GET /api/global/strategy` reads it. On first start an existing `strategy` global doc is moved into `blueprint.md` (unless a non-placeholder blueprint is already there) and removed from the docs index.
+
+- `sqlite.ts` registered SIGINT/SIGTERM handlers at import time that called `process.exit(0)` immediately, so the daemon's graceful `server.close` never ran. Signal handling now lives in the daemon entry point: stop accepting connections, finish in-flight requests, close the database, exit.
+
+- Tool arguments were never validated: the daemon cast whatever arrived and let SQLite or the filesystem fail later (for example `category: "SYSTEM"` surfaced as a `CHECK constraint failed` 500). Every tool now has a zod contract in `src/daemon/tools.ts`; the JSON Schema served to MCP clients is generated from it and the same contract validates tool calls and REST endpoints, returning 400 with the failing field. `patch` for `update_project` rejects unknown fields, `create_task` checks that `source_meeting_id` exists, and SQLite foreign keys are enforced.
+
+- The MCP adapter generated a random instance ID on every start, so an IDE restart reset unread cursors and left meetings that no one could end or archive (only the initiator may). The default is now `mcp-<hostname>-<hash of working directory>-<IDE name>` (IDE name from the MCP handshake), stable per machine, workspace and IDE. `reopen_meeting` applies the same initiator check as `end_meeting` and `archive_meeting`.
+
+- The daemon accepted any HTTP request, so a web page open in the user's browser could call `host_delete_project` on the local daemon with a cross-site `text/plain` POST. Requests carrying a browser `Origin` or cross-site `Sec-Fetch-Site` header are refused (403), POST requires `Content-Type: application/json` (415), and request bodies are capped at 16 MB (413) instead of being buffered without limit. The `Host` header must be an IP literal, `localhost`, `host.docker.internal` or a name in `NEXUS_ALLOWED_HOSTS`, which blocks DNS-rebinding pages that would otherwise reach the daemon as same-origin GETs.
+
+- The MCP adapter treated every failed tool call (unknown task, closed meeting, permission denied, ...) as the daemon going away: it cleared the tool list, notified the IDE and entered the reconnect loop. Transport failures and tool failures are now distinct (`NexusTransportError` vs `NexusToolError`); only the former triggers reconnection, and tool failures are returned as `isError` results. `POST /api/tools/call` answers 404 for an unknown tool and 400 when the tool rejects the call.
+
+### Changed
+
+- The MCP adapter moved from `@modelcontextprotocol/sdk` 1.x (protocol 2025-11-25) to the v2 SDK (`@modelcontextprotocol/server` 2.3) and serves both the stateless 2026-07-28 revision and 2025-era clients over stdio via `serveStdio`. 2026-07-28 clients get `server/discover`, the per-request `_meta` envelope and list-changed notifications on `subscriptions/listen`; the instance ID reads the client name from the request envelope. The first `tools/list` waits up to one second for the startup daemon fetch, so it is complete whenever a local daemon is up, while `server/discover` and `initialize` are answered immediately even if the daemon hangs.
+
+- Tools without parameters (`get_global_strategy`, `list_global_docs`) publish `{ "type": "object", "properties": {}, "additionalProperties": false }`, the form the MCP specification recommends, and reject unexpected arguments.
+
+- `send_message` routing no longer depends on `register_session_context`: a message goes to `meetingId` when given, else to the active meeting, else to global chat. `POST /api/messages/send` uses the same rule (its `source` parameter is gone) instead of a separate code path with different defaults.
+
+- Global chat moved from `global/discussion.json` into SQLite. `read_messages` without `meetingId` is now truly incremental per instance (the tool description had promised this), appends no longer rewrite the whole file, and `host_maintenance` reports how many messages were removed. On first start the daemon imports an existing `discussion.json` (categories outside the five known values become unset) and renames it to `discussion.json.migrated`.
+- Daemon state changes (session register, project sync/rename/delete, meeting end, ...) are recorded as events instead of `SYSTEM` lines in the global chat.
+
+- `sync_project_assets`, `update_project`, `rename_project`, and `host_delete_project` now run synchronously and return their result directly instead of a `task_id` to poll. The operations take milliseconds; the background-task wrapper only added a polling round-trip and let the work race with other requests.
+
+- Require Node.js 22.14+ on the 22.x release line, or Node.js 23.6+ and update MCP SDK, SQLite, and test dependencies to their latest compatible stable releases.
+
 ## [0.5.0] - 2026-06-14
 
 ### 🏗️ Daemon + MCP Architecture (Breaking Refactor)

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="./assets/n2n-nexus-logo.png" width="128" alt="n2n-nexus logo">
+</p>
+
 # n2n-nexus
 
 Local-first MCP coordination hub from N2NS Lab for multi-AI assistant collaboration across IDEs, machines, and projects.
@@ -7,7 +11,6 @@ Local-first MCP coordination hub from N2NS Lab for multi-AI assistant collaborat
 [![license](https://img.shields.io/github/license/n2ns/n2n-nexus)](https://github.com/n2ns/n2n-nexus/blob/main/LICENSE)
 [![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-blue)](https://modelcontextprotocol.io)
 [![node version](https://img.shields.io/node/v/n2n-nexus)](https://nodejs.org)
-[![DataFrog.io](https://datafrog.io/badges/datafrog.svg)](https://datafrog.io)
 
 [中文版](./docs/README_zh.md)
 
@@ -15,45 +18,33 @@ Local-first MCP coordination hub from N2NS Lab for multi-AI assistant collaborat
 
 > **One daemon. Many assistants. Shared project state.**
 
-n2n-nexus is an open-source Model Context Protocol (MCP) coordination server for teams and developers who use multiple AI coding assistants. A long-running local daemon owns project state, meetings, messages, tasks, shared docs, and project assets. Lightweight MCP adapters connect each IDE or assistant to the same daemon.
-
-Use it when Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, JetBrains, or other MCP-enabled clients need a shared local coordination layer instead of isolated per-chat context.
-
-## Search-friendly positioning
-
-If you are searching for:
-
-- multi-agent MCP coordination
-- multi-AI assistant collaboration
-- local MCP coordination hub
-- shared project context for AI coding agents
-- cross-IDE MCP collaboration server
-- local-first project registry for AI assistants
-- meeting and task coordination for coding agents
+n2n-nexus is an open-source Model Context Protocol (MCP) coordination server for developers and teams who use multiple AI coding assistants across IDEs, machines, and projects. Use it when Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, JetBrains, or other MCP-enabled clients need a shared local coordination layer instead of isolated per-chat context.
 
-n2n-nexus is designed for these goals: shared daemon state, stateless MCP adapters, project-aware collaboration, local storage, and cross-environment IDE workflows.
+## 📚 Contents
 
-## What Is n2n-nexus?
+- [What is n2n-nexus?](#-what-is-n2n-nexus)
+- [Architecture](#️-architecture)
+- [Quick start](#-quick-start)
+- [Toolset](#️-toolset)
+- [Data storage](#-data-storage)
+- [Project ID conventions](#️-project-id-conventions)
+- [CLI reference](#-cli-reference)
+- [Security and governance notes](#-security-and-governance-notes)
+- [Real-world example](#-real-world-example)
+- [Local development](#-local-development)
+- [Related docs](#-related-docs)
 
-n2n-nexus gives AI assistants a shared coordination workspace. Instead of each assistant keeping its own isolated conversation state, all connected MCP clients can read and write to the same local daemon.
+## 💡 What is n2n-nexus?
 
-**TL;DR**
-
-- **Install**: `npx n2n-nexus daemon --port 5688`
-- **Protocol**: Model Context Protocol (MCP), adapter-to-daemon HTTP bridge
-- **Storage**: local filesystem plus SQLite under `~/.n2n-nexus` by default
-- **Best for**: multi-assistant coding sessions, project handoffs, shared decisions, meeting notes, async tasks, project manifests
-- **Not for**: cloud team chat, public project management SaaS, source code indexing, vector search, or remote database hosting
-
-## Why Use It?
+n2n-nexus gives AI assistants a shared coordination workspace. A long-running local daemon owns project state, meetings, messages, tasks, shared docs, and project assets. Lightweight MCP adapters connect each IDE or assistant to the same daemon.
 
 - Coordinate multiple AI assistants working on the same project.
-- Share project manifests, internal notes, assets, and topology across IDEs.
-- Keep decisions, proposals, and updates in a local meeting/message log.
-- Run the daemon once and connect adapters from Windows, WSL, SSH hosts, VMs, or multiple editors.
-- Avoid giving each assistant broad filesystem or backend access just to exchange context.
+- Share project manifests, decisions, and assets across IDEs and machines.
+- Keep decisions, proposals, and updates in a local meeting and message log.
+- Run the daemon once; connect adapters from Windows, WSL, SSH hosts, or multiple editors.
+- Avoid giving each assistant broad filesystem or backend access.
 
-## Architecture
+## 🏗️ Architecture
 
 ```text
 ┌──────────────────────────────────────┐
@@ -70,10 +61,12 @@ n2n-nexus gives AI assistants a shared coordination workspace. Instead of each a
 ```
 
 - **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
+## 🚀 Quick start
+
+Requires Node.js 22.14+ on the 22.x release line, or Node.js 23.6+.
 
 ### 1. Start the daemon
 
@@ -108,48 +101,26 @@ The adapter can start before the daemon. It loads the daemon tool list once the
 | Windows IDE to WSL daemon | `http://<WSL-IP>:5688` |
 | Remote machine | `http://<Server-IP>:5688` |
 
-## Toolset
-
-### Session and context
+## 🛠️ Toolset
 
-- `register_session_context`: declare the active project ID.
+The daemon exposes 31 tools, grouped by purpose:
 
-### Project asset management
-
-- `sync_project_assets`: submit a project manifest and internal docs.
-- `update_project`: patch a project manifest.
-- `rename_project`: rename a project ID and update relations.
-- `upload_project_asset`: upload binary or text assets.
-- `search_projects`: search the project registry.
-- `get_global_topology`: inspect project topology and dependencies.
-
-### Messaging and collaboration
-
-- `send_message`: post meeting or global messages.
-- `read_messages`: read unread messages incrementally.
-- `update_global_strategy`: update the master strategy document.
-- `sync_global_doc`: create or update shared docs.
-
-### Meeting management
-
-- `start_meeting`: open a meeting session.
-- `end_meeting`: close and lock a meeting.
-- `archive_meeting`: move a closed meeting to archive.
-- `reopen_meeting`: reactivate a closed or archived meeting.
-
-### Async task management
-
-- `create_task`: create a background task.
-- `get_task`: poll task status and result.
-- `list_tasks`: list tasks by status.
-- `cancel_task`: cancel a pending or running task.
+| 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` | 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. |
 
-### Maintenance
+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).
 
-- `host_maintenance`: prune or clear system logs.
-- `host_delete_project`: delete a project and assets.
+See [Tools reference](./docs/TOOLS_REFERENCE.md) for parameter schemas and call examples.
 
-## Data Storage
+## 💾 Data storage
 
 Default storage root:
 
@@ -173,10 +144,10 @@ Override with `--root <path>` or `NEXUS_ROOT`.
 │       ├── internal_blueprint.md
 │       └── assets/
 ├── registry.json
-└── nexus.db
+└── nexus.db          # meetings, global chat, events, tasks, read cursors
 ```
 
-## Project ID Conventions
+## 🏷️ Project ID conventions
 
 Project IDs follow `[prefix]_[name]`.
 
@@ -192,7 +163,7 @@ Project IDs follow `[prefix]_[name]`.
 | `infra_` | Infrastructure / DevOps | `infra_k8s-config` |
 | `doc_` | Documentation | `doc_coding-guide` |
 
-## CLI Reference
+## 💻 CLI reference
 
 ```bash
 # Start daemon
@@ -209,9 +180,13 @@ NEXUS_ENDPOINT=http://127.0.0.1:5688 n2n-nexus mcp
 | `NEXUS_ENDPOINT` | Daemon URL for MCP adapter | `http://127.0.0.1:5688` |
 | `NEXUS_ROOT` | Storage root for daemon | `~/.n2n-nexus` |
 | `NEXUS_HOST` | Daemon bind host | `127.0.0.1` |
-| `NEXUS_INSTANCE_ID` | Override MCP instance ID | auto-generated |
+| `NEXUS_DAEMON_PORT` | Daemon port (overridden by `--port`) | `5688` |
+| `NEXUS_RATE_LIMIT` | Tool calls per second per instance; each client address gets 5x. `0` disables rate limiting | `20` |
+| `NEXUS_RATE_BURST` | Calls an instance may make at once before the per-second limit applies (minimum 1) | `60` |
+| `NEXUS_ALLOWED_HOSTS` | Extra DNS names accepted in the `Host` header (IP literals, `localhost`, `host.docker.internal` are always accepted) | empty |
+| `NEXUS_INSTANCE_ID` | Override MCP instance ID (read cursors and meeting permissions are keyed on it) | `mcp-<hostname>-<hash of working directory>-<IDE name>` |
 
-## Security and governance notes
+## 🔐 Security and governance notes
 
 - n2n-nexus stores coordination data locally by default.
 - Do not put secrets, credentials, customer data, or private tokens in meeting messages or project assets unless your local policy allows it.
@@ -219,16 +194,26 @@ NEXUS_ENDPOINT=http://127.0.0.1:5688 n2n-nexus mcp
 - Exposing the daemon beyond localhost is an operational choice; restrict network access when using remote endpoints.
 - Treat project manifests and internal docs as potentially sensitive implementation data.
 
-## Real-world example
+## 🌐 Real-world example
 
-The docs include a sample multi-agent session where several AI assistants collaborated on architecture and protocol decisions:
+The docs include a recorded multi-agent session that shows n2n-nexus in action. Four AI assistants — running in different IDEs and assigned to different projects — used a shared n2n-nexus daemon to coordinate in real time.
 
-| File | Description |
+What to look for in the session:
+
+- **Shared coordination space**: each assistant registered its active project (with the `register_session_context` tool of that release; current versions pass `projectId` explicitly instead), then read and wrote to the same daemon throughout the session.
+- **Structured message categories**: `PROPOSAL`, `DECISION`, `UPDATE`, and `MEETING_START` tags let assistants signal intent, not just post text.
+- **SYSTEM entries**: lines like `[Augment] Synced global doc: edge-sync-protocol-v1` record actual tool calls. That version wrote them into the chat stream; current versions keep them out of the conversation and expose them as structured events through `list_events`.
+- **Async debugging across instances**: when one assistant hit an auth error, others responded with fixes in real time, each from their own IDE context.
+- **Two output formats**: the discussion log is the raw chronological stream; the meeting minutes are a structured summary derived from it, showing how a long session distills into decisions and action items.
+
+| File | What it shows |
 | --- | --- |
-| [Meeting Minutes](docs/MEETING_MINUTES_2025-12-29.md) | Structured decisions and test notes |
-| [Discussion Log](docs/discussion_2025-12-29_en.md) | Human-readable discussion transcript |
+| [Discussion Log](docs/discussion_2025-12-29.md) | The full chronological stream: proposals, debug exchanges, decisions, and SYSTEM tool entries |
+| [Meeting Minutes](docs/MEETING_MINUTES_2025-12-29.md) | The structured output: participants, key decisions, test results, and action items |
 
-## Local Development
+## 🔧 Local development
+
+Use Node.js 24 for development, matching CI and the lint toolchain.
 
 ```bash
 git clone https://github.com/n2ns/n2n-nexus.git
@@ -243,44 +228,19 @@ node build/index.js daemon --root /tmp/nexus-test --port 5688
 NEXUS_ENDPOINT=http://127.0.0.1:5688 node build/index.js mcp
 ```
 
-## FAQ
-
-### Is n2n-nexus a project management SaaS?
-
-No. It is a local MCP coordination server for AI assistants. It stores state locally and exposes MCP tools to connected clients.
-
-### Does it replace n2n-memory?
-
-No. `n2n-memory` is repository-local memory for one project. `n2n-nexus` is a shared coordination hub for multiple assistants, project manifests, messages, meetings, and tasks.
-
-### Does it work with Claude Desktop, Cursor, VS Code, and other IDEs?
-
-Yes, when the client supports local MCP command servers. The adapter is started by the IDE and connects to the local daemon through `NEXUS_ENDPOINT`.
-
-### Can it coordinate assistants across Windows and WSL?
-
-Yes. Run the daemon in one environment and point each adapter at it using `NEXUS_ENDPOINT`.
-
-### Does it send data to the cloud?
-
-No cloud service is required. Data is stored under the configured local root. If you expose the daemon to a remote machine, that is your own network configuration.
-
-### Is this a vector database or code indexer?
-
-No. n2n-nexus coordinates project metadata, messages, meetings, docs, tasks, and assets. It is not a semantic code search engine.
-
-## Related docs
+## 📖 Related docs
 
-- [Architecture](./docs/ARCHITECTURE.md)
-- [AI Assistant Guide](./docs/ASSISTANT_GUIDE.md)
-- [Chinese README](./docs/README_zh.md)
-- [Changelog](./CHANGELOG.md)
-- [llms.txt](./llms.txt)
+- **[Architecture](./docs/ARCHITECTURE.md)**: System design and daemon-adapter separation explained.
+- **[Tools reference](./docs/TOOLS_REFERENCE.md)**: Full tool list and parameters.
+- **[AI Assistant Guide](./docs/ASSISTANT_GUIDE.md)**: How AI assistants should call tools and stay in project context.
+- **[Changelog](./CHANGELOG.md)**: Version history and release notes.
+- **[Contributing](./CONTRIBUTING.md)**: How to report issues and contribute.
+- **[Security](./SECURITY.md)**: How to report vulnerabilities.
 
-## License
+## 📄 License
 
 This project is licensed under the [Apache-2.0 License](./LICENSE).
 
 ---
 
-Built by N2NS Lab, short for Next-to-Native Systems Lab, Datafrog's open-source lab for practical AI developer tools.
+Built by [N2NS Lab](https://n2ns.com), the open-source lab of [datafrog.io](https://datafrog.io) for practical AI developer tools.

package/build/client/nexus-client.js

@@ -1,6 +1,22 @@
 import http from "node:http";
 import https from "node:https";
 import { URL } from "node:url";
+/** The daemon could not be reached or answered with something that is not JSON. */
+export class NexusTransportError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "NexusTransportError";
+    }
+}
+/** The daemon answered, but the tool call itself failed (unknown tool, validation, not found, ...). */
+export class NexusToolError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "NexusToolError";
+    }
+}
 function normalizeEndpoint(endpoint) {
     const raw = endpoint || process.env.NEXUS_ENDPOINT || "http://127.0.0.1:5688";
     if (/^https?:\/\//i.test(raw))
@@ -19,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) } : {})
@@ -32,40 +44,51 @@ 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;
                     try {
-                        const parsed = data ? JSON.parse(data) : {};
-                        if (res.statusCode && res.statusCode >= 400) {
-                            reject(new Error(parsed.error || `HTTP ${res.statusCode}`));
-                        }
-                        else {
-                            resolve(parsed);
-                        }
+                        parsed = data ? JSON.parse(data) : {};
                     }
                     catch {
-                        reject(new Error(`Invalid JSON response: ${data}`));
+                        reject(new NexusTransportError(`Invalid JSON response from daemon: ${data.slice(0, 200)}`));
+                        return;
+                    }
+                    const status = res.statusCode ?? 0;
+                    if (status >= 400) {
+                        reject(new NexusToolError(parsed.error || `HTTP ${status}`, status));
+                    }
+                    else {
+                        resolve(parsed);
                     }
                 });
             });
-            req.on("error", reject);
-            req.on("timeout", () => req.destroy(new Error("Request timeout")));
+            req.on("error", (e) => reject(e instanceof NexusTransportError ? e : new NexusTransportError(e.message)));
+            req.on("timeout", () => req.destroy(new NexusTransportError(`Request to ${this.endpoint} timed out after ${this.timeoutMs} ms`)));
             if (payload)
                 req.write(payload);
             req.end();
         });
     }
-    async health() {
-        return this.request("GET", "/health");
-    }
     async fetchTools() {
         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 Error(res.error || "Tool call failed");
+            throw new NexusToolError(res.error || "Tool call failed", 200);
         return res.result;
     }
 }

package/build/config/cli.js

@@ -6,6 +6,3 @@ export function getArg(k) {
     const i = args.indexOf(k);
     return i !== -1 && args[i + 1] ? args[i + 1] : "";
 }
-export function hasFlag(k) {
-    return args.includes(k) || args.includes(k.charAt(1) === "-" ? k : k.substring(0, 2));
-}

package/build/config/index.js

@@ -4,13 +4,3 @@ import { fileURLToPath } from "url";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkgPath = path.resolve(__dirname, "../../package.json");
 export const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-export function getRootPath() {
-    // Priority: --root CLI arg → NEXUS_ROOT env → ~/.n2n-nexus
-    const argIndex = process.argv.indexOf("--root");
-    if (argIndex !== -1 && process.argv[argIndex + 1]) {
-        return process.argv[argIndex + 1];
-    }
-    if (process.env.NEXUS_ROOT)
-        return process.env.NEXUS_ROOT;
-    return path.join(process.env.HOME || process.env.USERPROFILE || ".", ".n2n-nexus");
-}

package/build/constants.js

@@ -1,7 +1,5 @@
 /**
- * Nexus Network Constants
- *
- * Centralized configuration for network-related settings.
+ * Nexus constants
  */
 // Service identification
 export const SERVICE_NAME = "n2n-nexus";
@@ -9,14 +7,12 @@ export const SERVICE_NAME = "n2n-nexus";
 // Default to localhost because the daemon exposes unauthenticated local admin APIs.
 // Use "0.0.0.0" only when you intentionally expose it to another trusted environment.
 export const NEXUS_HOST = "127.0.0.1";
-// Port range for auto-election
-export const PORT_RANGE_START = 5688;
-export const PORT_RANGE_END = 5800;
-// Timeouts (milliseconds)
-export const HANDSHAKE_TIMEOUT = 200;
-export const HEARTBEAT_INTERVAL = 30000;
-// Task cleanup
+// Default daemon port
+export const NEXUS_PORT = 5688;
+// HTTP request body limit for the daemon (base64 asset uploads are the largest payload)
+export const MAX_BODY_BYTES = 16 * 1024 * 1024;
+// Task lifecycle: finished tasks are purged after this age; maintenance runs at this interval
 export const TASK_CLEANUP_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+export const TASK_MAINTENANCE_INTERVAL_MS = 60 * 60 * 1000; // 1 hour
 // File I/O
 export const FILE_ENCODING = "utf-8";
-export const PACKAGE_JSON = "package.json";