c8ctl-plugin-nano 1.57.1 → 1.58.0

package/acp-transcript-producer.mjs

@@ -0,0 +1,131 @@
+// Producer-side ACP → transcript-chunk mapping that PRESERVES message boundaries
+// (jwulf/c8ctl-plugin-nano#206), built on top of the published shared contract
+// from nanobpm/nano-ide#566 (@nanobpm/agentic >= 0.14.0).
+//
+// The problem: streaming ACP output arrives as arbitrary `agent_message_chunk`
+// deltas whose transport boundaries are NOT message boundaries. The canonical
+// bridge `acpUpdateToTranscriptChunk` (nanobpm/nano-ide#534) folds an ACP
+// `session/update` into the exact transcript-chunk bytes the cockpit decodes, but
+// it drops the ACP `messageId` that the shared classifier already extracts — so a
+// consumer folding those chunks through the shared ordered-display derivation
+// (`deriveDisplay`, #566) cannot tell a continuing delta of ONE message from the
+// first delta of a NEW same-speaker message. Two distinct assistant messages
+// emitted back-to-back would wrongly coalesce into one block; a single message
+// split across chunks reconstructs correctly either way.
+//
+// This module carries the AVAILABLE producer semantics — message identity
+// (`messageId`), role/channel and delta/snapshot mode — into the canonical
+// additive `MessageEvent` fields the shared contract added in #566, using the
+// SHARED classifier (`classifyUpdate`) and the SHARED canonical encoder
+// (`encodeTranscriptEvent`). It does NOT hand-roll a parallel wire grammar,
+// grouping implementation or heuristic sentence splitter: the marker, version,
+// kinds and additive fields all come from the package.
+//
+// Fidelity contract (the documented legacy fallback):
+//  - ACP `agent_message_chunk` / `agent_thought_chunk` / `user_message_chunk`
+//    text is an incremental DELTA (never a cumulative snapshot for the supported
+//    ACP providers), so a message event is tagged `mode: "delta"` — a cumulative
+//    snapshot is NEVER emitted as an additive delta (the #566 "never append a
+//    snapshot as a delta" rule).
+//  - Where the provider exposes a `messageId`, it is carried so the display fold
+//    groups a message's fragments and separates two distinct same-speaker
+//    messages even when their transport chunks are adjacent.
+//  - Where the provider omits `messageId` (a documented ACP fidelity gap), NO
+//    identity is fabricated and NO boundary is inferred from delays/punctuation:
+//    the chunk is emitted through the canonical bridge UNCHANGED (byte-identical
+//    to the pre-#206 wire), and the display fold's adjacent-same-speaker
+//    coalescing is the legacy fallback.
+//  - Tool-call / tool-result / permission / ignored updates are delegated to the
+//    canonical bridge untouched, so tool and permission events stay correctly
+//    ordered and paired and raw replay is unchanged.
+
+import { sessionAcp as defaultSessionAcp, transcript as defaultTranscript } from './agentic.mjs';
+
+// Map the shared classifier's message role to a canonical `TranscriptRole`. ACP's
+// `reasoning` (an `agent_thought_chunk`) has no distinct transcript role, so — like
+// the canonical bridge `acpUpdateToTranscriptChunk` — it folds to `assistant`,
+// which `deriveDisplay` renders as a message block rather than dropping to raw
+// bytes. This mirrors the package bridge exactly so the producer never diverges
+// from the shared role mapping.
+function transcriptRole(acpRole) {
+  return acpRole === 'user' ? 'user' : 'assistant';
+}
+
+// A non-empty string, else null. `messageId` is optional on the ACP update and the
+// shared classifier already normalises it to `string | null`.
+function nonBlankId(value) {
+  return typeof value === 'string' && value !== '' ? value : null;
+}
+
+/**
+ * Map one raw ACP `session/update` `update` object to the canonical transcript-chunk
+ * bytes a producer appends, carrying the available message identity / role / delta
+ * semantics into the shared additive `MessageEvent` contract (#566). Returns `null`
+ * for an update with no canonical meaning (an `ignored` classification), exactly like
+ * the underlying bridge, so a caller skips it.
+ *
+ * Pure and total: any classifier or encoder throw degrades to the canonical bridge,
+ * and a bridge throw is itself caught (yielding `null`), so the producer hot path
+ * never crashes on one malformed update.
+ *
+ * @param {unknown} update The raw ACP `session/update` `params.update` object.
+ * @param {object} [deps]
+ * @param {object} [deps.sessionAcp]  The shared ACP surface (`classifyUpdate` +
+ *   `acpUpdateToTranscriptChunk`); defaults to the package bridge.
+ * @param {object} [deps.transcript]  The shared transcript surface
+ *   (`encodeTranscriptEvent`); defaults to the package transcript module.
+ * @returns {string | null} The canonical transcript-chunk bytes, or `null`.
+ */
+export function acpUpdateToDisplayChunk(update, deps = {}) {
+  const sessionAcp = deps.sessionAcp || defaultSessionAcp;
+  const transcript = deps.transcript || defaultTranscript;
+
+  const classify = typeof sessionAcp?.classifyUpdate === 'function' ? sessionAcp.classifyUpdate : null;
+  const encode = typeof transcript?.encodeTranscriptEvent === 'function' ? transcript.encodeTranscriptEvent : null;
+  const bridge = typeof sessionAcp?.acpUpdateToTranscriptChunk === 'function' ? sessionAcp.acpUpdateToTranscriptChunk : null;
+
+  // Fallback to the canonical bridge output for this update. Never throws.
+  const viaBridge = () => {
+    if (!bridge) return null;
+    try { return bridge(update); }
+    catch { return null; }
+  };
+
+  // Without the shared classifier + encoder we cannot enrich the message event, so
+  // the byte-identical canonical bridge output is the only correct behaviour.
+  if (!classify || !encode) return viaBridge();
+
+  let classified;
+  try { classified = classify(update); }
+  catch { return viaBridge(); }
+
+  // Only message chunks carry identity/boundary semantics worth enriching. Every
+  // other classification (tool-call, tool-result, ignored) is delegated to the
+  // canonical bridge UNCHANGED — tool/permission ordering and raw replay untouched.
+  if (!classified || classified.kind !== 'message') return viaBridge();
+
+  const messageId = nonBlankId(classified.messageId);
+
+  // No provider-supplied identity → do NOT fabricate one or infer a boundary.
+  // Emit through the canonical bridge unchanged (byte-identical to the pre-#206
+  // wire) and let the display fold's adjacent-same-speaker coalescing be the
+  // documented legacy fallback.
+  if (messageId === null) return viaBridge();
+
+  // Carry the available semantics into the additive `MessageEvent` fields: the
+  // producer identity (`messageId`) so the fold groups this message's fragments and
+  // separates distinct same-speaker messages, and `mode: "delta"` because ACP
+  // message chunks are incremental deltas — never a cumulative snapshot. No `offset`
+  // is supplied here; the real store offset is assigned on append (matching every
+  // other `encodeTranscriptEvent` call site).
+  const event = {
+    kind: 'message',
+    role: transcriptRole(classified.role),
+    text: classified.text,
+    messageId,
+    mode: 'delta',
+  };
+
+  try { return encode(event); }
+  catch { return viaBridge(); }
+}

