c8ctl-plugin-nano 1.36.1 → 1.36.2

package/README.md

@@ -292,23 +292,28 @@ c8ctl nano work reviewer
 
 **Zero-config hub auto-discovery.** You usually don't even set `NANO_AGENTIC_URL`.
 When nwf runs **embedded**, the engine (`:8080`) serves the console but the
-`/agentic` channel is served by the **embedded app on its own loopback port**
-(e.g. `:3000`); the engine's console proxy deliberately refuses WebSocket
-upgrades (nanobpmn ADR 0057 §3 → `501`), so the channel is unreachable via the
-engine URL. With **no** agentic target configured, `work` therefore
-**auto-discovers** it: it reads `GET <engine>/console/api/projects` and, for each
-running app that advertises an agentic UI port (`appUi.enabled === true` and
-`appUi.port`), probes that app's direct `ws://127.0.0.1:<port>/agentic`. Discovery
-is **loopback-only** and **time-bounded** (≤2s) and never meaningfully delays job
-polling.
+`/agentic` channel is served by the **embedded app on its own port** (e.g.
+`:3000`); the engine's console proxy deliberately refuses WebSocket upgrades
+(nanobpmn ADR 0057 §3 → `501`), so the channel is unreachable via the engine URL.
+With **no** agentic target configured, `work` therefore **auto-discovers** it: it
+reads `GET <engine>/console/api/projects` and, for each running app that
+advertises an agentic UI port (`appUi.enabled === true` and `appUi.port`), probes
+that app's direct `ws://<engine-host>:<port>/agentic`. Discovery runs **against
+the engine's own host** — a local engine keeps probing `127.0.0.1`, while a
+remote/LAN engine (e.g. `merlin.local:8080`) steers the probe back at *itself*
+(`merlin.local:<port>`), never at the worker's own loopback services. It is
+**time-bounded** (≤2s) and never meaningfully delays job polling. The discovered
+host and port are printed for debugging. (An IPv6 literal engine host is bracketed
+in the URL authority, e.g. `ws://[2001:db8::1]:3000/agentic`.)
 
 - **Exactly one app →** the worker connects directly to
-  `ws://127.0.0.1:<appUi.port>/agentic` (bypassing the WS-incapable console proxy)
-  and appears live with **zero configuration**.
+  `ws://<engine-host>:<appUi.port>/agentic` (bypassing the WS-incapable console
+  proxy) and appears live with **zero configuration** — including cross-machine on
+  a trusted LAN.
 - **Two or more apps →** the worker **does not guess**: it prints an `ambiguous`
   error naming each discovered `project → :port` and **stops**. Pin the one you
-  want and re-run: `export NANO_AGENTIC_URL=http://127.0.0.1:<port>` (or persist
-  `agenticUrl`).
+  want and re-run: `export NANO_AGENTIC_URL=http://<engine-host>:<port>` (or
+  persist `agenticUrl`).
 - **Nothing discoverable (e.g. pointed at Camunda, or an API-only gateway) →** the
   worker prints a one-line advisory naming `NANO_AGENTIC_URL` and **continues
   doing real work** with the channel simply absent — discovery never fails the

package/c8ctl-plugin.js

@@ -4170,6 +4170,21 @@ function isLoopbackHost(hostname) {
   return /^127(?:\.\d{1,3}){3}$/.test(h);
 }
 
