@nanobpm/nano-workforce 0.114.1 → 0.115.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.115.0](https://github.com/nanobpm/nano-workforce/compare/v0.114.1...v0.115.0) (2026-08-20)
+
+
+### Features
+
+* **engine:** startup preflight + canonical engine address resolution ([#391](https://github.com/nanobpm/nano-workforce/issues/391)) ([#404](https://github.com/nanobpm/nano-workforce/issues/404)) ([16fcb71](https://github.com/nanobpm/nano-workforce/commit/16fcb711f190341f03fd84914fa66c1ee704b78c)), closes [Magikcraft/nano-bpm#940](https://github.com/Magikcraft/nano-bpm/issues/940)
+
 ## [0.114.1](https://github.com/nanobpm/nano-workforce/compare/v0.114.0...v0.114.1) (2026-08-20)
 
 

package/README.md

@@ -252,7 +252,7 @@ active epic already targets the same custom base. See
 |---|---|---|
 | `PR_REVIEW_PORT` | `3000` | app HTTP port |
 | `NANO_APP_DB_URL` | `file:./app.db` | sqlite datasource |
-| `NANOBPMN_BASE_URL` | `http://localhost:8080` | engine base URL (or set `CAMUNDA_REST_ADDRESS` to the `/v2` REST address directly) |
+| `NANOBPMN_BASE_URL` | `http://localhost:8080` | engine base URL (or set `CAMUNDA_REST_ADDRESS` to the `/v2` REST address directly). See [Engine address & the startup preflight](#engine-address--the-startup-preflight) |
 | `GITHUB_TOKEN` | — | token for the review poller / merge (or use the host `gh` CLI) |
 | `NANO_PR_GITHUB_TRANSPORT` | `auto` | how the poller reads GitHub: `gh` (host CLI), `token` (`GITHUB_TOKEN` over HTTP), or `auto` |
 | `NANO_PR_POLL_MS` | `60000` | review-ready poll interval |
@@ -267,6 +267,49 @@ active epic already targets the same custom base. See
 | `NANO_WORKFORCE_BASE_URL` | `http://localhost:3000` | externally-reachable base URL for the capability hooks (`/app/api/hooks/*`). Must resolve from **wherever the agent runs** — set it to the app's LAN address (or console-proxy URL) for a remote fleet. See [Fleet networking](#fleet-networking-remote-workers) |
 | `NANO_AGENTIC_SECRET` | — | enables **secure mode** for the agentic visibility channel (`/agentic`): every peer must present the **same** `NANO_AGENTIC_SECRET` value (set the identical env var on the server and every worker box — Tab A → Slot A). Unset = on-by-default **LOCAL mode** — the well-known token is honoured from **any origin** (open on the trusted LAN, matching the engine's posture); exposure is governed by the server bind address, not a shared secret. Also accepts `NANO_PR_WEBHOOK_SECRET` |
 
+### Engine address & the startup preflight
+
+The app talks to one engine over the Camunda 8 REST API. The REST address is
+resolved with a fixed precedence — set **one** of:
+
+1. **`CAMUNDA_REST_ADDRESS`** — used verbatim (it already points at the `/v2`
+   REST address, e.g. `http://engine.example:8080/v2`). **Wins** if set.
+2. **`NANOBPMN_BASE_URL`** — the engine *base*; the app appends `/v2`
+   (e.g. `http://localhost:7000` → `http://localhost:7000/v2`).
+3. Neither set → the base defaults to **`http://localhost:8080`**.
+
+At boot the app **echoes the resolved address and which input it came from**,
+then probes `/v2/topology` and announces **which engine answered** — so a
+misconfigured address is obvious immediately instead of surfacing later as a
+cryptic mid-run engine error:
+
+```
+Engine address: http://localhost:8080/v2 (from default (http://localhost:8080))
+Engine: Nano engine (nanobpmn v0.114.1) — Falcon streaming at /falcon at http://localhost:8080/v2.
+```
+
+The preflight is **informational, never a gate** — Nano Workforce runs against a
+stock **Camunda 8** cluster too, so a non-Nano engine is announced
+(`Engine: Camunda 8 (gateway v8.x) — REST only …`), not rejected. If nothing
+answers, it logs a `warn` (`could not reach … features will fail to start until
+the engine is reachable`) and boot continues. On a **secured** cluster the probe
+sends `CAMUNDA_TOKEN` as a bearer credential; a `401/403` is reported as an auth
+hint (check `CAMUNDA_TOKEN`), not as an unreachable engine.
+
+> **Watch the port when launched from a console.** A console-launched app can
+> default `NANOBPMN_BASE_URL` to `http://localhost:8080`. If **another Camunda 8**
+> is already on `:8080`, the app will talk to *that* engine (it works — C8 is
+> supported), which may not be the engine you intended. Check the startup
+> `Engine:` line; to target a Nano engine on a different port, set
+> `NANOBPMN_BASE_URL` (or `CAMUNDA_REST_ADDRESS`) explicitly.
+>
+> When the app *can't* work against the reached engine you'll see a job/instance
+> decode error at first feature start — `MalformedFrameError` / `MalformedJobError`
+> (Falcon) or the Camunda REST client's own `4xx` (older versions surfaced
+> `engine response missing processInstanceKey/key`). The startup `Engine:` line
+> tells you which engine you actually reached, before any such error.
+
+
 ### Fleet networking (remote workers)
 
 `nano-workforce` can drive a **distributed worker fleet** — `senior:*` agents running on other LAN

package/app/agentic/vocab/demand-report.ts

@@ -20,6 +20,7 @@ import {
 import type { RegisteredWorker } from "@nanobpm/agentic/vocab";
 import type { Logger } from "@nanobpm/urban";
 import type { RegistryReport as WireRegistryReport } from "../../../nano-generated/api-io.d.ts";
+import { resolveEngineAddress } from "../../enginePreflight.ts";
 import { envVar } from "../../version.ts";
 import { currentPresenceRegistry } from "../families/presence.family.ts";
 import { CREW_VOCAB_VERSION, crewResolver } from "./crew-vocab.ts";
@@ -40,17 +41,14 @@ export interface RegistryReport extends DemandSupplyReport {
 }
 
 /**
- * Derive the engine's C8 v2 REST base the demand reader targets — the same precedence/derivation
- * `main.ts` uses: an explicit `CAMUNDA_REST_ADDRESS` wins, else it is derived from `NANOBPMN_BASE_URL`
- * (+ `/v2`), defaulting to `http://localhost:8080/v2`. Read through the declared env schema (ADR 0004).
- * (This reader additionally strips trailing slashes off an explicit `CAMUNDA_REST_ADDRESS`, which
- * `main.ts` does not, so the derived base is well-formed regardless of a trailing `/`.)
+ * Derive the engine's C8 v2 REST base the demand reader targets. Delegates to
+ * the canonical {@link resolveEngineAddress} (the single source of truth shared
+ * with `main.ts`) so the precedence — explicit `CAMUNDA_REST_ADDRESS` wins, else
+ * `NANOBPMN_BASE_URL` (+ `/v2`), defaulting to `http://localhost:8080/v2` — lives
+ * in one place and cannot drift between call sites.
  */
 export function engineRestAddress(): string {
-  const explicit = envVar("CAMUNDA_REST_ADDRESS")?.replace(/\/+$/, "");
-  if (explicit) return explicit;
-  const base = (envVar("NANOBPMN_BASE_URL") ?? "http://localhost:8080").replace(/\/+$/, "");
-  return `${base}/v2`;
+  return resolveEngineAddress().restAddress;
 }
 
 /** The live supply rows (`{ instance, capability }`) from the H1 presence registry, or none when unmounted. */

package/app/enginePreflight.test.ts

@@ -0,0 +1,122 @@
+// Tests for engine address resolution + the startup preflight (nano-workforce#391).
+//
+// The resolver and the identity description are pure (an injectable env reader /
+// a plain topology body), and the preflight takes an injectable `fetch`, so none
+// of this needs a live engine or `process.env` mutation.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import {
+  announceEngine,
+  describeEngine,
+  type EngineAddress,
+  resolveEngineAddress,
+  type TopologyProbe,
+} from "./enginePreflight.ts";
+
+const reader = (vars: Record<string, string>) => (name: string): string | null => vars[name] ?? null;
+
+test("resolveEngineAddress honours an explicit CAMUNDA_REST_ADDRESS and strips trailing slashes", () => {
+  const addr = resolveEngineAddress(reader({ CAMUNDA_REST_ADDRESS: "http://engine.example:8080/v2///" }));
+  assertEquals(addr, { restAddress: "http://engine.example:8080/v2", source: "CAMUNDA_REST_ADDRESS" });
+});
+
+test("resolveEngineAddress derives /v2 from NANOBPMN_BASE_URL when no explicit address", () => {
+  const addr = resolveEngineAddress(reader({ NANOBPMN_BASE_URL: "http://engine.example:7000//" }));
+  assertEquals(addr, { restAddress: "http://engine.example:7000/v2", source: "NANOBPMN_BASE_URL" });
+});
+
+test("resolveEngineAddress defaults to localhost:8080 and labels the source as the default", () => {
+  const addr = resolveEngineAddress(reader({}));
+  assertEquals(addr, { restAddress: "http://localhost:8080/v2", source: "default (http://localhost:8080)" });
+});
+
+test("describeEngine reports a Nano engine from the `nano` marker", () => {
+  const line = describeEngine({ nano: { engine: "nanobpmn", version: "0.114.1", falconPath: "/falcon" } });
+  assert(line.includes("Nano engine (nanobpmn v0.114.1)"), "names the nano engine + version");
+  assert(line.includes("/falcon"), "mentions the Falcon path");
+});
+
+test("describeEngine reports Camunda 8 (never rejects) when the `nano` marker is absent", () => {
+  const line = describeEngine({ gatewayVersion: "8.6.0" });
+  assert(line.startsWith("Camunda 8"), "identifies Camunda 8");
+  assert(line.includes("8.6.0"), "surfaces the gateway version");
+  assert(line.includes("REST only"), "notes Falcon is unavailable");
+});
+
+test("describeEngine tolerates an empty / missing body", () => {
+  assert(describeEngine(null).startsWith("Camunda 8"), "null body degrades to Camunda 8");
+  assert(describeEngine({}).startsWith("Camunda 8"), "empty body degrades to Camunda 8");
+});
+
+// --- announceEngine (injected fetch; never throws) ---
+
+const ADDR: EngineAddress = { restAddress: "http://localhost:8080/v2", source: "default (http://localhost:8080)" };
+
+function capture() {
+  const info: string[] = [];
+  const warn: string[] = [];
+  return { log: { info: (m: string) => info.push(m), warn: (m: string) => warn.push(m) }, info, warn };
+}
+
+const okResponse = (body: TopologyProbe) =>
+  ({ ok: true, status: 200, json: () => Promise.resolve(body) }) as unknown as Response;
+
+test("announceEngine logs the resolved address + a Nano identity line", async () => {
+  const { log, info, warn } = capture();
+  let probed = "";
+  await announceEngine(ADDR, log, {
+    fetchImpl: ((url: string) => {
+      probed = url;
+      return Promise.resolve(okResponse({ nano: { engine: "nanobpmn", version: "1.2.3", falconPath: "/falcon" } }));
+    }) as unknown as typeof fetch,
+  });
+  assertEquals(probed, "http://localhost:8080/v2/topology");
+  assert(info.some((l) => l.includes("Engine address: http://localhost:8080/v2 (from default")), "echoes address+source");
+  assert(info.some((l) => l.includes("Nano engine (nanobpmn v1.2.3)")), "announces the Nano engine");
+  assertEquals(warn, []);
+});
+
+test("announceEngine announces Camunda 8 without rejecting", async () => {
+  const { log, info, warn } = capture();
+  await announceEngine(ADDR, log, {
+    fetchImpl: (() => Promise.resolve(okResponse({ gatewayVersion: "8.6.0" }))) as unknown as typeof fetch,
+  });
+  assert(info.some((l) => l.includes("Camunda 8")), "announces Camunda 8");
+  assertEquals(warn, []);
+});
+
+test("announceEngine sends CAMUNDA_TOKEN as a bearer credential on the probe", async () => {
+  const { log } = capture();
+  let sentAuth: string | undefined;
+  await announceEngine(ADDR, log, {
+    token: "secret-token",
+    fetchImpl: ((_url: string, init: { headers: Record<string, string> }) => {
+      sentAuth = init.headers.authorization;
+      return Promise.resolve(okResponse({ nano: { engine: "nanobpmn" } }));
+    }) as unknown as typeof fetch,
+  });
+  assertEquals(sentAuth, "Bearer secret-token");
+});
+
+test("announceEngine treats 401/403 as an auth hint, not an unreachable warning", async () => {
+  const { log, warn } = capture();
+  const res = { ok: false, status: 401, json: () => Promise.reject(new Error("unused")) } as unknown as Response;
+  await announceEngine(ADDR, log, { fetchImpl: (() => Promise.resolve(res)) as unknown as typeof fetch });
+  assert(warn.some((l) => l.includes("HTTP 401") && l.includes("CAMUNDA_TOKEN")), "points at the token, not unreachability");
+  assert(!warn.some((l) => l.includes("could not reach")), "does not claim the engine is unreachable");
+});
+
+test("announceEngine warns (does not throw) on a non-200 response", async () => {
+  const { log, warn } = capture();
+  const res = { ok: false, status: 503, json: () => Promise.reject(new Error("unused")) } as unknown as Response;
+  await announceEngine(ADDR, log, { fetchImpl: (() => Promise.resolve(res)) as unknown as typeof fetch });
+  assert(warn.some((l) => l.includes("HTTP 503")), "warns with the status code");
+});
+
+test("announceEngine warns (does not throw) when the engine is unreachable", async () => {
+  const { log, warn } = capture();
+  await announceEngine(ADDR, log, {
+    fetchImpl: (() => Promise.reject(new Error("ECONNREFUSED"))) as unknown as typeof fetch,
+  });
+  assert(warn.some((l) => l.includes("could not reach") && l.includes("ECONNREFUSED")), "warns with the reason");
+});

package/app/enginePreflight.ts

@@ -0,0 +1,134 @@
+// Engine address resolution + a lightweight, non-rejecting startup preflight
+// (nano-workforce#391).
+//
+// Two jobs, one source of truth:
+//   1. `resolveEngineAddress` is the CANONICAL resolver for the engine REST
+//      address. Both the engine client (`main.ts`) and the demand reader
+//      (`app/agentic/vocab/demand-report.ts`) derive from it, so the precedence
+//      lives in exactly one place instead of drifting across call sites.
+//   2. `announceEngine` probes `/v2/topology` at boot and reports which engine
+//      answered. It is DELIBERATELY informational: Nano Workforce is a
+//      first-class Camunda 8 client, so a non-Nano engine is announced, never
+//      rejected. It never throws — a boot preflight must not gate startup.
+//
+// Why: without this, pointing the app at the wrong address (classically another
+// service already on :8080) surfaces only later as a cryptic mid-run engine
+// error. Echoing the resolved address + which engine answered makes the
+// misconfiguration obvious at boot.
+
+import { envVar } from "./version.ts";
+
+/** The resolved engine REST address plus a human label for where it came from. */
+export interface EngineAddress {
+  /** The `/v2` REST base the engine client and demand reader talk to. */
+  restAddress: string;
+  /** Which input produced `restAddress`, for a legible startup line. */
+  source: string;
+}
+
+/**
+ * Canonical engine REST address resolution — the single source of truth.
+ *
+ * Precedence: an explicit `CAMUNDA_REST_ADDRESS` (already the `/v2` REST
+ * address) wins; otherwise the address is derived from `NANOBPMN_BASE_URL`
+ * (+ `/v2`), defaulting the base to `http://localhost:8080`. Trailing slashes
+ * are stripped from both inputs.
+ *
+ * `read` is injectable so the resolution is testable without mutating
+ * `process.env`; it defaults to the app's `envVar` (ADR 0004) accessor.
+ */
+export function resolveEngineAddress(
+  read: (name: string) => string | null = envVar,
+): EngineAddress {
+  const explicit = read("CAMUNDA_REST_ADDRESS")?.replace(/\/+$/, "");
+  if (explicit) return { restAddress: explicit, source: "CAMUNDA_REST_ADDRESS" };
+  const base = read("NANOBPMN_BASE_URL");
+  const normalized = (base ?? "http://localhost:8080").replace(/\/+$/, "");
+  return {
+    restAddress: `${normalized}/v2`,
+    source: base ? "NANOBPMN_BASE_URL" : "default (http://localhost:8080)",
+  };
+}
+
+/**
+ * The subset of a `/v2/topology` body we read. A nanobpmn gateway advertises a
+ * `nano` object (its own extension) so a single call distinguishes it from a
+ * stock Camunda 8 gateway, which returns the same shape without it.
+ */
+export interface TopologyProbe {
+  nano?: { engine?: string; version?: string; falconPath?: string } | null;
+  gatewayVersion?: string;
+}
+
+/**
+ * A human-readable identity line for whatever answered `/v2/topology`. Never
+ * rejects: a Camunda 8 gateway (no `nano` marker) is a supported target, so it
+ * is described, not refused.
+ */
+export function describeEngine(body: TopologyProbe | null | undefined): string {
+  const nano = body?.nano;
+  if (nano?.engine) {
+    const version = nano.version ? ` v${nano.version}` : "";
+    const falcon = nano.falconPath ?? "/falcon";
+    return `Nano engine (${nano.engine}${version}) — Falcon streaming at ${falcon}`;
+  }
+  const gateway = body?.gatewayVersion ? ` (gateway v${body.gatewayVersion})` : "";
+  return `Camunda 8${gateway} — REST only (Nano Falcon streaming unavailable)`;
+}
+
+/** The logging surface `announceEngine` needs (structurally a `Logger`). */
+export interface PreflightLog {
+  info(msg: string): void;
+  warn(msg: string): void;
+}
+
+/**
+ * Log the resolved engine address (and its source), then probe `/v2/topology`
+ * and announce which engine answered. Informational only — it swallows every
+ * failure into a `warn` and never throws, so a slow or absent engine cannot
+ * block boot. A missing engine is a `warn` (features will fail to start until
+ * it is reachable), not a fatal error.
+ *
+ * `opts.token` (the same `CAMUNDA_TOKEN` the engine client uses) is sent as a
+ * bearer credential so a secured cluster does not answer the probe with a
+ * misleading 401/403 while the real client is correctly configured.
+ */
+export async function announceEngine(
+  addr: EngineAddress,
+  log: PreflightLog,
+  opts: { token?: string; fetchImpl?: typeof fetch } = {},
+): Promise<void> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  log.info(`Engine address: ${addr.restAddress} (from ${addr.source})`);
+  const url = `${addr.restAddress.replace(/\/+$/, "")}/topology`;
+  const headers: Record<string, string> = { accept: "application/json" };
+  if (opts.token) headers.authorization = `Bearer ${opts.token}`;
+  try {
+    const res = await fetchImpl(url, { headers, signal: AbortSignal.timeout(3000) });
+    if (!res.ok) {
+      if (res.status === 401 || res.status === 403) {
+        // The engine is reachable but rejected the probe's credentials — the
+        // real client may still work (it authenticates independently), so this
+        // is an auth hint, not an "unreachable" warning.
+        log.warn(
+          `Engine preflight: ${url} returned HTTP ${res.status} (authentication). ` +
+            `If the engine requires a token, set CAMUNDA_TOKEN — the engine client uses it independently.`,
+        );
+        return;
+      }
+      log.warn(
+        `Engine preflight: ${url} returned HTTP ${res.status}. ` +
+          `Check CAMUNDA_REST_ADDRESS / NANOBPMN_BASE_URL — features will fail to start until the engine is reachable.`,
+      );
+      return;
+    }
+    const body: TopologyProbe = await res.json();
+    log.info(`Engine: ${describeEngine(body)} at ${addr.restAddress}.`);
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    log.warn(
+      `Engine preflight: could not reach ${url} (${reason}). ` +
+        `Check CAMUNDA_REST_ADDRESS / NANOBPMN_BASE_URL — features will fail to start until the engine is reachable.`,
+    );
+  }
+}

package/main.ts

@@ -20,6 +20,7 @@
 import { Server } from "node:http";
 import { createNanoSdkEngineClient, runFromEnv, selectHost } from "@nanobpm/urban";
 import { type AgenticChannelHandle, mountAgenticChannel } from "./app/agentic/channel.ts";
+import { announceEngine, resolveEngineAddress } from "./app/enginePreflight.ts";
 import { MAX_ROUNDS, pollOnce } from "./app/service.ts";
 import { envVar } from "./app/version.ts";
 
@@ -29,12 +30,18 @@ const GITHUB_TOKEN = process.env.GITHUB_TOKEN ?? "";
 
 const host = selectHost();
 
-// One engine client, shared by the runtime (surfaces/actions/workers) and the poller. Honour
-// the app's documented NANOBPMN_BASE_URL as well as the runtime's CAMUNDA_REST_ADDRESS.
-const restAddress = process.env.CAMUNDA_REST_ADDRESS ??
-  `${(process.env.NANOBPMN_BASE_URL ?? "http://localhost:8080").replace(/\/+$/, "")}/v2`;
+// One engine client, shared by the runtime (surfaces/actions/workers) and the poller. The address
+// resolution (CAMUNDA_REST_ADDRESS wins, else NANOBPMN_BASE_URL + /v2, else localhost:8080) is the
+// canonical `resolveEngineAddress`, shared with the demand reader. A non-rejecting startup preflight
+// then echoes the resolved address and announces which engine answered (nano-workforce#391) so a
+// misconfigured address is obvious at boot rather than as a cryptic mid-run engine error.
+const engineAddress = resolveEngineAddress();
+await announceEngine(engineAddress, {
+  info: (msg) => host.log("info", msg),
+  warn: (msg) => host.log("warn", msg),
+}, { token: process.env.CAMUNDA_TOKEN });
 const engine = await createNanoSdkEngineClient({
-  restAddress,
+  restAddress: engineAddress.restAddress,
   token: process.env.CAMUNDA_TOKEN,
   transport: process.env.CAMUNDA_TRANSPORT ?? "auto",
   log: host.log,
@@ -96,7 +103,7 @@ let shuttingDown = false;
 let pollTimer: ReturnType<typeof setTimeout> | null = null;
 async function pollLoop(): Promise<void> {
   try {
-    if (app.data) await pollOnce(app.data, engine, GITHUB_TOKEN, { restAddress, token: process.env.CAMUNDA_TOKEN });
+    if (app.data) await pollOnce(app.data, engine, GITHUB_TOKEN, { restAddress: engineAddress.restAddress, token: process.env.CAMUNDA_TOKEN });
   } catch (err) {
     console.error("poll error:", err);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.114.1",
+  "version": "0.115.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",