package/c8ctl-plugin.js

@@ -73,6 +73,13 @@ import { createLogRing, resolveLogMaxBytes } from './supervisor-log-ring.mjs';
 // raw ACP `session/update` to the exact transcript-chunk bytes the cockpit decodes,
 // replacing the plugin's former hand-rolled `nwfTranscriptEvent` envelope grammar.
 import { sessionAcp as agenticSessionAcp } from './agentic.mjs';
+// Producer-side message-boundary preservation (jwulf/c8ctl-plugin-nano#206). Wraps
+// the canonical bridge to carry the ACP `messageId` / role / delta semantics into
+// the shared additive `MessageEvent` contract (nanobpm/nano-ide#566), so a consumer
+// folding these chunks through `deriveDisplay` reconstructs transport-fragmented
+// deltas into coherent blocks and keeps distinct same-speaker messages apart —
+// falling back to byte-identical bridge output when the provider omits identity.
+import { acpUpdateToDisplayChunk } from './acp-transcript-producer.mjs';
 // Engine-native AgentInstance / AgentHistory durable-transcript producer (issue
 // #194): mints an AgentInstance for an `external` agent job and appends each ACP
 // turn to the engine's append-only AgentHistory via the host SDK client.
@@ -5455,20 +5462,25 @@ function spawnCaptureAcp({ command, args = [], cwd, env, stdinData, timeoutMs, i
       }
     };
 
