n2n-nexus 0.8.2 → 0.9.0

package/build/cli/doctor.js

@@ -1,13 +1,17 @@
 /**
  * `n2n-nexus doctor [claude|codex]`: check that the Node path and the entry
  * script in the hook commands and in the MCP server command that `install`
- * wrote still exist and run, and say how to fix what does not. Without a
- * client both are checked; a client with nothing installed is only reported
- * when it was named. Exit code 1 when a check failed.
+ * wrote still exist and run, that the host those commands talk to answers
+ * GET /health as n2n-nexus-host with this client's contract version, and say
+ * how to fix what does not. Without a client both are checked; a client with
+ * nothing installed is only reported when it was named. Exit code 1 when a
+ * check failed.
  */
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
-import { HOOK_CLIENTS, MCP_SERVER_NAME, isHookClient } from "../daemon/hook-contract.js";
+import { CONTRACT_VERSION, HOOK_CLIENTS, MCP_SERVER_NAME, isHookClient, noDaemonHint } from "../contract.js";
+import { NexusClient, NexusToolError } from "../client/nexus-client.js";
+import { LOCAL_ENDPOINT, resolveEndpoint } from "../client/discovery.js";
 import { pkg } from "../config/index.js";
 import { VERSIONED_NODE_DIR, configFile, isOurs, parseVersion, readConfig, satisfiesEngines } from "./install.js";
 import { mcpConfigFile, readMcpCommand } from "./mcp-config.js";
@@ -38,8 +42,46 @@ export function checkNode(node) {
     return ok(`${text}${VERSIONED_NODE_DIR.test(node) ? `, ${VERSIONED_NOTE}` : ""}`);
 }
 const checkEntry = (entry) => fs.existsSync(entry) ? ok("ok") : bad("missing");
