c8ctl-plugin-nano 1.16.0 → 1.18.0

package/README.md

@@ -150,6 +150,9 @@ c8ctl nano hire
 c8ctl nano hire --name reviewer --rank senior --command copilot \
   --model gpt-5 --capabilities code-review,testing
 
+# Give the harness command-line switches (e.g. run copilot with --allow-all)
+c8ctl nano hire --name coder --rank senior --command copilot --arg --allow-all
+
 # List profiles
 c8ctl nano hire --list
 ```
@@ -327,6 +330,24 @@ envelope layers on top (job-specific tuning wins), and the reserved `AGENT_*`
 variables and resolved secrets always win over user-supplied env so they can't be
 shadowed. For **secret** values use `secretRefs`, not `--env`.
 
+**Command-line switches.** Some harnesses take switches rather than env vars —
+e.g. `copilot --allow-all`. Append them to the harness command with a repeatable
+`--arg` (each `--arg` is one argv token). They are persisted on the profile at
+hire time and can be extended at work time:
+
+```bash
+c8ctl nano hire --name coder --rank senior --command copilot --arg --allow-all
+c8ctl nano work coder --arg --verbose            # appends to the profile args
+```
+
+The command is spawned through a shell (so `command` still resolves on `PATH`),
+but each `--arg` is shell-quoted as a single literal token, so a value with
+spaces or shell metacharacters can't break out or inject. They apply on the
+container path on any OS, and on the host path on POSIX systems. **On a Windows
+host (`sandbox=none`), `--arg` is rejected** with a clear error — the POSIX
+quoting isn't honoured by `cmd.exe` — so use a container sandbox
+(`--sandbox docker|podman`) or bake the switches into `--command` there.
+
 **Disk hygiene.** Host job **workspaces** and container sandboxes both get
 automatic cleanup so leaked artifacts can't fill the disk. Workspaces under
 `<state>/agent-runs` are removed after each job and swept at startup + on

package/c8ctl-plugin.js

@@ -461,6 +461,19 @@ function webConsoleUrl(baseUrl) {
   return `${baseUrl}/console`;
 }
 
+/**
+ * Human label for the console link, keyed on the runtime console profile.
+ * The default `studio` profile IS the full web IDE, so name it as such — users
+ * kept missing that Nano ships a browser IDE when it was labelled "Web console".
+ * `observe` is the read-only console. `off` serves no console, so the label is
+ * meaningless there; callers must guard `profile !== 'off'` before rendering it,
+ * and this helper returns null for `off` to enforce that contract.
+ */
+function consoleLinkLabel(profile) {
+  if (profile === 'off') return null;
+  return profile === 'studio' ? 'Web IDE (Studio)' : `Web console (${profile})`;
+}
+
 /** Probe a node's always-on GET /v2/topology endpoint for reachability. */
 async function probeHealthy(url) {
   const controller = new AbortController();
@@ -788,6 +801,7 @@ async function startCluster(req) {
     inMemory,
     historyMax: historyMax ?? null,
     basePort,
+    consoleProfile,
     nodes,
   };
   writeState(state);
@@ -834,15 +848,22 @@ async function printSummary(state) {
   // The landing page (and the /docs user guide + /console) only exist in builds
   // compiled with the web console; probe so we advertise the right entry point.
   const hasConsole = await probePath(entry.url, '/');
-  if (hasConsole) {
-    console.log(`  Start here   ${entry.url}/          (landing: console, user guide & API docs)`);
+  const profile = state.consoleProfile ?? 'studio';
+  // Lead with the web IDE — it is Nano's headline surface and the thing users
+  // most often did not realise was there. Only advertise it when this build
+  // actually serves a console and the profile is not 'off'.
+  if (hasConsole && profile !== 'off') {
+    console.log(`  ${consoleLinkLabel(profile)}   ${webConsoleUrl(entry.url)}`);
+    const surface = profile === 'studio' ? 'the Nano web IDE' : 'the Nano web console';
+    console.log(`    ^ open this in your browser: ${surface}`);
+    console.log('');
   }
-  console.log(`  REST API     ${entry.url}/v2`);
-  console.log(`  Topology     ${entry.url}/v2/topology`);
   if (hasConsole) {
-    console.log(`  Web console  ${webConsoleUrl(entry.url)}`);
+    console.log(`  Landing      ${entry.url}/          (console, user guide & API docs)`);
     console.log(`  User guide   ${entry.url}/docs`);
   }
+  console.log(`  REST API     ${entry.url}/v2`);
+  console.log(`  Topology     ${entry.url}/v2/topology`);
   if (state.workspaceDir) {
     console.log(`  Workspace    ${state.workspaceDir} (models/, workers/)`);
   }
@@ -1052,6 +1073,21 @@ async function statusCluster(req) {
   }
   console.log('');
 
+  // Surface the web IDE again here so it stays discoverable long after the
+  // initial `start` scrolled off — probe a healthy node so we only advertise a
+  // console that is actually served (API-only builds 404 `/`).
+  const profile = state.consoleProfile ?? 'studio';
+  if (overall !== 'stopped' && profile !== 'off') {
+    // Only probe a HEALTHY node: it already answered /v2/topology this run, so
+    // GET / returns fast. Falling back to a merely-alive (unreachable) node
+    // would add a full probe timeout to every `nano status` in a degraded state.
+    const consoleNode = checks.find((c) => c.healthy);
+    if (consoleNode && (await probePath(consoleNode.url, '/'))) {
+      console.log(`  ${consoleLinkLabel(profile)}   ${webConsoleUrl(consoleNode.url)}`);
+      console.log('');
+    }
+  }
+
   // Enrich with the live topology when reachable — the authoritative view of
   // partition leadership across the cluster.
   if (topo) {
@@ -1380,6 +1416,39 @@ function parseEnvPairs(input) {
   return { env, errors };
 }
 
+// Normalize a stored/CLI argument list (string | string[]) into a clean string[]:
+// each entry is one whole argv token (e.g. "--allow-all"), coerced to a string,
+// with null/undefined and empty tokens dropped. Interior whitespace is preserved
+// so a single arg may carry a value like "--foo=a b" intact.
+function normalizeArgList(input) {
+  const list = input == null ? [] : (Array.isArray(input) ? input : [input]);
+  const out = [];
+  for (const item of list) {
+    if (item == null) continue;
+    const s = String(item);
+    if (s.length === 0) continue;
+    out.push(s);
+  }
+  return out;
+}
+
+// POSIX single-quote a string so it survives `sh -c`/shell:true as one literal
+// argv token, no matter what it contains (spaces, $, quotes, globs). Empty
+// string → ''. This is what keeps structured `--arg` values injection-safe even
+// though the harness is spawned through a shell (for PATH resolution).
+function shQuote(s) {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}
+
+// Build the shell command line for the agent harness: the base command followed
+// by each structured argument, shell-quoted. With no args the command is used
+// verbatim (preserving pre-existing hires that baked switches into the command).
+function buildAgentCommandLine(command, args) {
+  const list = normalizeArgList(args);
+  if (list.length === 0) return command;
+  return `${command} ${list.map(shQuote).join(' ')}`;
+}
+
 // A worker job-type token: rank/capability tokens use `:` (rank↔cap) and `+`
 // (combined caps) as delimiters, and code-first `@nanobpm/workflow` job types
 // are `<flowId>:<taskName>` or an explicit override. The first character must be
@@ -1477,6 +1546,7 @@ function normalizeStoredProfile(name, profile) {
       name,
       rank,
       command,
+      args: normalizeArgList(profile.args),
       model: typeof profile.model === 'string' ? profile.model.trim() : '',
       capabilities: normalizeCapabilities(profile.capabilities),
       sandbox,
@@ -1505,7 +1575,7 @@ async function hireWorker(req, flags) {
     logger.info('Hired agent profiles:');
     for (const name of names.sort()) {
       const p = hires[name];
-      logger.info(`  ${name}  [${p.rank}]  ${p.command}  (model: ${p.model || '-'}; caps: ${normalizeCapabilities(p.capabilities).join(', ') || '-'})`);
+      logger.info(`  ${name}  [${p.rank}]  ${buildAgentCommandLine(p.command, p.args)}  (model: ${p.model || '-'}; caps: ${normalizeCapabilities(p.capabilities).join(', ') || '-'})`);
     }
     logger.info('');
     logger.info('Put one to work with: c8ctl nano work <name>');
@@ -1521,11 +1591,14 @@ async function hireWorker(req, flags) {
   let capabilities = flags?.capabilities !== undefined ? flags.capabilities : undefined;
   let sandbox = flags?.sandbox !== undefined ? String(flags.sandbox).trim().toLowerCase() : undefined;
   let image = flags?.image !== undefined ? String(flags.image).trim() : undefined;
+  // Structured command-line switches appended to the command when spawned, e.g.
+  // `--arg --allow-all` for `copilot`. Repeatable; each --arg is one argv token.
+  const commandArgs = normalizeArgList(flags?.arg);
   const envFromFlags = flags?.env !== undefined;
   const { env: profileEnv, errors: envErrors } = parseEnvPairs(flags?.env);
   if (envErrors.length > 0) {
     logger.error(envErrors.join('; '));
-    logger.info('Example: c8ctl nano hire --name coder --rank senior --command copilot --env COPILOT_ENABLE_ALL_TOOLS=1 --env FOO=bar');
+    logger.info('Example: c8ctl nano hire --name coder --rank senior --command copilot --arg --allow-all --env COPILOT_ENABLE_ALL_TOOLS=1');
     process.exit(1);
   }
 
@@ -1623,6 +1696,7 @@ async function hireWorker(req, flags) {
     name,
     rank,
     command,
+    args: commandArgs,
     model: model || '',
     capabilities: normalizeCapabilities(capabilities),
     sandbox,
@@ -1633,9 +1707,10 @@ async function hireWorker(req, flags) {
   writeHire(profile);
 
   const matrix = jobTypeMatrix(profile.rank, profile.capabilities);
-  logger.info(`${existed ? 'Updated' : 'Hired'} "${name}" [${profile.rank}] → ${profile.command}`);
+  logger.info(`${existed ? 'Updated' : 'Hired'} "${name}" [${profile.rank}] → ${buildAgentCommandLine(profile.command, profile.args)}`);
   logger.info(`  model: ${profile.model || '(none)'}`);
   logger.info(`  capabilities: ${profile.capabilities.join(', ') || '(none)'}`);
+  if (profile.args.length > 0) logger.info(`  args: ${profile.args.map(shQuote).join(' ')}`);
   logger.info(`  sandbox: ${profile.sandbox}${CONTAINER_SANDBOXES.has(profile.sandbox) ? ` (image ${profile.image})` : ''}`);
   const envKeys = Object.keys(profile.env);
   if (envKeys.length > 0) logger.info(`  env: ${envKeys.join(', ')}`);
@@ -2414,9 +2489,13 @@ function baseAgentEnv(profile, job) {
  * Both paths resolve to the same result contract.
  */
 function runAgentJob(profile, job, opts = {}) {
-  const { timeoutMs, envelope, sandbox = 'none', image, runId, secretEnv = {}, passThroughSecretNames = [], cwd, extraEnv = {}, profileEnv = {}, resultFile, stream = false, streamPrefix = '', onStreamOut, onStreamErr } = opts;
+  const { timeoutMs, envelope, sandbox = 'none', image, runId, secretEnv = {}, passThroughSecretNames = [], cwd, extraEnv = {}, profileEnv = {}, resultFile, stream = false, streamPrefix = '', onStreamOut, onStreamErr, args: commandArgs } = opts;
   const payload = JSON.stringify(buildAgentPayload(profile, job, envelope));
   const agentEnv = baseAgentEnv(profile, job);
+  // The harness command line: the profile command plus its structured switches
+  // (persisted `--arg`s, possibly extended at work time via opts.args), each
+  // shell-quoted. Spawned through a shell so `command` still resolves on PATH.
+  const commandLine = buildAgentCommandLine(profile.command, commandArgs ?? profile.args);
   // Static, non-secret env for the harness: the worker/profile's env (e.g. a
   // harness's permission toggles) plus the per-job envelope's setup.env
   // (job-specific tuning wins over the profile default). Reserved AGENT_* and
@@ -2425,9 +2504,16 @@ function runAgentJob(profile, job, opts = {}) {
 
   if (!CONTAINER_SANDBOXES.has(sandbox)) {
     // Host: hand the agent the result file by its real path.
+    // Defense in depth: --arg tokens are POSIX single-quoted, which cmd.exe on
+    // a Windows host does not honour, so args would be mis-parsed under the
+    // shell:true spawn. workAgent already rejects this at startup, but guard the
+    // spawn site too so the invariant holds for any direct caller of runAgentJob.
+    if (commandLine !== profile.command && process.platform === 'win32') {
+      return Promise.resolve({ ok: false, exitCode: null, stdout: '', stderr: '', error: 'command-line args (--arg) are not supported for host execution on Windows; use a container sandbox or bake switches into the command', truncated: false, stderrTruncated: false });
+    }
     const resultEnv = resultFile ? { [AGENT_RESULT_FILE_ENV]: resultFile } : {};
     return spawnCaptureOneShot({
-      command: profile.command,
+      command: commandLine,
       shell: true,
       // Own process group so the timeout handler can kill the whole tree.
       detached: process.platform !== 'win32',
@@ -2480,7 +2566,7 @@ function runAgentJob(profile, job, opts = {}) {
     ...mountArgs,
     ...envArgs,
     image,
-    'sh', '-c', profile.command,
+    'sh', '-c', commandLine,
   ];
 
   return spawnCaptureOneShot({
@@ -2582,6 +2668,11 @@ async function workAgent(req, flags) {
   }
   const profileEnv = { ...profile.env, ...workEnv };
 
+  // Structured command-line switches: the profile's persisted `--arg`s, extended
+  // by any work-time `--arg` (appended). Lets an operator add switches (e.g.
+  // `--allow-all`) at dispatch time without re-hiring.
+  const effectiveArgs = [...profile.args, ...normalizeArgList(flags?.arg)];
+
   const intFlag = (v, dflt) => {
     const n = Number.parseInt(String(v ?? ''), 10);
     return Number.isFinite(n) && n > 0 ? n : dflt;
@@ -2602,6 +2693,17 @@ async function workAgent(req, flags) {
     logger.error(`--sandbox ${sandbox} requires an --image (or hire the profile with --image).`);
     process.exit(1);
   }
+  // Structured --arg tokens are POSIX single-quoted (shQuote) for the harness
+  // shell. On the host path that shell is the platform default — cmd.exe on
+  // Windows, which does not honour single quotes — so the quoting would leak
+  // literal quote characters and mis-parse the switches. The container path
+  // always targets the image's `sh`, so it stays correct regardless of host OS.
+  // Fail fast with actionable guidance rather than silently corrupting argv.
+  if (!isContainer && effectiveArgs.length > 0 && process.platform === 'win32') {
+    logger.error('--arg is not supported for host execution on Windows (cmd.exe does not honour POSIX quoting).');
+    logger.error('Use a container sandbox (--sandbox docker|podman --image <ref>) or bake the switches into --command.');
+    process.exit(1);
+  }
 
   const secretResolver = makeSecretResolver(flags?.['secret-resolver']);
   if (!secretResolver) {
@@ -2677,7 +2779,7 @@ async function workAgent(req, flags) {
   const jobTypes = [...new Set([...matrix, ...extraJobTypes])];
   const camunda = globalThis.c8ctl.createClient();
 
-  logger.info(`Putting "${name}" [${profile.rank}] to work → ${profile.command}`);
+  logger.info(`Putting "${name}" [${profile.rank}] to work → ${buildAgentCommandLine(profile.command, effectiveArgs)}`);
   logger.info(`  model: ${profile.model || '(none)'}; capabilities: ${profile.capabilities.join(', ') || '(none)'}`);
   logger.info(`  sandbox: ${sandbox}${isContainer ? ` (image ${image})` : ''}`);
   const profileEnvKeys = Object.keys(profileEnv);
@@ -2694,7 +2796,7 @@ async function workAgent(req, flags) {
       maxParallelJobs,
       jobTimeoutMs,
       jobHandler: async (job) => {
-        logger.info(`[${jobType}] job ${job.jobKey} (instance ${job.processInstanceKey ?? '-'}) → ${profile.command}`);
+        logger.info(`[${jobType}] job ${job.jobKey} (instance ${job.processInstanceKey ?? '-'}) → ${buildAgentCommandLine(profile.command, effectiveArgs)}`);
 
         // Disk-budget admission shed: if the engine data root is below the free
         // floor, don't start a container — fail (retryable) so work sheds until
@@ -2788,6 +2890,7 @@ async function workAgent(req, flags) {
             resultFile,
             stream,
             streamPrefix: `[${jobType} ${job.jobKey}] `,
+            args: effectiveArgs,
             // Route the --stream tee through c8ctl's output-mode-aware logger so
             // spying never corrupts a structured/JSON output mode.
             onStreamOut: stream ? (line) => logger.info(line) : undefined,
@@ -4217,6 +4320,7 @@ export { resolveBinary, findBinary, launcherEnvMarkers };
 export { buildNpmInvocation };
 export {
   webConsoleUrl,
+  consoleLinkLabel,
   hireWorker,
 };
 export {
@@ -4236,6 +4340,9 @@ export {
   sanitizeResultVars,
   parseEnvPairs,
   normalizeEnvMap,
+  normalizeArgList,
+  shQuote,
+  buildAgentCommandLine,
   reapAgentContainers,
   diskBudgetOk,
   containerEngineAvailable,
@@ -4290,6 +4397,7 @@ export const metadata = {
         { command: 'c8ctl nano update --check', description: 'Check whether a newer nano release is available' },
         { command: 'c8ctl nano hire', description: 'Interactively create a CLI agent worker profile (name, rank, command, model, capabilities)' },
         { command: 'c8ctl nano hire --name reviewer --rank senior --command copilot --model gpt-5 --capabilities code-review,testing', description: 'Create a profile non-interactively' },
+        { command: 'c8ctl nano hire --name coder --rank senior --command copilot --arg --allow-all', description: 'Hire copilot with a command-line switch (copilot --allow-all)' },
         { command: 'c8ctl nano hire --name coder --rank senior --command copilot --env COPILOT_ENABLE_ALL_TOOLS=1', description: 'Persist a harness startup env var (e.g. permissions) on the profile' },
         { command: 'c8ctl nano hire --list', description: 'List hired agent profiles' },
         { command: 'c8ctl nano hire --name coder --rank senior --command "agent-harness" --sandbox docker --image ghcr.io/acme/agent:1', description: 'Create a profile that runs each job in a throwaway Docker container' },
@@ -4338,6 +4446,7 @@ export const commands = {
       name: { type: 'string', description: 'hire/work: 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' },
       sandbox: { type: 'string', description: 'hire/work: execution sandbox none|docker|podman (default none). Containers isolate each job.' },
@@ -4496,8 +4605,8 @@ function printUsage() {
   console.log('  c8ctl nano set <bin|model-dir> <path>');
   console.log('  c8ctl nano config');
   console.log('  c8ctl nano update [--check]');
-  console.log('  c8ctl nano hire [--name <n>] [--rank <r>] [--command <c>] [--model <m>] [--capabilities <a,b>] [--sandbox none|docker|podman] [--image <ref>] [--env NAME=VALUE ...] [--list]');
-  console.log('  c8ctl nano work <profileName> [--max-parallel <n>] [--job-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('  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>] [--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');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -49,12 +49,12 @@
     "semantic-release": "^25.0.3"
   },
   "optionalDependencies": {
-    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.16.0",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.16.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.16.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.16.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.16.0",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.16.0",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.16.0"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.18.0",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.18.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.18.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.18.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.18.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.18.0",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.18.0"
   }
 }