c8ctl-plugin-nano 1.59.0 → 1.60.0

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/c8ctl-plugin.js

@@ -6373,16 +6373,25 @@ function normalizeProjectApps(projects) {
 }
 
 /**
- * Probe whether an embedded app's `/agentic` endpoint answers a WebSocket
- * upgrade. Connects to `ws://<host>:<port>/agentic?token=…` (host defaults to
+ * Probe whether a `/agentic` endpoint answers a WebSocket upgrade. Connects to
+ * `ws(s)://<host>:<port><pathPrefix>/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`. Self-cleaning — the probe socket is closed as soon as the
- * outcome is known. Never throws.
+ * connection, a `404`/`501`, or a timeout all 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 agentic port (`appUi.port`)
- * @param {{ host?: string, token?: string, WebSocketImpl?: Function, timeoutMs?: number }} [opts]
+ * `pathPrefix` targets either the app's own port (empty prefix → `/agentic`) or
+ * the engine's console **app-view WebSocket tunnel** (engine #1054), where the
+ * prefix is `/console/app-view/<project>` so the channel rides the single engine
+ * port instead of the app's direct port (see {@link discoverAgenticHubs}).
+ *
+ * `secure` selects the WS scheme: `false` → `ws://` (plain), `true` → `wss://`.
+ * The tunnel leg rides the engine's own port, so an `https://` engine base
+ * requires a `wss://` upgrade — probing it with plain `ws://` would spuriously
+ * fail the tunnel and force the direct-port fallback (see {@link discoverAgenticHubs}).
+ *
+ * @param {number|string} port the port the WS connects to (app port, or engine port for the tunnel)
+ * @param {{ host?: string, token?: string, WebSocketImpl?: Function, timeoutMs?: number, pathPrefix?: string, secure?: boolean }} [opts]
  * @returns {Promise<boolean>}
  */
 function probeAgenticChannel(port, {
@@ -6390,9 +6399,12 @@ function probeAgenticChannel(port, {
   token = LOCAL_AGENTIC_TOKEN,
   WebSocketImpl = globalThis.WebSocket,
   timeoutMs = AGENTIC_DISCOVERY_TIMEOUT_MS,
+  pathPrefix = '',
+  secure = false,
 } = {}) {
   if (typeof WebSocketImpl !== 'function') return Promise.resolve(false);
-  const url = `ws://${wsHostPart(host)}:${port}/agentic?token=${encodeURIComponent(token)}`;
+  const wsScheme = secure ? 'wss' : 'ws';
+  const url = `${wsScheme}://${wsHostPart(host)}:${port}${pathPrefix}/agentic?token=${encodeURIComponent(token)}`;
   return new Promise((resolve) => {
     let done = false;
     let ws;
@@ -6499,8 +6511,8 @@ async function resolveProbeCandidates(host, { lookupImpl = dnsLookup } = {}) {
  * slow-to-open one can't stall the whole probe: a fast later candidate still
  * wins. Each per-host probe is bounded by `timeoutMs`. A single candidate skips
  * the racing machinery entirely (unchanged legacy path).
- * @param {number} port
- * @param {{ hosts?: string[], token?: string, timeoutMs?: number, wsProbe?: Function, staggerMs?: number }} [opts]
+ * @param {number|string} port
+ * @param {{ hosts?: string[], token?: string, timeoutMs?: number, wsProbe?: Function, staggerMs?: number, pathPrefix?: string, secure?: boolean }} [opts]
  * @returns {Promise<string|null>} the winning host, or null
  */
 async function raceProbeCandidates(port, {
@@ -6509,12 +6521,14 @@ async function raceProbeCandidates(port, {
   timeoutMs = AGENTIC_DISCOVERY_TIMEOUT_MS,
   wsProbe = probeAgenticChannel,
   staggerMs = 250,
+  pathPrefix = '',
+  secure = false,
 } = {}) {
   const list = Array.isArray(hosts) ? hosts.filter(Boolean) : [];
   if (list.length === 0) return null;
   if (list.length === 1) {
     try {
-      return (await wsProbe(port, { host: list[0], token, timeoutMs })) ? list[0] : null;
+      return (await wsProbe(port, { host: list[0], token, timeoutMs, pathPrefix, secure })) ? list[0] : null;
     } catch {
       return null;
     }
@@ -6531,7 +6545,7 @@ async function raceProbeCandidates(port, {
     };
     const start = (host) => {
       Promise.resolve()
-        .then(() => wsProbe(port, { host, token, timeoutMs }))
+        .then(() => wsProbe(port, { host, token, timeoutMs, pathPrefix, secure }))
         .catch(() => false)
         .then((ok) => {
           if (ok) done(host);
@@ -6547,23 +6561,32 @@ async function raceProbeCandidates(port, {
 
 /**
  * Auto-discover the embedded nwf agentic hub(s) reachable from an engine base
- * 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). Gives the projects fetch and each WS probe
- * INDEPENDENT deadlines (#133) so a slow fetch can't starve the probe, prefers a
- * routable address over a link-local `fe80::` one (Happy-Eyeballs), and is
- * fail-open: any error — not a nano engine (Camunda), network failure, malformed
- * body, or a timeout — degrades to `[]` so the worker's real job is never
- * blocked.
+ * URL (#75, #96, #97). 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. 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).
+ *
+ * **Single-port hardening (#97, engine #1054):** each app is probed **tunnel-first** —
+ * `ws://<engineHost>:<enginePort>/console/app-view/<project>/agentic`, the console
+ * app-view WebSocket tunnel on the engine's *own* port (the same host:port the
+ * worker already reached for the projects read). A surviving tunnel hub is marked
+ * `via:'tunnel'` and needs only the engine port to be reachable — the app's direct
+ * port need not be LAN-open. If the tunnel probe fails (an engine that predates
+ * #1054 refuses the `/agentic` WS upgrade with `501`), it falls back to probing the
+ * app's **direct** port and marks the hub `via:'direct'` (unchanged #96 behaviour).
+ *
+ * Gives the projects fetch and each WS probe INDEPENDENT deadlines (#133) so a slow
+ * fetch can't starve the probe, prefers a routable address over a link-local `fe80::`
+ * one (Happy-Eyeballs), and is fail-open: any error — not a nano engine (Camunda),
+ * network failure, malformed body, or a timeout — degrades to `[]` so the worker's
+ * real job is never blocked.
  *
  * @param {string} engineBaseUrl the engine base URL (e.g. `http://merlin.local:8080`)
  * @param {{ token?: string, fetchImpl?: Function, wsProbe?: Function, lookupImpl?: Function, timeoutMs?: number, fetchTimeoutMs?: number, probeTimeoutMs?: number }} [opts]
- * @returns {Promise<Array<{ project: string, port: number, label?: string, host: string }>>}
+ * @returns {Promise<Array<{ project: string, port: number, label?: string, host: string, via: 'tunnel'|'direct', enginePort?: string, scheme?: string }>>}
  */
 async function discoverAgenticHubs(engineBaseUrl, {
   token = LOCAL_AGENTIC_TOKEN,
@@ -6586,12 +6609,15 @@ async function discoverAgenticHubs(engineBaseUrl, {
   // 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;
+  let engineUrl;
   try {
-    host = new URL(base).hostname;
+    engineUrl = new URL(base);
   } catch {
     return [];
   }
+  const host = engineUrl.hostname;
+  const engineScheme = engineUrl.protocol; // 'http:' | 'https:'
+  const enginePort = engineUrl.port || (engineScheme === 'https:' ? '443' : '80');
   const probeHost = isLoopbackHost(host) ? '127.0.0.1' : host;
   // (C) Decoupled budgets (#133): the projects fetch and each WS probe get their
   // OWN independent deadline. Previously they shared one 2s budget, so a fetch
@@ -6623,13 +6649,32 @@ async function discoverAgenticHubs(engineBaseUrl, {
   const candidates = await resolveProbeCandidates(probeHost, { lookupImpl });
   const settled = await Promise.all(apps.map(async (app) => {
     try {
-      const winner = await raceProbeCandidates(app.port, {
+      // Tunnel-first (#97): confirm the channel over the console app-view WS
+      // tunnel on the ENGINE port — the same host:port the projects read just
+      // used — so the app's direct port need not be reachable. A pre-#1054
+      // engine 501s the upgrade and the probe fails; we then fall back to the
+      // app's direct port (unchanged #96 path).
+      const tunnelHost = await raceProbeCandidates(enginePort, {
+        hosts: candidates,
+        token,
+        timeoutMs: probeTimeoutMs,
+        wsProbe,
+        pathPrefix: `/console/app-view/${encodeURIComponent(app.project)}`,
+        // The tunnel rides the engine's own port, so match its TLS: an
+        // `https://` engine base upgrades over `wss://`, not `ws://` (else the
+        // tunnel probe spuriously fails and we drop to the direct port).
+        secure: engineScheme === 'https:',
+      });
+      if (tunnelHost) {
+        return { ...app, host: tunnelHost, via: 'tunnel', enginePort, scheme: engineScheme };
+      }
+      const directHost = await raceProbeCandidates(app.port, {
         hosts: candidates,
         token,
         timeoutMs: probeTimeoutMs,
         wsProbe,
       });
-      return winner ? { ...app, host: winner } : null;
+      return directHost ? { ...app, host: directHost, via: 'direct' } : null;
     } catch {
       return null;
     }
@@ -6646,8 +6691,11 @@ 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 `ws://<engineHost>:<port>/agentic` (loopback for a
- *     local engine, the engine's LAN host for a remote one).
+ *     single discovered app: the console app-view WS tunnel on the engine port
+ *     (`<engineHost>:<enginePort>/console/app-view/<project>/agentic`, `via:'tunnel'`,
+ *     #97) when available, else the direct app port
+ *     (`ws://<engineHost>:<appPort>/agentic`, `via:'direct'`, #96) — 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,
@@ -6681,10 +6729,18 @@ async function resolveAgenticTarget({ camunda, cache, ...opts } = {}) {
   } catch { /* keep the loopback default */ }
 
   if (hubs.length === 1) {
-    const { project, port, host } = hubs[0];
+    const { project, port, host, via, enginePort, scheme } = hubs[0];
+    // A tunnel hub rides the console app-view WS bridge on the engine's own port
+    // (#97): `<scheme>//<engineHost>:<enginePort>/console/app-view/<project>`, to
+    // which `buildAgenticUrl` appends `/agentic`. A direct hub keeps the #96
+    // `http://<host>:<appPort>` form. `discovered.port` stays the app's advertised
+    // port either way (the hub identity); the local `via` records the route taken.
+    const url = via === 'tunnel'
+      ? `${scheme}//${wsHostPart(host)}:${enginePort}/console/app-view/${encodeURIComponent(project)}`
+      : `http://${wsHostPart(host)}:${port}`;
     const config = {
       ...base,
-      url: `http://${wsHostPart(host)}:${port}`,
+      url,
       discovered: { project, port, host },
     };
     // Cache the known-good hub so a later blip self-heals from cache (#133-C).

package/package.json

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

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.