c8ctl-plugin-nano 1.36.0 → 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

@@ -2408,11 +2408,16 @@ function sameOrigin(a, b) {
   }
 }
 
-function resolveBrokerRestConfig(env = process.env) {
+function resolveBrokerRestConfig(env = process.env, opts = {}) {
   // readConfig() swallows parse/IO errors and never throws (returns {}), so no
   // local try/catch is needed here.
   const cfg = readConfig() || {};
+  // `opts.baseUrl` lets a caller pin the effective base (e.g. the active c8ctl
+  // profile's REST address — see resolveAutoRestConfig) while still running it
+  // through the SAME token same-origin gate below, so the token logic stays
+  // single-sourced (never duplicated per call site).
   const baseUrl =
+    opts.baseUrl ||
     env.NANO_REST_URL ||
     env.NANO_BASE_URL ||
     cfg.nanoUrl ||
@@ -2440,6 +2445,33 @@ function resolveBrokerRestConfig(env = process.env) {
   return { baseUrl, token };
 }
 
+// Resolve the C8 REST config the `--auto` engine-read reader is built from.
+// This is the job-type-read analogue of resolveLinkedPromptSource: an explicit
+// NANO_REST_URL / NANO_BASE_URL / cfg.nanoUrl override still wins (operator
+// escape hatch), but with NONE of those set the base is derived from the SAME
+// c8ctl client that activates jobs (its getConfig().restAddress) rather than the
+// localhost default — so a worker that can activate jobs against a profile
+// engine can also read the deployed job types from it. Without this, an `--auto`
+// worker on an active remote profile reads from http://localhost:8080, finds no
+// engine, discovers 0 job types, and crash-loops (jwulf/c8ctl-plugin-nano#93).
+// Falls back to resolveBrokerRestConfig's localhost default only when the client
+// exposes no usable restAddress. The token same-origin gate lives in
+// resolveBrokerRestConfig (re-run against the profile base), never duplicated.
+function resolveAutoRestConfig(camunda, env = process.env) {
+  const cfg = readConfig() || {};
+  const hasExplicitBase = Boolean(env.NANO_REST_URL || env.NANO_BASE_URL || cfg.nanoUrl);
+  if (!hasExplicitBase && camunda && typeof camunda.getConfig === 'function') {
+    let profileBase = '';
+    try {
+      profileBase = normalizeRestBase(camunda.getConfig()?.restAddress);
+    } catch {
+      // ignore — degrade to the resolveBrokerRestConfig (localhost) default below
+    }
+    if (profileBase) return resolveBrokerRestConfig(env, { baseUrl: profileBase });
+  }
+  return resolveBrokerRestConfig(env);
+}
+
 // ---------------------------------------------------------------------------
 // `nano work --auto`: zero-config engine-read enrolment (issue #66).
 //
@@ -4138,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
@@ -4175,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;
@@ -4217,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,
@@ -4241,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
@@ -4272,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;
     }
@@ -4292,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,
@@ -4310,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) {
@@ -4323,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.`,
   };
 }
 
@@ -4558,10 +4631,14 @@ async function workAgent(req, flags) {
   }
   const camunda = globalThis.c8ctl.createClient();
 
-  // Broker REST endpoint for live linked-resource prompts (issue #63) — the same
-  // nano endpoint this worker already talks to. Resolved once at startup, and
-  // reused as the C8 REST source for `--auto`'s engine-read enrolment.
-  const restConfig = resolveBrokerRestConfig();
+  // Broker REST endpoint for live linked-resource prompts (issue #63) and the
+  // C8 REST source for `--auto`'s engine-read enrolment. Derived from the SAME
+  // client that activates jobs (its profile REST address) when no explicit
+  // NANO_REST_URL/NANO_BASE_URL/cfg.nanoUrl override is set — so a worker that
+  // can activate jobs against the active profile engine also reads job types
+  // from it, instead of a localhost default that crash-loops when nothing is
+  // listening on :8080 (jwulf/c8ctl-plugin-nano#93). Resolved once at startup.
+  const restConfig = resolveAutoRestConfig(camunda);
 
   // The desired job-type set. In `--auto` it is engine-read (∪ any --job-type
   // extras); otherwise it is the rank×capability matrix (∪ extras). The initial
@@ -4708,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) {
@@ -5183,7 +5261,16 @@ async function workAgent(req, flags) {
       if (inFlightReconcile) return;
       reconcile().catch((err) => logger.warn(`--auto reconcile failed: ${err?.message || err}`));
     }, AUTO_POLL_INTERVAL_MS);
-    if (typeof autoPollTimer.unref === 'function') autoPollTimer.unref();
+    // Deliberately REF'd (unlike the reaper/run-dir hygiene timers, which are
+    // unref'd): in `--auto` this poll IS the retry loop, and it must keep the
+    // process alive even with zero pollers. When the INITIAL engine read fails
+    // (transient miss, or the engine isn't up yet) the worker registers 0
+    // pollers; nothing else holds the event loop open (the SDK client with no
+    // job workers doesn't, and the hygiene timers are unref'd), so an unref'd
+    // poll timer would let the process exit 0 — the observed crash-loop under a
+    // supervisor (jwulf/c8ctl-plugin-nano#93). Keeping it ref'd makes the worker
+    // stay up and re-read on the next poll, exactly as the initial-read warning
+    // promises. Shutdown clears it (clearInterval), so Ctrl-C/SIGTERM still exit.
   } else {
     // `watchFile` (polling stat) is deliberate over `fs.watch`: it survives the
     // atomic temp+rename that `writeConfig` does (fs.watch would rebind to the old
@@ -8547,6 +8634,7 @@ export {
   parseLinkedResources,
   pickLinkedResource,
   resolveBrokerRestConfig,
+  resolveAutoRestConfig,
   resourceContentUrl,
   fetchLinkedResourceContent,
   resolveLinkedPrompt,
@@ -8602,6 +8690,7 @@ export {
   scanAgentTaskLeaves,
   readDeployedAgentJobTypes,
   resolveAutoJobTypes,
+  workAgent,
   derivePollTimeoutMs,
   AGENT_TASK_NS,
   AGENT_RESULT_KEY,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.36.0",
+  "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.0",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.36.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.36.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.36.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.36.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.36.0",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.36.0"
+    "@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"
   }
 }