c8ctl-plugin-nano 1.52.0 → 1.53.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.52.0",
+  "version": "1.53.1",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -39,7 +39,7 @@
     "build:supervisor": "node supervisor/build.mjs",
     "vendor:effect": "node scripts/vendor-effect.mjs",
     "test:supervisor": "node --experimental-strip-types --test supervisor/test/*.test.ts",
-    "test": "node --check c8ctl-plugin.js && npm run typecheck:supervisor && npm run build:supervisor && npm run test:supervisor && node --test",
+    "test": "node --check c8ctl-plugin.js && npm run typecheck:supervisor && npm run build:supervisor && npm run test:supervisor && node --test --test-timeout=120000 --test-force-exit",
     "prepublishOnly": "npm run typecheck:supervisor && npm run build:supervisor"
   },
   "license": "MIT",
@@ -60,7 +60,7 @@
     "@semantic-release/github": "^12.0.6",
     "@types/node": "^22.20.1",
     "effect": "4.0.0-rc.112",
-    "esbuild": "^0.24.2",
+    "esbuild": "^0.28.0",
     "semantic-release": "^25.0.3",
     "typescript": "^5.9.3"
   },
@@ -70,12 +70,12 @@
   },
   "optionalDependencies": {
     "node-pty": "^1.0.0",
-    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.52.0",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.52.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.52.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.52.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.52.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.52.0",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.52.0"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.53.1",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.53.1",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.53.1",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.53.1",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.53.1",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.53.1",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.53.1"
   }
 }

package/supervisor-engine.mjs

@@ -4,19 +4,45 @@
  * (issue #156).
  *
  * #154's activation loop deliberately does NOT use the `@camunda8` SDK job
- * worker: the SDK models one poller per type with `maxJobsToActivate =
- * maxParallel − active` and structurally cannot express "global capacity S
- * shared across K types with per-type gating". The supervisor rolls its own race
- * over a NARROW two-call engine surface instead:
+ * worker (`createJobWorker`): that convenience loop models one self-driving
+ * poller per type with `maxJobsToActivate = maxParallel − active` and cannot
+ * express "global capacity S shared across K types with per-type gating". The
+ * supervisor rolls its own race over a NARROW single-shot engine surface — but
+ * every call on that surface still PREFERS the injected `camunda` SDK client's
+ * typed method, hand-rolling REST only as a standalone/wire-test fallback:
  *
- *   - `activate` → `POST <base>/v2/jobs/activation` for exactly ONE type, one
- *     long-poll, resolving 0..`maxJobsToActivate` jobs (0 == the long-poll
- *     expired empty). `timeout` is the SHORT initial lock (the crash-safety net);
- *     `requestTimeout` is how long the call blocks server-side.
- *   - `extendLock` → `PATCH <base>/v2/jobs/{jobKey}/timeout` with `{ timeout }`.
+ *   - `activate` → the SDK's typed `activateJobs` (operationId `activateJobs` →
+ *     `POST <base>/jobs/activation`) for exactly ONE type, one long-poll,
+ *     resolving 0..`maxJobsToActivate` jobs (0 == the long-poll expired empty).
+ *     `activateJobs` is the SINGLE-SHOT primitive `createJobWorker` is built on;
+ *     its input body (`JobActivationRequest`) is 1:1 with ours and its returned
+ *     `CancelablePromise.cancel()` aborts the in-flight long-poll, so a losing
+ *     `raceAll` fiber interrupts its poll at once. Falls back to the SAME call
+ *     issued raw via `fetchImpl` when no SDK client is injected. `timeout` is the
+ *     SHORT initial lock (the crash-safety net); `requestTimeout` is how long the
+ *     call blocks server-side.
+ *   - `extendLock` → the SDK's typed `updateJob` (operationId `updateJob`,
+ *     `PATCH <base>/jobs/{jobKey}` with `{ changeset: { timeout } }`) when a
+ *     `camunda` SDK client is injected, else the SAME call issued raw via
+ *     `fetchImpl` (so the module stays wire-testable without a live client).
  *     The C8 contract SETs the lock to `ms` from now (a duration-from-now), which
  *     is exactly the supervisor's "extend the winner to the recovery window, then
