c8ctl-plugin-nano 1.18.1 → 1.19.0

package/README.md

@@ -24,7 +24,7 @@ It adds a single `nano` command:
 
 ```bash
 c8ctl nano start|status|stop|restart|logs|pause|resume|clean|set|config|update
-c8ctl nano hire|work   # turn a CLI agent harness into a Nano job worker
+c8ctl nano hire|assign|work   # hire/assign manage agent profiles; work runs one as a Nano job worker
 ```
 
 `nano start N` spawns **N** nanobpmn node processes wired to talk to each other
@@ -157,6 +157,24 @@ c8ctl nano hire --name coder --rank senior --command copilot --arg --allow-all
 c8ctl nano hire --list
 ```
 
+**`assign <name> [capabilities...]`** grants new capabilities (roles) to an
+existing hire without re-running `hire`. Capabilities are **added** to (unioned
+with) the profile's current set — `assign` never removes a role — and the
+updated job-type matrix is printed. Restart the profile's workers so they pick
+up the new job types:
+
+```bash
+# Give an existing reviewer two more capabilities
+c8ctl nano assign reviewer triage refactoring
+
+# --capabilities works too (comma-separated), equivalent to the positionals above
+c8ctl nano assign reviewer --capabilities triage,refactoring
+
+# then restart its workers to service the new job types
+c8ctl nano work reviewer
+```
+
+
 **`work <name>`** loads the profile, connects with the c8ctl SDK client, and
 registers one job worker per token in the **rank × capability matrix**, then
 polls for work in the foreground until Ctrl-C. For rank `senior` and
@@ -217,6 +235,16 @@ config`).
 > Raising `--job-timeout` alone does **not** fix this — it moves both coupled
 > deadlines together; widen `--lock-grace` (or keep the default) instead.
 
+> **Long-poll window.** `--poll-timeout` (default `30000`ms) is how long the
+> broker holds each `activateJobs` request open waiting for work before returning
+> empty. A longer window keeps an idle worker on **one** connection for that whole
+> window instead of reconnecting every few seconds — cutting the number of
+> connection establishments, and thus the chances of hitting a transient connect
+> error (`ECONNREFUSED` / connect-timeout) on a flaky link. It maps straight to
+> the SDK's `pollTimeoutMs` → the broker's `requestTimeout`: `0` selects the
+> broker's own default (~5s) and a negative value returns immediately when no job
+> is available.
+
 > **Trust boundary.** The profile `command` is run through a shell so you can
 > write a full invocation (args, pipes, multi-word commands). It is
 > **operator-authored** — only what you put in your own `config.json` is
@@ -246,6 +274,16 @@ Element templates emit flat dotpath header keys (strings); the plugin expands
 them into a nested object and coerces `"true"/"false"` → bool and numeric
 strings → int. The normalized shape is
 `{ schemaVersion, repository{provider,url,ref,depth,submodules,authRef}, branch{base,create,push}, setup{commands,env,secretRefs}, task{prompt,promptFile,maxIterations,timeoutMs,allowPr,prBase} }`.
+
+**Prompt = base + optional verbatim append.** The agent's prompt resolves to
+`task.prompt` (typically a model header filled at deploy time), falling back to a
+plain `prompt`/`task` variable. Because a header-delivered base prompt can't be
+composed in FEEL, a task may supply per-instance context via **`task.appendPrompt`**
+(reserved) or a plain **`appendPrompt`** variable — it is concatenated onto the base
+**verbatim, with no injected separator** (the model's ioMapping owns any leading
+separator/preamble), so a null/empty append leaves the base untouched. This lets the
+static prompt live in a model header/side-car while the dynamic tail (e.g. plan-revision
+feedback, a per-task brief) is built per instance.
 On completion the plugin writes an **output envelope** back under
 `io.nanobpm.agentResult` (`{schemaVersion, status, sandbox, image, output, truncated, stderrTruncated, exitCode, signal, error}`). When a repository was
 provisioned (below) it also carries `{repository, branch, baseSha, headSha, commits[], pushed, pushError?, gitError?, pr?}`.

