@nanobpm/nano-workforce 0.123.2 → 0.125.0

package/docs/agent-guide.md

@@ -407,9 +407,12 @@ PR #202 → a human does a manual OTP publish → PR #303 consumes the just-publ
 lets you compose exactly that as **data** and hand it to a generic runner.
 
 You author the graph as **JSON — never BPMN or code** (Decision 1: the agent must never
-author the executable artifact; the closed node vocabulary is the trust boundary). Two
-doors take that JSON: a **pure `compile`** door you hammer while drafting, and a **gated
-`start`** door that dispatches it.
+author the executable artifact; the closed node vocabulary is the trust boundary). Your
+surface ends at **propose → compile → stage**: a single `compile` door validates the JSON,
+renders a preview, and — when valid — **stages the compiled graph as a proposal** for a
+human. **Dispatch is an operator action in the cockpit, not an agent endpoint** (issue #460):
+there is deliberately no `start` door on the agent surface, so there is nothing an agent can
+call — or replay — to launch a run. A human previews the staged proposal and dispatches it.
 
 ### 9.1 The `DeliveryGraph` shape
 
@@ -445,22 +448,23 @@ A **typed fact** (`emits[]` entry) is `{ name, type, description? }` where
 downstream as `<nodeId>.<name>`. A "click done" human node or a pass-through node declares
 no facts.
 
-### 9.2 The agent loop: draft → compile → fix → approve → start
+### 9.2 The agent loop: draft → compile → stage → ask an operator to dispatch
 
 ```
 GET __BASE__/agent           # ← you are reading it; learn the vocabulary + endpoints
    └─ draft a DeliveryGraph JSON
-        └─ POST __BASE__/actions/compile-delivery-graph   # PURE — validate + preview, repeat freely
+        └─ POST __BASE__/actions/compile-delivery-graph   # validate + preview + STAGE
              ├─ 400 { ok:false, errors:[{path,message}] } → fix the exact offending input, recompile
-             └─ 200 { ok:true, diagram, bpmn, resolved, humanNodes, sideEffects } → review the preview
-                  └─ POST __BASE__/actions/start/delivery-graph   # GATED dispatch
-                       ├─ 400 awaiting-approval (has side effects) → re-POST with approvalToken
-                       └─ 202 running → track it like a plan (§5)
+             └─ 200 { status:"ready", message, digest, preview, reviewUrl }
+                  └─ ask the operator to preview + dispatch it in the cockpit (there is no start door)
 ```
 
-**Compile (pure preview — never deploys).** The fast inner loop. It runs the semantic
-validator and the deterministic compiler and returns a preview with **zero side effects**,
-so call it as often as you like:
+**Compile (validate + preview + stage).** The compile door runs the semantic validator and
+the deterministic compiler and, on success, **stages** the compiled graph as a proposal a
+human can dispatch — it does **not** deploy or run anything. Recompiling a graph you are
+still drafting is safe: a re-compile of the same graph is idempotent, and a changed graph
+with the same `name` supersedes the prior staged proposal, so the cockpit shows exactly one
+live proposal per graph.
 
 ```bash
 curl -sS -X POST __BASE__/actions/compile-delivery-graph \
@@ -468,49 +472,37 @@ curl -sS -X POST __BASE__/actions/compile-delivery-graph \
   -d @graph.json | jq
 ```
 
-- `200 { ok:true, diagram, bpmn, resolved, humanNodes, sideEffects }` — `diagram` is a
-  mermaid `flowchart` of the resolved graph; `bpmn` is the compiled one-shot definition
-  (deterministic — same JSON → byte-identical XML, **not** deployed here); `resolved` is
-  the normalised graph; `humanNodes[]` are the stop-points where it waits for a person;
-  `sideEffects[]` are the `agent`/`connector` actions it **will** perform (what a human
-  approves).
+- `200 { status:"ready", message, digest, preview, reviewUrl }` — the graph compiled and is
+  **staged for operator review**. `digest` is the content-address that NAMES the proposal (so
+  you can tell the operator exactly which one to dispatch); `preview` is `{ diagram,
+  sideEffects, humanNodes }` — `diagram` is a mermaid `flowchart` of the resolved graph,
+  `humanNodes[]` are the stop-points where it waits for a person, and `sideEffects[]` are the
+  `agent`/`connector` actions it **will** perform once an operator dispatches it; `reviewUrl`
+  is a **navigational** cockpit deep-link (a pointer only — **not** a dispatch handle). The
+  response carries **no run key, no token, and no process-instance key**: nothing you can
+  replay to start a run. Your role ends here — hand the operator the `digest` (or `reviewUrl`)
+  and ask them to preview and dispatch it.
 - `400 { ok:false, errors:[{ path, message }] }` — every error path-qualified
   (`nodes[2].kind`, `edges[1].from`, …) for unknown kind, dangling edge, a cycle, or an
-  unresolvable `from` fact. Fix and recompile.
-
-**Start (gated dispatch — the OUTER action).** `compile` and `start` are **separate**
-operations — there is deliberately **no `dryRun` flag** on start (Decision 5/7). The door
-re-validates, re-compiles, then launches the runner:
-
-```bash
-# First submit — a graph with side effects is refused and PARKED for approval:
-curl -sS -X POST __BASE__/actions/start/delivery-graph \
-  -H 'content-type: application/json' \
-  -d '{ "graph": { … } }' | jq
-# → 400 { ok:false, status:"awaiting-approval", runKey, digest, sideEffecting:true,
-#          approvalToken:"<digest>", message:"graph has N side-effecting node(s); re-submit with approvalToken" }
-
-# Approve by re-submitting with the token (== the digest) you were handed:
-curl -sS -X POST __BASE__/actions/start/delivery-graph \
-  -H 'content-type: application/json' \
-  -d '{ "graph": { … }, "approvalToken": "<digest>" }' | jq
-# → 202 { ok:true, status:"running", runKey, digest, sideEffecting:true,
-#          alreadyRunning:false, processInstanceKey, processDefinitionId:"delivery-graph-<digest>" }
-```
-
-The request body is `{ graph, approvalToken?, idempotencyKey? }`:
-
-| field | type | meaning |
-|---|---|---|
-| `graph` | `DeliveryGraph` | the JSON graph. Required. |
-| `approvalToken` | string | the approval **of the rendered preview** (Decision 7). A graph with any **side-effecting** (`agent`/`connector`) node — one that merges PRs / publishes — dispatches **only** when you present its content-addressed token (the `digest`, returned on the first unapproved submit). A graph with **only** `wait`/`human` nodes needs none and dispatches straight away. |
-| `idempotencyKey` | string | optional. A re-POST with the same key (or, when omitted, the same graph — the default key is the content digest) does **not** double-launch: an in-flight run short-circuits with `alreadyRunning: true`. |
-
-The running graph registers as a run aggregate, so its current phase / parked node shows
-in the cockpit's **Active Delivery Graphs** grid (e.g. *"parked on human node: manual OTP
-publish"*). Track it like a plan (§5) via its `processInstanceKey`. A `human` node parks
-on the **Tasks** inbox and is answered exactly as an escalation is (§3) — its completion
-emits any declared facts, which downstream edges bind.
+  unresolvable `from` fact. Fix and recompile; nothing is staged.
+
+**Dispatch (operator-only — NOT on the agent surface).** There is deliberately no agent
+`start` endpoint (Decision 5/7, issue #460). Dispatch is a human action: an operator opens
+the **Delivery Graphs** page in the cockpit, reviews the staged proposal's rendered preview
+(its diagram, the human stop-points, and the side effects a dispatch authorises), and clicks
+**Dispatch** on the one they approve. The operator clicking Dispatch **is** the approval — it
+is content-addressed to the exact digest they previewed, so it cannot be a replay of some
+other graph. Once dispatched, the graph deploys + runs engine-natively and registers as a run
+aggregate, so its current phase / parked node shows in the cockpit's **Active Delivery
+Graphs** grid (e.g. *"parked on human node: manual OTP publish"*). A `human` node parks on the
+**Tasks** inbox and is answered exactly as an escalation is (§3) — its completion emits any
+declared facts, which downstream edges bind.
+
+> **Why the split?** Making the compile door the end of the agent surface closes a
+> self-approval hole: the old flow handed the same caller a content-addressed approval token
+> to re-submit with, so any holder of the API credential approved its own graph. Removing the
+> dispatch affordance from the agent surface entirely (capability by absence) means there is
+> nothing to replay — the human in the cockpit is the only actor who can launch side effects.
 
 ### 9.3 Worked example — the cross-repo human-in-the-loop release
 
@@ -557,11 +549,11 @@ humanNodes: [ { nodeId: "manual-publish", emits: [ { name: "publishedVersion", t
 sideEffects: [ { nodeId: "open-pr-c", kind: "agent", … }, { nodeId: "undraft-merge-b", kind: "agent", … } ]
 ```
 
-Two side-effecting `agent` nodes ⇒ `start` **requires approval**: the first submit returns
-`awaiting-approval` with an `approvalToken`; re-submit carrying it to dispatch. The graph
-then runs to `manual-publish`, parks it on the Tasks inbox (`now do X`), and — once a human
-(or agent) completes it with the `publishedVersion` — binds that fact into `open-pr-c` and
-carries on to `merge-c`.
+Two side-effecting `agent` nodes ⇒ the compile door **stages** the proposal and hands you a
+`digest` + `reviewUrl`; ask an operator to preview and **Dispatch** it in the cockpit. Once
+they do, the graph runs to `manual-publish`, parks it on the Tasks inbox (`now do X`), and —
+once a human (or agent) completes it with the `publishedVersion` — binds that fact into
+`open-pr-c` and carries on to `merge-c`.
 
 To swap the manual PR-#303 path for a **capability** edge instead of a raw `pr` watch, make
 the consumer a `wait` node with `kind: "capability"` (resolving *which published

package/e2e/delivery-graph-dispatch.e2e.ts

@@ -0,0 +1,155 @@
+// End-to-end proof of the OPERATOR DISPATCH flow (ADR 0005 Decision 7, issue #460) driven through its
+// REAL ingress: the agent `compileDeliveryGraph` door STAGES a proposal, and the operator
+// `dispatchDeliveryGraph` door launches the one the operator picked BY DIGEST. Hermetic: deterministic
+// virtual clock, no network. It proves the acceptance the slice hinges on:
+//
+//   • AGENT SURFACE ENDS AT STAGE: compiling a side-effecting graph returns a `ready` preview + a
+//     content `digest` and STAGES a durable `delivery_graph_proposals` row — but NO run key, token, or
+//     PIK, and NO engine instance is started (the agent cannot reach a run through its surface).
+//   • OPERATOR DISPATCH: dispatching that digest deploys + runs the graph engine-natively (the agent
+//     side effect fires), marks the proposal `dispatched`, and the run's derived phase shows WHERE it
+//     is parked ("Parked on human node: …") via the same `pollDeliveryGraphPhase` projection.
+//   • NO REPLAY: there is no agent `start/delivery-graph` operation to call — the self-approval hole is
+//     closed by absence.
+//   • COMPLETION: when the instance ends, the poller reconciles the run to `done`.
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { after, describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { deliveryGraphProposals } from "../app/deliveryGraphProposals.ts";
+import { deliveryGraphRuns } from "../app/deliveryGraphRun.ts";
+import { pollDeliveryGraphPhase } from "../app/service.ts";
+import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
+
+const APP_ROOT = resolve(import.meta.dirname, "..");
+const GITHUB_ENV: Record<string, string> = { NANO_PR_GITHUB_TRANSPORT: "token", GITHUB_TOKEN: "" };
+
+interface StagedResult {
+  status: string;
+  message: string;
+  digest: string;
+  reviewUrl?: string;
+}
+interface DispatchResult {
+  ok: boolean;
+  status?: string;
+  runKey?: string;
+  digest?: string;
+  sideEffecting?: boolean;
+  alreadyRunning?: boolean;
+  processInstanceKey?: string;
+  error?: string;
+}
+
+// A side-effecting graph: an `agent` side effect gated ahead of a `human` stop. Dispatch is an operator
+// action (the agent + the human-facing merge/publish class of graphs Decision 7 protects).
+const GRAPH: DeliveryGraph = {
+  name: "release runbook e2e",
+  nodes: [
+    { id: "open", kind: "agent", agent: { jobType: "senior:demo", prompt: "open + prep" } },
+    { id: "publish", kind: "human", human: { prompt: "run the manual OTP publish" } },
+  ],
+  edges: [{ from: "open", to: "publish" }],
+};
+
+describe("delivery-graph dispatch — agent compiles→stages, operator dispatches by digest, idempotent (#460)", () => {
+  const dirs: string[] = [];
+  const apps: TestApp[] = [];
+  after(async () => {
+    for (const app of apps) await app.stop?.();
+    for (const d of dirs) rmSync(d, { recursive: true, force: true });
+  });
+  const boot = async (): Promise<TestApp> => {
+    const d = mkdtempSync(join(tmpdir(), "nwf-delivery-dispatch-e2e-"));
+    dirs.push(d);
+    const app = await bootTestApp(APP_ROOT, { env: { ...GITHUB_ENV, NANO_APP_DB_URL: `file:${join(d, "app.db")}` } });
+    apps.push(app);
+    return app;
+  };
+
+  test("the agent compile door stages a proposal (no run handle); the operator dispatches it by digest, once", async () => {
+    const app = await boot();
+    assert.ok(app.api, "app declares an `api` binding");
+    const api = app.api;
+
+    let agentFired = 0;
+    await app.engine.registerWorker("senior:demo", async () => {
+      agentFired++;
+      return {};
+    });
+
+    // ── Agent surface ends at stage: compile → ready + digest, staged, NOTHING launched ───────────
+    const staged = await api.call<StagedResult>("compileDeliveryGraph", { body: GRAPH });
+    assert.equal(staged.status, 200, "a valid graph compiles");
+    assert.equal(staged.body.status, "ready");
+    assert.ok(staged.body.digest, "the response carries the content digest that names the proposal");
+    // The self-approval hole is closed by ABSENCE: no run key / token / PIK in the response.
+    assert.equal((staged.body as unknown as Record<string, unknown>).runKey, undefined);
+    assert.equal((staged.body as unknown as Record<string, unknown>).approvalToken, undefined);
+    assert.equal((staged.body as unknown as Record<string, unknown>).processInstanceKey, undefined);
+    await app.settle();
+    assert.equal(agentFired, 0, "a staged graph never dispatched its side effect");
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 0, "no run row while merely staged");
+
+    // The proposal is durable + visible for operator dispatch.
+    const digest = staged.body.digest;
+    const proposal = await deliveryGraphProposals(app.db).get(digest);
+    assert.ok(proposal, "a delivery_graph_proposals row exists for the staged graph");
+    assert.equal(proposal?.status, "staged");
+
+    // ── Operator dispatch: dispatch the digest → deploys + runs engine-natively ───────────────────
+    const dispatched = await api.call<DispatchResult>("dispatchDeliveryGraph", { body: { digest } });
+    assert.equal(dispatched.status, 202, "dispatching a staged digest launches the run");
+    assert.equal(dispatched.body.status, "running");
+    assert.equal(dispatched.body.alreadyRunning, false);
+    assert.ok(dispatched.body.processInstanceKey, "the run carries the started engine instance key");
+    await app.settle();
+    assert.equal(agentFired, 1, "the agent side effect fired exactly once");
+    assert.equal((await deliveryGraphProposals(app.db).get(digest))?.status, "dispatched", "the proposal is consumed");
+
+    // Exactly one running run, carrying its instance.
+    const runningRows = await deliveryGraphRuns(app.db).find({ status: "running" });
+    assert.equal(runningRows.length, 1, "exactly one running run");
+    assert.equal(runningRows[0]?.process_key, dispatched.body.processInstanceKey);
+    const runKey = runningRows[0]?.run_key as string;
+
+    // ── Cockpit phase: the poller derives WHERE the run is parked (the human node) ─────────────────
+    await pollDeliveryGraphPhase(app.db, app.engine);
+    const phased = await deliveryGraphRuns(app.db).get(runKey);
+    assert.equal(phased?.status, "running");
+    assert.match(String(phased?.phase), /^Parked on human node:/, `phase shows the parked human node, got ${phased?.phase}`);
+
+    // ── No replay: the consumed proposal cannot re-launch ─────────────────────────────────────────
+    const replay = await api.call<DispatchResult>("dispatchDeliveryGraph", { body: { digest } });
+    assert.equal(replay.status, 400, "an already-dispatched digest cannot be re-dispatched");
+    await app.settle();
+    assert.equal(agentFired, 1, "the agent side effect STILL fired only once (no double-launch)");
+
+    // ── Completion: complete the human stop → the instance ends → the poller reconciles to done ───
+    const open = await app.engine.searchUserTasks({ state: "CREATED" });
+    const human = open.find((t) => t.elementId?.startsWith("delivery-human-task__") && !t.elementId?.endsWith("__esc"));
+    assert.ok(human, `a human user task is open, got ${JSON.stringify(open.map((t) => t.elementId))}`);
+    await app.engine.completeUserTask(human.userTaskKey, { humanOutcome: "completed" });
+    await app.settle();
+    await pollDeliveryGraphPhase(app.db, app.engine);
+    const done = await deliveryGraphRuns(app.db).get(runKey);
+    assert.equal(done?.status, "done", "the completed instance reconciled the run to done");
+    assert.equal(done?.phase, "Completed");
+  });
+
+  test("a non-side-effecting (human-only) graph: stage then dispatch runs it straight away", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    const graph: DeliveryGraph = { name: "manual gate", nodes: [{ id: "ack", kind: "human", human: { prompt: "click done" } }] };
+    const staged = await api.call<StagedResult>("compileDeliveryGraph", { body: graph });
+    assert.equal(staged.status, 200);
+    const res = await api.call<DispatchResult>("dispatchDeliveryGraph", { body: { digest: staged.body.digest } });
+    assert.equal(res.status, 202, "dispatching a human-only graph runs it");
+    assert.equal(res.body.status, "running");
+    assert.equal(res.body.sideEffecting, false);
+    assert.ok(res.body.processInstanceKey);
+  });
+});