- *     heartbeat" model — set, not accumulate.
+ *     heartbeat" model — set, not accumulate. NOTE: there is no
+ *     `/jobs/{jobKey}/timeout` sub-route — that was a drifted URL that 404s on the
+ *     engine; the timeout is a `changeset` field on the job resource itself.
+ *   - `complete` / `fail` → the SDK's typed `completeJob` / `failJob` (operationIds
+ *     `completeJob` → `POST <base>/jobs/{jobKey}/completion`, `failJob` →
+ *     `POST <base>/jobs/{jobKey}/failure`) when a `camunda` SDK client is injected,
+ *     else the SAME calls issued raw via `fetchImpl` — the settle surface the
+ *     supervisor's JobRunner uses once an agent finishes.
+ *
+ * Every method on this surface (`activate`→`activateJobs`,
+ * `extendLock`→`updateJob`, `complete`→`completeJob`, `fail`→`failJob`) PREFERS
+ * the injected `camunda` client and only hand-rolls the REST call as a
+ * standalone/wire-test fallback; there is no sanctioned raw-only method. This
+ * convention is pinned by `supervisor-engine-sdk-preference.test.mjs` — a new
+ * engine method that hits a raw route must either prefer an SDK method or be
+ * added to that test's raw-only allowlist with a reason.
  *
  * This module is the raw-JS analogue of `agentic-endpoint.mjs`: it is Effect-free
  * (the supervisor's `makeEngineClient` lift wraps each method into the Effect
@@ -136,7 +162,8 @@ async function readErrorBody(res) {
  * @param {Record<string,string>|(() => (Record<string,string>|Promise<Record<string,string>>))} [opts.authHeaders] Ready-made auth header map, OR a resolver invoked per request (so rotating SDK auth — e.g. an OAuth bearer that refreshes — is re-derived each call rather than frozen). Wins over `token`.
  * @param {typeof fetch} [opts.fetchImpl] Injected `fetch` (defaults to the global; overridden in tests).
  * @param {number} [opts.requestTimeoutSlackMs] Extra ms added to a call's abort budget over its server long-poll (default 5000).
- * @returns {{ activate(req: ActivateRequest): Promise<ReadonlyArray<ActivatedJob>>, extendLock(jobKey: string, ms: number): Promise<void>, complete(jobKey: string, variables?: object): Promise<void>, fail(jobKey: string, opts?: { retries?: number, errorMessage?: string, retryBackOff?: number, variables?: object }): Promise<void> }}
+ * @param {{ activateJobs?: (input: { type: string, worker?: string, maxJobsToActivate: number, timeout: number, requestTimeout?: number }) => (Promise<{ jobs?: object[] }> & { cancel?: () => void }), updateJob?: (req: { jobKey: string, changeset: { timeout: number } }) => Promise<unknown>, completeJob?: (req: { jobKey: string, variables?: object }) => Promise<unknown>, failJob?: (req: { jobKey: string, retries?: number, errorMessage?: string, retryBackOff?: number, variables?: object }) => Promise<unknown> }} [opts.camunda] Optional Camunda SDK client. When present, each engine method prefers its typed SDK method over the raw fetch fallback: `activate`→`activateJobs` (`POST /v2/jobs/activation`, cancelled via the returned `CancelablePromise.cancel()`), `extendLock`→`updateJob` (`PATCH /v2/jobs/{jobKey}` `{ changeset: { timeout } }`), `complete`→`completeJob` (`POST /v2/jobs/{jobKey}/completion`), `fail`→`failJob` (`POST /v2/jobs/{jobKey}/failure`).
+ * @returns {{ activate(req: ActivateRequest, signal?: AbortSignal): Promise<ReadonlyArray<ActivatedJob>>, extendLock(jobKey: string, ms: number): Promise<void>, complete(jobKey: string, variables?: object): Promise<void>, fail(jobKey: string, opts?: { retries?: number, errorMessage?: string, retryBackOff?: number, variables?: object }): Promise<void> }}
  */
 export function createRawEngineClient(opts = {}) {
   const {
@@ -146,6 +173,7 @@ export function createRawEngineClient(opts = {}) {
     authHeaders,
     fetchImpl = fetch,
     requestTimeoutSlackMs = 5_000,
+    camunda,
   } = opts;
   if (typeof fetchImpl !== "function") {
     throw new TypeError("createRawEngineClient: `fetchImpl` must be a function (global fetch or an injected fake)");
@@ -172,34 +200,78 @@ export function createRawEngineClient(opts = {}) {
 
   /**
    * Issue one call with an abort budget. `abortAfterMs <= 0` means no timer
-   * (the caller relies purely on the server long-poll / connection).
+   * (the caller relies purely on the server long-poll / connection). An optional
+   * `extSignal` (e.g. the Effect fiber's interruption signal for the `activate`
+   * long-poll) also aborts the in-flight fetch, so a losing `raceAll` fiber stops
+   * its poll immediately instead of leaking it until the budget timer fires.
    */
-  async function call(url, init, abortAfterMs) {
+  async function call(url, init, abortAfterMs, extSignal) {
     const controller = new AbortController();
     const timer = abortAfterMs > 0 ? setTimeout(() => controller.abort(), abortAfterMs) : null;
+    const onExtAbort = () => controller.abort();
+    if (extSignal) {
+      if (extSignal.aborted) controller.abort();
+      else extSignal.addEventListener("abort", onExtAbort, { once: true });
+    }
     try {
       const headers = await resolveHeaders();
       return await fetchImpl(url, { ...init, headers, signal: controller.signal });
     } finally {
       if (timer) clearTimeout(timer);
+      if (extSignal) extSignal.removeEventListener("abort", onExtAbort);
     }
   }
 
   return {
-    async activate(req) {
-      const body = JSON.stringify({
+    async activate(req, signal) {
+      // Prefer the SDK's typed `activateJobs` (operationId `activateJobs` →
+      // `POST /v2/jobs/activation`) so the ONE-type long-poll tracks the engine
+      // contract instead of a hand-rolled body/URL. The SDK's `createJobWorker`
+      // convenience loop can't express the supervisor's global-capacity single
+      // race — but `activateJobs` is the SAME single-shot primitive that loop is
+      // built on, and its input body (`JobActivationRequest`) is 1:1 with ours.
+      // Its `CancelablePromise.cancel()` aborts the in-flight long-poll, so a
+      // losing `raceAll` fiber (interruption → `signal.aborted`) stops its poll
+      // immediately. Fall back to the SAME call issued raw via `fetchImpl` when no
+      // SDK client is injected (keeps this module wire-testable and standalone).
+      // `timeout` is the SHORT initial lock applied to any returned job;
+      // `requestTimeout` is the server-side long-poll window.
+      const input = {
         type: req.type,
         worker,
         maxJobsToActivate: req.maxJobsToActivate,
-        // `timeout` is the SHORT initial lock applied to any returned job.
         timeout: req.lockMs,
-        // `requestTimeout` is the server-side long-poll window.
         requestTimeout: req.requestTimeoutMs,
-      });
+      };
       // 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.
       const abortAfterMs = req.requestTimeoutMs > 0 ? req.requestTimeoutMs + requestTimeoutSlackMs : 0;
-      const res = await call(`${base}/jobs/activation`, { method: "POST", body }, abortAfterMs);
+      if (camunda && typeof camunda.activateJobs === "function") {
+        const p = camunda.activateJobs(input);
+        // Wire BOTH cancellation sources onto the CancelablePromise: the external
+        // interruption signal (fiber lost the race) and the client-side abort
+        // budget (a hung connection past the server window). `cancel()` aborts the
+        // SDK's own AbortController, ending the long-poll.
+        const cancel = typeof p?.cancel === "function" ? () => p.cancel() : () => {};
+        const timer = abortAfterMs > 0 ? setTimeout(cancel, abortAfterMs) : null;
+        const onExtAbort = () => cancel();
+        if (signal) {
+          if (signal.aborted) cancel();
+          else signal.addEventListener("abort", onExtAbort, { once: true });
+        }
+        try {
+          const result = await p;
+          const jobs = Array.isArray(result?.jobs) ? result.jobs : Array.isArray(result) ? result : [];
+          return jobs.map(mapJob);
+        } catch (err) {
+          throw new Error(`activate ${req.type}: SDK activateJobs failed: ${err?.message ?? err}`, { cause: err });
+        } finally {
+          if (timer) clearTimeout(timer);
+          if (signal) signal.removeEventListener("abort", onExtAbort);
+        }
+      }
+      const body = JSON.stringify(input);
+      const res = await call(`${base}/jobs/activation`, { method: "POST", body }, abortAfterMs, signal);
       if (!res || !res.ok) {
         const status = res ? res.status : "?";
         throw new Error(`activate ${req.type}: HTTP ${status} from ${base}/jobs/activation${res ? await readErrorBody(res) : ""}`);
@@ -210,8 +282,21 @@ export function createRawEngineClient(opts = {}) {
     },
 
     async extendLock(jobKey, ms) {
-      const url = `${base}/jobs/${encodeURIComponent(jobKey)}/timeout`;
-      const res = await call(url, { method: "PATCH", body: JSON.stringify({ timeout: ms }) }, 15_000);
+      // Prefer the SDK's typed `updateJob` (operationId `updateJob` →
+      // `PATCH /v2/jobs/{jobKey}` with `{ changeset: { timeout } }`) so the lock
+      // extension tracks the engine contract instead of a hand-rolled URL. Fall
+      // back to the SAME call issued raw when no SDK client is injected (keeps
+      // this module wire-testable and usable standalone).
+      if (camunda && typeof camunda.updateJob === "function") {
+        try {
+          await camunda.updateJob({ changeset: { timeout: ms }, jobKey: String(jobKey) });
+          return;
+        } catch (err) {
+          throw new Error(`extendLock ${jobKey}: SDK updateJob failed: ${err?.message ?? err}`, { cause: err });
+        }
+      }
+      const url = `${base}/jobs/${encodeURIComponent(jobKey)}`;
+      const res = await call(url, { method: "PATCH", body: JSON.stringify({ changeset: { timeout: ms } }) }, 15_000);
       if (!res || !res.ok) {
         const status = res ? res.status : "?";
         throw new Error(`extendLock ${jobKey}: HTTP ${status} from ${url}${res ? await readErrorBody(res) : ""}`);
@@ -220,21 +305,33 @@ export function createRawEngineClient(opts = {}) {
 
     // ---- Job completion / failure ------------------------------------------
     // The narrow surface the supervisor's JobRunner needs to SETTLE a job once
-    // its agent harness finishes — the direct-REST analogue of the SDK job
-    // object's `job.complete()` / `job.fail()` (which the per-type SDK poller
-    // path in `workAgent` still uses). A plain `ActivatedJob` (jobKey/type/
-    // variables) carries no settle methods, so the supervisor path completes via
-    // these calls instead. Effect-free and wire-testable like `activate` /
-    // `extendLock`; a non-2xx (e.g. a 409 when the lock already lapsed and the
-    // job was reclaimed) surfaces as a rejected promise for the port to map.
+    // its agent harness finishes — the analogue of the SDK job object's
+    // `job.complete()` / `job.fail()` (which the per-type SDK poller path in
+    // `workAgent` still uses). A plain `ActivatedJob` (jobKey/type/variables)
+    // carries no settle methods, so the supervisor path settles via these calls.
+    // Like `extendLock`, each PREFERS the injected `camunda` SDK client's typed
+    // method (`completeJob` / `failJob`) and only hand-rolls the REST call as a
+    // standalone/wire-test fallback. Effect-free and wire-testable; a non-2xx /
+    // SDK rejection (e.g. a 409 when the lock lapsed and the job was reclaimed)
+    // surfaces as a rejected promise for the port to map.
 
     async complete(jobKey, variables) {
-      // `POST <base>/v2/jobs/{jobKey}/completion` with `{ variables }` — the
+      // Prefer the SDK's typed `completeJob` (operationId `completeJob` →
+      // `POST /v2/jobs/{jobKey}/completion` with `{ variables }`) when a `camunda`
+      // SDK client is injected, else the SAME call issued raw via `fetchImpl`. The
       // result-variable map the model produced is merged onto the process
       // instance. C8 v2 answers 204 No Content on success.
+      const vars = isPlainObjectMap(variables) ? { variables } : {};
+      if (camunda && typeof camunda.completeJob === "function") {
+        try {
+          await camunda.completeJob({ jobKey: String(jobKey), ...vars });
+          return;
+        } catch (err) {
+          throw new Error(`complete ${jobKey}: SDK completeJob failed: ${err?.message ?? err}`, { cause: err });
+        }
+      }
       const url = `${base}/jobs/${encodeURIComponent(jobKey)}/completion`;
-      const body = JSON.stringify(isPlainObjectMap(variables) ? { variables } : {});
-      const res = await call(url, { method: "POST", body }, 15_000);
+      const res = await call(url, { method: "POST", body: JSON.stringify(vars) }, 15_000);
       if (!res || !res.ok) {
         const status = res ? res.status : "?";
         throw new Error(`complete ${jobKey}: HTTP ${status} from ${url}${res ? await readErrorBody(res) : ""}`);
@@ -246,19 +343,30 @@ export function createRawEngineClient(opts = {}) {
       // null-safe `variables`), so a caller passing `null` never trips the
       // signature-destructure TypeError.
       const { retries = 0, errorMessage, retryBackOff, variables } = opts || {};
-      // `POST <base>/v2/jobs/{jobKey}/failure` with `{ retries, errorMessage?,
-      // retryBackOff?, variables? }` — `retries > 0` re-queues for another
-      // attempt, `retries === 0` raises an incident. Optional fields are omitted
-      // when absent so the engine applies its own defaults. C8 v2 answers 204.
-      const url = `${base}/jobs/${encodeURIComponent(jobKey)}/failure`;
       // Normalize retries to a non-negative integer (mirrors `mapJob`), so a
-      // string/float/negative never reaches the engine as an invalid count.
+      // string/float/negative never reaches the engine (or SDK) as an invalid
+      // count. `retries > 0` re-queues for another attempt, `retries === 0`
+      // raises an incident. Optional fields are omitted when absent so the engine
+      // applies its own defaults.
       const nRetries = Number(retries);
-      const payload = { retries: Number.isFinite(nRetries) ? Math.max(0, Math.trunc(nRetries)) : 0 };
-      if (errorMessage !== undefined && errorMessage !== null) payload.errorMessage = String(errorMessage);
-      if (Number.isFinite(retryBackOff) && retryBackOff > 0) payload.retryBackOff = retryBackOff;
-      if (isPlainObjectMap(variables)) payload.variables = variables;
-      const res = await call(url, { method: "POST", body: JSON.stringify(payload) }, 15_000);
+      const normRetries = Number.isFinite(nRetries) ? Math.max(0, Math.trunc(nRetries)) : 0;
+      const extra = {};
+      if (errorMessage !== undefined && errorMessage !== null) extra.errorMessage = String(errorMessage);
+      if (Number.isFinite(retryBackOff) && retryBackOff > 0) extra.retryBackOff = retryBackOff;
+      if (isPlainObjectMap(variables)) extra.variables = variables;
+      // Prefer the SDK's typed `failJob` (operationId `failJob` →
+      // `POST /v2/jobs/{jobKey}/failure`) when a `camunda` SDK client is injected,
+      // else the SAME call issued raw via `fetchImpl`. C8 v2 answers 204.
+      if (camunda && typeof camunda.failJob === "function") {
+        try {
+          await camunda.failJob({ jobKey: String(jobKey), retries: normRetries, ...extra });
+          return;
+        } catch (err) {
+          throw new Error(`fail ${jobKey}: SDK failJob failed: ${err?.message ?? err}`, { cause: err });
+        }
+      }
+      const url = `${base}/jobs/${encodeURIComponent(jobKey)}/failure`;
+      const res = await call(url, { method: "POST", body: JSON.stringify({ retries: normRetries, ...extra }) }, 15_000);
       if (!res || !res.ok) {
         const status = res ? res.status : "?";
         throw new Error(`fail ${jobKey}: HTTP ${status} from ${url}${res ? await readErrorBody(res) : ""}`);