@nanobpm/nano-workforce 0.146.0 → 0.148.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.148.0](https://github.com/nanobpm/nano-workforce/compare/v0.147.0...v0.148.0) (2026-08-26)
+
+### Features
+
+* **agentic:** bridge escalate-policy ACP permission requests to the nwf Tasks inbox ([#562](https://github.com/nanobpm/nano-workforce/issues/562)) ([44e5cfb](https://github.com/nanobpm/nano-workforce/commit/44e5cfb3ff262fa50db17466f690b64eb3405e56)), closes [#559](https://github.com/nanobpm/nano-workforce/issues/559) [#setMode](https://github.com/nanobpm/nano-workforce/issues/setMode) [#structuredRegion](https://github.com/nanobpm/nano-workforce/issues/structuredRegion) [#561](https://github.com/nanobpm/nano-workforce/issues/561)
+
+## [0.147.0](https://github.com/nanobpm/nano-workforce/compare/v0.146.0...v0.147.0) (2026-08-26)
+
+### Features
+
+* **cockpit:** rich tool/diff cards + permission prompt mounted into the typed replay path ([#561](https://github.com/nanobpm/nano-workforce/issues/561)) ([4bd04a0](https://github.com/nanobpm/nano-workforce/commit/4bd04a06f12569e418566cb47b8a7bbf053cdb20)), closes [#559](https://github.com/nanobpm/nano-workforce/issues/559) [#setMode](https://github.com/nanobpm/nano-workforce/issues/setMode) [#structuredRegion](https://github.com/nanobpm/nano-workforce/issues/structuredRegion)
+
 ## [0.146.0](https://github.com/nanobpm/nano-workforce/compare/v0.145.1...v0.146.0) (2026-08-26)
 
 ### Features

package/app/agentCompletion.ts

@@ -24,6 +24,7 @@ import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { CONFORMANCE_ESCALATION_ELEMENT } from "./conformance.ts";
 import { DELIVERY_HUMAN_ELEMENT, isDeliveryHumanElement } from "./deliveryHuman.ts";
+import { ACP_PERMISSION_ELEMENT } from "./userTasks.ts";
 
 const now = () => new Date().toISOString();
 
@@ -92,13 +93,18 @@ export const CONFORMANCE_ESCALATION_TASK_ELEMENT = CONFORMANCE_ESCALATION_ELEMEN
 
 /** The user-task `elementId`s a HUMAN operator may complete from the Tasks inbox via the one canonical
  *  `complete-user-task` door: every agent-answerable escalation PLUS the human-only `feature-blocked`
- *  and `conformance-escalation` acknowledgements. The AGENT completer stays scoped to
- *  `ESCALATION_TASK_ELEMENTS` (neither ack), so widening the human surface never lets an agent retire
- *  a blocked run or a conformance review. */
+ *  and `conformance-escalation` acknowledgements, PLUS the advisory ACP permission prompt
+ *  (`ACP_PERMISSION_ELEMENT`, issue #559) a bridged escalate-policy `session/request_permission` raises.
+ *  The AGENT completer stays scoped to `ESCALATION_TASK_ELEMENTS` (none of these three), so widening the
+ *  human surface never lets an agent retire a blocked run, a conformance review, or an agent-permission
+ *  prompt. The permission element has no static `.form` (it is not a BPMN user task), so
+ *  `validateEscalationVariables` leaves its Allow/Deny variables unenforced — the permission bridge
+ *  translates them into a RESOLUTION frame (`app/agentic/permission-bridge.ts`). */
 export const HUMAN_COMPLETABLE_ELEMENTS: ReadonlySet<string> = new Set([
   ...ESCALATION_TASK_ELEMENTS,
   FEATURE_BLOCKED_TASK_ELEMENT,
   CONFORMANCE_ESCALATION_TASK_ELEMENT,
+  ACP_PERMISSION_ELEMENT,
 ]);
 
 /** Each escalation `elementId` → the `.form` whose contract governs its completion variables (the

package/app/agentic/cockpit/index.ts

@@ -36,6 +36,7 @@ export {
 export {
   type DerivedTranscriptDom,
   deriveTranscript,
+  type RenderDerivedTranscriptOptions,
   renderDerivedTranscript,
 } from "./transcript-derive.ts";
 export {

package/app/agentic/cockpit/supply-boot.test.ts

@@ -7,8 +7,10 @@ import assert from "node:assert/strict";
 import { test } from "node:test";
 
 import { FakeDocument, FakeElement, FakeSocket } from "../../../test/agentic-cockpit-doubles.ts";
+import { TRANSCRIPT_EVENT_MARKER, TRANSCRIPT_EVENT_VERSION } from "../transcript-events.ts";
 import { bootSupplyCockpit, type SupplyCockpitEnv } from "./supply-boot.ts";
 import type { SupplyReport } from "./supply-view.ts";
+import type { TranscriptDataReport } from "./transcript-render.ts";
 
 const flush = () => new Promise<void>((resolve) => setImmediate(resolve));
 
@@ -358,3 +360,95 @@ test("a drill whose terminal build throws resets the panel to idle instead of le
   assert.equal(cockpit.currentMode, "live");
   assert.equal(cockpit.currentStream, "wk-a");
 });
+
+// A transcript envelope (marker + kind + fields), matching the one event grammar the fold parses.
+function env(kind: string, extra: Record<string, unknown> = {}): string {
+  return JSON.stringify({ [TRANSCRIPT_EVENT_MARKER]: TRANSCRIPT_EVENT_VERSION, kind, ...extra });
+}
+
+// A captured transcript carrying a pending ESCALATE permission request, for the structured replay path.
+function permissionTranscript(stream: string): TranscriptDataReport {
+  const chunks = [
+    env("turn", { index: 0 }),
+    env("message", { role: "assistant", text: "I need to run a command" }),
+    env("permission", {
+      phase: "request",
+      callId: "perm-1",
+      policy: "escalate",
+      title: "Run `rm -rf build`?",
+      options: [
+        { optionId: "allow", name: "Allow", kind: "allow-once" },
+        { optionId: "deny", name: "Deny", kind: "reject-once" },
+      ],
+    }),
+  ];
+  return { stream, from: 0, gap: false, nextOffset: chunks.length, entries: chunks.map((chunk, offset) => ({ offset, chunk })) };
+}
+
+// A rig whose replay endpoints (list + per-session bytes) are wired, plus an optional permission hook.
+function replayRig(onPermissionResolve?: SupplyCockpitEnv["onPermissionResolve"]): {
+  readonly env: SupplyCockpitEnv;
+  readonly host: FakeElement;
+  readonly data: TranscriptDataReport;
+} {
+  const r = rig();
+  const data = permissionTranscript("job:done");
+  const env: SupplyCockpitEnv = {
+    ...r.env,
+    fetchTranscripts: () => Promise.resolve({ count: 0, transcripts: [] }),
+    fetchTranscript: () => Promise.resolve(data),
+    ...(onPermissionResolve !== undefined ? { onPermissionResolve } : {}),
+  };
+  return { env, host: r.host, data };
+}
+
+test("replay MOUNTS the structured derived view beside the byte replay (typed boot/replay path)", async () => {
+  const { env, host } = replayRig();
+  const cockpit = bootSupplyCockpit(env);
+  await cockpit.replay("job:done");
+
+  // The dedicated structured region exists and now holds the derived view (the byte terminal replay,
+  // asserted elsewhere, is untouched — this is additive beside it).
+  const region = host.byData("structured", "region")[0];
+  assert.ok(region !== undefined, "the structured region is present");
+  assert.equal(region?.byClass("cockpit-transcript-derived").length, 1, "the derived structured view is mounted");
+  assert.equal(host.byData("permission", "request").length, 1, "the permission prompt is rendered in the structured view");
+});
+
+test("a SupplyCockpitEnv.onPermissionResolve hook is threaded into the structured render so a click reaches it", async () => {
+  const resolutions: Array<{ callId: string; optionId: string; allowed: boolean }> = [];
+  const { env, host } = replayRig((resolution) => resolutions.push(resolution));
+  const cockpit = bootSupplyCockpit(env);
+  await cockpit.replay("job:done");
+
+  const allow = host.byClass("cockpit-transcript-permission-option").find((b) => b.getAttribute("data-option-id") === "allow");
+  assert.ok(allow !== undefined, "the Allow button rendered");
+  allow?.dispatch("click");
+  assert.deepEqual(resolutions, [{ callId: "perm-1", optionId: "allow", allowed: true }]);
+});
+
+test("the structured view renders even without an onPermissionResolve hook (buttons are inert, no throw)", async () => {
+  const { env, host } = replayRig();
+  const cockpit = bootSupplyCockpit(env);
+  await cockpit.replay("job:done");
+  const allow = host.byClass("cockpit-transcript-permission-option").find((b) => b.getAttribute("data-option-id") === "allow");
+  assert.ok(allow !== undefined, "the Allow button rendered without a hook");
+  allow?.dispatch("click"); // no handler wired — must not throw
+});
+
+test("switching from replay to a LIVE drill CLEARS the stale structured derived view (no wrong-callId clicks)", async () => {
+  const { env, host } = replayRig();
+  const cockpit = bootSupplyCockpit(env);
+  await cockpit.replay("job:done");
+  // The structured region is populated with the derived view + pending permission prompt.
+  assert.equal(host.byData("permission", "request").length, 1, "the permission prompt is mounted on replay");
+
+  // Drilling into a live stream must tear the stale structured view down — leaving a clickable permission
+  // prompt over a live terminal risks an operator action against the wrong callId.
+  cockpit.drill("wk-a");
+  assert.equal(cockpit.currentMode, "live");
+  const region = host.byData("structured", "region")[0];
+  assert.ok(region !== undefined, "the structured region element persists (it is cleared, not removed)");
+  assert.equal(region?.byClass("cockpit-transcript-derived").length, 0, "the derived structured view is cleared on live drill");
+  assert.equal(host.byData("permission", "request").length, 0, "the stale permission prompt is gone in live mode");
+});

package/app/agentic/cockpit/supply-boot.ts

@@ -32,6 +32,7 @@ import type { CockpitRoute } from "./cockpit-route.ts";
 import { renderSupply } from "./supply-render.ts";
 import type { SupplyReport, SupplyView } from "./supply-view.ts";
 import { supplyView } from "./supply-view.ts";
+import { type RenderDerivedTranscriptOptions, renderDerivedTranscript } from "./transcript-derive.ts";
 import { renderTranscripts, replayTranscript, type TranscriptDataReport } from "./transcript-render.ts";
 import type { TranscriptListReport } from "./transcript-view.ts";
 import { transcriptsView } from "./transcript-view.ts";
@@ -88,6 +89,16 @@ export interface SupplyCockpitEnv {
   readonly pastFetchTimeoutMs?: number;
   /** Notified of a fetch/render/relay error (the poll keeps going). */
   readonly onError?: (err: unknown) => void;
+  /**
+   * The seam the wave-2 escalation bridge attaches to: threaded into the STRUCTURED replay view's
+   * {@link RenderDerivedTranscriptOptions.onPermissionResolve}, so a pending escalate-permission
+   * prompt's Allow/Deny click reaches the bridge. Optional (default `undefined`): the structured view
+   * still renders, its prompt buttons just have no handler. NOTE (runtime-layer truth): this is the
+   * TYPED boot/replay path exercised by unit tests + the published package, NOT the operator's live
+   * browser cockpit (`pages/cockpit/mount.js`, a hand-maintained drift twin) — surfacing the prompt
+   * there is a separate follow-up.
+   */
+  readonly onPermissionResolve?: RenderDerivedTranscriptOptions["onPermissionResolve"];
 }
 
 /** The running supply cockpit; dispose to stop polling and tear down the terminal. */
@@ -132,6 +143,10 @@ class SupplyCockpit implements SupplyCockpitHandle {
   readonly #env: SupplyCockpitEnv;
   readonly #listRegion: ElementLike;
   readonly #pastRegion: ElementLike | undefined;
+  // A dedicated volatile region the STRUCTURED derived view (messages, rich tool/diff cards, permission
+  // prompts) is mounted into on a replay — beside, and additive to, the byte-level terminal replay
+  // (which is left untouched). Present only when the transcript read endpoints are wired.
+  readonly #structuredRegion: ElementLike | undefined;
   readonly #terminalHost: ElementLike;
   readonly #terminalTitle: ElementLike;
   readonly #terminalNote: ElementLike;
@@ -247,6 +262,14 @@ class SupplyCockpit implements SupplyCockpitHandle {
     this.#terminalHost.className = "cockpit-terminal-host";
     this.#terminalHost.setAttribute("data-terminal", "host");
     this.#terminalPanel.appendChild(this.#terminalHost);
+    // The STRUCTURED derived view is mounted here on a replay, additive beside the byte terminal above.
+    // Only exists when the transcript read endpoints are wired (same pairing as the past-sessions list).
+    if (env.fetchTranscripts !== undefined) {
+      this.#structuredRegion = env.doc.createElement("div");
+      this.#structuredRegion.className = "cockpit-structured-region";
+      this.#structuredRegion.setAttribute("data-structured", "region");
+      this.#terminalPanel.appendChild(this.#structuredRegion);
+    }
     // A status note under the terminal, shown while a LIVE drill has connected but no output has
     // arrived yet (a quiet job between frames): without it the panel is an indistinguishable blank
     // black rectangle, so the operator can't tell "connected, waiting" from "broken". Cleared the
@@ -284,6 +307,11 @@ class SupplyCockpit implements SupplyCockpitHandle {
     // Any mode change replaces what's behind the panel, so the prior "waiting for output" note is
     // stale — clear it. A live drill re-arms it (below) once its fresh terminal is mounted.
     this.#setNote(undefined);
+    // The STRUCTURED derived view is only valid alongside a replay. Any non-replay mode (a live drill
+    // or idle) must clear it, or a stale derived transcript / pending permission prompt would linger —
+    // visible and CLICKABLE — over the live terminal, risking an operator action against the wrong
+    // callId. A replay re-mounts it (in replay(), after this #setMode("replay", …)).
+    if (mode !== "replay") this.#structuredRegion?.replaceChildren();
   }
 
   /** Show (or clear) the terminal status note — the "connected, waiting for output" affordance. */
@@ -577,6 +605,14 @@ class SupplyCockpit implements SupplyCockpitHandle {
       const session = new TerminalSession({ stream, sink, send: () => {}, from: data.from });
       replayTranscript(session, data);
       this.#setMode("replay", stream);
+      // Additively mount the STRUCTURED derived view beside the byte replay above (the byte replay is
+      // left untouched). The env's onPermissionResolve seam is threaded into the render so a pending
+      // escalate-permission prompt's Allow/Deny click reaches whatever the bridge wires there.
+      if (this.#structuredRegion !== undefined) {
+        renderDerivedTranscript(this.#structuredRegion, this.#env.doc, data, {
+          onPermissionResolve: this.#env.onPermissionResolve,
+        });
+      }
       // Re-render the past list so the just-selected session shows as active (best-effort).
       void this.#refreshPast(this.#route.kind === "worker" ? this.#route.instance : undefined);
     } catch (err) {

package/app/agentic/cockpit/transcript-derive.test.ts

@@ -4,7 +4,7 @@
 // cards, per-turn boundaries), and that raw chunks are preserved in the fidelity footer — the byte
 // replay is not lost. It renders into the in-memory DOM double, no browser.
 import { test } from "node:test";
-import { assertEquals } from "#test-assert";
+import { assert, assertEquals, assertStringIncludes } from "#test-assert";
 import { FakeDocument, FakeElement } from "../../../test/agentic-cockpit-doubles.ts";
 import { TRANSCRIPT_EVENT_MARKER, TRANSCRIPT_EVENT_VERSION } from "../transcript-events.ts";
 import { deriveTranscript, renderDerivedTranscript } from "./transcript-derive.ts";
@@ -76,3 +76,184 @@ test("renderDerivedTranscript shows an empty state for an all-raw (unstructured)
   assertEquals(host.byData("empty", "true").length, 1);
   assertEquals(host.byData("turn-count", "0").length, 1);
 });
+
+// A minimal single-page report of the given entries (offsets assigned in order).
+function page(chunks: readonly string[], stream = "job:x"): TranscriptDataReport {
+  return { stream, from: 0, gap: false, nextOffset: chunks.length, entries: chunks.map((chunk, offset) => ({ offset, chunk })) };
+}
+
+test("a tool card renders its args and result content", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("tool-call", { name: "read", callId: "c1", args: { path: "README.md" } }),
+      env("tool-result", { callId: "c1", ok: true, content: "file contents here" }),
+    ]),
+  );
+  const card = host.byData("tool", "read")[0];
+  assertEquals(card?.getAttribute("data-status"), "ok");
+  assertEquals(card?.getAttribute("data-tool-kind"), undefined); // not a diff
+  const argsEl = host.byData("tool-args", "true")[0];
+  assertStringIncludes(argsEl?.textContent ?? "", "README.md");
+  const resultEl = host.byData("tool-result", "true")[0];
+  assertEquals(resultEl?.textContent, "file contents here");
+});
+
+test("a diff tool renders a cockpit-transcript-diff block with per-line add/del/ctx markers", () => {
+  const host = new FakeElement("div");
+  const unified = "--- a/foo.txt\n+++ b/foo.txt\n@@ -1,2 +1,2 @@\n-old line\n+new line\n unchanged\n";
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("tool-call", { name: "edit", callId: "d1" }),
+      env("tool-result", { callId: "d1", ok: true, content: unified }),
+    ]),
+  );
+  const card = host.byData("tool", "edit")[0];
+  assertEquals(card?.getAttribute("data-tool-kind"), "diff");
+  assertEquals(host.byClass("cockpit-transcript-diff").length, 1);
+  assertEquals(host.byData("diff-line", "add").length, 1);
+  assertEquals(host.byData("diff-line", "del").length, 1);
+  assert(host.byData("diff-line", "ctx").length >= 1, "the hunk/header/context lines are marked ctx");
+  // The diff replaces the plain result rendering — no raw result <pre> for a diff tool.
+  assertEquals(host.byData("tool-result", "true").length, 0);
+});
+
+test("structured edit args (path + old/new text) render as a synthesized diff", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([env("tool-call", { name: "write", callId: "s1", args: { path: "a.txt", oldText: "one\ntwo", newText: "one\nTWO" } })]),
+  );
+  const card = host.byData("tool", "write")[0];
+  assertEquals(card?.getAttribute("data-tool-kind"), "diff");
+  assertEquals(host.byData("diff-line", "del").length, 2);
+  assertEquals(host.byData("diff-line", "add").length, 2);
+  // The diff was synthesized FROM args, so the raw args <pre> is not ALSO rendered.
+  assertEquals(host.byData("tool-args", "true").length, 0);
+});
+
+test("structured edit args ending in a trailing newline do not synthesize a spurious empty diff line", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([env("tool-call", { name: "write", callId: "s2", args: { path: "a.txt", oldText: "one\ntwo\n", newText: "one\nTWO\n" } })]),
+  );
+  // "one\ntwo\n" would naively split into 3 segments (…, "two", "") — the trailing empty is dropped.
+  assertEquals(host.byData("diff-line", "del").length, 2);
+  assertEquals(host.byData("diff-line", "add").length, 2);
+});
+
+test("an args-synthesized diff still renders non-diff result content (args+result, diff special render)", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("tool-call", { name: "write", callId: "s3", args: { path: "a.txt", oldText: "one", newText: "ONE" } }),
+      env("tool-result", { callId: "s3", ok: true, content: "wrote 1 file" }),
+    ]),
+  );
+  const card = host.byData("tool", "write")[0];
+  assertEquals(card?.getAttribute("data-tool-kind"), "diff");
+  // The diff came from args, so the result content is not the diff source — it is still shown.
+  const resultEl = host.byData("tool-result", "true")[0];
+  assertEquals(resultEl?.textContent, "wrote 1 file");
+});
+
+test("a pending escalate permission renders Allow/Deny buttons that invoke onPermissionResolve", () => {
+  const host = new FakeElement("div");
+  const calls: Array<{ callId: string; optionId: string; allowed: boolean }> = [];
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("permission", {
+        phase: "request",
+        callId: "p1",
+        policy: "escalate",
+        title: "Run a shell command?",
+        options: [
+          { optionId: "allow", name: "Allow", kind: "allow-once" },
+          { optionId: "deny", name: "Deny", kind: "reject-once" },
+        ],
+      }),
+    ]),
+    { onPermissionResolve: (resolution) => calls.push(resolution) },
+  );
+  const card = host.byData("permission", "request")[0];
+  assertEquals(card?.getAttribute("data-policy"), "escalate");
+  assertEquals(card?.getAttribute("data-status"), "pending");
+  assertEquals(card?.getAttribute("data-call-id"), "p1");
+  const buttons = host.byClass("cockpit-transcript-permission-option");
+  assertEquals(buttons.length, 2);
+
+  buttons.find((b) => b.getAttribute("data-option-id") === "allow")?.dispatch("click");
+  buttons.find((b) => b.getAttribute("data-option-id") === "deny")?.dispatch("click");
+  assertEquals(calls, [
+    { callId: "p1", optionId: "allow", allowed: true },
+    { callId: "p1", optionId: "deny", allowed: false },
+  ]);
+});
+
+test("a yolo permission request renders informational only — no Allow/Deny buttons", () => {
+  const host = new FakeElement("div");
+  const calls: unknown[] = [];
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("permission", {
+        phase: "request",
+        callId: "y1",
+        policy: "yolo",
+        options: [{ optionId: "allow", name: "Allow", kind: "allow-always" }],
+      }),
+    ]),
+    { onPermissionResolve: (resolution) => calls.push(resolution) },
+  );
+  const card = host.byData("permission", "request")[0];
+  assertEquals(card?.getAttribute("data-policy"), "yolo");
+  assertEquals(card?.getAttribute("data-status"), "auto");
+  assertEquals(host.byClass("cockpit-transcript-permission-option").length, 0);
+  assertEquals(calls.length, 0);
+});
+
+test("a resolved permission renders settled (allowed/denied) with the chosen option and no live buttons", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(
+    host,
+    doc,
+    page([
+      env("permission", {
+        phase: "request",
+        callId: "r1",
+        policy: "escalate",
+        title: "Delete the file?",
+        options: [
+          { optionId: "allow", name: "Allow once", kind: "allow-once" },
+          { optionId: "deny", name: "Deny", kind: "reject-once" },
+        ],
+      }),
+      env("permission", { phase: "resolution", callId: "r1", optionId: "deny", allowed: false, by: "operator" }),
+    ]),
+  );
+  const card = host.byData("permission", "request")[0];
+  assertEquals(card?.getAttribute("data-status"), "denied");
+  const settled = host.byClass("cockpit-transcript-permission-settled")[0];
+  assertEquals(settled?.getAttribute("data-chosen-option"), "deny");
+  assertEquals(settled?.textContent, "Deny");
+  assertEquals(host.byClass("cockpit-transcript-permission-option").length, 0);
+});
+
+test("the existing 3-arg renderDerivedTranscript(host, doc, data) call still works (options optional)", () => {
+  const host = new FakeElement("div");
+  renderDerivedTranscript(host, doc, report());
+  assertEquals(host.byData("turn-count", "1").length, 1);
+  assertEquals(host.byData("permission-count", "0").length, 1);
+});