-    // #110 / nanobpm/nano-ide#534: map an ACP session/update to the CANONICAL
-    // transcript-chunk wire form via the shared `@nanobpm/agentic` bridge —
-    // `classifyUpdate` composed with `encodeTranscriptEvent` behind the single
-    // `acpUpdateToTranscriptChunk` helper. It returns the exact
-    // `{ nwfTranscriptEvent: 1, kind, … }` bytes the cockpit's `parseTranscriptEvent`
-    // decodes and `deriveView` folds into messages / tool cards, or `null` for an
+    // #110 / nanobpm/nano-ide#534 / jwulf/c8ctl-plugin-nano#206: map an ACP
+    // session/update to the CANONICAL transcript-chunk wire form via the shared
+    // `@nanobpm/agentic` seams. `acpUpdateToDisplayChunk` (this plugin's producer)
+    // wraps the canonical bridge (`classifyUpdate` composed with
+    // `encodeTranscriptEvent`) and additionally carries the ACP `messageId` / role /
+    // delta semantics into the shared additive `MessageEvent` contract (#566) so a
+    // consumer folding these chunks through `deriveDisplay` reconstructs
+    // transport-fragmented deltas into coherent blocks and keeps distinct
+    // same-speaker messages apart — degrading to byte-identical bridge output when
+    // the provider omits identity. It returns the exact `{ nwfTranscriptEvent: 1,
+    // kind, … }` bytes the cockpit's `parseTranscriptEvent` decodes, or `null` for an
     // update with no canonical meaning (an `ignored` classification: a plan, an
     // intermediate tool_call_update, a non-text chunk, or a malformed update). No
-    // envelope grammar or vocab is hand-rolled here anymore — the marker, version,
-    // kinds and fields all come from the package, so a producer and a consumer can
-    // never diverge on the wire again. `null` (and any bridge throw) falls through
-    // to the minimal human-text path below, so nothing is ever dropped.
+    // envelope grammar or vocab is hand-rolled here — the marker, version, kinds and
+    // additive fields all come from the package, so a producer and a consumer can
+    // never diverge on the wire again. `null` (and any throw) falls through to the
+    // minimal human-text path below, so nothing is ever dropped.
     const encodeTranscriptChunk = (update) => {
-      try { return agenticSessionAcp.acpUpdateToTranscriptChunk(update); }
+      try { return acpUpdateToDisplayChunk(update, { sessionAcp: agenticSessionAcp }); }
       catch { return null; }
     };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "c8ctl-plugin-nano",
-  "version": "1.57.1",
+  "version": "1.58.0",
   "type": "module",
   "description": "c8ctl plugin to start, inspect, and stop a local Nano BPM (nanobpmn) cluster",
   "main": "c8ctl-plugin.js",
@@ -22,6 +22,7 @@
   "files": [
     "c8ctl-plugin.js",
     "agent-instance.mjs",
+    "acp-transcript-producer.mjs",
     "platforms.mjs",
     "agentic.mjs",
     "agentic-loader-hook.mjs",
@@ -67,17 +68,17 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@nanobpm/agentic": "^0.13.0",
-    "@nanobpm/urban-agent-client": "^0.1.13"
+    "@nanobpm/agentic": "^0.14.0",
+    "@nanobpm/urban-agent-client": "^0.1.14"
   },
   "optionalDependencies": {
     "node-pty": "^1.0.0",
-    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.57.1",
-    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.57.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.57.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.57.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.57.1",
-    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.57.1",
-    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.57.1"
+    "@nanobpm/c8ctl-plugin-nano-darwin-arm64": "1.58.0",
+    "@nanobpm/c8ctl-plugin-nano-darwin-x64": "1.58.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-x64": "1.58.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-arm64": "1.58.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv7": "1.58.0",
+    "@nanobpm/c8ctl-plugin-nano-linux-armv6": "1.58.0",
+    "@nanobpm/c8ctl-plugin-nano-win32-x64": "1.58.0"
   }
 }