@nanobpm/nano-workforce 0.146.0 → 0.148.0

package/app/agentic/permission-bridge.ts

@@ -0,0 +1,268 @@
+// The ACP permission → nano-workforce escalation bridge (issue #559, ADR 0056 — the advisory agentic
+// app-tier plane). It does NOT touch BPMN, the agent job envelope, or the worker⇄engine protocol.
+//
+// When an ACP-driven agent emits a permission REQUEST tagged `policy: "escalate"` on the relay lane
+// (a blocked `session/request_permission`), this bridge:
+//   1. raises it as an answerable row in the unified Tasks inbox (a new `ACP_PERMISSION_ELEMENT` kind,
+//      via the pure `buildUserTaskRow` derivation), carrying the request's title/reason as the question;
+//   2. lets a human operator answer Allow/Deny through the ONE canonical completion door
+//      (`completeEscalationAsHuman`), the exact seam every other escalation uses; then
+//   3. flows the answer BACK DOWN the relay as a permission RESOLUTION frame on the CONTROL lane (a
+//      permission answer is high-priority control), releasing the agent's blocked request.
+//
+// A `yolo`-policy request NEVER reaches this path (it auto-allows elsewhere), and the whole bridge is
+// OPT-IN per hire — the default (`NANO_WORKFORCE_PERMISSION_ESCALATION` off) is yolo: no user task, no
+// prompt, no bridge resolution.
+//
+// Derivation over duplication: the core is a set of PURE functions (raise the row / build the
+// resolution frame), with the side-effecting relay `send` and the completion door kept as thin edges.
+// Because the cockpit-render slice exposed a `RenderDerivedTranscriptOptions.onPermissionResolve` seam,
+// this module ALSO exports an adapter that produces an `onPermissionResolve` handler backed by the SAME
+// pure resolution builder, so the seam and the completion door converge on one bridge. Wiring the live
+// in-browser Allow/Deny of `pages/cockpit/mount.js` to this bridge is a deferred follow-up (there is no
+// in-repo cockpit boot site), OUT OF SCOPE here.
+import type { Frame } from "@nanobpm/agentic/protocol";
+import { RELAY_FAMILY } from "@nanobpm/agentic/relay";
+import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { type AgentCompleteResult, completeEscalationAsHuman } from "../agentCompletion.ts";
+import { readEnvOr } from "../contracts.ts";
+import { ACP_PERMISSION_ELEMENT, buildUserTaskRow, type UserTaskRow } from "../userTasks.ts";
+import type { RenderDerivedTranscriptOptions } from "./cockpit/transcript-derive.ts";
+import { jobStream } from "./correlation.ts";
+import {
+  type DerivedPermission,
+  encodeTranscriptEvent,
+  optionKindAllows,
+  type PermissionResolutionEvent,
+} from "./transcript-events.ts";
+
+/** The exact `onPermissionResolve` seam the cockpit-render slice exported — consumed VERBATIM (not
+ *  re-declared) so a drift in the cockpit's prop shape is a compile error here, never a silent skew. */
+export type OnPermissionResolve = NonNullable<RenderDerivedTranscriptOptions["onPermissionResolve"]>;
+
+/** Read the per-hire opt-in master switch for the permission-escalation bridge. Default OFF (yolo).
+ *  Governed by the one typed env schema (`NANO_WORKFORCE_PERMISSION_ESCALATION`, `app/contracts.ts`). */
+export function permissionEscalationEnabled(env: Record<string, string | undefined> = process.env): boolean {
+  const raw = readEnvOr("NANO_WORKFORCE_PERMISSION_ESCALATION", "off", env).toLowerCase();
+  return raw === "1" || raw === "true" || raw === "on" || raw === "yes";
+}
+
+/** Re-exported canonical allow/deny derivation (defined beside `PermissionOptionKind` in
+ *  `transcript-events.ts`). The bridge and the cockpit render seam share this ONE implementation, so the
+ *  completion-door path and the `onPermissionResolve` seam can never disagree on what a chosen option means. */
+export { optionKindAllows };
+
+/** Pure: whether the chosen `optionId` allows the action, derived from the REQUEST's own options.
+ *  Returns false for an unknown option (fail-closed — an unrecognised answer denies). */
+export function permissionOptionAllows(permission: DerivedPermission, optionId: string): boolean {
+  const option = permission.options.find((o) => o.optionId === optionId);
+  return option !== undefined && optionKindAllows(option.kind);
+}
+
+/** Pure: fold a permission request's `title`/`reason` (falling back to its `toolName`) into the one
+ *  human-readable `question` the Tasks inbox row shows. */
+export function permissionQuestion(permission: DerivedPermission): string {
+  const parts: string[] = [];
+  if (permission.title) parts.push(permission.title);
+  if (permission.reason) parts.push(permission.reason);
+  if (parts.length === 0 && permission.toolName) parts.push(`Permission requested for ${permission.toolName}`);
+  return parts.join(" — ");
+}
+
+/** The denormalised context a bridged permission request needs to raise its Tasks-inbox row. */
+export interface PermissionUserTaskContext {
+  /** The completable key the raised row carries (the operator answers this key through the door). */
+  readonly userTaskKey: string;
+  /** The subject the row is keyed on (the hire / job / session the permission belongs to). */
+  readonly subjectKey: string;
+  readonly subjectTitle?: string | null;
+  readonly subjectUrl?: string | null;
+  readonly processKey?: string | null;
+}
+
+/** Pure: the Tasks-inbox row an escalate-policy permission REQUEST raises, or `null` when the bridge is
+ *  disabled (opt-out default) or the policy is `yolo` (auto-allow — no user task, no prompt). The row is
+ *  the `ACP_PERMISSION_ELEMENT` kind, carrying the request's title/reason as its `question`, so a bridged
+ *  permission surfaces in the SAME inbox as every other escalation. */
+export function permissionUserTaskRow(
+  permission: DerivedPermission,
+  ctx: PermissionUserTaskContext,
+  opts: { enabled: boolean },
+  at?: string,
+): UserTaskRow | null {
+  if (!opts.enabled) return null;
+  if (permission.policy !== "escalate") return null;
+  return buildUserTaskRow(
+    {
+      userTaskKey: ctx.userTaskKey,
+      elementId: ACP_PERMISSION_ELEMENT,
+      subjectType: "agent",
+      subjectKey: ctx.subjectKey,
+      subjectTitle: ctx.subjectTitle,
+      subjectUrl: ctx.subjectUrl,
+      question: permissionQuestion(permission),
+      processKey: ctx.processKey,
+    },
+    at,
+  );
+}
+
+/** The chosen answer to a permission request: the option id and whether it allows the action. */
+export interface PermissionDecision {
+  readonly callId: string;
+  readonly optionId: string;
+  readonly allowed: boolean;
+  /** Provenance of the decision — an operator answer (default) or an auto policy. */
+  readonly by?: "operator" | "auto";
+}
+
+/** A produced permission RESOLUTION: the typed event, its encoded wire chunk, and the control-lane
+ *  relay frame that carries it back down to the blocked agent. */
+export interface PermissionResolution {
+  readonly event: PermissionResolutionEvent;
+  readonly chunk: string;
+  readonly frame: Frame;
+}
+
+/** Pure: the typed RESOLUTION event that releases a blocked `session/request_permission`. The `offset`
+ *  is a placeholder — `encodeTranscriptEvent` strips it (the hub assigns the authoritative offset). */
+export function buildPermissionResolutionEvent(decision: PermissionDecision): PermissionResolutionEvent {
+  return {
+    kind: "permission",
+    phase: "resolution",
+    offset: 0,
+    callId: decision.callId,
+    optionId: decision.optionId,
+    allowed: decision.allowed,
+    ...(decision.by !== undefined ? { by: decision.by } : {}),
+  };
+}
+
+/** Options for the wire framing of a resolution — the producer generation and per-stream sequence the
+ *  edge assigns. Both default to `0` so two independent callers with the same decision + stream produce
+ *  byte-identical frames (the convergence the completion door and the `onPermissionResolve` seam rely on). */
+export interface ResolutionFrameOptions {
+  readonly seq?: number;
+  readonly incarnation?: number;
+}
+
+/** Pure: encode a permission RESOLUTION into the CONTROL-lane relay frame that carries it back down to
+ *  the blocked agent. The chunk speaks the one envelope grammar (`encodeTranscriptEvent`); the frame
+ *  rides the control lane because a permission answer is high-priority control. This is the single
+ *  builder BOTH the completion-door path and the `onPermissionResolve` adapter converge on. */
+export function buildPermissionResolutionFrame(
+  stream: string,
+  decision: PermissionDecision,
+  opts: ResolutionFrameOptions = {},
+): PermissionResolution {
+  const event = buildPermissionResolutionEvent(decision);
+  const chunk = encodeTranscriptEvent(event);
+  const frame: Frame = {
+    lane: "control",
+    family: RELAY_FAMILY,
+    seq: opts.seq ?? 0,
+    payload: { op: "produce", stream, incarnation: opts.incarnation ?? 0, chunk },
+  };
+  return { event, chunk, frame };
+}
+
+/** The thin side-effecting edge: emit a resolution frame down the relay to the blocked agent. */
+export type RelayResolutionSend = (frame: Frame) => void;
+
+/** The bridge's edge dependencies: the relay `send`, plus how a permission `callId` maps to the relay
+ *  stream its resolution travels back down and the frame's per-stream `seq`/`incarnation`. */
+export interface PermissionBridgeDeps {
+  /** Emit the RESOLUTION frame down the relay (control lane). */
+  readonly send: RelayResolutionSend;
+  /** Resolve the relay stream a permission `callId` is answered on. Defaults to `job:<callId>` (the
+   *  request's `callId` is the blocked job's key); a bridge with richer correlation supplies its own. */
+  readonly streamForCallId?: (callId: string) => string;
+  /** The frame `seq` for a resolution on a `callId`'s stream (default 0). */
+  readonly seq?: (callId: string) => number;
+  /** The producer generation stamped on the resolution frame (default 0). */
+  readonly incarnation?: number;
+}
+
+function resolveStream(deps: PermissionBridgeDeps, callId: string): string {
+  return deps.streamForCallId?.(callId) ?? jobStream(callId);
+}
+
+function sendResolution(deps: PermissionBridgeDeps, stream: string, decision: PermissionDecision): PermissionResolution {
+  const resolution = buildPermissionResolutionFrame(stream, decision, {
+    seq: deps.seq?.(decision.callId),
+    incarnation: deps.incarnation,
+  });
+  deps.send(resolution.frame);
+  return resolution;
+}
+
+/**
+ * The exported adapter behind the cockpit slice's `RenderDerivedTranscriptOptions.onPermissionResolve`
+ * seam. Given the bridge's relay-send dependency, returns a handler matching the seam signature verbatim
+ * that emits the SAME control-lane RESOLUTION frame the completion-door path emits (both route through
+ * `buildPermissionResolutionFrame`). Provided so a future cockpit boot site can plug it in — this module
+ * does NOT wire it into a live boot (there is no in-repo cockpit boot site; that is a deferred follow-up).
+ */
+export function createOnPermissionResolve(deps: PermissionBridgeDeps): OnPermissionResolve {
+  return (resolution) => {
+    sendResolution(deps, resolveStream(deps, resolution.callId), {
+      callId: resolution.callId,
+      optionId: resolution.optionId,
+      allowed: resolution.allowed,
+      by: "operator",
+    });
+  };
+}
+
+/** What an operator supplies to answer a bridged permission escalation through the completion door. */
+export interface PermissionEscalationAnswer {
+  /** The request being answered (its `callId`/`options` are the source of truth for the resolution). */
+  readonly permission: DerivedPermission;
+  /** The completable key of the raised Tasks-inbox row. */
+  readonly userTaskKey: string;
+  /** The relay stream the resolution travels back down. Defaults to the deps' `streamForCallId`. */
+  readonly stream?: string;
+  /** The option the operator chose (Allow/Deny). `allowed` is derived from the request's option kind. */
+  readonly optionId: string;
+  /** The operator's audit handle. */
+  readonly operatorId: string;
+}
+
+/** The result of answering a bridged permission escalation: the completion-door result plus (on
+ *  success) the RESOLUTION that was sent down the relay. */
+export interface PermissionEscalationResult {
+  readonly completion: AgentCompleteResult;
+  readonly resolution?: PermissionResolution;
+}
+
+/**
+ * Answer a bridged permission escalation AS A HUMAN operator through the ONE canonical completion door
+ * (`completeEscalationAsHuman`), then flow the answer back down the relay as a control-lane RESOLUTION
+ * frame that releases the agent's blocked `session/request_permission`. The completion and the relay
+ * `send` are the thin edges; the resolution itself is the pure `buildPermissionResolutionFrame`, so this
+ * converges with the `onPermissionResolve` adapter on one bridge. When the completion door refuses the
+ * task (a 404-style no-op or a failed engine completion) NO resolution is sent — the block is only
+ * released when the operator's answer actually took.
+ */
+export async function completePermissionEscalationAsHuman(
+  data: DataLayer,
+  engine: EngineClient,
+  deps: PermissionBridgeDeps,
+  answer: PermissionEscalationAnswer,
+): Promise<PermissionEscalationResult> {
+  const allowed = permissionOptionAllows(answer.permission, answer.optionId);
+  const completion = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: answer.userTaskKey,
+    variables: { optionId: answer.optionId, allowed },
+    operatorId: answer.operatorId,
+  });
+  if (!completion.ok) return { completion };
+  const stream = answer.stream ?? resolveStream(deps, answer.permission.callId);
+  const resolution = sendResolution(deps, stream, {
+    callId: answer.permission.callId,
+    optionId: answer.optionId,
+    allowed,
+    by: "operator",
+  });
+  return { completion, resolution };
+}

