c8ctl-plugin-nano 1.62.0 → 1.62.2

package/README.md

@@ -197,6 +197,21 @@ capabilities `code-review, testing` the matrix is:
 so a BPMN service task can target a worker at any granularity by setting its job
 type to the matching token.
 
+**Choosing which engine a worker connects to.** By default `work` (and
+`supervisor start --worker`) connects to your **active** c8ctl session profile
+(`c8ctl use profile <name>`). To point a single invocation at a different
+cluster without switching the active session, pass c8ctl's global
+`--profile <name>` — it is honoured the same way it is for core c8ctl commands:
+
+```bash
+c8ctl nano work fleet --profile nano-validate            # this worker only → nano-validate's engine
+c8ctl nano supervisor start --worker fleet --profile nano-validate   # the whole fleet → nano-validate
+```
+
+The named profile wins over the active session for that run only; a supervised
+fleet is pinned to it (the daemon forwards it to every worker it spawns), and
+`supervisor status` reports the matching `ENGINE`.
+
 To also service a job type the matrix can't express — for example a code-first
 [`@nanobpm/workflow`](https://www.npmjs.com/package/@nanobpm/workflow) flow whose
 external task type is `<flowId>:<taskName>`, or any bespoke token — add one or

package/agent-instance.mjs

@@ -311,6 +311,23 @@ function shortHash(text) {
   return (h >>> 0).toString(36);
 }
 
+// #247: the per-ACTIVATION namespace folded into every content-derived historyItemId
+// so a resumed harness (which restarts its ACP message / tool-call numbering) does not
+// collide with — and get silently deduplicated against — the prior activation's turns.
+// The activation identity is the lease token (a fresh token per `activate jobs`), else
+// the jobKey, else the elementInstanceKey. It is HASHED — the lease token is a
+// secret-ish fence token that must never be embedded raw in a persisted id — and stays
+// STABLE for the life of one activation, so an at-least-once redelivery still dedups
+// within the activation while a genuine resume (new lease) gets a distinct namespace.
+// Returns '' when no identity is available, leaving the id un-namespaced (unchanged).
+export function activationNamespace(job = {}) {
+  const leaseToken = job?.leaseToken != null ? String(job.leaseToken) : '';
+  const jobKey = job?.jobKey != null ? String(job.jobKey) : '';
+  const elementInstanceKey = job?.elementInstanceKey != null ? String(job.elementInstanceKey) : '';
+  const token = leaseToken || jobKey || elementInstanceKey || '';
+  return token ? shortHash(token) : '';
+}
+
 // Extract per-call metrics from an ACP update when the agent carries them (many
 // ACP agents do not — a documented ACP fidelity gap — so this is usually absent).
 // Reads the common usage locations and maps to the AgentHistory item metric field
@@ -408,6 +425,21 @@ export function createAgentInstanceProducer(opts = {}) {
   const elementInstanceKey = job?.elementInstanceKey != null ? String(job.elementInstanceKey) : '';
   const elementId = job?.elementId != null ? String(job.elementId) : null;
   const processInstanceKey = job?.processInstanceKey != null ? String(job.processInstanceKey) : '';
+  // #247: namespace every content-derived historyItemId per ACTIVATION. When a parked
+  // process resumes, a fresh (cold-started) harness re-activates the SAME AgentInstance
+  // and generally RESTARTS its ACP message / tool-call numbering (m-1, call-1, …). The
+  // engine dedups appends by historyItemId, so without a per-activation namespace those
+  // continuation turns collide with the PRIOR activation's ids and are silently dropped
+  // as stale history — the transcript never advances, and the next reactivation replays
+  // the same side effects (the failure mode #239 exists to prevent). The namespace is
+  // derived from the job's ACTIVATION identity (see `activationNamespace`): stable for
+  // the life of this producer, so an at-least-once redelivery of the SAME activation
+  // still dedups correctly, while a genuine resume (new lease → new namespace) appends
+  // instead of colliding. The CONFIGURATION turn is left keyed on the elementInstanceKey
+  // ALONE (stable across activations) so its single header dedups per instance rather
+  // than duplicating on every resume.
+  const activationNs = activationNamespace(job);
+  const nsHistoryId = (id) => (activationNs ? `${activationNs}:${id}` : id);
   // #229 cross-channel correlation, compact form. Stamps job/eik/pik so the
   // AgentInstance channel can be joined to the job / relay / git channels. This is the
   // terse rendering used by the observability lines; `correlation()` below is the
@@ -637,7 +669,7 @@ export function createAgentInstanceProducer(opts = {}) {
     if (!hasText && !hasMetrics) return;
     const idBasis = isNonBlank(msg.messageId) ? String(msg.messageId) : `h:${shortHash(text)}`;
     const turn = {
-      historyItemId: `${msg.role.toLowerCase()}:${idBasis}`,
+      historyItemId: nsHistoryId(`${msg.role.toLowerCase()}:${idBasis}`),
       loopIteration: msg.loopIteration,
       role: msg.role,
       content: hasText ? [{ contentType: 'TEXT', text }] : [],
@@ -653,7 +685,7 @@ export function createAgentInstanceProducer(opts = {}) {
     flushMessage();
     if (isNonBlank(c.name)) toolNames.set(String(c.callId), String(c.name));
     const turn = {
-      historyItemId: `toolcall:${c.callId}`,
+      historyItemId: nsHistoryId(`toolcall:${c.callId}`),
       loopIteration,
       role: 'ASSISTANT',
       content: [],
@@ -673,7 +705,7 @@ export function createAgentInstanceProducer(opts = {}) {
   const onToolResult = (c) => {
     flushMessage();
     const turn = {
-      historyItemId: `toolresult:${c.callId}`,
+      historyItemId: nsHistoryId(`toolresult:${c.callId}`),
       loopIteration,
       role: 'TOOL_RESULT',
       content: contentForResult(c.result),

package/c8ctl-plugin.js

@@ -8568,7 +8568,7 @@ function checkSetupAbort(abortSignal, { jobType, jobKey, stage, logger } = {}) {
  * the rank×capability matrix) and poll for work in the foreground until Ctrl-C.
  * Uses the c8ctl-provided SDK client (globalThis.c8ctl.createClient()).
  */
-async function workAgent(req, flags) {
+async function workAgent(req, flags, ctx) {
   const logger = getLogger();
   // The hire to run always comes from the positional profile. `--name` no longer
   // selects the hire (that was a footgun: `work reviewer --name coder` silently
@@ -8850,7 +8850,14 @@ async function workAgent(req, flags) {
   // bad DNS answer is corrected, without a supervisor restart. Set before the
   // client is created so every outbound inherits it.
   preferIpv4Resolution();
-  const camunda = globalThis.c8ctl.createClient();
+  // Honour c8ctl's global `--profile <name>` for this invocation: the handler
+  // ctx carries `profile` (the `--profile` override, else the active session
+  // profile). Passing it to createClient(profile) connects the worker to the
+  // profile named on the command line, not just the active session — closing the
+  // silently-ignored-`--profile` gap (jwulf/c8ctl-plugin-nano#189). ctx-less
+  // callers (undefined) fall back to createClient(undefined), which resolves the
+  // active profile itself — identical to the old no-arg behaviour.
+  const camunda = globalThis.c8ctl.createClient(resolveConnectionProfile(ctx));
 
   // Broker REST endpoint for live linked-resource prompts (issue #63) and the
   // C8 REST source for `--auto`'s engine-read enrolment. Derived from the SAME
@@ -10315,6 +10322,55 @@ function reconstructWorkArgs(flags) {
   return out;
 }
 
+// The c8ctl connection profile (its global `--profile` flag) resolved for THIS
+// invocation, for handing to `createClient(profile)`. c8ctl core builds the
+// plugin handler's third `ctx` argument with `ctx.profile = --profile override
+// ?? activeProfile` (index.js), then exposes a lazy `createClient(pluginProfile)`
+// — but this plugin creates its own client via `globalThis.c8ctl.createClient()`
+// and, before this, called it with NO profile, so `work`/`supervisor` always
+// connected to the ACTIVE session profile and silently ignored a per-invocation
+// `--profile <name>` (jwulf/c8ctl-plugin-nano#189). Threading this value into
+// `createClient(profile)` makes them honour `--profile` the way core c8ctl
+// commands do. Returns undefined when ctx carries no profile, so
+// `createClient(undefined)` resolves the active session profile itself (its own
+// documented default) — byte-identical to the old no-arg call. Pure.
+function resolveConnectionProfile(ctx) {
+  const p = ctx && typeof ctx.profile === 'string' ? ctx.profile.trim() : '';
+  return p || undefined;
+}
+
+// The EXPLICIT `--profile <name>` override only (distinct from the active
+// session profile), for FORWARDING to spawned `nano work` children. When an
+// operator runs `supervisor start --worker <p> --profile <conn>` (or
+// `supervisor add … --profile <conn>`), each supervised worker is a fresh
+// `c8ctl nano work` process that must connect to <conn>, not the daemon's/
+// session's active profile. c8ctl strips the global `--profile` before the
+// plugin parser sees it, so it never lands in `flags`; we recover it from
+// `ctx.profile` and re-emit it as a `--profile` token in the child argv (c8ctl
+// core parses it position-independently as a global). Returns undefined when no
+// override was given — i.e. `ctx.profile` is absent or merely equals the active
+// session profile — so the child inherits the active profile exactly as before
+// (no spurious pin). Pure.
+function explicitConnectionProfile(ctx) {
+  const p = resolveConnectionProfile(ctx);
+  if (!p) return undefined;
+  const active = globalThis.c8ctl && typeof globalThis.c8ctl.activeProfile === 'string'
+    ? globalThis.c8ctl.activeProfile
+    : undefined;
+  return p === active ? undefined : p;
+}
+
+// Append the explicit connection-profile override (if any) to a reconstructed
+// `work` argv tail as a c8ctl global `--profile <conn>` token, so a supervised
+// worker connects to the profile named on the `supervisor start`/`add` command
+// line rather than the active session profile (jwulf/c8ctl-plugin-nano#189).
+// A no-op when no `--profile` override was passed. Pure.
+function withConnectionProfileArg(workArgs, ctx) {
+  const conn = explicitConnectionProfile(ctx);
+  const base = Array.isArray(workArgs) ? workArgs : [];
+  return conn ? [...base, '--profile', conn] : base;
+}
+
 /**
  * Sanitize one token for use inside a worker name: keep `[A-Za-z0-9._-]`,
  * collapse every other run to a single `-`, and trim leading/trailing
@@ -11737,13 +11793,17 @@ async function startSupervisorWithServicePolicy(logger = getLogger()) {
   return startSupervisorDaemon({ adoptOnly: serviceOwned });
 }
 
-async function supervisorStartCmd(req, flags) {
+async function supervisorStartCmd(req, flags, ctx) {
   const logger = getLogger();
   const state = await startSupervisorWithServicePolicy(logger);
   logger.info(`Supervisor daemon running (pid ${state.pid}).`);
 
   const specs = normalizeArgList(flags?.worker);
-  const workArgs = reconstructWorkArgs(flags);
+  // Forward c8ctl's global `--profile <conn>` (when it overrides the active
+  // session profile) to every spawned worker, so `supervisor start --worker <p>
+  // --profile <conn>` pins the fleet to <conn> instead of silently connecting to
+  // the active session engine (jwulf/c8ctl-plugin-nano#189).
+  const workArgs = withConnectionProfileArg(reconstructWorkArgs(flags), ctx);
   // `--name` names a single launched worker. With several `--worker` specs a lone
   // name can't apply to all of them, so honour it only for a single spec and let
   // the rest auto-name; warn so the intent isn't silently dropped.
@@ -11803,7 +11863,7 @@ async function supervisorStatusCmd() {
   printSupervisorStatus(logger, statusFromState(running));
 }
 
-async function supervisorAddCmd(req, flags) {
+async function supervisorAddCmd(req, flags, ctx) {
   const logger = getLogger();
   // The positional profile is what runs; `--name` names this worker instance
   // (forwarded to the child as `nano work … --name`, and used as its supervisor
@@ -11822,7 +11882,10 @@ async function supervisorAddCmd(req, flags) {
     process.exit(1);
   }
   await startSupervisorWithServicePolicy(logger);
-  const workArgs = reconstructWorkArgs(flags);
+  // Forward the global `--profile <conn>` override to the spawned worker(s) so
+  // `supervisor add … --profile <conn>` connects them to <conn>, matching
+  // `supervisor start` (jwulf/c8ctl-plugin-nano#189).
+  const workArgs = withConnectionProfileArg(reconstructWorkArgs(flags), ctx);
   let added = 0;
   let failed = 0;
   for (let i = 0; i < count; i++) {
@@ -12617,7 +12680,7 @@ async function maybeReparentOrWarnOnStart(logger) {
 }
 
 /** Dispatch the `supervisor` subcommand's action. */
-async function supervisorCommand(req, flags) {
+async function supervisorCommand(req, flags, ctx) {
   const action = (req.positional[0] || '').toLowerCase();
   switch (action) {
     case '__daemon':
@@ -12632,7 +12695,7 @@ async function supervisorCommand(req, flags) {
       return;
     }
     case 'start':
-      await supervisorStartCmd(req, flags);
+      await supervisorStartCmd(req, flags, ctx);
       return;
     case 'install':
       await supervisorInstallCmd();
@@ -12646,7 +12709,7 @@ async function supervisorCommand(req, flags) {
       await supervisorStatusCmd();
       return;
     case 'add':
-      await supervisorAddCmd(req, flags);
+      await supervisorAddCmd(req, flags, ctx);
       return;
     case 'remove':
     case 'rm':
@@ -15463,6 +15526,9 @@ export {
 };
 export {
   reconstructWorkArgs,
+  resolveConnectionProfile,
+  explicitConnectionProfile,
+  withConnectionProfileArg,
   supervisorWorkerId,
   autoWorkerName,
   sanitizeNameToken,
@@ -15498,6 +15564,7 @@ export {
   runSupervisorDaemon,
   startSupervisorDaemon,
   supervisorRequest,
+  supervisorStartCmd,
   supervisorAddCmd,
   runningSupervisor,
   readSupervisorState,
@@ -15687,7 +15754,7 @@ export const commands = {
       manifest: { type: 'string', description: `workforce: manifest name to operate on (default ${DEFAULT_WORKFORCE_MANIFEST}); each subcommand reads/writes <stateHome>/workforce/<name>.json. Renamed from --profile (which now collides with c8ctl's global connection-profile flag).` },
       roles: { type: 'string', description: 'workforce add: comma-separated role list for the entry (→ --job-type <rank>:<role> at start); mutually exclusive with --auto' },
     },
-    handler: async (args, flags) => {
+    handler: async (args, flags, ctx) => {
       const logger = getLogger();
       const req = parseRequest(args, flags);
 
@@ -15744,10 +15811,10 @@ export const commands = {
             await assignCapabilities(req, flags);
             break;
           case 'work':
-            await workAgent(req, flags);
+            await workAgent(req, flags, ctx);
             break;
           case 'supervisor':
-            await supervisorCommand(req, flags);
+            await supervisorCommand(req, flags, ctx);
             break;
           case 'workforce':
             await workforceCommand(req, flags);

package/package.json

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