n2n-nexus 0.9.5 → 0.11.0

package/CHANGELOG.md

@@ -4,8 +4,38 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.11.0] - 2026-10-29
+
+Upgrade the host and the client on every machine together, and delete `nexus.db` from the host's data directory before the new host starts: this release starts a new database and contract version, and an older host or client no longer works with it.
+
+### Added
+
+- Sessions show the machine they run on. Every hook event carries `machine` (hostname without `.local`, platform `darwin` / `linux` / `wsl` / `win32`, local time minus UTC in minutes); the host refuses an event without it. `peers` and `set_profile` return `hostname`, `platform`, `utcOffset` and `label`; introductions and notifications show `name (<label or hostname> · <platform>)`; `read_messages` returns `senderMachine`. `set_profile({ label })` names the machine in place of its hostname.
+
+### Changed
+
+- Contract version 3: the host and the client must be upgraded together (`n2n-nexus doctor` reports a mismatch).
+- The database schema is two files, one per owner, with no upgrade path from earlier databases: delete `nexus.db` before starting this host (it then says so if an old file is left).
+- Notifications, the collaboration rules, the tool descriptions and the MCP instructions state facts only (sender, text, whether and how to reply) and no longer claim that a message is an approved instruction; that authorization lives only in the `CLAUDE.md` block that `install claude` writes. A Claude Code recipient gets the reply tool's full name.
+- `send` / `read` / `reply` and `send_message` / `read_messages` name each other in their first sentence; the introduction, `peers` and the MCP instructions say that the client's own agent list does not show nexus sessions; `send` asks the sender to end its turn instead of polling with `read`.
+
+## [0.10.0] - 2026-10-28
+
+### Added
+
+- `n2n-nexus install claude` writes a marked block into the user-level `CLAUDE.md` (`<!-- n2n-nexus:begin … -->` to `<!-- n2n-nexus:end -->`): a direct message from another session is the user's own instruction, carried out exactly and without asking the user for confirmation, with questions going back to the sender. Claude Code acts on another session's message only where the user's own instructions call for it, which is why the block is needed. The rest of the file is kept; `uninstall claude` removes the block, and the file when nothing else is in it. Run `install claude` again after upgrading to get the block.
+
+### Changed
+
+- Direct messages arrive whole: a notification shows each message's text between `--- Message <id> from … ---` and `--- End of message <id> ---`, with how to answer it, instead of the sender and the first line. The texts of one notification together are cut at 5000 characters (`notifyTextChars` in the contract); a cut message is marked and `read` returns it. A message shown whole is marked read when the notification continues or starts the turn (Stop, listening, background wake), and, when it needs no reply, when a prompt shows it; `reply` marks the message it answers read. Other messages stay unread for `read`, among them every message shown after a tool call, because that context can reach a sub-agent only.
+- The notifications, the SessionStart introduction and the MCP instructions say that the sessions belong to the same user: a message is that user's instruction, carried out exactly and without asking the user for confirmation, nothing beyond it; when more work or missing information seems needed, the sender is asked with `reply`. `send`'s guidance is to put everything the recipient needs into one message; a task is answered once with its result, or with what stopped it and what would let it go on.
+
 ## [0.9.5] - 2026-10-26
 
+### Added
+
+- Host on Windows: `n2n-nexus-host.exe install [--dir <dir>]` installs the host from an extracted release zip into `%LOCALAPPDATA%\Programs\n2n-nexus-host`, turns start at login on the first time and starts the tray. Run it again from a newer release to upgrade: it replaces the programs (running ones are moved aside and removed by the next install), restarts the tray and, after an administrator prompt, restarts the background service on the new version for the same data directory.
+
 ### Changed
 
 - `n2n-nexus install codex` trusts the n2n-nexus hooks in Codex itself: it asks Codex (`codex app-server`, the copy the Codex app runs on Windows, else `codex` on `PATH`) for each hook's trust hash and stores it, so no `/hooks` step is needed. If that fails, it says how to trust them by hand (the Codex app's settings, or `/hooks` in the CLI). `n2n-nexus doctor codex` checks with Codex that the hooks are trusted, which a Codex update can undo.