package/app/agentic/transcript-events.test.ts

@@ -275,6 +275,14 @@ test("core vocab: malformed permission envelopes fall back to raw stream-chunk",
     }).kind,
     "stream-chunk",
   );
+  // resolution with a present-but-NON-STRING `by` (e.g. 123) — rejected, not accepted with `by` dropped
+  assertEquals(
+    parseTranscriptEvent({
+      offset: 0,
+      chunk: env("permission", { phase: "resolution", callId: "p1", optionId: "allow", allowed: true, by: 123 }),
+    }).kind,
+    "stream-chunk",
+  );
   // missing callId
   assertEquals(
     parseTranscriptEvent({ offset: 0, chunk: env("permission", { phase: "request", policy: "escalate", options: REQUEST_OPTIONS }) }).kind,

package/app/agentic/transcript-events.ts

@@ -143,6 +143,15 @@ export type PermissionPolicy = "escalate" | "yolo";
 /** The kind of a permission option — mirrors ACP's option kinds (allow/reject × once/always). */
 export type PermissionOptionKind = "allow-once" | "allow-always" | "reject-once" | "reject-always";
 
+/** Pure, canonical: does a permission option kind ALLOW (true) or REJECT (false) the proposed action?
+ *  The `allow-*` vs `reject-*` prefix is the single source of truth. This lives beside
+ *  {@link PermissionOptionKind} so every consumer (the cockpit render seam and the permission-escalation
+ *  bridge) derives allow/deny from ONE implementation — the two paths can never disagree on what a
+ *  chosen option means (no drift surface). */
+export function optionKindAllows(kind: PermissionOptionKind): boolean {
+  return kind === "allow-once" || kind === "allow-always";
+}
+
 /** One offered permission option (ACP `options[]` member): a stable id, a label, and its kind. */
 export interface PermissionOption {
   readonly optionId: string;
@@ -346,7 +355,10 @@ export const CORE_TRANSCRIPT_VOCAB: TranscriptVocab = Object.freeze({
       if (typeof body.allowed !== "boolean") return undefined;
       const by = str(body, "by");
       // Reject a malformed `by` rather than silently dropping it: a present-but-unknown provenance is a
-      // producer bug, and swallowing it would make the typed event diverge from the on-wire JSON.
+      // producer bug, and swallowing it would make the typed event diverge from the on-wire JSON. This
+      // covers BOTH a present-but-non-string `by` (e.g. `by: 123`, where str() coerces to undefined) and
+      // a string that isn't a known provenance — either way the on-wire `by` is present but invalid.
+      if (body.by !== undefined && by === undefined) return undefined;
       if (by !== undefined && by !== "operator" && by !== "auto") return undefined;
       const event: PermissionResolutionEvent = {
         kind: "permission",

package/app/contracts.ts

@@ -292,6 +292,14 @@ export const ENV_CONTRACTS = {
     owner: "app/agentGuide.ts",
     semantics: "Engine transport selector.",
   },
+  NANO_WORKFORCE_PERMISSION_ESCALATION: {
+    category: "env",
+    name: "NANO_WORKFORCE_PERMISSION_ESCALATION",
+    owner: "app/agentic/permission-bridge.ts",
+    semantics:
+      "Per-hire opt-in master switch for the ACP permission-escalation bridge (issue #559, ADR 0056). When on ('1'/'true'/'on'/'yes'), an escalate-policy session/request_permission is bridged to a nano-workforce Tasks-inbox escalation and the operator's Allow/Deny answer is flowed back down the relay as a permission RESOLUTION. Default OFF → yolo auto-allow: no user task, no prompt. A yolo-policy request never reaches the bridge regardless.",
+    default: "off",
+  },
 } as const satisfies Record<string, EnvContract>;
 
 /** The set of declared config-key names — the single typed vocabulary of env keys. */

package/app/userTasks.ts

@@ -44,6 +44,15 @@ export const PR_WAIT_ANSWER_ELEMENT = "wait-answer";
  *  canonical `completeUserTask` door and surfaced in this same Tasks inbox. */
 export const PR_WAIT_MERGE_ANSWER_ELEMENT = "wait-merge-answer";
 
+/** The ACP permission-prompt escalation (issue #559, ADR 0056) — the Tasks-inbox kind a bridged
+ *  `session/request_permission` surfaces under when an escalate-policy agent asks a human to Allow/Deny
+ *  a proposed action. Unlike the other escalation elements this is NOT a BPMN user-task element; it is
+ *  the advisory app-tier permission bridge's row kind, raised from a derived permission REQUEST and
+ *  answered through the same canonical `completeEscalationAsHuman` door as every other escalation, with
+ *  the operator's answer flowed back down the relay as a permission RESOLUTION. The bridge is OPT-IN per
+ *  hire — a `yolo`-policy request never reaches this path (see `app/agentic/permission-bridge.ts`). */
+export const ACP_PERMISSION_ELEMENT = "acp-permission";
+
 /** One row per currently-open native user-task escalation, denormalised for the Tasks page. Keyed on
  *  the completable `user_task_key` (a task is open at most once). Present iff the engine reports the
  *  task open; `pollUserTasks` deletes it once the task is gone. */
@@ -83,6 +92,7 @@ export const USER_TASK_KIND_LABELS: Readonly<Record<string, string>> = {
   [PR_WAIT_MERGE_ANSWER_ELEMENT]: "PR merge",
   [CONFORMANCE_ESCALATION_ELEMENT]: "Conformance review",
   [DELIVERY_HUMAN_ELEMENT]: "Delivery: human step",
+  [ACP_PERMISSION_ELEMENT]: "Agent permission",
 };
 
 /** The Tasks-inbox label for an open user-task `elementId`, or `undefined` when the element is not a
@@ -99,7 +109,7 @@ export function userTaskKindLabel(elementId: string): string | undefined {
 export interface UserTaskContext {
   userTaskKey: string;
   elementId: string;
-  subjectType: "feature" | "plan" | "pr" | "delivery";
+  subjectType: "feature" | "plan" | "pr" | "delivery" | "agent";
   subjectKey: string;
   /** The subject's human-readable title from its own row (`feature_runs`/`plans`/`pull_requests`.
    *  `title`). Optional/blank tolerated — `buildUserTaskRow` coalesces it to `subjectKey` so the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.146.0",
+  "version": "0.148.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",