-/** Check one client; prints the report and returns whether everything passed, or undefined when nothing is installed. */
-function doctorClient(client) {
+/** The `--endpoint` a hook command was installed with, if any. */
+const hookEndpoint = (command) => / --endpoint (\S+)/.exec(command)?.[1];
+/** Ask the host at `endpoint` for GET /health: it must be n2n-nexus-host speaking this client's contract version. */
+export async function checkHost(endpoint) {
+    let health;
+    try {
+        health = await new NexusClient({ endpoint, timeoutMs: 3000 }).health();
+    }
+    catch (error) {
+        // It answered but refused (e.g. 403 for a Host name not in its allowedHosts): running, not missing.
+        if (error instanceof NexusToolError)
+            return bad(`answers with HTTP ${error.status}: ${error.message}`);
+        return bad(`not reachable (${error.message}). ${noDaemonHint(endpoint)}`);
+    }
+    if (health.service !== "n2n-nexus")
+        return bad("answers, but is not an n2n-nexus host");
+    const version = typeof health.version === "string" ? health.version : "unknown version";
+    if (health.contractVersion !== CONTRACT_VERSION) {
+        return bad(`n2n-nexus-host ${version} speaks contract version ${String(health.contractVersion)}, this client ${CONTRACT_VERSION}: upgrade the older of n2n-nexus-host and n2n-nexus`);
+    }
+    return ok(`n2n-nexus-host ${version}, contract version ${CONTRACT_VERSION}`);
+}
+/** Check the host at each endpoint; prints the report and returns whether all passed. */
+async function doctorHosts(endpoints) {
+    let passed = true;
+    for (const configured of endpoints) {
+        const endpoint = await resolveEndpoint(configured);
+        const check = await checkHost(endpoint);
+        if (!check.ok)
+            passed = false;
+        const label = endpoint === configured ? endpoint : `${endpoint} (${configured})`;
+        process.stdout.write(`host ${label}\n  ${check.ok ? "ok  " : "FAIL"} ${check.text}\n`);
+    }
+    return passed;
+}
+/**
+ * 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`.
+ */
+function doctorClient(client, endpoints, defaultEndpoint) {
     const hooksFile = configFile(client);
     const mcpFile = mcpConfigFile(client);
     const lines = [];
@@ -70,6 +112,8 @@ function doctorClient(client) {
     const mcp = readMcpCommand(client, mcpFile);
     if (commands.size === 0 && !mcp)
         return undefined;
+    for (const command of commands)
+        endpoints.add(hookEndpoint(command) ?? defaultEndpoint);
     lines.push(`${client}`);
     if (commands.size === 0)
         report(`hooks in ${hooksFile}`, bad("not installed"));
@@ -103,7 +147,7 @@ function doctorClient(client) {
     return !failed;
 }
 /** Parse `[claude|codex]`, run the checks and return the exit code. */
-export function runDoctor(argv) {
+export async function runDoctor(argv) {
     const client = argv[0];
     if (client !== undefined && !isHookClient(client)) {
         process.stderr.write("Usage: n2n-nexus doctor [claude|codex]\n");
@@ -111,8 +155,10 @@ export function runDoctor(argv) {
     }
     try {
         let failed = false;
+        const defaultEndpoint = process.env.NEXUS_ENDPOINT || LOCAL_ENDPOINT;
+        const endpoints = new Set();
         for (const c of client ? [client] : HOOK_CLIENTS) {
-            const result = doctorClient(c);
+            const result = doctorClient(c, endpoints, defaultEndpoint);
             if (result === undefined) {
                 if (client) {
                     process.stdout.write(`${c}\n  FAIL nothing installed: run "n2n-nexus install ${c}".\n`);
@@ -126,6 +172,10 @@ export function runDoctor(argv) {
                 failed = true;
             }
         }
+        if (endpoints.size === 0)
+            endpoints.add(defaultEndpoint);
+        if (!await doctorHosts(endpoints))
+            failed = true;
         return failed ? 1 : 0;
     }
     catch (error) {

package/build/cli/entry.js

@@ -0,0 +1,5 @@
+import { fileURLToPath } from "node:url";
+/** Absolute path of the package entry script (`build/index.js` next to `build/cli/`). */
+export function entryScript() {
+    return fileURLToPath(new URL("../index.js", import.meta.url));
+}

package/build/cli/hook.js

@@ -1,12 +1,16 @@
 /**
- * `n2n-nexus hook <claude|codex> [--endpoint <url>]`: forward one client hook
- * event to the daemon and print its output. Runs on every tool call, so it
- * loads only node built-ins (no MCP SDK, zod or SQLite), and every failure is
- * silent: exit 0 with nothing on stdout, so the client carries on unaffected.
+ * `n2n-nexus hook <claude|codex> [--endpoint <url>] [--wait]`: forward one client
+ * hook event to the daemon and print its output, or with `--wait` run the
+ * background wait that wakes an idle conversation. Runs on every tool call, so
+ * it loads only node built-ins (no MCP SDK, zod or SQLite), and every failure
+ * is silent: exit 0 with nothing on stdout, so the client carries on unaffected.
  */
-import { HOOK_INPUT_FIELDS, HOOK_REQUEST_TIMEOUT_MS, HOOK_STOP_REQUEST_TIMEOUT_MS, isHookClient } from "../daemon/hook-contract.js";
-import { NexusClient, NexusTransportError } from "../client/nexus-client.js";
-const DEFAULT_ENDPOINT = "http://127.0.0.1:5688";
+import { spawn } from "node:child_process";
+import { BACKGROUND_WAIT_EVENT, HOOK_INPUT_FIELDS, HOOK_REQUEST_TIMEOUT_MS, HOOK_STOP_REQUEST_TIMEOUT_MS, WAIT_HOOK_TIMEOUT_SEC, 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";
+/** 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"]);
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -25,7 +29,7 @@ async function forward(argv) {
     const client = argv[0];
     if (!isHookClient(client))
         throw new Error(`unknown client "${client ?? ""}" (expected claude or codex)`);
-    const endpoint = argValue(argv, "--endpoint") || process.env.NEXUS_ENDPOINT || DEFAULT_ENDPOINT;
+    const configured = argValue(argv, "--endpoint") || process.env.NEXUS_ENDPOINT || LOCAL_ENDPOINT;
     const stdin = JSON.parse(await readStdin());
     if (!isPlainObject(stdin))
         throw new Error("hook input is not a JSON object");
@@ -35,19 +39,33 @@ async function forward(argv) {
             input[field] = stdin[field];
     }
     const timeoutMs = stdin.hook_event_name === "Stop" ? HOOK_STOP_REQUEST_TIMEOUT_MS : HOOK_REQUEST_TIMEOUT_MS;
-    const nexus = new NexusClient({ endpoint });
-    const send = () => nexus.hook({ client, input }, timeoutMs);
+    /** Send to `endpoint`; nothing listening there is reported with what to do about it. */
+    const send = async (endpoint) => {
+        try {
+            return await new NexusClient({ endpoint }).hook({ client, input }, timeoutMs);
+        }
+        catch (error) {
+            if (!(error instanceof NexusTransportError && error.code === "ECONNREFUSED"))
+                throw error;
+            throw new NexusTransportError(`No daemon at ${endpoint}. ${noDaemonHint(endpoint)}`, error.code);
+        }
+    };
+    const endpoint = await resolveEndpoint(configured);
     let response;
     try {
-        response = await send();
+        response = await send(endpoint);
     }
     catch (error) {
-        if (!(error instanceof NexusTransportError && error.code === "ECONNREFUSED"))
+        // The cached daemon is gone: look again, and fall back to the local endpoint if none answers.
+        // A timed-out Stop may have been waiting for messages on purpose, so only other events count a timeout.
+        const code = error instanceof NexusTransportError ? error.code ?? "" : "";
+        const unreachable = UNREACHABLE_CODES.has(code) || (code === REQUEST_TIMEOUT_CODE && stdin.hook_event_name !== "Stop");
+        if (configured !== DISCOVER_ENDPOINT || !unreachable)
             throw error;
-        const { startLocalDaemon } = await import("./autostart.js");
-        if (!await startLocalDaemon(endpoint))
+        const found = await resolveEndpoint(configured, { fresh: true });
+        if (found === endpoint)
             throw error;
-        response = await send();
+        response = await send(found);
     }
     if (!isPlainObject(response) || !("output" in response))
         throw new Error("invalid response from daemon");
@@ -58,8 +76,78 @@ async function forward(argv) {
         throw new Error("invalid output from daemon");
     return JSON.stringify(output) + "\n";
 }
-/** Run the hook command; always resolves to exit code 0. */
+/** 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;
+/**
+ * Ask the daemon until something arrives for the session (the notification
+ * text), 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;
+    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);
+        const output = isPlainObject(response) ? response.output : null;
+        if (isPlainObject(output) && typeof output.wake === "string")
+            return output.wake;
+        if (!(isPlainObject(output) && output.timeout === true))
+            return null;
+    }
+    return null;
+}
+/**
+ * `--wait`, started by a Stop hook when a turn ends. Claude runs it as an
+ * asyncRewake hook: exit code 2 with the notification on stderr wakes the
+ * conversation. Codex has no such hook, so its Stop hook starts a detached copy
+ * (`--session <id>`) and returns at once; the copy hands the notification to
+ * `codex queue` (NEXUS_CODEX_COMMAND, default `codex`), which starts a turn.
+ */
+async function runWait(argv) {
+    const client = argv[0];
+    if (!isHookClient(client))
+        throw new Error(`unknown client "${client ?? ""}" (expected claude or codex)`);
+    // claude -p (unattended) waits for this hook before it exits, and nobody would see a woken turn.
+    if (client === "claude" && process.env.CLAUDE_CODE_SESSION_ATTENDED === "0")
+        return 0;
+    const configured = argValue(argv, "--endpoint") || process.env.NEXUS_ENDPOINT || LOCAL_ENDPOINT;
+    let sessionId = argValue(argv, "--session");
+    if (!sessionId) {
+        const stdin = JSON.parse(await readStdin());
+        if (!isPlainObject(stdin) || typeof stdin.session_id !== "string" || !stdin.session_id)
+            return 0;
+        sessionId = stdin.session_id;
+        if (client === "codex") {
+            const { entryScript } = await import("./entry.js");
+            const args = [entryScript(), "hook", "codex", "--wait", "--session", sessionId, ...(argValue(argv, "--endpoint") ? ["--endpoint", configured] : [])];
+            spawn(process.execPath, args, { detached: true, stdio: "ignore", windowsHide: true }).unref();
+            return 0;
+        }
+    }
+    const text = await waitForWake(client, sessionId, await resolveEndpoint(configured));
+    if (text === null)
+        return 0;
+    if (client === "codex") {
+        // Never through cmd.exe: the text comes from another session and spans several lines.
+        const { spawnClientSync } = await import("./client-command.js");
+        spawnClientSync(process.env.NEXUS_CODEX_COMMAND || "codex", ["queue", "--thread", sessionId, "--message", text], { stdio: "ignore", windowsHide: true });
+        return 0;
+    }
+    await new Promise((resolve) => process.stderr.write(text + "\n", () => resolve()));
+    return 2;
+}
+/** Run the hook command; resolves to exit code 0, or 2 when a background wait wakes a Claude conversation. */
 export async function runHook(argv) {
+    if (argv.includes("--wait")) {
+        try {
+            return await runWait(argv);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`[n2n-nexus] hook --wait: ${message.replace(/\s+/g, " ").slice(0, 300)}\n`);
+            return 0;
+        }
+    }
     let text = "";
     try {
         text = await forward(argv);

package/build/cli/install.js

@@ -10,13 +10,14 @@
  * is the running binary, because process.execPath is the resolved, versioned
  * location (nvm, Homebrew Cellar, ...) that disappears when Node is upgraded.
  */
-import { execFileSync, spawnSync } from "node:child_process";
+import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { CLAUDE_PRE_TOOL_MATCHER, HOOK_STOP_TIMEOUT_SEC, HOOK_TIMEOUT_SEC, MCP_SERVER_NAME, isHookClient } from "../daemon/hook-contract.js";
+import { CLAUDE_PRE_TOOL_MATCHER, HOOK_STOP_TIMEOUT_SEC, HOOK_TIMEOUT_SEC, MCP_SERVER_NAME, WAIT_HOOK_TIMEOUT_SEC, isHookClient } from "../contract.js";
 import { pkg } from "../config/index.js";
-import { entryScript } from "./autostart.js";
+import { spawnClientSync } from "./client-command.js";
+import { entryScript } from "./entry.js";
 import { mcpConfigFile, readMcpCommand } from "./mcp-config.js";
 const EVENTS = {
     claude: ["SessionStart", "SessionEnd", "UserPromptSubmit", "PreToolUse", "PostToolUse", "Stop"],
@@ -25,9 +26,9 @@ const EVENTS = {
 export class InstallError extends Error {
 }
 /** Path segments of Node installs that are replaced on upgrade. */
-export const VERSIONED_NODE_DIR = /\/Cellar\/|\/\.nvm\/versions\/|\/node-v\d|\/fnm\/|\/fnm_multishells\/|\/\.volta\/|\/\.asdf\/installs\//;
+export const VERSIONED_NODE_DIR = /[/\\]Cellar[/\\]|[/\\]\.nvm[/\\]versions[/\\]|[/\\]node-v\d|[/\\]fnm[/\\]|[/\\]fnm_multishells[/\\]|[/\\]\.volta[/\\]|[/\\]\.asdf[/\\]installs[/\\]/;
 /** fnm puts a per-shell symlink directory first on PATH; it is gone when the shell ends. */
-const PER_SHELL_NODE_DIR = /\/fnm_multishells\//;
+const PER_SHELL_NODE_DIR = /[/\\]fnm_multishells[/\\]/;
 function sameFile(a, b) {
     try {
         return fs.realpathSync(a) === fs.realpathSync(b);
@@ -45,7 +46,7 @@ export function stableNodePath(env = process.env) {
     for (const dir of (env.PATH ?? "").split(path.delimiter)) {
         if (!path.isAbsolute(dir) || PER_SHELL_NODE_DIR.test(dir))
             continue;
-        const candidate = path.join(dir, "node");
+        const candidate = path.join(dir, process.platform === "win32" ? "node.exe" : "node");
         if (sameFile(candidate, process.execPath))
             return candidate;
     }
@@ -70,7 +71,7 @@ export function satisfiesEngines(version, range = pkg.engines.node) {
     });
 }
 /** Check a `--node` path: it must exist, run, and satisfy engines.node. Returns the absolute path. */
-function checkNodePath(given) {
+export function checkNodePath(given) {
     const node = path.resolve(given);
     try {
         fs.accessSync(node, fs.constants.X_OK);
@@ -158,10 +159,12 @@ function removeOurEntries(config, client, file) {
     }
     return changed;
 }
-function addOurEntries(config, client, command) {
+function addOurEntries(config, client, command, commandWindows) {
     const hooks = (config.hooks ??= {});
     for (const event of EVENTS[client]) {
         const entry = { type: "command", command, timeout: event === "Stop" ? HOOK_STOP_TIMEOUT_SEC : HOOK_TIMEOUT_SEC };
+        if (commandWindows)
+            entry.commandWindows = commandWindows;
         const group = client === "claude" && event === "PreToolUse"
             ? { matcher: CLAUDE_PRE_TOOL_MATCHER, hooks: [entry] }
             : { hooks: [entry] };
@@ -171,6 +174,12 @@ function addOurEntries(config, client, command) {
         else
             hooks[event] = [group];
     }
+    // The background wait that wakes an idle conversation (hook.ts --wait): Claude runs it as an
+    // asyncRewake hook; for Codex it starts a detached wait and returns at once.
+    const wait = client === "claude"
+        ? { type: "command", command: `${command} --wait`, asyncRewake: true, timeout: WAIT_HOOK_TIMEOUT_SEC }
+        : { type: "command", command: `${command} --wait`, ...(commandWindows ? { commandWindows: `${commandWindows} '--wait'` } : {}), timeout: HOOK_TIMEOUT_SEC };
+    hooks.Stop.push({ hooks: [wait] });
 }
 function writeConfig(file, config) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -188,6 +197,18 @@ function mcpAddArgs(client, node, entry, endpoint) {
     const scope = client === "claude" ? ["--scope", "user"] : [];
     return ["mcp", "add", ...scope, MCP_SERVER_NAME, ...env, "--", node, entry, "mcp"];
 }
+/**
+ * Run `<client> <args>` and throw like execFileSync when it fails. On Windows
+ * spawnClientSync runs the script behind npm's `.cmd` shim, never cmd.exe.
+ */
+function runClient(client, args, stdio) {
+    const result = spawnClientSync(client, args, { encoding: "utf8", stdio });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0) {
+        throw Object.assign(new Error(`Command failed: ${client} ${args.join(" ")}`), { status: result.status, stderr: result.stderr });
+    }
+}
 /**
  * Run `<client> mcp remove`. A failure is ignored only when `<client> mcp get`
  * shows the server is not registered (never installed, or already removed);
@@ -196,7 +217,7 @@ function mcpAddArgs(client, node, entry, endpoint) {
 function removeMcpServer(client, action, hooksRemoved) {
     const removeArgs = mcpRemoveArgs(client);
     try {
-        execFileSync(client, removeArgs, { encoding: "utf8", stdio: ["ignore", "ignore", "pipe"] });
+        runClient(client, removeArgs, ["ignore", "ignore", "pipe"]);
         if (action === "uninstall")
             process.stdout.write(`Ran: ${client} ${removeArgs.join(" ")}\n`);
         return;
@@ -227,10 +248,10 @@ export function runInstall(options) {
     const { action, client, endpoint } = options;
     const entry = options.entry ?? entryScript();
     try {
-        if (action === "install" && entry.includes("/_npx/")) {
+        if (action === "install" && /[/\\]_npx[/\\]/.test(entry)) {
             throw new InstallError(`n2n-nexus is running from an npx cache (${entry}), which can be cleared at any time. Install it first: npm i -g n2n-nexus`);
         }
-        const probe = spawnSync(client, ["--version"], { stdio: "ignore" });
+        const probe = spawnClientSync(client, ["--version"], { stdio: "ignore" });
         if (probe.error || probe.status !== 0) {
             throw new InstallError(`The "${client}" command was not found on PATH; install ${client === "claude" ? "Claude Code" : "Codex"} first.`);
         }
@@ -240,7 +261,10 @@ export function runInstall(options) {
         const removed = removeOurEntries(config, client, file);
         if (action === "install") {
             const command = `"${node}" "${entry}" hook ${client}${endpoint ? ` --endpoint ${endpoint}` : ""}`;
-            addOurEntries(config, client, command);
+            const commandWindows = client === "codex"
+                ? `& ${[node, entry, "hook", client, ...(endpoint ? ["--endpoint", endpoint] : [])].map((arg) => `'${arg.replace(/['\u2018\u2019]/g, "$&$&")}'`).join(" ")}`
+                : undefined;
+            addOurEntries(config, client, command, commandWindows);
         }
         if (action === "install" || removed) {
             writeConfig(file, config);
@@ -249,7 +273,7 @@ export function runInstall(options) {
         removeMcpServer(client, action, removed);
         if (action === "install" && node) {
             const addArgs = mcpAddArgs(client, node, entry, endpoint);
-            execFileSync(client, addArgs, { stdio: ["ignore", "ignore", "inherit"] });
+            runClient(client, addArgs, ["ignore", "ignore", "inherit"]);
             process.stdout.write(`Ran: ${client} ${addArgs.join(" ")}\n`);
             process.stdout.write(`Node: ${node}\n`);
             if (VERSIONED_NODE_DIR.test(node)) {

package/build/cli/mcp-config.js

@@ -8,7 +8,7 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { MCP_SERVER_NAME } from "../daemon/hook-contract.js";
+import { MCP_SERVER_NAME } from "../contract.js";
 /** Where the client keeps the MCP server command. */
 export function mcpConfigFile(client) {
     if (client === "claude") {
@@ -41,22 +41,26 @@ export function readMcpCommand(client, file) {
             return undefined;
         return { command: server.command, args: Array.isArray(server.args) ? server.args.map(String) : [] };
     }
-    // Codex: a TOML table [mcp_servers.n2n-nexus] (the key may be quoted) with command = "..." and args = [...].
+    // 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));
+    const start = lines.findIndex((line) => new RegExp(`^\\s*\\[mcp_servers\\.(["']?)${MCP_SERVER_NAME}\\1\\]\\s*(?:#.*)?$`).test(line));
     if (start === -1)
         return undefined;
-    let command;
-    let args = [];
+    const body = [];
     for (const line of lines.slice(start + 1)) {
         if (/^\s*\[/.test(line))
             break;
-        const c = /^\s*command\s*=\s*"((?:[^"\\]|\\.)*)"/.exec(line);
-        if (c)
-            command = JSON.parse(`"${c[1]}"`);
-        const a = /^\s*args\s*=\s*\[(.*)\]/.exec(line);
-        if (a)
-            args = [...a[1].matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => JSON.parse(`"${m[1]}"`));
+        body.push(line);
     }
-    return command === undefined ? undefined : { command, args };
+    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);
+    if (!command)
+        return undefined;
+    // Treat strings and comments as whole tokens so brackets and quotes inside them are not syntax.
+    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 };
 }

package/build/client/discovery.js

@@ -0,0 +1,115 @@
+/**
+ * LAN discovery of a host, query side. An n2n-nexus-host bound to a
+ * non-loopback address answers UDP queries on the discovery port; a client
+ * configured with the endpoint `discover` broadcasts a query, uses the first
+ * host that answers and caches it in `~/.n2n-nexus/discovered-endpoint`. When
+ * none answers it falls back to the local default endpoint (a host running on
+ * this machine); it never starts a host or makes one reachable from the LAN.
+ *
+ * Node built-ins only: the hook command imports this on every client event.
+ */
+import dgram from "node:dgram";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/** 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";
+export const DISCOVERY_QUERY = "n2n-nexus/discover";
+const DEFAULT_DISCOVERY_PORT = 5688;
+const DISCOVERY_WAIT_MS = 1000;
+/** How long "no daemon answered" stays cached before the next lookup. */
+const NOT_FOUND_TTL_MS = 60_000;
+const ALL_INTERFACES = new Set(["0.0.0.0", "::", ""]);
+/** UDP port of discovery queries (NEXUS_DISCOVERY_PORT, default 5688). */
+export function discoveryPort() {
+    const parsed = parseInt(process.env.NEXUS_DISCOVERY_PORT || "", 10);
+    return parsed > 0 ? parsed : DEFAULT_DISCOVERY_PORT;
+}
+/** IPv4 LAN interfaces of this machine. */
+function lanInterfaces() {
+    return Object.values(os.networkInterfaces()).flatMap((addresses) => addresses ?? [])
+        .filter((a) => a.family === "IPv4" && !a.internal);
+}
+/** Directed broadcast address of every IPv4 LAN interface, plus the limited broadcast and loopback. */
+function queryTargets() {
+    const targets = new Set(["255.255.255.255", "127.0.0.1"]);
+    for (const a of lanInterfaces()) {
+        const ip = a.address.split(".").map(Number);
+        const mask = a.netmask.split(".").map(Number);
+        targets.add(ip.map((octet, i) => (octet | (~mask[i] & 255))).join("."));
+    }
+    return [...targets];
+}
+/** Broadcast a query and return the endpoint of the first daemon that answers, or null. */
+export function discoverEndpoint(udpPort = discoveryPort(), waitMs = DISCOVERY_WAIT_MS) {
+    // A daemon on this machine answers from loopback or one of its own addresses: use loopback when it
+    // 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."))
+            return rinfo.address;
+        return typeof reply.host === "string" && !ALL_INTERFACES.has(reply.host) ? reply.host : "127.0.0.1";
+    };
+    return new Promise((resolve) => {
+        const socket = dgram.createSocket("udp4");
+        let done = false;
+        const finish = (endpoint) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            socket.close();
+            resolve(endpoint);
+        };
+        const timer = setTimeout(() => finish(null), waitMs);
+        socket.on("error", () => finish(null));
+        socket.on("message", (msg, rinfo) => {
+            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}`);
+                }
+            }
+            catch { /* not a discovery reply */ }
+        });
+        socket.bind(0, () => {
+            socket.setBroadcast(true);
+            const query = Buffer.from(DISCOVERY_QUERY);
+            for (const target of queryTargets())
+                socket.send(query, udpPort, target, () => { });
+        });
+    });
+}
+const cacheFile = () => path.join(os.homedir(), ".n2n-nexus", "discovered-endpoint");
+/** The cached lookup result and its age, or null when there is none. */
+export function cachedEndpoint() {
+    try {
+        const endpoint = fs.readFileSync(cacheFile(), "utf8").trim();
+        return endpoint ? { endpoint, ageMs: Date.now() - fs.statSync(cacheFile()).mtimeMs } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The endpoint to use for a configured value: anything but `discover` as is.
+ * For `discover`: the cached result unless `fresh`, else a lookup. A found
+ * daemon stays cached until a client fails to reach it and looks again; "none
+ * answered" (the local default) is cached for NOT_FOUND_TTL_MS so hooks do not
+ * wait for a lookup on every event.
+ */
+export async function resolveEndpoint(configured, options = {}) {
+    if (configured !== DISCOVER_ENDPOINT)
+        return configured;
+    const cached = options.fresh ? null : cachedEndpoint();
+    if (cached && (cached.endpoint !== LOCAL_ENDPOINT || cached.ageMs < NOT_FOUND_TTL_MS))
+        return cached.endpoint;
+    const endpoint = await discoverEndpoint() ?? LOCAL_ENDPOINT;
+    try {
+        fs.mkdirSync(path.dirname(cacheFile()), { recursive: true });
+        fs.writeFileSync(cacheFile(), endpoint + "\n");
+    }
+    catch { /* caching is best effort */ }
+    return endpoint;
+}

package/build/client/nexus-client.js

@@ -11,6 +11,8 @@ export class NexusTransportError extends Error {
         this.name = "NexusTransportError";
     }
 }
+/** NexusTransportError code when the daemon did not answer within the request timeout. */
+export const REQUEST_TIMEOUT_CODE = "EREQUESTTIMEOUT";
 /** The daemon answered, but the tool call itself failed (unknown tool, validation, not found, ...). */
 export class NexusToolError extends Error {
     status;
@@ -73,12 +75,16 @@ export class NexusClient {
                 });
             });
             req.on("error", (e) => reject(e instanceof NexusTransportError ? e : new NexusTransportError(e.message, e.code)));
-            req.on("timeout", () => req.destroy(new NexusTransportError(`Request to ${this.endpoint} timed out after ${timeoutMs} ms`)));
+            req.on("timeout", () => req.destroy(new NexusTransportError(`Request to ${this.endpoint} timed out after ${timeoutMs} ms`, REQUEST_TIMEOUT_CODE)));
             if (payload)
                 req.write(payload);
             req.end();
         });
     }
+    /** GET /health: n2n-nexus-host answers `{ ok, service: "n2n-nexus", version, contractVersion, sessions: { online } }`. */
+    async health() {
+        return this.request("GET", "/health");
+    }
     async fetchTools() {
         const res = await this.request("GET", "/api/tools");
         return res.tools;
@@ -88,7 +94,7 @@ export class NexusClient {
         return this.request("POST", "/api/hook", request, timeoutMs);
     }
     async callTool(name, args, instanceId, caller) {
-        const res = await this.request("POST", "/api/tools/call", { tool: name, args: args || {}, instanceId: instanceId || "unknown", ...(caller ? { caller } : {}) });
+        const res = await this.request("POST", "/api/tools/call", { tool: name, args: args || {}, ...(instanceId ? { instanceId } : {}), ...(caller ? { caller } : {}) });
         if (!res.ok)
             throw new NexusToolError(res.error || "Tool call failed", 200);
         return res.result;