package/c8ctl-plugin.js

@@ -368,7 +368,7 @@ function launcherEnvMarkers(resolved) {
 // Argument parsing
 // ---------------------------------------------------------------------------
 
-const VALID_SUBCOMMANDS = ['start', 'stop', 'status', 'logs', 'log', 'restart', 'pause', 'resume', 'clean', 'set', 'config', 'update', 'hire', 'work'];
+const VALID_SUBCOMMANDS = ['start', 'stop', 'status', 'logs', 'log', 'restart', 'pause', 'resume', 'clean', 'set', 'config', 'update', 'hire', 'assign', 'work'];
 
 /**
  * Parse positional args + flags into a normalized request.
@@ -1518,7 +1518,32 @@ function deriveJobLockMs(jobTimeoutMs, lockGraceMs) {
   return { killMs, lockMs: killMs + grace };
 }
 
-/** A profile name must be a safe, filesystem/token-friendly slug. */
+/**
+ * Resolve the broker long-poll window (ms) each `activateJobs` request is held
+ * open before returning empty. A longer window keeps an idle worker on ONE open
+ * connection for that whole window instead of reconnecting every few seconds,
+ * cutting the number of connection establishments — and thus the number of
+ * chances to hit a transient connect failure (ECONNREFUSED / connect-timeout)
+ * on a flaky link.
+ *
+ * The value is passed straight through to the SDK as `pollTimeoutMs` → the
+ * broker's `requestTimeout`, so the documented broker semantics apply: `0` =
+ * broker default (~5s), a negative value = return immediately when no job is
+ * available. Parsing is `parseInt`-style: only a flag with no leading integer
+ * (absent, blank, or non-numeric such as `"abc"`) falls back to the default,
+ * while a leading integer with trailing junk (e.g. `"30000ms"`) is honoured as
+ * that integer. `0` and negatives are honoured too (which is why this cannot
+ * reuse `intFlag`, whose "> 0" guard would floor them to the default).
+ *
+ * @returns {number}
+ */
+function derivePollTimeoutMs(flagValue, dflt = 30_000) {
+  if (flagValue === undefined || flagValue === null || String(flagValue).trim() === '') {
+    return dflt;
+  }
+  const n = Number.parseInt(String(flagValue), 10);
+  return Number.isFinite(n) ? n : dflt;
+}
 function isValidProfileName(name) {
   return typeof name === 'string' && /^[a-z0-9][a-z0-9._-]*$/i.test(name);
 }
@@ -1597,7 +1622,99 @@ function normalizeStoredProfile(name, profile) {
 }
 
 /**
- * hire — create (or overwrite) an agent profile. Interactive by default; every
+ * Merge additional capabilities into an already-normalized profile, returning a
+ * new profile object with the union of capabilities (canonical order) and a
+ * refreshed `updatedAt`. Pure (no config I/O), so it is unit-testable. Existing
+ * fields — including `createdAt` — are preserved. `incoming` may be a
+ * comma-string or an array. Returns `{ profile, added }`, where `added` lists
+ * the newly gained capabilities (empty when the assign is a no-op).
+ */
+function applyAssign(existing, incoming, now = new Date().toISOString()) {
+  const before = new Set(normalizeCapabilities(existing && existing.capabilities));
+  const union = normalizeCapabilities([...before, ...normalizeCapabilities(incoming)]);
+  const added = union.filter((c) => !before.has(c));
+  return {
+    profile: { ...existing, capabilities: union, updatedAt: now },
+    added,
+  };
+}
+
+/**
+ * Resolve the profile name and the raw comma-joined capability string for an
+ * `assign` invocation from parsed positionals + flags. Pure (no I/O) so the
+ * positional-slicing rules are unit-testable.
+ *
+ * When `--name` is supplied the name does NOT consume a positional, so every
+ * positional is a capability. Otherwise the first positional is the name and
+ * the rest are capabilities. `--capabilities a,b` is always appended.
+ */
+function resolveAssignInputs(req, flags) {
+  const positional = Array.isArray(req?.positional) ? req.positional : [];
+  const name = flags?.name ? String(flags.name).trim() : positional[0];
+  const positionalCaps = flags?.name ? positional : positional.slice(1);
+  const flagCaps = flags?.capabilities !== undefined ? String(flags.capabilities) : '';
+  const incomingRaw = [...positionalCaps, flagCaps].filter(Boolean).join(',');
+  return { name, incomingRaw };
+}
+
+/**
+ * assign — grant new capabilities (roles) to an existing hire without
+ * re-running `hire`. The profile name is positional[0] (or `--name`);
+ * capabilities are the remaining positionals and/or `--capabilities a,b`.
+ * Capabilities are unioned with the profile's existing set (additive; assign
+ * never removes a role) and the updated rank×capability job-type matrix is
+ * printed. Re-run `work` to pick up the new job types.
+ */
+async function assignCapabilities(req, flags) {
+  const logger = getLogger();
+  const { name, incomingRaw } = resolveAssignInputs(req, flags);
+  if (!name) {
+    logger.error('Usage: c8ctl nano assign <profileName> [<capability> ...] [--name <n>] [--capabilities <a,b>]');
+    logger.info('Grant new capabilities to an existing hire. List profiles with: c8ctl nano hire --list');
+    process.exit(1);
+  }
+  if (!isValidProfileName(name)) {
+    logger.error(`Invalid profile name "${name}". Use letters, digits, dot, dash or underscore.`);
+    process.exit(1);
+  }
+
+  if (normalizeCapabilities(incomingRaw).length === 0) {
+    logger.error('Provide at least one capability to assign.');
+    logger.info(`Example: c8ctl nano assign ${name} code-review testing`);
+    process.exit(1);
+  }
+
+  const raw = readHires()[name];
+  if (!raw) {
+    logger.error(`No hire named "${name}". List profiles with: c8ctl nano hire --list`);
+    process.exit(1);
+  }
+  const normalized = normalizeStoredProfile(name, raw);
+  if (normalized.error) {
+    logger.error(`Cannot assign to "${name}": ${normalized.error}. Re-create it with: c8ctl nano hire`);
+    process.exit(1);
+  }
+
+  // Preserve createdAt (normalizeStoredProfile drops it) on the canonical form.
+  const base = {
+    ...normalized.profile,
+    createdAt: typeof raw.createdAt === 'string' ? raw.createdAt : new Date().toISOString(),
+  };
+  const { profile, added } = applyAssign(base, incomingRaw);
+  if (added.length === 0) {
+    logger.info(`"${name}" already has: ${profile.capabilities.join(', ') || '(none)'} — no change.`);
+    return;
+  }
+  writeHire(profile);
+
+  const matrix = jobTypeMatrix(profile.rank, profile.capabilities);
+  logger.info(`Assigned to "${name}" [${profile.rank}]: +${added.join(', ')}`);
+  logger.info(`  capabilities: ${profile.capabilities.join(', ')}`);
+  logger.info(`  job types (${matrix.length}): ${matrix.join('  ')}`);
+  logger.info(`Restart its workers to pick up the new roles: c8ctl nano work ${name}`);
+}
+
+/**
  * field can also be supplied via a flag (--name/--rank/--command/--model/
  * --capabilities) for scripting. Prompts only for the fields still missing.
  * `--list` prints existing profiles instead.
@@ -2006,8 +2123,21 @@ function normalizeTaskEnvelope(customHeaders, variables) {
   };
 
   const task = isPlainObject(raw.task) ? raw.task : {};
+  // Base prompt: the reserved `task.prompt` (typically a model header filled at deploy time),
+  // else a plain `prompt`/`task` job variable (the pre-header delivery path).
+  const basePrompt = str(task.prompt) ?? str(variables?.prompt) ?? str(variables?.task);
+  // Verbatim dynamic append: a header-delivered base prompt can't be composed in FEEL, so a task
+  // may supply per-instance context (e.g. plan-revision feedback, a per-task brief) via the
+  // reserved `task.appendPrompt`, or a plain `appendPrompt` variable. It is concatenated onto the
+  // base with NO injected separator — the caller (the model's ioMapping) owns any leading
+  // separator/preamble — so a null/empty append leaves the base prompt untouched.
+  const appendPrompt = str(task.appendPrompt) ?? str(variables?.appendPrompt);
+  const prompt =
+    appendPrompt != null && appendPrompt !== ''
+      ? `${basePrompt ?? ''}${appendPrompt}`
+      : basePrompt;
   env.task = {
-    prompt: str(task.prompt) ?? str(variables?.prompt) ?? str(variables?.task),
+    prompt,
     promptFile: str(task.promptFile),
     maxIterations: coerceInt(task.maxIterations, undefined),
     timeoutMs: coerceInt(task.timeoutMs, undefined),
@@ -2730,6 +2860,11 @@ async function workAgent(req, flags) {
   // MUST enforce the clamped `jobKillMs` (not the raw --job-timeout), or a very
   // large --job-timeout would outlive the broker lock and re-break the invariant.
   const { killMs: jobKillMs, lockMs: jobLockMs } = deriveJobLockMs(jobTimeoutMs, lockGraceMs);
+  // Broker long-poll window: how long each activateJobs request is held open
+  // waiting for work. 30s default so idle workers hold one connection open ~30s
+  // rather than reconnecting every few seconds — fewer reconnects, fewer chances
+  // to hit a transient connect error on a flaky link. Passed to the SDK verbatim.
+  const pollTimeoutMs = derivePollTimeoutMs(flags?.['poll-timeout']);
 
   // Sandbox: flag overrides the stored profile default. `none` runs on the host
   // (legacy); `docker`/`podman` run each job in a throwaway labelled container.
@@ -2837,7 +2972,7 @@ async function workAgent(req, flags) {
   if (profileEnvKeys.length > 0) logger.info(`  harness env: ${profileEnvKeys.join(', ')}`);
   const extraNote = extraJobTypes.length > 0 ? ` (${extraJobTypes.length} via --job-type)` : '';
   logger.info(`  listening on ${jobTypes.length} job type(s)${extraNote}: ${jobTypes.join('  ')}`);
-  logger.info(`  max parallel: ${maxParallelJobs}; job timeout: ${jobKillMs}ms; activation lock: ${jobLockMs}ms`);
+  logger.info(`  max parallel: ${maxParallelJobs}; job timeout: ${jobKillMs}ms; activation lock: ${jobLockMs}ms; poll timeout: ${pollTimeoutMs}ms`);
   logger.info('Polling for work — press Ctrl-C to stop.');
 
   const workers = jobTypes.map((jobType) =>
@@ -2846,6 +2981,7 @@ async function workAgent(req, flags) {
       workerName: `${name}:${jobType}`,
       maxParallelJobs,
       jobTimeoutMs: jobLockMs,
+      pollTimeoutMs,
       jobHandler: async (job) => {
         logger.info(`[${jobType}] job ${job.jobKey} (instance ${job.processInstanceKey ?? '-'}) → ${buildAgentCommandLine(profile.command, effectiveArgs)}`);
 
@@ -4373,6 +4509,7 @@ export {
   webConsoleUrl,
   consoleLinkLabel,
   hireWorker,
+  assignCapabilities,
 };
 export {
   normalizeTaskEnvelope,
@@ -4407,9 +4544,12 @@ export {
   agentRunsRoot,
   ProvisionError,
   normalizeStoredProfile,
+  applyAssign,
+  resolveAssignInputs,
   jobTypeMatrix,
   parseJobTypeFlags,
   deriveJobLockMs,
+  derivePollTimeoutMs,
   AGENT_TASK_NS,
   AGENT_RESULT_KEY,
   RESULT_SENTINEL,
@@ -4495,12 +4635,12 @@ export const commands = {
       workspace: { type: 'boolean', description: 'clean: also delete the workspace (models + workers)' },
       check: { type: 'boolean', description: 'update: only report whether a new release is available; do not install' },
       binary: { type: 'string', description: 'Path to the nanobpmn server binary' },
-      name: { type: 'string', description: 'hire/work: agent profile name (alt to positional arg)' },
+      name: { type: 'string', description: 'hire/work/assign: agent profile name (alt to positional arg)' },
       rank: { type: 'string', description: 'hire: agent rank (principal|senior|junior|decider)' },
       command: { type: 'string', description: 'hire: CLI command that runs the agent harness (e.g. copilot, claude, pi)' },
       arg: { type: 'string', multiple: true, description: 'hire/work: command-line switch/arg appended to the harness command (repeatable), e.g. --arg --allow-all. Persisted on hire; work appends more.' },
       model: { type: 'string', description: 'hire: model name passed to the harness (AGENT_MODEL)' },
-      capabilities: { type: 'string', description: 'hire: comma-separated capability list' },
+      capabilities: { type: 'string', description: 'hire/assign: comma-separated capability list' },
       sandbox: { type: 'string', description: 'hire/work: execution sandbox none|docker|podman (default none). Containers isolate each job.' },
       image: { type: 'string', description: 'hire/work: container image the agent runs in (required for --sandbox docker|podman)' },
       env: { type: 'string', multiple: true, description: 'hire/work: static env var for the harness as NAME=VALUE (repeatable); persisted on hire, work extends/overrides. E.g. permission toggles.' },
@@ -4515,6 +4655,7 @@ export const commands = {
       'max-parallel': { type: 'string', description: 'work: max concurrent jobs per worker (default 1)' },
       'job-timeout': { type: 'string', description: 'work: max harness runtime per job in ms; the spawned process is killed past this (default 300000)' },
       'lock-grace': { type: 'string', description: 'work: extra ms added to --job-timeout to derive the broker activation lock, so the worker reports before the lock lapses (default 120000)' },
+      'poll-timeout': { type: 'string', description: 'work: broker long-poll window in ms each activateJobs request is held open (fewer reconnects → fewer transient connect errors); default 30000, 0 = broker default, negative = return immediately' },
       'job-type': { type: 'string', multiple: true, description: 'work: extra job type to service alongside the rank×capability matrix (repeatable)' },
     },
     handler: async (args, flags) => {
@@ -4567,6 +4708,9 @@ export const commands = {
           case 'hire':
             await hireWorker(req, flags);
             break;
+          case 'assign':
+            await assignCapabilities(req, flags);
+            break;
           case 'work':
             await workAgent(req, flags);
             break;
@@ -4659,7 +4803,8 @@ function printUsage() {
   console.log('  c8ctl nano config');
   console.log('  c8ctl nano update [--check]');
   console.log('  c8ctl nano hire [--name <n>] [--rank <r>] [--command <c>] [--arg <switch> ...] [--model <m>] [--capabilities <a,b>] [--sandbox none|docker|podman] [--image <ref>] [--env NAME=VALUE ...] [--list]');
-  console.log('  c8ctl nano work <profileName> [--arg <switch> ...] [--max-parallel <n>] [--job-timeout <ms>] [--lock-grace <ms>] [--job-type <token> ...] [--sandbox none|docker|podman] [--image <ref>] [--env NAME=VALUE ...] [--secret-resolver host] [--min-free-mb <n>] [--clone-timeout <ms>] [--keep-runs] [--stream]');
+  console.log('  c8ctl nano assign <profileName> [<capability> ...] [--name <n>] [--capabilities <a,b>]');
+  console.log('  c8ctl nano work <profileName> [--arg <switch> ...] [--max-parallel <n>] [--job-timeout <ms>] [--lock-grace <ms>] [--poll-timeout <ms>] [--job-type <token> ...] [--sandbox none|docker|podman] [--image <ref>] [--env NAME=VALUE ...] [--secret-resolver host] [--min-free-mb <n>] [--clone-timeout <ms>] [--keep-runs] [--stream]');
   console.log('');
   console.log('Subcommands:');
   console.log('  start    Spawn an N-node local cluster wired to talk to each other on localhost');
@@ -4674,6 +4819,7 @@ function printUsage() {
   console.log('  config   Show current configuration and on-disk locations');
   console.log('  update   Pull the latest published nano release (--check to only report)');
   console.log('  hire     Create a CLI agent worker profile (rank + capabilities → job-type matrix)');
+  console.log('  assign   Grant new capabilities (roles) to an existing hire (additive)');
   console.log('  work     Run a hired profile as Nano job workers, polling for work until Ctrl-C');
   console.log('');
   console.log('Options:');
@@ -4690,11 +4836,11 @@ function printUsage() {
   console.log('  --purge              stop: also delete per-node engine data');
   console.log('  --force              start: stop any existing cluster first');
   console.log('  --workspace          clean: also delete the workspace (models + workers)');
-  console.log('  --name <n>           hire/work: agent profile name (alt to positional arg)');
+  console.log('  --name <n>           hire/work/assign: agent profile name (alt to positional arg)');
   console.log('  --rank <r>           hire: agent rank (principal|senior|junior|decider)');
   console.log('  --command <c>        hire: CLI command that runs the agent harness');
   console.log('  --model <m>          hire: model name passed to the harness (AGENT_MODEL)');
-  console.log('  --capabilities <a,b> hire: comma-separated capability list');
+  console.log('  --capabilities <a,b> hire/assign: comma-separated capability list');
   console.log('  --sandbox <s>        hire/work: execution sandbox none|docker|podman (default none)');
   console.log('  --image <ref>        hire/work: container image the agent runs in (required for docker|podman)');
   console.log('  --env NAME=VALUE     hire/work: static env var for the harness (repeatable); persisted on hire, work extends/overrides');
@@ -4703,6 +4849,7 @@ function printUsage() {
   console.log('  --job-type <token>   work: extra job type to service alongside the rank×capability matrix (repeatable)');
   console.log('  --job-timeout <ms>   work: max harness runtime per job in ms (default 300000)');
   console.log('  --lock-grace <ms>    work: extra ms over --job-timeout for the broker activation lock (default 120000)');
+  console.log('  --poll-timeout <ms>  work: broker long-poll window per activateJobs request (default 30000; 0 = broker default, negative = immediate)');
   console.log('  --secret-resolver <r> work: secret resolver for task secretRefs (host; default host)');
   console.log('  --reap-age <ms>      work: age before a finished agent container/workspace is reaped (default 3600000)');
   console.log('  --reap-interval <ms> work: how often to sweep finished agent containers/workspaces (default 300000)');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.18.1",
+  "version": "1.19.0",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -42,19 +42,17 @@
   "devDependencies": {
     "@commitlint/cli": "^20.4.1",
     "@commitlint/config-conventional": "^20.4.1",
-    "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/exec": "^7.1.0",
-    "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.6",
     "semantic-release": "^25.0.3"
   },
   "optionalDependencies": {
-    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.18.1",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.18.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.18.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.18.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.18.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.18.1",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.18.1"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.19.0",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.19.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.19.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.19.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.19.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.19.0",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.19.0"
   }
 }