package/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [2025] [Antigravity Dev Team]
+   Copyright 2025-2026 Datafrog LLC
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/README.md

@@ -98,7 +98,7 @@ Other MCP clients and several machines: see the [Installation guide](docs/INSTAL
 
 ## 🛠️ Toolset
 
-The host exposes 33 tools, grouped by purpose:
+The host exposes 36 tools, grouped by purpose:
 
 | Group | Tools | Purpose |
 | --- | --- | --- |
@@ -107,7 +107,7 @@ The host exposes 33 tools, grouped by purpose:
 | **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 meeting or global messages; read them and the activity log. |
 | **Direct messages** | `peers`, `send`, `read`, `reply`, `listen`, `set_profile` | Find other Claude Code / Codex conversations, message them, read and answer what arrives, wait for messages, and name yourself. |
-| **Meetings** | `list_meetings`, `start_meeting`, `end_meeting`, `archive_meeting`, `reopen_meeting` | List, open, close, archive, and reopen meeting sessions. |
+| **Meetings** | `list_meetings`, `start_meeting`, `join_meeting`, `leave_meeting`, `stance`, `end_meeting`, `archive_meeting`, `reopen_meeting` | List and open meetings; join (woken by new messages) or leave them; endorse or object to the current draft, which closes the meeting by consensus; close, archive, and reopen them. |
 | **Tasks** | `create_task`, `get_task`, `list_tasks`, `update_task`, `cancel_task` | Create, update and track tasks that assistants manage themselves. |
 | **Maintenance** | `host_maintenance`, `host_delete_project` | Prune or clear the global chat stream; delete a project. |
 

package/build/cli/doctor.js

@@ -81,7 +81,7 @@ async function doctorHosts(endpoints) {
 }
 /**
  * Check one client; prints the report and returns whether everything passed, or undefined when nothing is installed.
- * Adds the endpoints its hook commands use (`defaultEndpoint` for those without --endpoint) to `endpoints`.
+ * Adds the endpoints its hook and MCP commands use to `endpoints`, falling back to defaultEndpoint.
  */
 function doctorClient(client, endpoints, defaultEndpoint) {
     const hooksFile = configFile(client);
@@ -132,6 +132,7 @@ function doctorClient(client, endpoints, defaultEndpoint) {
         report(`MCP server ${MCP_SERVER_NAME} in ${mcpFile}`, bad("not registered"));
     }
     else {
+        endpoints.add(mcp.endpoint === undefined ? defaultEndpoint : mcp.endpoint || LOCAL_ENDPOINT);
         report(`MCP Node ${mcp.command}`, checkNode(mcp.command));
         const [npx, ...rest] = mcp.args;
         if (npx && rest.join(" ") === `-y ${MCP_PACKAGE} mcp`)

package/build/cli/hook.js

@@ -10,6 +10,7 @@ import { spawn } from "node:child_process";
 import { BACKGROUND_WAIT_EVENT, WAKE_RESULT_EVENT, HOOK_INPUT_FIELDS, HOOK_REQUEST_TIMEOUT_MS, HOOK_STOP_REQUEST_TIMEOUT_MS, SESSION_END_REQUEST_TIMEOUT_MS, WAIT_HOOK_TIMEOUT_SEC, WAKE_RETRY_FIRST_DELAY_MS, WAKE_RETRY_MAX_DELAY_MS, noDaemonHint, isHookClient } from "../contract.js";
 import { NexusClient, NexusTransportError, REQUEST_TIMEOUT_CODE } from "../client/nexus-client.js";
 import { DISCOVER_ENDPOINT, LOCAL_ENDPOINT, resolveEndpoint } from "../client/discovery.js";
+import { machineInfo } from "./machine.js";
 import { readTitle } from "./title.js";
 /** Errors after which a discovered daemon is looked up again: it was never reached, so resending is safe. */
 const UNREACHABLE_CODES = new Set(["ECONNREFUSED", "EHOSTUNREACH", "ENETUNREACH", "ETIMEDOUT", "EADDRNOTAVAIL"]);
@@ -48,6 +49,8 @@ async function forward(argv) {
         if (title !== undefined)
             input.title = title;
     }
+    // Every event says where the conversation runs; the host refuses one without it.
+    input.machine = machineInfo();
     // SessionEnd must finish within Codex's 3 s hook limit (discovery included): a short budget and a single attempt.
     const sessionEnd = stdin.hook_event_name === "SessionEnd";
     const timeoutMs = stdin.hook_event_name === "Stop" ? HOOK_STOP_REQUEST_TIMEOUT_MS : sessionEnd ? SESSION_END_REQUEST_TIMEOUT_MS : HOOK_REQUEST_TIMEOUT_MS;
@@ -90,19 +93,41 @@ async function forward(argv) {
 }
 /** The background wait ends before the client's hook timeout would kill it during a request. */
 const WAIT_DEADLINE_MS = (WAIT_HOOK_TIMEOUT_SEC - 10) * 1000;
+const WAIT_RETRY_CODES = new Set([...UNREACHABLE_CODES, "ECONNRESET", "EPIPE", "ENOTFOUND", "EAI_AGAIN", REQUEST_TIMEOUT_CODE]);
 /**
  * Ask the daemon until something arrives for the session (the wake), the
  * session becomes active again or the deadline passes (null).
  */
-export async function waitForWake(client, sessionId, endpoint, deadlineMs = WAIT_DEADLINE_MS) {
-    const nexus = new NexusClient({ endpoint });
-    // Start a request only if it can run to its own timeout before the deadline.
-    const deadline = Date.now() + deadlineMs - HOOK_STOP_REQUEST_TIMEOUT_MS;
+export async function waitForWake(client, sessionId, configured, deadlineMs = WAIT_DEADLINE_MS) {
+    const deadline = Date.now() + deadlineMs;
+    let endpoint = await resolveEndpoint(configured);
+    let delay = WAKE_RETRY_FIRST_DELAY_MS;
+    let fresh = false;
     while (Date.now() < deadline) {
-        const response = await nexus.hook({ client, input: { hook_event_name: BACKGROUND_WAIT_EVENT, session_id: sessionId } }, HOOK_STOP_REQUEST_TIMEOUT_MS);
+        if (fresh)
+            endpoint = await resolveEndpoint(configured, { fresh: true });
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            return null;
+        let response;
+        try {
+            response = await new NexusClient({ endpoint }).hook({ client, input: { hook_event_name: BACKGROUND_WAIT_EVENT, session_id: sessionId } }, Math.min(HOOK_STOP_REQUEST_TIMEOUT_MS, remaining));
+        }
+        catch (error) {
+            if (!(error instanceof NexusTransportError) || !WAIT_RETRY_CODES.has(error.code ?? ""))
+                throw error;
+            if (Date.now() + delay >= deadline)
+                return null;
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            delay = Math.min(delay * 2, WAKE_RETRY_MAX_DELAY_MS);
+            fresh = true;
+            continue;
+        }
+        fresh = false;
+        delay = WAKE_RETRY_FIRST_DELAY_MS;
         const output = isPlainObject(response) ? response.output : null;
         if (isPlainObject(output) && typeof output.wake === "string" && typeof output.dispatchId === "string")
-            return { text: output.wake, dispatchId: output.dispatchId };
+            return { text: output.wake, dispatchId: output.dispatchId, endpoint };
         if (!(isPlainObject(output) && output.timeout === true))
             return null;
     }
@@ -143,10 +168,9 @@ async function runWait(argv) {
     // Load what a wake needs before waiting: the wait lasts up to an hour, and an
     // upgrade or a cleared npx cache may remove the package's files meanwhile.
     const { spawnClientSync } = client === "codex" ? await import("./client-command.js") : { spawnClientSync: undefined };
-    const endpoint = await resolveEndpoint(configured);
     const deadline = Date.now() + WAIT_DEADLINE_MS;
     for (let delay = WAKE_RETRY_FIRST_DELAY_MS;; delay = Math.min(delay * 2, WAKE_RETRY_MAX_DELAY_MS)) {
-        const wake = await waitForWake(client, sessionId, endpoint, deadline - Date.now());
+        const wake = await waitForWake(client, sessionId, configured, deadline - Date.now());
         if (wake === null)
             return 0;
         if (!spawnClientSync) {
@@ -157,7 +181,7 @@ async function runWait(argv) {
         const queued = spawnClientSync(process.env.NEXUS_CODEX_COMMAND || "codex", ["queue", "--thread", sessionId, "--message", wake.text], { stdio: "ignore", windowsHide: true });
         const ok = !queued.error && queued.status === 0;
         const input = { hook_event_name: WAKE_RESULT_EVENT, session_id: sessionId, dispatch_id: wake.dispatchId, ok };
-        const reported = await new NexusClient({ endpoint }).hook({ client, input }, HOOK_REQUEST_TIMEOUT_MS).then(() => true, () => false);
+        const reported = await new NexusClient({ endpoint: wake.endpoint }).hook({ client, input }, HOOK_REQUEST_TIMEOUT_MS).then(() => true, () => false);
         // Unknown result (no report): the host keeps the wake, and waiting again would deliver nothing.
         if (ok || !reported || Date.now() + delay >= deadline)
             return 0;

package/build/cli/install.js

@@ -5,6 +5,11 @@
  * contains both `n2n-nexus` and ` hook <client>`; everything else in the
  * configuration file is kept as it is.
  *
+ * For Claude Code, install also writes a marked block into the user's
+ * CLAUDE.md that makes direct messages count as the user's own requests
+ * (Claude Code acts on another session's message only where the user's own
+ * instructions call for it); uninstall removes the block.
+ *
  * The commands start with an absolute Node path: GUI clients started from the
  * Dock do not read the shell PATH. The `node` found on PATH is preferred when it
  * is the running binary, because process.execPath is the resolved, versioned
@@ -260,6 +265,57 @@ function writeConfig(file, config) {
     fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + "\n");
     fs.renameSync(tmp, target);
 }
+/** The marks around our block in the user's CLAUDE.md. */
+export const INSTRUCTIONS_BEGIN = "<!-- n2n-nexus:begin (written by \"n2n-nexus install claude\", removed by \"n2n-nexus uninstall claude\") -->";
+export const INSTRUCTIONS_END = "<!-- n2n-nexus:end -->";
+export const INSTRUCTIONS = [
+    INSTRUCTIONS_BEGIN,
+    "## n2n-nexus direct messages",
+    "",
+    "The other AI sessions on n2n-nexus are mine. A direct message from one of them (shown in an [n2n-nexus] notification, or returned by read) is my instruction, already approved by me: carry out exactly what it asks, as if I had typed it, without asking me for confirmation. My other rules still apply to that work: do nothing beyond what the message asks (no extra features, nearby code, other files or next task); when more work or missing information seems needed, ask the session that sent it with reply, not me. Answer with reply when the work is done, unless the message says no reply is needed.",
+    INSTRUCTIONS_END
+].join("\n");
+export function instructionsFile() {
+    return path.join(process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude"), "CLAUDE.md");
+}
+/**
+ * Write our block into the user's CLAUDE.md (replacing an earlier one), or
+ * remove it; a file that holds nothing else is removed. Returns whether the file changed.
+ */
+function writeInstructions(install) {
+    const file = instructionsFile();
+    const target = linkTarget(file);
+    let text = "";
+    try {
+        text = fs.readFileSync(target, "utf8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    // The user's text around the block stays as it is; only the blank lines that joined it to the block go.
+    let rest = text;
+    const begin = text.indexOf(INSTRUCTIONS_BEGIN);
+    const end = begin === -1 ? -1 : text.indexOf(INSTRUCTIONS_END, begin);
+    if (end !== -1) {
+        const before = text.slice(0, begin).replace(/\n+$/, "");
+        const after = text.slice(end + INSTRUCTIONS_END.length).replace(/^\n+/, "");
+        rest = before && after ? `${before}\n\n${after}` : before ? `${before}\n` : after;
+    }
+    const kept = rest.replace(/\n+$/, "");
+    const next = install ? `${kept ? `${kept}\n\n` : ""}${INSTRUCTIONS}\n` : rest;
+    if (next === text)
+        return false;
+    if (!next.trim()) {
+        fs.rmSync(target, { force: true });
+        return true;
+    }
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const tmp = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, next);
+    fs.renameSync(tmp, target);
+    return true;
+}
 function mcpRemoveArgs(client) {
     return client === "claude"
         ? ["mcp", "remove", "--scope", "user", MCP_SERVER_NAME]
@@ -364,6 +420,9 @@ export function runInstall(options) {
             writeConfig(file, config);
             process.stdout.write(`${action === "install" ? "Wrote hooks to" : "Removed hooks from"} ${file}\n`);
         }
+        if (client === "claude" && writeInstructions(action === "install")) {
+            process.stdout.write(`${action === "install" ? "Wrote the n2n-nexus instructions to" : "Removed the n2n-nexus instructions from"} ${instructionsFile()}\n`);
+        }
         removeMcpServer(client, action, removed);
         if (action === "install" && node && npm) {
             const addArgs = mcpAddArgs(client, node, npm, endpoint);

package/build/cli/machine.js

@@ -0,0 +1,27 @@
+/**
+ * Where this conversation runs, which the hook command adds to the input of
+ * every event it forwards as `machine`, so that other sessions can tell the machines apart
+ * (several sessions share a name and a working directory across machines).
+ * Node built-ins only: the hook command imports this on client events.
+ */
+import fs from "node:fs";
+import os from "node:os";
+/** darwin, linux, win32 as Node reports them; wsl for a Linux that runs under Windows. */
+export function platformOf(platform = process.platform, readProcVersion = () => fs.readFileSync("/proc/version", "utf8")) {
+    if (platform !== "linux")
+        return platform;
+    try {
+        return /microsoft/i.test(readProcVersion()) ? "wsl" : "linux";
+    }
+    catch {
+        return "linux";
+    }
+}
+/** The host name without the `.local` suffix that macOS adds. */
+export function hostnameOf(hostname = os.hostname()) {
+    return hostname.replace(/\.local$/i, "");
+}
+export function machineInfo(now = new Date()) {
+    // 0 - x, not -x: at UTC -x is -0, which JSON writes as 0.
+    return { hostname: hostnameOf(), platform: platformOf(), utcOffset: 0 - now.getTimezoneOffset() };
+}

package/build/cli/mcp-config.js

@@ -39,20 +39,27 @@ export function readMcpCommand(client, file) {
         const server = servers?.[MCP_SERVER_NAME];
         if (!server || typeof server.command !== "string")
             return undefined;
-        return { command: server.command, args: Array.isArray(server.args) ? server.args.map(String) : [] };
+        const endpoint = server.env?.NEXUS_ENDPOINT;
+        return { command: server.command, args: Array.isArray(server.args) ? server.args.map(String) : [],
+            ...(typeof endpoint === "string" ? { endpoint } : {}) };
     }
     // Codex: a TOML table [mcp_servers.n2n-nexus] (the key may be quoted) with command and args.
     const lines = text.split("\n");
-    const start = lines.findIndex((line) => new RegExp(`^\\s*\\[mcp_servers\\.(["']?)${MCP_SERVER_NAME}\\1\\]\\s*(?:#.*)?$`).test(line));
-    if (start === -1)
+    const readTable = (suffix = "") => {
+        const start = lines.findIndex((line) => new RegExp(`^\\s*\\[mcp_servers\\.(["']?)${MCP_SERVER_NAME}\\1${suffix}\\]\\s*(?:#.*)?$`).test(line));
+        if (start === -1)
+            return undefined;
+        const body = [];
+        for (const line of lines.slice(start + 1)) {
+            if (/^\s*\[/.test(line))
+                break;
+            body.push(line);
+        }
+        return body.join("\n");
+    };
+    const table = readTable();
+    if (table === undefined)
         return undefined;
-    const body = [];
-    for (const line of lines.slice(start + 1)) {
-        if (/^\s*\[/.test(line))
-            break;
-        body.push(line);
-    }
-    const table = body.join("\n");
     const value = String.raw `"(?:[^"\\\r\n]|\\.)*"|'[^'\r\n]*'`;
     const decode = (s) => s.startsWith("'") ? s.slice(1, -1) : JSON.parse(s);
     const command = new RegExp(`^\\s*command\\s*=\\s*(${value})`, "m").exec(table);
@@ -62,5 +69,19 @@ export function readMcpCommand(client, file) {
     const array = new RegExp(`^\\s*args\\s*=\\s*\\[((?:${value}|#[^\\n]*|[^\\]"'#])*)\\]`, "m").exec(table);
     const args = array ? [...array[1].matchAll(new RegExp(`(${value})|#[^\\n]*`, "g"))]
         .filter((m) => m[1] !== undefined).map((m) => decode(m[1])) : [];
-    return { command: decode(command[1]), args };
+    const endpointKey = `(?:NEXUS_ENDPOINT|"NEXUS_ENDPOINT"|'NEXUS_ENDPOINT')`;
+    const envTable = readTable(String.raw `\.(?:env|"env"|'env')`);
+    let endpoint = envTable === undefined ? undefined : new RegExp(`^\\s*${endpointKey}\\s*=\\s*(${value})`, "m").exec(envTable)?.[1];
+    endpoint ??= new RegExp(`^\\s*env\\.${endpointKey}\\s*=\\s*(${value})`, "m").exec(table)?.[1];
+    if (endpoint === undefined) {
+        const inline = new RegExp(`^\\s*env\\s*=\\s*\\{((?:${value}|#[^\\n]*|[^}"'#])*)\\}`, "m").exec(table)?.[1];
+        if (inline !== undefined) {
+            // Consume complete key/value pairs: endpoint-looking text inside another value is not a setting.
+            for (const entry of inline.matchAll(new RegExp(`(${value}|[A-Za-z0-9_-]+)\\s*=\\s*(${value})|#[^\\n]*`, "g"))) {
+                if (entry[1] && (entry[1] === "NEXUS_ENDPOINT" || /^["']/.test(entry[1]) && decode(entry[1]) === "NEXUS_ENDPOINT"))
+                    endpoint = entry[2];
+            }
+        }
+    }
+    return { command: decode(command[1]), args, ...(endpoint === undefined ? {} : { endpoint: decode(endpoint) }) };
 }

package/build/client/discovery.js

@@ -12,6 +12,7 @@ import dgram from "node:dgram";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { isIPv6 } from "node:net";
 /** Endpoint value that turns discovery on (NEXUS_ENDPOINT or --endpoint). */
 export const DISCOVER_ENDPOINT = "discover";
 export const LOCAL_ENDPOINT = "http://127.0.0.1:5688";
@@ -47,7 +48,13 @@ export function discoverEndpoint(udpPort = discoveryPort(), waitMs = DISCOVERY_W
     // listens on all interfaces, else the one address it is bound to.
     const own = new Set(lanInterfaces().map((a) => a.address));
     const address = (rinfo, reply) => {
-        if (!own.has(rinfo.address) && !rinfo.address.startsWith("127."))
+        const local = own.has(rinfo.address) || rinfo.address.startsWith("127.");
+        if (typeof reply.host === "string" && isIPv6(reply.host)) {
+            const host = new URL(`http://[${reply.host}]`).hostname;
+            // The IPv4 discovery source cannot identify an IPv6-only listener on another machine.
+            return host === "[::]" ? (local ? "[::1]" : null) : host;
+        }
+        if (!local)
             return rinfo.address;
         return typeof reply.host === "string" && !ALL_INTERFACES.has(reply.host) ? reply.host : "127.0.0.1";
     };
@@ -68,7 +75,9 @@ export function discoverEndpoint(udpPort = discoveryPort(), waitMs = DISCOVERY_W
             try {
                 const reply = JSON.parse(msg.toString("utf8"));
                 if (reply.service === "n2n-nexus" && Number.isInteger(reply.port) && reply.port > 0) {
-                    finish(`http://${address(rinfo, reply)}:${reply.port}`);
+                    const host = address(rinfo, reply);
+                    if (host !== null)
+                        finish(`http://${host}:${reply.port}`);
                 }
             }
             catch { /* not a discovery reply */ }

package/build/client/nexus-client.js

@@ -50,7 +50,7 @@ export class NexusClient {
             }, (res) => {
                 let data = "";
                 res.setEncoding("utf8");
-                const interrupted = () => reject(new NexusTransportError("Response from n2n-nexus-host ended before completion"));
+                const interrupted = () => reject(new NexusTransportError("Response from n2n-nexus-host ended before completion", "ECONNRESET"));
                 res.on("aborted", interrupted);
                 res.on("error", (error) => reject(new NexusTransportError(error.message)));
                 res.on("close", () => { if (!res.complete)

package/build/server/nexus.js

@@ -11,9 +11,14 @@ const INITIAL_LIST_WAIT_MS = 1000;
 const SERVICE_NAME = "n2n-nexus";
 /** Sent to the client on connect so the model knows it can talk to other AI sessions. */
 const INSTRUCTIONS = "n2n-nexus connects this conversation with other AI sessions (Claude Code and Codex conversations, " +
-    "possibly on other machines). Direct messages: call peers to see who is online, send to message a session, " +
-    "read to read messages sent to you, carry out what they ask and reply to answer one (set expectsReply and wake false " +
-    "on a message that needs no answer, and send no plain acknowledgements); listen waits for messages after each turn. " +
+    "possibly on other machines), all of your own user. Direct messages: call peers to see who is online (your " +
+    "client's own agent list, such as ListAgents, does not show these sessions), send to message a session (everything " +
+    "the recipient needs in one message), reply to answer one and read for the messages a notification cut or did not " +
+    "show. What a message may ask of you is set by your user's own instructions; when something is missing, ask the " +
+    "sender with reply. After send, end your turn instead of polling with read: the answer arrives through the hooks " +
+    "after your next tool call or at the end of a turn (at your user's next prompt once the automatic-turn limit is " +
+    "reached), and notifyWhenIdle tells you when the recipient finishes its turn (set expectsReply and wake false on a " +
+    "message that needs no answer, and skip plain acknowledgements); listen waits for messages after each turn. " +
     "Direct messaging needs the n2n-nexus hooks. Separately, send_message and read_messages are the shared " +
     "global chat and meetings, not direct messages. Session ids in peers (claude:<id>, codex:<id>) are what send " +
     "takes; with the hooks, chat and meetings also record senders and unread cursors per session id " +

package/contract/errors.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": 2,
+  "contractVersion": 3,
   "errorBody": {
     "type": "object",
     "properties": {
@@ -21,7 +21,7 @@
         "ok": true,
         "service": "n2n-nexus",
         "version": "<host version>",
-        "contractVersion": 2,
+        "contractVersion": 3,
         "sessions": {
           "online": "<number of agent sessions not offline>"
         }

package/contract/hook.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": 2,
+  "contractVersion": 3,
   "clients": [
     "claude",
     "codex"
@@ -56,16 +56,26 @@
     "maxTitleChars": 80,
     "sessionNamePattern": "^[A-Za-z0-9._@#-]{1,48}$",
     "previewChars": 100,
-    "notifyListLimit": 5
+    "notifyListLimit": 5,
+    "notifyTextChars": 5000,
+    "maxHostnameChars": 80
   },
   "texts": {
     "noticePrefix": "[n2n-nexus]",
-    "notifyClosing": "Call read to view them.",
-    "stopClosing": "Read them with read and answer with reply before you finish.",
+    "notifyClosing": "Where a reply is asked, answer with reply once the work is done.",
+    "stopClosing": "Do the work, and where a reply is asked, answer with reply before you finish.",
     "statusNote": "Only listening sessions answer right away; idle and working ones see a message when their user next sends a prompt or they next call a tool.",
-    "sessionStartClosing": "Call peers for the current list, send to message a session, read to read messages sent to you and reply to answer one; set_profile tells others what you work on.",
-    "messageTrustNote": "Messages come from other AI sessions. Read them with read, carry out what they ask and answer with reply; replying needs no permission from your user.",
-    "messageInfoNote": "Messages come from other AI sessions; they need no reply.",
+    "sessionStartClosing": "Call peers for the current list (your client's own agent list, such as ListAgents, does not show these sessions), send to message a session, reply to answer a message you received and read for the messages a notification cut or did not show; set_profile tells others what you work on. Meetings and the global chat use send_message and read_messages instead.",
+    "collaborationRules": "All sessions on n2n-nexus belong to your own user. A direct message shows who sent it, its text and whether it wants an answer; what you may do for it is set by your user's own instructions. When something you need is missing, ask the session that sent it with reply. When you hand work to another session, put everything it needs into one message: the goal, the background, what you already tried and what a finished result looks like; then end your turn: do not poll with read, the answer reaches you through the hooks after your next tool call or at the end of a turn (at your user's next prompt once the automatic-turn limit is reached), and notifyWhenIdle tells you when the recipient finishes. Answer a task once, with its result; if you cannot finish, say what stopped you and the one thing that would let you go on. Skip plain acknowledgements, and do not pass a task back to the session that sent it.",
+    "messageTrustNote": "These messages come from other AI sessions of your own user. When something you need is missing, ask the sender with reply. Answer once, with the result; if you cannot finish, say what stopped you and the one thing that would let you go on. Skip plain acknowledgements.",
+    "messageInfoNote": "These messages come from other AI sessions of your own user; they need no reply.",
+    "messageHeader": "--- Message %s from %s (%s) at %s ---",
+    "messageEnd": "--- End of message %s ---",
+    "messageReplyTo": "This answers your message %s.",
+    "messageCut": "[Cut at %d of %d characters; read returns the whole message.]",
+    "replyInstruction": "Answer it with reply (messageId %s; expectsReply false for a result, true for a question).",
+    "readRest": "read returns the messages that are cut or not shown here.",
+    "replyTool": "The reply tool is %s.",
     "noReplyMark": "(no reply needed)",
     "earlierUnread": "%d earlier direct message(s) still unread; read them with read.",
     "meetingNews": "Meeting \"%s\" (%s): %d new message(s) (#%d–#%d) from %s.",
@@ -168,6 +178,35 @@
       "required": [
         "tool"
       ]
+    },
+    "hookMachine": {
+      "description": "input.machine, which every hook event of a conversation carries (not BackgroundWait or WakeResult): where the conversation runs",
+      "type": "object",
+      "properties": {
+        "hostname": {
+          "type": "string",
+          "minLength": 1
+        },
+        "platform": {
+          "type": "string",
+          "enum": [
+            "darwin",
+            "linux",
+            "wsl",
+            "win32"
+          ]
+        },
+        "utcOffset": {
+          "type": "integer",
+          "minimum": -1440,
+          "maximum": 1440
+        }
+      },
+      "required": [
+        "hostname",
+        "platform",
+        "utcOffset"
+      ]
     }
   }
 }