c8ctl-plugin-nano 1.58.0 → 1.59.1

package/agent-instance.mjs

@@ -34,9 +34,10 @@ const isPlainObject = (v) => v != null && typeof v === 'object' && !Array.isArra
  * element carries `zeebe:agentDefinition agentType="external"`?
  *
  * The engine surfaces exactly this eligibility as the pair of fields it stamps on
- * an external agent job's activation: an opaque per-activation `jobLease` token
- * (distinct from the job's `deadline`; nanobpmn #1106) plus the `elementInstanceKey`
- * the AgentInstance correlates on. The engine-native `aiAgentTask`/`aiAgentSubProcess`
+ * an external agent job's activation: an opaque per-activation lease token —
+ * `leaseToken` on the activated job (Camunda v10 ActivatedJobResult; distinct from
+ * the job's `deadline`, nanobpmn #1106) — plus the `elementInstanceKey` the
+ * AgentInstance correlates on. The engine-native `aiAgentTask`/`aiAgentSubProcess`
  * variants auto-mint their AgentInstance and never create an activatable job, so any
  * job a worker actually activates that carries a lease token IS an external agent
  * job. Absence of either field means "not an external agent job" → the producer
@@ -44,7 +45,7 @@ const isPlainObject = (v) => v != null && typeof v === 'object' && !Array.isArra
  */
 export function isExternalAgentJob(job) {
   if (!isPlainObject(job)) return false;
-  return isNonBlank(job.jobLease) && isNonBlank(job.elementInstanceKey);
+  return isNonBlank(job.leaseToken) && isNonBlank(job.elementInstanceKey);
 }
 
 /** Best-effort provider inference from a model identifier (openai/anthropic/…). */
@@ -145,7 +146,7 @@ function contentForResult(result) {
  *
  * @param {object} opts
  * @param {object} opts.camunda   Host SDK client (createAgentInstance/updateAgentInstance).
- * @param {object} opts.job       The activated job (jobKey/jobLease/elementInstanceKey/elementId).
+ * @param {object} opts.job       The activated job (jobKey/leaseToken/elementInstanceKey/elementId).
  * @param {object} [opts.profile] The worker profile (model/provider seed the definition).
  * @param {object} [opts.envelope] The normalized task envelope (task.prompt → systemPrompt).
  * @param {object} [opts.logger]  Output-mode-aware logger (warn/info/debug).
@@ -166,7 +167,12 @@ export function createAgentInstanceProducer(opts = {}) {
   const classify = typeof sessionAcp?.classifyUpdate === 'function' ? sessionAcp.classifyUpdate : null;
 
   const jobKey = job?.jobKey != null ? String(job.jobKey) : '';
-  const jobLease = job?.jobLease != null ? String(job.jobLease) : '';
+  // The activation lease is carried on the job as `leaseToken` (Camunda v10
+  // ActivatedJobResult). It is submitted BACK to createAgentInstance/updateAgentInstance
+  // as the request-body field `jobLease` (agent-instances.yaml) — the same opaque token,
+  // named differently on the two sides of the contract. One internal name here; the
+  // translation to `jobLease` happens only at each SDK call below.
+  const leaseToken = job?.leaseToken != null ? String(job.leaseToken) : '';
   const elementInstanceKey = job?.elementInstanceKey != null ? String(job.elementInstanceKey) : '';
   const elementId = job?.elementId != null ? String(job.elementId) : null;
 
@@ -212,7 +218,7 @@ export function createAgentInstanceProducer(opts = {}) {
         agentInstanceKey,
         elementInstanceKey,
         jobKey,
-        jobLease,
+        jobLease: leaseToken,
         history: [turn],
       };
       if (status) req.status = status;
@@ -321,7 +327,7 @@ export function createAgentInstanceProducer(opts = {}) {
         const res = await camunda[SDK_CREATE]({
           elementInstanceKey,
           jobKey,
-          jobLease,
+          jobLease: leaseToken,
           history: [configTurn],
         });
         agentInstanceKey =
@@ -425,7 +431,7 @@ export function createAgentInstanceProducer(opts = {}) {
             agentInstanceKey,
             elementInstanceKey,
             jobKey,
-            jobLease,
+            jobLease: leaseToken,
             status: 'COMPLETED',
           });
         });

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

package/supervisor-engine.mjs

@@ -141,17 +141,22 @@ function mapJob(raw) {
   const pik = raw.processInstanceKey;
   if (pik !== undefined && pik !== null) job.processInstanceKey = String(pik);
   // Engine-native AgentInstance attribution (issue #194): the element instance the
-  // AgentInstance correlates on, the element id, and the opaque per-activation
-  // `jobLease` token that lease-gates a `createAgentInstance` for an `external`
-  // agent job (nanobpmn #1099/#1106). These ride opaquely to the runner exactly as
-  // the SDK activation surfaces them; absent for ordinary (non-agent) jobs, in which
-  // case the durable-transcript producer stays inert.
+  // AgentInstance correlates on, the element id, and the opaque per-activation lease
+  // token that lease-gates a `createAgentInstance` for an `external` agent job
+  // (nanobpmn #1099/#1106). The Camunda v10 REST contract carries the lease on the
+  // ACTIVATED JOB as `leaseToken` (jobs.yaml ActivatedJobResult) — NOT `jobLease`,
+  // which is the field name only on the createAgentInstance/updateAgentInstance REQUEST
+  // body (agent-instances.yaml). The harness carries ONE internal name — `leaseToken` —
+  // all the way through, and translates to `jobLease` only at that SDK body (see
+  // agent-instance.mjs). These ride opaquely to the runner exactly as the SDK activation
+  // surfaces them; absent for ordinary (non-agent) jobs, in which case the
+  // durable-transcript producer stays inert.
   const eik = raw.elementInstanceKey;
   if (eik !== undefined && eik !== null) job.elementInstanceKey = String(eik);
   const eid = raw.elementId;
   if (eid !== undefined && eid !== null) job.elementId = String(eid);
-  const lease = raw.jobLease;
-  if (lease !== undefined && lease !== null) job.jobLease = String(lease);
+  const lease = raw.leaseToken;
+  if (lease !== undefined && lease !== null) job.leaseToken = String(lease);
   return job;
 }
 
@@ -254,6 +259,12 @@ export function createRawEngineClient(opts = {}) {
         maxJobsToActivate: req.maxJobsToActivate,
         timeout: req.lockMs,
         requestTimeout: req.requestTimeoutMs,
+        // Request a per-activation lease (Camunda v10 `withLease`): the engine then
+        // stamps each activated job with a distinct opaque `leaseToken`
+        // (ActivatedJobResult.leaseToken) which lease-gates the external agent job's
+        // `createAgentInstance` (nanobpmn #1099/#1106). Without it the token is absent
+        // and the durable AgentInstance producer stays inert.
+        withLease: true,
       };
       // Give the abort budget slack over the server long-poll so we don't cancel
       // a still-valid long-poll a hair before the server would answer it.