c8ctl-plugin-nano 1.34.0 → 1.35.0

package/README.md

@@ -289,6 +289,35 @@ c8ctl nano work reviewer
 #   agentic channel (local): announcing presence as ‹worker› on ws://localhost:8080/agentic
 ```
 
+**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.
+
+- **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**.
+- **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`).
+- **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
+  worker's actual job.
+
+Setting `NANO_AGENTIC_URL` (or persisted `agenticUrl`) **skips discovery** and is
+used **verbatim** — so an explicit target always wins, and it's also how you
+disambiguate when several apps are running. `NANO_AGENTIC=off` disables the
+channel entirely and attempts **no** discovery.
+
 **Secure mode (opt-in).** For a shared/remote deployment, enrol the worker with an
 ADR 0028 **identity token** and a **capability credential** (the same `?token=…`
 pattern the blackboard uses). Setting either switches the worker into SECURE mode,

package/c8ctl-plugin.js

@@ -3834,6 +3834,11 @@ function resolveAgenticConfig() {
     ?? (cfg.agentic === false ? 'off' : cfg.agentic);
   if (/^(0|off|false|no)$/i.test(String(offSetting ?? ''))) return null;
 
+  // An explicit agentic target (env NANO_AGENTIC_URL or persisted `agenticUrl`)
+  // is used verbatim and short-circuits hub auto-discovery (#75). When neither is
+  // set the URL below is the ENGINE base (nanoUrl → NANO_BASE_URL → default), off
+  // which `resolveAgenticTarget()` discovers the embedded app's own /agentic port.
+  const explicitUrl = !!(process.env.NANO_AGENTIC_URL || cfg.agenticUrl);
   const url = process.env.NANO_AGENTIC_URL
     || cfg.agenticUrl
     || cfg.nanoUrl
@@ -3853,11 +3858,230 @@ function resolveAgenticConfig() {
   // enrolment — require BOTH halves, fail closed if only one is present.
   if (token || credential) {
     if (!token || !credential) return null;
-    return { url, token, credential, bufferCapacity, secure: true };
+    return { url, token, credential, bufferCapacity, secure: true, explicitUrl };
   }
 
   // LOCAL mode (default): well-known localhost token, no capability credential.
-  return { url, token: LOCAL_AGENTIC_TOKEN, credential: '', bufferCapacity, secure: false };
+  return { url, token: LOCAL_AGENTIC_TOKEN, credential: '', bufferCapacity, secure: false, explicitUrl };
+}
+
+// Total budget for zero-config hub auto-discovery (#75): the projects-API read
+// and every WS upgrade probe must degrade to a "not discoverable" advisory
+// within this window so discovery never meaningfully delays job polling.
+const AGENTIC_DISCOVERY_TIMEOUT_MS = 2_000;
+
+/**
+ * Is `hostname` a loopback address? Discovery reads the engine's projects API
+ * and then probes `127.0.0.1:<advertised port>`, so it must only run against a
+ * loopback engine — otherwise a remote engine's response would steer a local
+ * port probe, breaking the loopback-only guarantee (#75/#76). Accepts
+ * `localhost`, the IPv4 loopback block `127.0.0.0/8`, and IPv6 `::1` (with or
+ * without URL brackets); case-insensitive and trimmed.
+ *
+ * @param {string} hostname a URL hostname (e.g. `127.0.0.1`, `localhost`, `[::1]`)
+ * @returns {boolean}
+ */
+function isLoopbackHost(hostname) {
+  const h = String(hostname || '').trim().toLowerCase().replace(/^\[|\]$/g, '');
+  if (!h) return false;
+  if (h === 'localhost' || h === '::1') return true;
+  return /^127(?:\.\d{1,3}){3}$/.test(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
+ * console may serve — a keyed map (`{ "Nano_Workforce": { appUi } }`), a bare
+ * array (`[{ name, appUi }]`), or a wrapped array (`{ projects: [...] }`) — and
+ * keeps only apps with `appUi.enabled === true` and a positive integer
+ * `appUi.port`. Anything else (a Camunda engine, an API-only gateway, malformed
+ * JSON) yields `[]`.
+ *
+ * @param {unknown} projects the parsed projects-API body
+ * @returns {Array<{ project: string, port: number, label?: string }>}
+ */
+function normalizeProjectApps(projects) {
+  if (!projects || typeof projects !== 'object') return [];
+  let entries;
+  if (Array.isArray(projects)) {
+    entries = projects.map((p) => [p?.name ?? p?.project ?? p?.id, p]);
+  } else if (Array.isArray(projects.projects)) {
+    entries = projects.projects.map((p) => [p?.name ?? p?.project ?? p?.id, p]);
+  } else {
+    entries = Object.entries(projects);
+  }
+  const apps = [];
+  for (const [name, proj] of entries) {
+    const ui = proj?.appUi;
+    if (ui && ui.enabled === true && Number.isInteger(ui.port) && ui.port > 0) {
+      apps.push({
+        project: String(name ?? ui.label ?? ui.port),
+        port: ui.port,
+        label: ui.label,
+      });
+    }
+  }
+  return apps;
+}
+
+/**
+ * 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
+ * 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.
+ *
+ * @param {number} port the app's direct loopback port (`appUi.port`)
+ * @param {{ token?: string, WebSocketImpl?: Function, timeoutMs?: number }} [opts]
+ * @returns {Promise<boolean>}
+ */
+function probeAgenticChannel(port, {
+  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)}`;
+  return new Promise((resolve) => {
+    let done = false;
+    let ws;
+    const finish = (ok) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      try { ws?.close(); } catch { /* best-effort cleanup */ }
+      resolve(ok);
+    };
+    const timer = setTimeout(() => finish(false), timeoutMs);
+    try {
+      ws = new WebSocketImpl(url);
+      ws.onopen = () => finish(true);
+      ws.onerror = () => finish(false);
+      ws.onclose = () => finish(false);
+    } catch {
+      finish(false);
+    }
+  });
+}
+
+/**
+ * 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.
+ *
+ * @param {string} engineBaseUrl the engine base URL (e.g. `http://localhost:8080`)
+ * @param {{ token?: string, fetchImpl?: Function, wsProbe?: Function, timeoutMs?: number }} [opts]
+ * @returns {Promise<Array<{ project: string, port: number, label?: string }>>}
+ */
+async function discoverAgenticHubs(engineBaseUrl, {
+  token = LOCAL_AGENTIC_TOKEN,
+  fetchImpl = globalThis.fetch,
+  wsProbe = probeAgenticChannel,
+  timeoutMs = AGENTIC_DISCOVERY_TIMEOUT_MS,
+} = {}) {
+  if (typeof fetchImpl !== 'function' || typeof engineBaseUrl !== 'string' || !engineBaseUrl.trim()) {
+    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).
+  let host;
+  try {
+    host = new URL(base).hostname;
+  } catch {
+    return [];
+  }
+  if (!isLoopbackHost(host)) return [];
+  // 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
+  // budget). Probes get only the time left after the fetch (#76).
+  const deadline = Date.now() + timeoutMs;
+  let projects;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchImpl(`${base}/console/api/projects`, { signal: controller.signal });
+    if (!res || !res.ok) return [];
+    projects = await res.json();
+  } catch {
+    return [];
+  } finally {
+    clearTimeout(timer);
+  }
+  const apps = normalizeProjectApps(projects);
+  if (apps.length === 0) return [];
+  const remainingMs = deadline - Date.now();
+  if (remainingMs <= 0) return [];
+  // Probe candidate ports concurrently within the remaining shared budget.
+  const settled = await Promise.all(apps.map(async (app) => {
+    try {
+      return (await wsProbe(app.port, { token, timeoutMs: remainingMs })) ? app : null;
+    } catch {
+      return null;
+    }
+  }));
+  return settled.filter(Boolean);
+}
+
+/**
+ * Resolve the final agentic-channel target for a worker, running zero-config hub
+ * auto-discovery when no explicit target is configured (#75). Layered on top of
+ * {@link resolveAgenticConfig}:
+ *
+ *   - `{ status: 'off' }` — visibility disabled (off-switch) or SECURE mode
+ *     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.
+ *   - `{ 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,
+ *     no projects API / not a nano engine, or discovery error/timeout). The
+ *     worker continues doing real work with no channel.
+ *
+ * @param {{ fetchImpl?: Function, wsProbe?: Function, timeoutMs?: number }} [opts]
+ * @returns {Promise<{ status: string, config?: object, message?: string, candidates?: Array }>}
+ */
+async function resolveAgenticTarget(opts = {}) {
+  const base = resolveAgenticConfig();
+  if (!base) return { status: 'off' };
+  // Explicit target wins verbatim and skips discovery entirely.
+  if (base.explicitUrl) return { status: 'connect', config: base };
+
+  const hubs = await discoverAgenticHubs(base.url, { token: base.token, ...opts });
+
+  if (hubs.length === 1) {
+    const { project, port } = hubs[0];
+    return {
+      status: 'connect',
+      config: { ...base, url: `http://127.0.0.1:${port}`, discovered: { project, port } },
+    };
+  }
+  if (hubs.length > 1) {
+    const list = hubs.map((h) => `${h.project} → :${h.port}`).join(', ');
+    return {
+      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.',
+    };
+  }
+  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.',
+  };
 }
 
 /**
@@ -4184,7 +4408,26 @@ async function workAgent(req, flags) {
   // worker joins with the well-known localhost token and no credential; SECURE
   // mode (NANO_AGENTIC_TOKEN + NANO_AGENTIC_CREDENTIAL) sends a real ADR 0028
   // identity + capability; NANO_AGENTIC=off disables it (see resolveAgenticConfig).
-  const agenticCfg = resolveAgenticConfig();
+  const agenticTarget = await resolveAgenticTarget({ logger });
+  let agenticCfg = null;
+  switch (agenticTarget.status) {
+    case 'connect':
+      agenticCfg = agenticTarget.config;
+      break;
+    case 'ambiguous':
+      // The operator ran with visibility on-by-default but the hub is
+      // unresolved — a misconfiguration to fix, not to guess through. Hard stop.
+      logger.error(`  agentic visibility is ambiguous: ${agenticTarget.message}`);
+      process.exit(1);
+      break;
+    case 'advisory':
+      logger.info(`  agentic channel: ${agenticTarget.message}`);
+      break;
+    case 'off':
+    default:
+      logger.info('  agentic channel: disabled — either the off-switch is set (NANO_AGENTIC=off or persisted agentic:false), or SECURE mode is half-configured (set BOTH NANO_AGENTIC_TOKEN + NANO_AGENTIC_CREDENTIAL). Clear the off-switch to use default LOCAL visibility.');
+      break;
+  }
   if (agenticCfg) {
     try {
       workChannel = await createWorkChannel({
@@ -4204,6 +4447,9 @@ 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).`);
+      }
       logger.info(`  agentic channel (${mode}): announcing presence as ${workerName} on ${shown}`);
     } catch (err) {
       // Never let a channel failure stop the worker from doing its actual job.
@@ -4227,8 +4473,6 @@ async function workAgent(req, flags) {
         logger.warn(`  agentic buffer monitor unavailable (${err?.message || err}); channel presence still active.`);
       }
     }
-  } else {
-    logger.info('  agentic channel: disabled — either the off-switch is set (NANO_AGENTIC=off or persisted agentic:false), or SECURE mode is half-configured (set BOTH NANO_AGENTIC_TOKEN + NANO_AGENTIC_CREDENTIAL). Clear the off-switch to use default LOCAL visibility.');
   }
 
   // C3 (#42): the role's live-terminal mode — a full PTY (streamed on the relay
@@ -7604,6 +7848,7 @@ export { resolveBinary, findBinary, launcherEnvMarkers };
 export { setConfig, unsetConfig, readConfig, writeConfig, getConfigFile, SETTING_ALIASES };
 export { buildNpmInvocation };
 export { resolveAgenticConfig, LOCAL_AGENTIC_TOKEN };
+export { resolveAgenticTarget, discoverAgenticHubs, probeAgenticChannel, normalizeProjectApps, isLoopbackHost };
 export { compareSemver, githubRepoSlug, filterReleasesSince, renderReleaseBody };
 export {
   webConsoleUrl,

package/package.json

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