c8ctl-plugin-nano 1.58.0 → 1.59.0

package/agentic-endpoint.mjs

@@ -305,7 +305,10 @@ function buildRawEmitClient({ channelUrl, transportFactory, peerAdvertisement, l
  * `transportFactory` and never touches the real client.
  *
  * @param {object} opts
- * @param {string} opts.url the app's HTTP(S) base URL (channel served same-port at `/agentic`)
+ * @param {string} [opts.url] the app's HTTP(S) base URL (channel served same-port at
+ *   `/agentic`). OPTIONAL in self-heal mode: when `resolveConfig` is supplied the base
+ *   URL is not fixed, but a static `url` may still be passed to SEED the initial memo
+ *   before the first re-discovery lands. Required only when `resolveConfig` is absent.
  * @param {string} [opts.token] ADR 0028 identity token (carried as `?token=`)
  * @param {string} [opts.credential] capability credential (carried as `?capability=`)
  * @param {import('@nanobpm/agentic/protocol').ProtocolAdvertisement} [opts.remoteAdvertisement]
@@ -314,23 +317,91 @@ function buildRawEmitClient({ channelUrl, transportFactory, peerAdvertisement, l
  * @param {(state: 'connected'|'disconnected') => void} [opts.onConnectionState] observer fired
  *   when the single host connection opens/drops, so a caller can track its liveness
  * @param {{ warn?: Function, debug?: Function }} [opts.logger]
- * @returns {Promise<() => import('./supervisor.dist.js').RawEmitClient>} a synchronous `connect` factory
+ * @param {() => Promise<{url:string, token?:string, credential?:string}|null>} [opts.resolveConfig]
+ *   OPTIONAL self-heal resolver (jwulf/c8ctl-plugin-nano#133). When present the
+ *   base URL is NOT fixed: each (re)connect consults a background-refreshed,
+ *   memoised config, and while none is known the synchronous factory THROWS —
+ *   which `superviseAgentic` turns into its jittered, ≤30s-capped reconnect
+ *   retry — and kicks a guarded async re-discovery, so a later retry finds the
+ *   hub and connects (`advisory → connected` without a restart). A moved hub
+ *   self-heals the same way. Fail-open: a throwing resolver is swallowed.
+ * @returns {Promise<() => import('./supervisor.dist.js').RawEmitClient>} a synchronous
+ *   `connect` factory. In self-heal (`resolveConfig`) mode it may THROW when the
+ *   hub is not yet discoverable — by contract that drives `superviseAgentic`'s retry.
  */
 export async function createRawEmitConnect(opts) {
-  const { url, token, credential, remoteAdvertisement, transportFactory, logger, onConnectionState } = opts || {};
-  if (typeof url !== 'string' || url.trim() === '') {
-    throw new Error('createRawEmitConnect requires an agentic channel base url');
+  const { url, token, credential, remoteAdvertisement, transportFactory, logger, onConnectionState, resolveConfig } =
+    opts || {};
+  const hasResolver = typeof resolveConfig === 'function';
+  const hasStaticUrl = typeof url === 'string' && url.trim() !== '';
+  if (!hasResolver && !hasStaticUrl) {
+    throw new Error(
+      'createRawEmitConnect requires an agentic channel base `url`, or a `resolveConfig` self-heal resolver to discover one',
+    );
   }
 
-  const channelUrl = buildAgenticUrl(url, { token, credential });
   const factory = transportFactory ?? (await loadAgenticClient()).websocketTransport;
 
-  return () =>
-    buildRawEmitClient({
-      channelUrl,
+  // Static mode: a fixed, known URL (explicit NANO_AGENTIC_URL or an
+  // already-discovered hub). The channel URL is built once; the emit client owns
+  // reconnect to it and `superviseAgentic` re-`connect`s to the SAME URL on a
+  // permanent close. Unchanged behaviour.
+  if (!hasResolver) {
+    const channelUrl = buildAgenticUrl(url, { token, credential });
+    return () =>
+      buildRawEmitClient({
+        channelUrl,
+        transportFactory: factory,
+        peerAdvertisement: remoteAdvertisement,
+        logger,
+        onConnectionState,
+      });
+  }
+
+  // Self-heal mode: re-resolve discovery on each (re)connect via a guarded,
+  // background-refreshed memoised config. While unresolved the factory throws so
+  // `superviseAgentic`'s ≤30s-capped retry doubles as periodic re-discovery.
+  let current = hasStaticUrl ? { url, token, credential } : null;
+  let refreshing = false;
+  const kickRefresh = () => {
+    if (refreshing) return;
+    refreshing = true;
+    Promise.resolve()
+      .then(() => resolveConfig())
+      .then((next) => {
+        if (next && typeof next.url === 'string' && next.url.trim() !== '') {
+          // Preserve the last memoised credentials when a later refresh omits
+          // them, falling back to the initial opts only when nothing was ever
+          // discovered — so a partial refresh never clears a known-good token.
+          current = {
+            url: next.url,
+            token: next.token ?? current?.token ?? token,
+            credential: next.credential ?? current?.credential ?? credential,
+          };
+        }
+      })
+      .catch((err) => {
+        logger?.debug?.(`agentic re-discovery attempt failed: ${err?.message || err}`);
+      })
+      .finally(() => {
+        refreshing = false;
+      });
+  };
+
+  return () => {
+    // Kick a background refresh on every (re)connect so a moved hub self-heals on
+    // the next attempt; it's a no-op while one is in flight, and only runs on a
+    // (re)connect (a steady socket never re-enters this factory).
+    kickRefresh();
+    if (!current) {
+      throw new Error('agentic hub not yet discoverable — retrying via supervised reconnect');
+    }
+    return buildRawEmitClient({
+      channelUrl: buildAgenticUrl(current.url, { token: current.token, credential: current.credential }),
       transportFactory: factory,
       peerAdvertisement: remoteAdvertisement,
       logger,
       onConnectionState,
     });
+  };
 }

package/c8ctl-plugin.js

@@ -6715,94 +6715,6 @@ async function resolveAgenticTarget({ camunda, cache, ...opts } = {}) {
   };
 }
 
-/**
- * A jittered backoff schedule (ms) for background agentic re-discovery (#133-A):
- * ~2s → 4s → 8s → 16s → 30s (capped), each waited value randomised ±20%, spanning
- * roughly `ceilingMs` (default ~5 minutes) of total elapsed retry time before the
- * loop gives up. A worker that lost the cold-start discovery race walks this
- * schedule to upgrade `advisory → connected` without a restart.
- * @param {{ base?: number, cap?: number, ceilingMs?: number, rng?: () => number }} [opts]
- * @returns {number[]} the ordered per-attempt wait durations
- */
-function defaultAgenticRediscoveryDelays({
-  base = 2_000,
-  cap = 30_000,
-  ceilingMs = 5 * 60 * 1_000,
-  rng = Math.random,
-} = {}) {
-  const delays = [];
-  let d = base;
-  let total = 0;
-  while (total < ceilingMs) {
-    const jitter = Math.round((rng() - 0.5) * 0.4 * d); // ±20%
-    const wait = Math.max(500, d + jitter);
-    delays.push(wait);
-    total += wait;
-    d = Math.min(cap, d * 2);
-  }
-  return delays;
-}
-
-/**
- * Background self-heal loop for agentic discovery (#133-A). After an initial
- * cold-start miss leaves a worker in `advisory`, re-run `resolveTarget` on a
- * jittered backoff schedule and, on the FIRST attempt that yields a
- * `status:'connect'` target, invoke `onConnect(target)` and stop — so the worker
- * upgrades to `connected` without a restart. Fail-open: an attempt whose
- * `resolveTarget` throws is swallowed and the loop continues; likewise, if
- * `onConnect` itself throws (a transient channel-open failure), the loop keeps
- * re-discovering rather than stopping, so retries proceed until a connect
- * callback actually succeeds. The loop also stops early whenever
- * `shouldContinue()` returns false (e.g. a channel already came up, or the worker
- * is shutting down). Returns the connecting target, or `null` if the schedule was
- * exhausted / cancelled without a hit. Timers and the resolver are injectable so
- * this is unit-testable without real waits or sockets.
- *
- * @param {{
- *   resolveTarget: () => Promise<{status:string, config?:object}>,
- *   onConnect?: (target: {status:string, config?:object}) => (void|Promise<void>),
- *   delaysMs?: number[],
- *   sleep?: (ms:number) => Promise<void>,
- *   shouldContinue?: () => boolean,
- *   logger?: object,
- * }} opts
- * @returns {Promise<object|null>}
- */
-async function rediscoverAgenticUntilConnected({
-  resolveTarget,
-  onConnect,
-  delaysMs = defaultAgenticRediscoveryDelays(),
-  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
-  shouldContinue = () => true,
-  logger = null,
-} = {}) {
-  if (typeof resolveTarget !== 'function') return null;
-  for (const delay of delaysMs) {
-    if (!shouldContinue()) return null;
-    try { await sleep(delay); } catch { return null; }
-    if (!shouldContinue()) return null;
-    let target;
-    try {
-      target = await resolveTarget();
-    } catch (err) {
-      logger?.debug?.(`agentic re-discovery attempt failed: ${err?.message || err}`);
-      continue;
-    }
-    if (target && target.status === 'connect') {
-      try {
-        await onConnect?.(target);
-      } catch (err) {
-        // A transient channel-open failure must not prematurely stop self-heal:
-        // keep re-discovering until an onConnect callback actually succeeds.
-        logger?.debug?.(`agentic re-discovery onConnect failed, will retry: ${err?.message || err}`);
-        continue;
-      }
-      return target;
-    }
-  }
-  return null;
-}
-
 // Worker-side liveness watchdog defaults (jwulf/c8ctl-plugin-nano#144). A
 // previously-connected agentic channel that has been `disconnected` for longer
 // than the stale threshold — because the client lib's own reconnect never
@@ -7828,8 +7740,24 @@ async function workAgent(req, flags) {
   // worker joins with the well-known LOCAL token and no credential; SECURE mode
   // (NANO_AGENTIC_SECRET) sends a real per-peer shared secret as the identity;
   // NANO_AGENTIC=off disables it (see resolveAgenticConfig).
-  const agenticTarget = await resolveAgenticTarget({ camunda, logger });
+  const agenticDiscoveryCache = new Map();
+  const agenticTarget = await resolveAgenticTarget({ camunda, logger, cache: agenticDiscoveryCache });
   let agenticCfg = null;
+  let agenticSelfHeal = false;
+  // Self-heal resolver (jwulf/c8ctl-plugin-nano#133): re-run discovery on demand
+  // and hand back a fresh connect config, or null while still undiscoverable. The
+  // endpoint's connect factory calls this in the background so `superviseAgentic`'s
+  // ≤30s-capped reconnect doubles as periodic re-discovery — an `advisory`-at-
+  // startup worker (a cold-start discovery miss during an engine hiccup) upgrades
+  // to `connected` without a restart when the hub reappears. The shared cache lets
+  // a later transient miss reuse the last known-good hub (#133-C).
+  const resolveAgenticConnectConfig = async () => {
+    const t = await resolveAgenticTarget({ camunda, logger, cache: agenticDiscoveryCache });
+    if (t && t.status === 'connect') {
+      return { url: t.config.url, token: t.config.token, credential: t.config.credential };
+    }
+    return null;
+  };
   // buildAgenticUrl can throw on a malformed/unsupported explicit NANO_AGENTIC_URL.
   // This is only the display URL for the activity marker, so compute it
   // defensively: a bad URL must be recorded as a channel failure (via the
@@ -7853,10 +7781,31 @@ async function workAgent(req, flags) {
       logger.error(`  agentic visibility is ambiguous: ${agenticTarget.message}`);
       process.exit(1);
       break;
-    case 'advisory':
-      agenticState = agenticStateForTarget(agenticTarget);
-      logger.info(`  agentic channel: ${agenticTarget.message}`);
+    case 'advisory': {
+      // Don't give up: build a SELF-HEALING endpoint whose connect re-discovers
+      // on each of `superviseAgentic`'s ≤30s-capped reconnects, so a cold-start
+      // discovery miss (e.g. the engine hiccuped just as the worker started)
+      // upgrades to `connected` without a restart (jwulf/c8ctl-plugin-nano#133).
+      agenticSelfHeal = true;
+      // Derive one retry-aware message so the marker's `agentic.message` and the
+      // log line agree: consumers of `supervisor status`/markers must see that the
+      // worker WILL self-heal, not the raw "Continuing without it." advisory text.
+      const retryMessage = agenticTarget.message.replace(
+        'Continuing without it.',
+        'Retrying discovery on each ≤30s reconnect until it self-heals.',
+      );
+      // Derive the auth mode from the resolved agentic config so `supervisor
+      // status`/markers report SECURE (NANO_AGENTIC_SECRET) correctly while the
+      // worker is still reconnecting, instead of hard-coding 'local'.
+      agenticState = {
+        status: 'connecting',
+        mode: resolveAgenticConfig(camunda)?.secure ? 'secure' : 'local',
+        url: null,
+        message: retryMessage,
+      };
+      logger.info(`  agentic channel: ${retryMessage}`);
       break;
+    }
     case 'off':
     default:
       agenticState = agenticStateForTarget(agenticTarget);
@@ -7885,17 +7834,23 @@ async function workAgent(req, flags) {
   // the raw-JS wire (`agentic-endpoint.mjs` → the single agentic import surface)
   // with the bundle's Effect adapter; additive negotiation still degrades
   // claim/release/steer to a no-op against an older hub. Reconnect + resync (and
-  // teardown-on-interruption) are owned by the runtime's `superviseAgentic`, so the
-  // retired #133 self-heal loop and #144/#147 liveness watchdog are gone — the
-  // marker's agentic status is driven by the endpoint's connection observer below.
-  // Constructing the endpoint opens NO socket (the runtime's supervision calls the
-  // connect factory), so this stays cheap and side-effect-free until `run` forks.
-  if (agenticCfg) {
+  // teardown-on-interruption) are owned by the runtime's `superviseAgentic`; the
+  // #133 self-heal is REINSTATED without a parallel loop by handing the `advisory`
+  // case a re-discovering connect factory (`resolveConfig`), so `superviseAgentic`'s
+  // own ≤30s-capped reconnect retry IS the periodic re-discovery (the #144/#147
+  // liveness watchdog remains retired) — the marker's agentic status is driven by
+  // the endpoint's connection observer below. Constructing the endpoint opens NO
+  // socket (the runtime's supervision calls the connect factory), so this stays
+  // cheap and side-effect-free until `run` forks.
+  if (agenticCfg || agenticSelfHeal) {
     try {
       agenticEndpoint = await createAgenticEndpoint({
-        url: agenticCfg.url,
-        token: agenticCfg.token,
-        credential: agenticCfg.credential,
+        // Discovered/explicit connect: a fixed URL (static factory). Advisory
+        // self-heal: no URL yet — the resolver supplies it (and heals a moved hub)
+        // on each supervised reconnect.
+        ...(agenticCfg
+          ? { url: agenticCfg.url, token: agenticCfg.token, credential: agenticCfg.credential }
+          : { resolveConfig: resolveAgenticConnectConfig }),
         // Keep the activity marker's agentic status honest across the single
         // connection's open/drop transitions (#99) — the direct analogue of the
         // retired createWorkChannel onConnect/onDisconnect marker wiring.
@@ -13744,8 +13699,6 @@ export {
   resolveProbeCandidates,
   raceProbeCandidates,
   isLinkLocalAddress,
-  rediscoverAgenticUntilConnected,
-  defaultAgenticRediscoveryDelays,
   agenticChannelIsStale,
   agenticPresenceIsStale,
   jitteredDelay,

package/package.json

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