+/**
+ * Format a hostname for the authority component of a `ws://`/`http://` URL:
+ * a bare IPv6 literal (contains `:`, not already bracketed) is wrapped in `[…]`,
+ * everything else is used verbatim. Idempotent — an already-bracketed host is
+ * left as-is. Guards against building an invalid `ws://::1:3000/…` when a raw or
+ * normalized IPv6 host (e.g. the `::1` constant) has not been bracketed.
+ *
+ * @param {string} host a hostname from `URL.hostname` or a normalized loopback
+ * @returns {string}
+ */
+function wsHostPart(host) {
+  const h = String(host || '');
+  return h.includes(':') && !h.startsWith('[') ? `[${h}]` : h;
+}
+
 /**
  * Normalise the engine's `GET /console/api/projects` payload into the running
  * embedded apps that advertise an agentic UI port. Accepts the shapes the
@@ -4207,24 +4222,26 @@ function normalizeProjectApps(projects) {
 }
 
 /**
- * Probe whether an embedded app's own loopback `/agentic` endpoint answers a
- * WebSocket upgrade. Connects to `ws://127.0.0.1:<port>/agentic?token=…` and
+ * Probe whether an embedded app's `/agentic` endpoint answers a WebSocket
+ * upgrade. Connects to `ws://<host>:<port>/agentic?token=…` (host defaults to
+ * `127.0.0.1`; a bare IPv6 literal is bracketed for the URL authority) and
  * resolves `true` only if the socket opens within `timeoutMs`; a refused
  * connection, the console proxy's deliberate `501`, a `404`, or a timeout all
- * resolve `false`. Loopback-only and self-cleaning — the probe socket is closed
- * as soon as the outcome is known. Never throws.
+ * resolve `false`. Self-cleaning — the probe socket is closed as soon as the
+ * outcome is known. Never throws.
  *
- * @param {number} port the app's direct loopback port (`appUi.port`)
- * @param {{ token?: string, WebSocketImpl?: Function, timeoutMs?: number }} [opts]
+ * @param {number} port the app's direct agentic port (`appUi.port`)
+ * @param {{ host?: string, token?: string, WebSocketImpl?: Function, timeoutMs?: number }} [opts]
  * @returns {Promise<boolean>}
  */
 function probeAgenticChannel(port, {
+  host = '127.0.0.1',
   token = LOCAL_AGENTIC_TOKEN,
   WebSocketImpl = globalThis.WebSocket,
   timeoutMs = AGENTIC_DISCOVERY_TIMEOUT_MS,
 } = {}) {
   if (typeof WebSocketImpl !== 'function') return Promise.resolve(false);
-  const url = `ws://127.0.0.1:${port}/agentic?token=${encodeURIComponent(token)}`;
+  const url = `ws://${wsHostPart(host)}:${port}/agentic?token=${encodeURIComponent(token)}`;
   return new Promise((resolve) => {
     let done = false;
     let ws;
@@ -4249,19 +4266,21 @@ function probeAgenticChannel(port, {
 
 /**
  * Auto-discover the embedded nwf agentic hub(s) reachable from an engine base
- * URL (#75). Reads `GET <engine>/console/api/projects`, keeps the apps that
- * advertise an agentic UI port, and WS-probes each app's direct loopback
- * `/agentic` to confirm the channel is actually served there (bypassing the
- * WS-incapable console proxy). Loopback-only (the engine host itself must be
- * loopback, since the response steers a local port probe), enforces a single
- * shared time budget across the fetch + probes, and is fail-open: any error —
- * not a nano engine (Camunda), a non-loopback engine, network failure,
- * malformed body, or an overall timeout — degrades to `[]` so the worker's real
- * job is never blocked.
+ * URL (#75, #96). Reads `GET <engine>/console/api/projects`, keeps the apps that
+ * advertise an agentic UI port, and WS-probes each app's `/agentic` **on the
+ * engine's own host** to confirm the channel is actually served there (bypassing
+ * the WS-incapable console proxy). Works cross-machine on a trusted LAN: a
+ * loopback engine probes `127.0.0.1`, a remote engine (e.g. `merlin.local`)
+ * probes that same host — the port is taken from the projects API but the host is
+ * always the engine's, so a rogue projects API can never steer a probe at the
+ * worker's own loopback (#76). Enforces a single shared time budget across the
+ * fetch + probes, and is fail-open: any error — not a nano engine (Camunda),
+ * network failure, malformed body, or an overall timeout — degrades to `[]` so
+ * the worker's real job is never blocked.
  *
- * @param {string} engineBaseUrl the engine base URL (e.g. `http://localhost:8080`)
+ * @param {string} engineBaseUrl the engine base URL (e.g. `http://merlin.local:8080`)
  * @param {{ token?: string, fetchImpl?: Function, wsProbe?: Function, timeoutMs?: number }} [opts]
- * @returns {Promise<Array<{ project: string, port: number, label?: string }>>}
+ * @returns {Promise<Array<{ project: string, port: number, label?: string, host: string }>>}
  */
 async function discoverAgenticHubs(engineBaseUrl, {
   token = LOCAL_AGENTIC_TOKEN,
@@ -4273,16 +4292,21 @@ async function discoverAgenticHubs(engineBaseUrl, {
     return [];
   }
   const base = engineBaseUrl.replace(/\/+$/, '');
-  // Loopback-only: discovery probes 127.0.0.1:<port> using a port advertised by
-  // the engine's projects API, so a non-loopback (remote) engine could steer a
-  // local port probe. Refuse discovery unless the engine host is loopback (#76).
+  // Discover against the ENGINE's own host — the app is embedded in the engine,
+  // so its /agentic port lives on the same host the worker already trusts as its
+  // engine (that's where it pulls jobs from). A loopback engine keeps probing
+  // 127.0.0.1 (unchanged local behaviour); a remote/LAN engine (e.g.
+  // merlin.local) steers the probe back to ITSELF, never at the worker's own
+  // loopback services — which was the actual #76 concern (a rogue projects API
+  // making the worker probe its own localhost). So the port comes from the
+  // engine's projects API, but the HOST is always the engine's, never guessed.
   let host;
   try {
     host = new URL(base).hostname;
   } catch {
     return [];
   }
-  if (!isLoopbackHost(host)) return [];
+  const probeHost = isLoopbackHost(host) ? '127.0.0.1' : host;
   // Single discovery budget: the projects fetch and the WS probes share ONE
   // deadline, so total discovery can't approach 2× timeoutMs (the fetch could
   // consume ~timeoutMs and then each probe was previously given a fresh full
@@ -4304,10 +4328,13 @@ async function discoverAgenticHubs(engineBaseUrl, {
   if (apps.length === 0) return [];
   const remainingMs = deadline - Date.now();
   if (remainingMs <= 0) return [];
-  // Probe candidate ports concurrently within the remaining shared budget.
+  // Probe candidate ports concurrently within the remaining shared budget. Each
+  // surviving hub carries the engine host so the caller builds the right URL.
   const settled = await Promise.all(apps.map(async (app) => {
     try {
-      return (await wsProbe(app.port, { token, timeoutMs: remainingMs })) ? app : null;
+      return (await wsProbe(app.port, { host: probeHost, token, timeoutMs: remainingMs }))
+        ? { ...app, host: probeHost }
+        : null;
     } catch {
       return null;
     }
@@ -4324,7 +4351,8 @@ async function discoverAgenticHubs(engineBaseUrl, {
  *     half-configured. No discovery attempted.
  *   - `{ status: 'connect', config }` — a target to connect to. Either the
  *     explicit `NANO_AGENTIC_URL`/`agenticUrl` verbatim (no discovery), or the
- *     single discovered app's direct `ws://127.0.0.1:<port>/agentic` loopback.
+ *     single discovered app's `ws://<engineHost>:<port>/agentic` (loopback for a
+ *     local engine, the engine's LAN host for a remote one).
  *   - `{ status: 'ambiguous', message, candidates }` — two+ apps expose a
  *     channel. Hard stop for the worker: it must not silently pick one.
  *   - `{ status: 'advisory', message }` — nothing discoverable (zero matches,
@@ -4342,11 +4370,24 @@ async function resolveAgenticTarget(opts = {}) {
 
   const hubs = await discoverAgenticHubs(base.url, { token: base.token, ...opts });
 
+  // The host to suggest in operator-facing messages: the engine's own host
+  // (bracketed if an IPv6 literal, so the suggested URL authority is valid), so a
+  // remote-engine advisory names the reachable LAN host rather than 127.0.0.1.
+  let suggestHost = '127.0.0.1';
+  try {
+    const h = new URL(base.url).hostname;
+    suggestHost = wsHostPart(isLoopbackHost(h) ? '127.0.0.1' : h);
+  } catch { /* keep the loopback default */ }
+
   if (hubs.length === 1) {
-    const { project, port } = hubs[0];
+    const { project, port, host } = hubs[0];
     return {
       status: 'connect',
-      config: { ...base, url: `http://127.0.0.1:${port}`, discovered: { project, port } },
+      config: {
+        ...base,
+        url: `http://${wsHostPart(host)}:${port}`,
+        discovered: { project, port, host },
+      },
     };
   }
   if (hubs.length > 1) {
@@ -4355,14 +4396,14 @@ async function resolveAgenticTarget(opts = {}) {
       status: 'ambiguous',
       candidates: hubs,
       message: `multiple embedded apps expose an agentic channel (${list}); refusing to guess. `
-        + 'Disambiguate by setting NANO_AGENTIC_URL=http://127.0.0.1:<port> (or persisted agenticUrl) to the one you want.',
+        + `Disambiguate by setting NANO_AGENTIC_URL=http://${suggestHost}:<port> (or persisted agenticUrl) to the one you want.`,
     };
   }
   return {
     status: 'advisory',
     message: `agentic visibility was not discoverable at ${base.url} — the embedded app port could `
       + 'not be found (not a nano engine, or its console projects API is absent). Set '
-      + 'NANO_AGENTIC_URL=http://127.0.0.1:<appUi.port> to enable the visibility channel. Continuing without it.',
+      + `NANO_AGENTIC_URL=http://${suggestHost}:<appUi.port> to enable the visibility channel. Continuing without it.`,
   };
 }
 
@@ -4744,7 +4785,8 @@ async function workAgent(req, flags) {
       const shown = redactAgenticUrl(buildAgenticUrl(agenticCfg.url, {}));
       const mode = agenticCfg.secure ? 'secure' : 'local';
       if (agenticCfg.discovered) {
-        logger.info(`  agentic channel: auto-discovered ${agenticCfg.discovered.project} on the embedded app port :${agenticCfg.discovered.port} (bypassing the WS-incapable console proxy).`);
+        const d = agenticCfg.discovered;
+        logger.info(`  agentic channel: auto-discovered ${d.project} on the app's /agentic port ${wsHostPart(d.host)}:${d.port} (bypassing the WS-incapable console proxy).`);
       }
       logger.info(`  agentic channel (${mode}): announcing presence as ${workerName} on ${shown}`);
     } catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.36.1",
+  "version": "1.36.2",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -57,12 +57,12 @@
   },
   "optionalDependencies": {
     "node-pty": "^1.0.0",
-    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.36.1",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.36.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.36.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.36.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.36.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.36.1",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.36.1"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.36.2",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.36.2",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.36.2",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.36.2",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.36.2",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.36.2",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.36.2"
   }
 }