c8ctl-plugin-nano 1.41.0 → 1.42.1

package/README.md

@@ -157,6 +157,9 @@ c8ctl nano hire --name reviewer --rank senior --command copilot \
 # 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
 
+# Opt a role into the ACP harness mode (JSON-RPC/stdio) — see "ACP harness mode" below
+c8ctl nano hire --name coder --rank senior --command copilot --protocol acp
+
 # List profiles
 c8ctl nano hire --list
 ```
@@ -409,6 +412,86 @@ bound is operator-tunable for a long expected outage; raise it with
 `NANO_AGENTIC_BUFFER_CAPACITY` (frames). When the bound is hit the worker warns
 rather than silently shedding.
 
+### ACP harness mode (opt-in)
+
+Alongside the `pipe`/`pty` terminal choice above, a role can opt into driving its
+harness over the **[Agent Client Protocol (ACP)](https://agentclientprotocol.com)**
+— JSON-RPC 2.0 over stdio — instead of the default stdin/scrape **pipe**. ACP is
+**additive, not a switch**: `pipe` stays the default floor, so every CLI harness
+(and non-agent record-keepers) keeps working unchanged, and **YOLO stays the
+default** via auto-approve. You turn ACP on per role, exactly like `--terminal`:
+
+```bash
+# Drive a role's harness over ACP (JSON-RPC/stdio) instead of the pipe
+c8ctl nano hire --name coder --rank senior --command copilot --protocol acp
+
+# Override protocol/permission for a one-off worker without re-hiring
+NANO_AGENTIC_PROTOCOL=pipe c8ctl nano work coder
+NANO_AGENTIC_PERMISSION=escalate c8ctl nano work coder
+```
+
+- `--protocol pipe|acp` (default `pipe`) selects the harness protocol.
+  `NANO_AGENTIC_PROTOCOL` overrides it at work time (mirroring
+  `NANO_AGENTIC_TERMINAL`).
+- `--permission yolo|escalate|filter` (default `yolo`) selects the ACP permission
+  policy. `NANO_AGENTIC_PERMISSION` overrides it at work time.
+
+**What ACP unlocks.** Because the harness speaks a structured protocol rather than
+a scraped terminal, the ACP path gives you a **structured turn/tool event stream**
+(today serialized to text chunks on the relay lane — a *minimal* mode, not yet
+typed turn/tool envelopes), **native permission handling**, and **PTY-free
+steering** — an operator's
+steer text is delivered as a `session/prompt` and an interrupt as a
+`session/cancel`, with no keystroke injection. The ACP path therefore does **not**
+need the optional native `node-pty` dependency at all.
+
+**Permission policies — mind the status.** Only `yolo` is enforced today:
+
+- **`yolo`** *(default, the only enforced policy today)* — auto-allows every
+  permission request the agent raises: full speed, no human in the loop. This is
+  the same auto-approve posture the pipe/PTY paths already run with.
+- **`escalate`** and **`filter`** are **RESERVED / not-yet-active** in this build.
+  They are **accepted and persisted** for forward-compatibility, but they are
+  **not yet enforced**: at work time they fall back to a **safe interim policy**
+  (currently auto-allow, like `yolo`) and the CLI **emits a warning** so an
+  operator is never misled into thinking destructive operations are gated. Their
+  intended future behavior — **`escalate`** blocking a permission request until a
+  human answers it, and **`filter`** auto-allowing reads/edits while escalating
+  destructive operations — is **not available yet**; it lands once the companion
+  permission-event + escalation bridge (nanobpm/nano-workforce#559) ships.
+
+**Per-CLI hire examples.** Some CLIs speak ACP natively; others ride a thin
+adapter binary. In every case the profile's command (plus any `--arg`s) assembles
+the ACP invocation; a default `--acp` switch is appended only when the assembled
+command line doesn't already select ACP, so a native/adapter invocation is never
+doubled. All of these run with the enforced default `yolo` policy:
+
+```bash
+# Copilot CLI — native ACP (assembles `copilot --acp`)
+c8ctl nano hire --name coder --rank senior --command copilot --protocol acp --permission yolo
+
+# OpenCode — native ACP server (assembles `opencode acp`)
+c8ctl nano hire --name coder --rank senior --command opencode --arg acp --protocol acp --permission yolo
+
+# Claude Code — via the `claude-agent-acp` adapter
+c8ctl nano hire --name coder --rank senior --command claude-agent-acp --protocol acp --permission yolo
+
+# Pi — via the `pi-acp` adapter
+c8ctl nano hire --name coder --rank senior --command pi-acp --protocol acp --permission yolo
+```
+
+> `--permission yolo` is the default, so you can omit it. You **may** hire with
+> `--permission escalate` or `--permission filter` today — the value is persisted
+> — but it is **reserved / not-yet-active** (pending nanobpm/nano-workforce#559)
+> and currently behaves as the safe interim policy with a warning, so do **not**
+> rely on it to gate destructive operations yet.
+
+**Non-goals.** ACP does not replace anything: the **pipe/PTY** surface stays the
+default floor and every existing harness keeps working unchanged (ACP is enforced
+on the host executor; container sandboxes remain **pipe-only** for now). There is
+**no change to the Camunda-8 worker⇄engine job protocol** — ACP governs only how a
+worker drives its local agent harness, not how it talks to the engine.
+
 ### Live profile reload (no restart on `assign`)
 
 A running `c8ctl nano work <name>` **watches** the profile it is servicing. When

package/c8ctl-plugin.js

@@ -4026,11 +4026,15 @@ const ACP_MAX_LINE_BYTES = 8 * 1024 * 1024; // 8 MiB
 
 // Drive an ACP (Agent Client Protocol) agent over JSON-RPC 2.0 on stdio.
 //
-// This is the "minimal mode" executor (#110, step 1): it proves ACP end-to-end
-// with ZERO downstream changes by serialising each `session/update` to a short
-// human-readable TEXT chunk and feeding it to the SAME relay/tee lane the pipe
-// path uses (`relayTap.onData`) — it never tee's the raw JSON-RPC. Typed
-// transcript envelopes are a separate downstream task.
+// This executor drives ACP end-to-end. Each `session/update` is mapped to a
+// typed `nwfTranscriptEvent` envelope (#110, step 2) and published on the relay
+// session's typed publish seam (`relayTap.relayEnvelope`) — the rich cockpit
+// format its derive+render consumes. The raw relay TRANSPORT is untouched (still
+// `relaySession.relay(text)`); only the payload shape on the lane changes. When
+// an update has no typed mapping, or the relay exposes no typed seam (minimal
+// mode / a plain tap), it falls back to the step-1 human-TEXT chunk on the same
+// lane (`relayTap.onData`) so nothing is dropped. The raw JSON-RPC is never
+// tee'd either way.
 //
 // Framing: ACP frames are newline-delimited JSON-RPC 2.0 messages on stdio (one
 // compact JSON object per line, `\n`-terminated). We implement a tiny inline
@@ -4111,22 +4115,35 @@ function spawnCaptureAcp({ command, args = [], cwd, env, stdinData, timeoutMs, i
 
     const humanStdout = () => joinCapped(humanChunks);
 
-    // Emit a human-meaningful text chunk on the SAME lanes the pipe/pty paths
-    // use: the relay tap (framed + jobKey-tagged by the caller) and the local
-    // --stream spy tee. Byte-capped like the raw captures.
-    const emitHuman = (text) => {
+    // Local mirrors of a human text chunk: the --stream spy tee and the byte-
+    // capped stdout capture (what the result envelope carries). Deliberately does
+    // NOT touch the relay lane, so a typed-transcript update can mirror its human
+    // text locally (for the result + spy) WITHOUT also re-emitting raw text onto
+    // the relay lane — which, in step 2, carries the typed envelope instead.
+    const captureHuman = (text) => {
       if (!text) return;
       const buf = Buffer.from(text, 'utf8');
       if (teeSink) tee(text, false);
-      if (relayTap && typeof relayTap.onData === 'function') {
-        try { relayTap.onData(text); } catch { /* relay best-effort */ }
-      }
       const remaining = MAX_CAPTURE_BYTES - humanBytes;
       if (remaining <= 0) { humanTruncated = true; return; }
       if (buf.length > remaining) { humanChunks.push(buf.subarray(0, remaining)); humanBytes = MAX_CAPTURE_BYTES; humanTruncated = true; }
       else { humanChunks.push(buf); humanBytes += buf.length; }
     };
 
+    // Emit a human-meaningful text chunk on the SAME lanes the pipe/pty paths
+    // use: the relay tap (framed + jobKey-tagged by the caller) and the local
+    // --stream spy tee. Byte-capped like the raw captures. This is the minimal-
+    // mode text path — used for stderr, and as the fallback for any session/update
+    // that has no typed nwfTranscriptEvent mapping (or when the relay exposes no
+    // typed publish seam).
+    const emitHuman = (text) => {
+      if (!text) return;
+      if (relayTap && typeof relayTap.onData === 'function') {
+        try { relayTap.onData(text); } catch { /* relay best-effort */ }
+      }
+      captureHuman(text);
+    };
+
     const finish = (result) => {
       if (settled) return;
       settled = true;
@@ -4200,25 +4217,30 @@ function spawnCaptureAcp({ command, args = [], cwd, env, stdinData, timeoutMs, i
       }
     };
 
-    // Serialise an ACP session/update into a short human-readable line. Minimal
-    // mode: this is TEXT for the existing cockpit lane, not a typed envelope.
+    // Extract plain text from an ACP content value (string, {type,text}, or an
+    // array of content blocks). Shared by the typed-envelope mapper and the
+    // human-text describer so both agree on what the "text" of an update is.
+    const acpTextOf = (content) => {
+      if (content == null) return '';
+      if (typeof content === 'string') return content;
+      if (Array.isArray(content)) return content.map(acpTextOf).join('');
+      if (typeof content === 'object') return typeof content.text === 'string' ? content.text : '';
+      return '';
+    };
+
+    // Serialise an ACP session/update into a short human-readable line. This is
+    // the minimal-mode TEXT for the existing cockpit lane (the fallback), not a
+    // typed envelope.
     const describeUpdate = (update) => {
       if (!update || typeof update !== 'object') return '';
       const kind = update.sessionUpdate || update.type || 'update';
-      const textOf = (content) => {
-        if (content == null) return '';
-        if (typeof content === 'string') return content;
-        if (Array.isArray(content)) return content.map(textOf).join('');
-        if (typeof content === 'object') return typeof content.text === 'string' ? content.text : '';
-        return '';
-      };
       switch (kind) {
         case 'agent_message_chunk':
-          return textOf(update.content);
+          return acpTextOf(update.content);
         case 'agent_thought_chunk':
-          return `\u{1F4AD} ${textOf(update.content)}`;
+          return `\u{1F4AD} ${acpTextOf(update.content)}`;
         case 'user_message_chunk':
-          return textOf(update.content);
+          return acpTextOf(update.content);
         case 'tool_call': {
           const title = update.title || update.toolCallId || 'tool';
           return `\u2699 [tool: ${title}${update.status ? ` — ${update.status}` : ''}]\n`;
@@ -4234,6 +4256,80 @@ function spawnCaptureAcp({ command, args = [], cwd, env, stdinData, timeoutMs, i
       }
     };
 
+    // #110 step 2: map an ACP session/update to a typed `nwfTranscriptEvent`
+    // envelope — the rich cockpit wire format (the existing downstream
+    // derive+render consumes it). Returns null for an update kind we don't model,
+    // so the caller falls back to the minimal human-text path (nothing dropped,
+    // no regression vs step 1). The `text` field carries the same plain text the
+    // fallback would relay, so a lightweight consumer can still render it.
+    const TRANSCRIPT_EVENT_TYPE = 'nwfTranscriptEvent';
+    const TRANSCRIPT_EVENT_VERSION = 1;
+    const mapTranscriptEnvelope = (update) => {
+      if (!update || typeof update !== 'object') return null;
+      const kind = update.sessionUpdate || update.type;
+      if (!kind) return null;
+      const base = { type: TRANSCRIPT_EVENT_TYPE, v: TRANSCRIPT_EVENT_VERSION, ts: Date.now() };
+      // Optional fields stay `undefined` (JSON encoding omits them) rather than
+      // becoming explicit `null`s, and `??` preserves empty strings — so
+      // consumers see omitted/optional strings, not coerced nulls. `status`
+      // falls through to the kind's default only when genuinely absent.
+      const toolOf = (u, defaultStatus) => ({
+        id: u.toolCallId ?? undefined,
+        title: u.title ?? undefined,
+        status: u.status ?? defaultStatus ?? undefined,
+        kind: u.kind ?? undefined,
+      });
+      switch (kind) {
+        case 'agent_message_chunk':
+          return { ...base, kind: 'message', role: 'agent', text: acpTextOf(update.content) };
+        case 'agent_thought_chunk':
+          return { ...base, kind: 'thought', role: 'agent', text: acpTextOf(update.content) };
+        case 'user_message_chunk':
+          return { ...base, kind: 'message', role: 'user', text: acpTextOf(update.content) };
+        case 'tool_call':
+          // `text` mirrors the fallback's plain text so the typed envelope stays
+          // self-contained for lightweight renderers (matches the stated contract).
+          return { ...base, kind: 'tool_call', text: describeUpdate(update), tool: toolOf(update, 'pending') };
+        case 'tool_call_update':
+          return { ...base, kind: 'tool_call_update', text: describeUpdate(update), tool: toolOf(update, undefined) };
+        case 'plan':
+          // Carry the actual plan entries (rich cockpit renders them), not a
+          // count — an absent/malformed payload stays `undefined` (omitted).
+          return { ...base, kind: 'plan', entries: Array.isArray(update.entries) ? update.entries : undefined };
+        default:
+          // Unmodelled kind → no typed envelope; caller uses the text fallback.
+          return null;
+      }
+    };
+
+    // Publish a session/update: prefer the typed nwfTranscriptEvent envelope on
+    // the relay's typed publish seam; fall back to the minimal human-text path
+    // when the update has no typed mapping OR the relay exposes no typed seam, so
+    // nothing is ever dropped (no regression vs minimal mode).
+    const emitTranscript = (update) => {
+      const env = mapTranscriptEnvelope(update);
+      if (env && relayTap && typeof relayTap.relayEnvelope === 'function') {
+        // Only skip the text fallback when the typed publish ACTUALLY succeeded.
+        // If the seam throws (a downstream tap implementation, not just the
+        // built-in best-effort stringify guard), the envelope never reached the
+        // relay lane — so we must fall through to the text path or that update
+        // would be silently dropped, breaking the "nothing is ever dropped"
+        // guarantee.
+        let published = false;
+        try { relayTap.relayEnvelope(env); published = true; } catch { /* relay best-effort */ }
+        if (published) {
+          // Mirror the human text locally (spy tee + captured stdout) so the
+          // result envelope and --stream spy are unchanged — without re-emitting
+          // raw text onto the relay lane, which now carries the typed envelope.
+          captureHuman(describeUpdate(update));
+          return;
+        }
+        // Typed publish threw → fall through to the text lane below.
+      }
+      // Fallback: minimal text-chunk path (relay text + spy tee + capture).
+      emitHuman(describeUpdate(update));
+    };
+
     const handleMessage = (msg) => {
       if (!msg || typeof msg !== 'object') return;
       // A response to one of OUR requests.
@@ -4248,7 +4344,7 @@ function spawnCaptureAcp({ command, args = [], cwd, env, stdinData, timeoutMs, i
       }
       // A request or notification FROM the agent.
       if (typeof msg.method === 'string') {
-        if (msg.method === 'session/update') { emitHuman(describeUpdate(msg.params?.update)); return; }
+        if (msg.method === 'session/update') { emitTranscript(msg.params?.update); return; }
         if (msg.method === 'session/request_permission') {
           if (msg.id !== undefined) handlePermission(msg.id, msg.params);
           return;
@@ -4590,6 +4686,18 @@ function runAgentJob(profile, job, opts = {}) {
   const relayTap = relaySession
     ? {
         onData: (buf) => relaySession.relay(buf),
+        // #110 step 2: typed transcript publish seam. The ACP producer maps each
+        // session/update to an `nwfTranscriptEvent` envelope and publishes it
+        // here; we JSON-encode it (newline-delimited) onto the SAME relay lane —
+        // the raw relay TRANSPORT (ring/QoS/offsets/jobKey routing) is unchanged,
+        // still `relaySession.relay(text)`. Consumers (cockpit derive+render)
+        // parse the envelope; unmapped updates fall back to the `onData` text path
+        // so nothing is dropped (no regression vs the minimal-mode floor).
+        // Best-effort: a bad envelope (circular refs / BigInt making
+        // JSON.stringify throw) must never crash the worker, so swallow here.
+        relayEnvelope: (env) => {
+          try { relaySession.relay(`${JSON.stringify(env)}\n`); } catch { /* relay best-effort */ }
+        },
         attachSteer: (write) => relaySession.attachSteer(write),
       }
     : null;

package/nanobpmn-binary.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.15",
-  "commit": "a2d2d77",
-  "updated": "2026-08-18T06:11:07Z"
+  "version": "0.0.16",
+  "commit": "9014e90",
+  "updated": "2026-08-26T23:27:46Z"
 }

package/package.json

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