@nanobpm/nano-workforce 0.170.1 → 0.171.1

package/openapi.yaml

@@ -3118,6 +3118,39 @@ components:
         abandoned:
           type: boolean
           description: Derived from pull_requests.status; true ⇒ the run was cancelled and the agent must stop.
+    CancelInstanceIntent:
+      type: object
+      additionalProperties: false
+      required:
+        - processInstanceKey
+      properties:
+        processInstanceKey:
+          type: string
+          description: The engine process-instance key of the run to cancel (the `process_key` column surfaced by `listActivePrs`/the Convergence page). Must be a string — engine keys are 64-bit and a numeric value risks silent JS precision loss.
+    CancelInstanceResult:
+      type: object
+      required:
+        - ok
+        - processInstanceKey
+        - state
+        - reconciled
+      properties:
+        ok:
+          type: boolean
+          description: True when the engine confirmed the instance is terminated (the record is now — or derives as — `abandoned`). False ⇒ the engine did NOT stop the instance (surfaced as a 502).
+        processInstanceKey:
+          type: string
+          description: The cancelled instance key, echoed back.
+        state:
+          type: string
+          enum: [ACTIVE, COMPLETED, TERMINATED, gone]
+          description: The instance state read back from the engine after the cancel attempt. `gone` ⇒ the engine has no record of the key (already cleaned up / never existed).
+        reconciled:
+          type: integer
+          description: 1 when the immediate reconcile recorded the terminal source into the canonical instance-state projection (so the PR's derived tracking status flips to `abandoned` at once), else 0.
+        error:
+          type: string
+          description: Present only on a non-terminal failure — the reason the cancel did not take.
 # ─────────────────────────────────────────────────────────────────────────────────────────────
 # MCP tool-schema convention (epic nano-workforce#605, S0 — the shared invariant every later slice
 # inherits). The Urban runtime projects THIS document into MCP tools (ADR 0067 — zero MCP server
@@ -3159,6 +3192,59 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /actions/cancel:
+    post:
+      operationId: cancelInstance
+      summary: "Cancel a wedged run the app-owned, record-consistent way: terminate the engine instance AND flip its PR/plan record to `abandoned` (issue #667). The correct unstick — go through the app so its record state stays consistent, rather than engine-level `urban_debug_cancel_instance`, which cancels out from under the app and leaves the PR row inconsistent."
+      security:
+        - hookSecret: []
+        - {}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              # BEGIN generated:mcp-body source=#/components/schemas/CancelInstanceIntent (scripts/inline-mcp-bodies.ts — do not hand-edit)
+              type: object
+              additionalProperties: false
+              required:
+                - processInstanceKey
+              properties:
+                processInstanceKey:
+                  type: string
+                  description: The engine process-instance key of the run to cancel (the `process_key` column surfaced by `listActivePrs`/the Convergence page). Must be a string — engine keys are 64-bit and a numeric value risks silent JS precision loss.
+              # END generated:mcp-body
+      responses:
+        "200":
+          description: The instance was terminated; its record derives/flips to `abandoned` and drops out of `listActivePrs`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CancelInstanceResult"
+        "400":
+          description: Missing/invalid `processInstanceKey`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "502":
+          description: The engine did NOT stop the instance (the cancel was not committed); the run may still be live.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CancelInstanceResult"
+        "503":
+          description: The app has no data source configured, so the cancel cannot be reconciled into the record.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /escalations:
     get:
       operationId: listEscalations

package/operations/cancelInstance.test.ts

@@ -0,0 +1,138 @@
+// Tests for POST /app/api/actions/cancel — operationId `cancelInstance` (issue #667, epic #664).
+//
+// The delegate is a thin, record-consistent door over the SAME primitive the UI's per-row Cancel
+// uses (urban's `cancelInstanceReconciling`). These tests drive the REAL primitive through a fake
+// engine — no second source of truth for the cancel-then-reconcile dance — and pin the delegate's
+// own contract: body validation, string-key enforcement, and the ok→200 / not-committed→502 mapping. The
+// `abandoned` transition itself is DERIVED off the instance-state projection the primitive feeds
+// (ADR 0065), so terminating the instance through this door is exactly what makes the PR drop out of
+// `listActivePrs`; that derivation is the framework's, exercised via the shared primitive here.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import handler from "./cancelInstance.ts";
+
+interface FakeEngineOpts {
+  /** Reject the cancel call (an uncommitted termination). */
+  cancelThrows?: boolean;
+  /** The state `searchProcessInstances` reads back for the key. `undefined` ⇒ "gone" (empty). */
+  readBackState?: "ACTIVE" | "COMPLETED" | "TERMINATED" | undefined;
+}
+
+function makeApp(opts: FakeEngineOpts = {}): { app: AppApi; cancelCalls: string[] } {
+  const cancelCalls: string[] = [];
+  const engine = {
+    async cancelInstance({ processInstanceKey }: { processInstanceKey: string }) {
+      cancelCalls.push(processInstanceKey);
+      if (opts.cancelThrows) throw new Error("engine refused");
+    },
+    async searchProcessInstances() {
+      return opts.readBackState ? [{ state: opts.readBackState }] : [];
+    },
+  };
+  // hasDefaultSource:false makes the primitive's projection feed a clean no-op (no derived-status
+  // store to fake here) — the reconcile-through-projection path is the framework's own tested seam.
+  const data = { hasDefaultSource: () => false };
+  const app = { engine, data, log: noopLog() } as unknown as AppApi;
+  return { app, cancelCalls };
+}
+
+function req(headers: Record<string, string> = {}) {
+  return { method: "POST", path: "/app/api/actions/cancel", headers: new Headers(headers) };
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: test-only invocation shim for the delegate.
+async function callHandler(
+  h: typeof handler,
+  app: AppApi,
+  body: unknown,
+  headers: Record<string, string> = {},
+  // biome-ignore lint/suspicious/noExplicitAny: test-only invocation shim for the delegate.
+): Promise<any> {
+  return await h({ req: req(headers) as any, params: {}, query: {}, body } as any, app);
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: test-only invocation shim for the delegate.
+async function call(app: AppApi, body: unknown): Promise<any> {
+  return await callHandler(handler, app, body);
+}
+
+test("a missing processInstanceKey → 400 and never touches the engine", async () => {
+  const { app, cancelCalls } = makeApp();
+  assertEquals((await call(app, {})).status, 400);
+  assertEquals((await call(app, { processInstanceKey: "  " })).status, 400);
+  assertEquals((await call(app, undefined)).status, 400);
+  assertEquals(cancelCalls.length, 0, "no cancel attempted without a key");
+});
+
+test("a committed cancel (engine terminates) → 200 ok, echoes the key, and cancels via the engine", async () => {
+  const { app, cancelCalls } = makeApp({ readBackState: "TERMINATED" });
+  const res = await call(app, { processInstanceKey: "2985" });
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assertEquals(res.body.processInstanceKey, "2985");
+  assertEquals(res.body.state, "TERMINATED");
+  assertEquals(cancelCalls, ["2985"], "the shared primitive issued the engine cancel for the key");
+});
+
+test("an accepted cancel whose read model lags at ACTIVE is still trusted → 200 ok", async () => {
+  // A non-throwing cancelInstance is a committed 204; the primitive trusts it even if the read
+  // model still reports ACTIVE. The door must surface that as success, not a spurious 502.
+  const { app } = makeApp({ readBackState: "ACTIVE" });
+  const res = await call(app, { processInstanceKey: "42" });
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+});
+
+test("a numeric processInstanceKey is rejected → 400 and never touches the engine", async () => {
+  // Engine keys are 64-bit and can exceed JS's safe-integer range, so a numeric JSON value has
+  // already lost precision before we see it — the door requires a string (matching the OpenAPI
+  // contract) rather than coercing a possibly-corrupted number.
+  const { app, cancelCalls } = makeApp({ readBackState: "TERMINATED" });
+  const res = await call(app, { processInstanceKey: 2985 });
+  assertEquals(res.status, 400);
+  assertEquals(cancelCalls.length, 0, "a non-string key never reaches the engine");
+});
+
+test("an uncommitted cancel (engine throws, instance still ACTIVE) → 502 not-ok with the reason", async () => {
+  const { app } = makeApp({ cancelThrows: true, readBackState: "ACTIVE" });
+  const res = await call(app, { processInstanceKey: "77" });
+  assertEquals(res.status, 502, "an unconfirmed termination must NOT be reported as success");
+  assertEquals(res.body.ok, false);
+  assert(typeof res.body.error === "string" && res.body.error.length > 0, "carries the failure reason");
+});
+
+test("no data source configured → 503 and never touches the engine (cannot reconcile the record)", async () => {
+  // The record-consistent door refuses to cancel when it has no data source to reconcile the
+  // terminal state into — a live cancel with no derived-status update would leave the record lying.
+  const { app, cancelCalls } = makeApp();
+  // Strip the data source the primitive would reconcile against.
+  (app as unknown as { data?: unknown }).data = undefined;
+  const res = await call(app, { processInstanceKey: "2985" });
+  assertEquals(res.status, 503);
+  assert("error" in res.body, "carries an error reason");
+  assertEquals(cancelCalls.length, 0, "no cancel attempted without a data source");
+});
+
+test("shared-secret guard: when NANO_PR_WEBHOOK_SECRET is set, a missing/wrong secret → 401; the right one passes", async () => {
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    // SECRET is captured at module load, so import a cache-busted copy to observe the guard.
+    const mod = await import(`./cancelInstance.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    const { app, cancelCalls } = makeApp({ readBackState: "TERMINATED" });
+    const missing = await callHandler(guarded, app, { processInstanceKey: "2985" });
+    assertEquals(missing.status, 401, "no secret header is rejected");
+    const wrong = await callHandler(guarded, app, { processInstanceKey: "2985" }, { "x-hook-secret": "nope" });
+    assertEquals(wrong.status, 401, "a wrong secret is rejected");
+    assertEquals(cancelCalls.length, 0, "a rejected request never reaches the engine");
+    const ok = await callHandler(guarded, app, { processInstanceKey: "2985" }, { "x-hook-secret": "s3cr3t" });
+    assertEquals(ok.status, 200, "the correct secret is accepted");
+    assertEquals(cancelCalls, ["2985"], "only the authorized request issues the engine cancel");
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});

package/operations/cancelInstance.ts

@@ -0,0 +1,80 @@
+// POST /app/api/actions/cancel → operationId `cancelInstance` (issue #667, epic #664).
+//
+// The app-owned, RECORD-CONSISTENT unstick for a wedged run. agent-guide §7 documents
+// `POST /actions/cancel { processInstanceKey }` as the CORRECT way to abort a run — "go through the
+// app so its record state stays consistent" — but until now the only cancel projected over MCP was
+// the engine-level `urban_debug_cancel_instance`, which §7 warns against because it terminates the
+// instance out from under the app and leaves the PR/plan row inconsistent. This delegate closes that
+// doc/impl drift by exposing the app door as a projected MCP tool.
+//
+// Derivation over duplication (AGENTS.md): it does NOT re-implement the cancel-then-transition
+// dance. It routes through the EXACT same primitive the UI's per-row Cancel button uses —
+// urban's `cancelInstanceReconciling` (the handler wired to the built-in `/app/actions/cancel`
+// page action) — so there is ONE source of truth for terminating the instance and recording the
+// terminal source into the canonical instance-state projection. The PR's tracking status then
+// derives to `abandoned` (ADR 0065) and the row drops out of `listActivePrs`. The `instanceTracking`
+// bindings come from the app's single accessor (`engineBackedBindings`), so the set can never drift
+// from the reconciler's registry.
+//
+// The runtime validates the body against openapi.yaml (`processInstanceKey` required); the optional
+// shared-secret guard stays HERE (the runtime does not enforce OpenAPI `security`): as a MUTATING
+// door, when NANO_PR_WEBHOOK_SECRET is set callers must present it via the x-hook-secret header —
+// mirroring `reconcileEngineState`/`agentCompleteEscalation`.
+
+import { cancelInstanceReconciling } from "@nanobpm/urban";
+import { engineBackedBindings } from "../app/instanceTracking.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("cancelInstance", async ({ req, body }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("cancelInstance rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  if (!app.data) {
+    app.log.warn("cancelInstance: no data source configured — cannot reconcile the record");
+    return { status: 503, body: { error: "no data source configured" } };
+  }
+
+  // Require a STRING key. Engine instance keys are 64-bit and can exceed JS's safe-integer range,
+  // so a numeric JSON value would already have lost precision before it reached us — accepting it
+  // (and coercing it back to a string) would silently cancel the wrong instance and also contradicts
+  // the OpenAPI `string` contract. Reject a non-string with a 400 rather than coerce.
+  const raw = body && typeof body === "object" ? body.processInstanceKey : undefined;
+  const processInstanceKey = typeof raw === "string" ? raw.trim() : "";
+  if (!processInstanceKey) {
+    return { status: 400, body: { error: "processInstanceKey is required and must be a string" } };
+  }
+
+  const result = await cancelInstanceReconciling(
+    app,
+    [...engineBackedBindings()],
+    processInstanceKey,
+  );
+  const responseBody = {
+    ok: result.ok,
+    processInstanceKey: result.processInstanceKey,
+    state: result.state,
+    reconciled: result.reconciled,
+    ...(result.error !== undefined ? { error: result.error } : {}),
+  };
+  if (result.ok) {
+    app.log.info("cancelInstance: instance terminated", {
+      processInstanceKey,
+      state: result.state,
+      reconciled: result.reconciled,
+    });
+    return { status: 200, body: responseBody };
+  }
+  // A !ok result means the engine did NOT stop the instance (the cancel was not committed); the run
+  // may still be live, so surface 502 — the same non-committed-cancel signal the built-in page
+  // action returns.
+  app.log.warn("cancelInstance: engine did not confirm termination", {
+    processInstanceKey,
+    state: result.state,
+    error: result.error,
+  });
+  return { status: 502, body: responseBody };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.170.1",
+  "version": "0.171.1",
   "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",
@@ -62,7 +62,7 @@
     "lint:fix": "biome check --write app operations workers pages components scripts e2e main.ts"
   },
   "dependencies": {
-    "@nanobpm/agentic": "^0.4.0",
+    "@nanobpm/agentic": "^0.10.0",
     "@nanobpm/urban": "^0.88.1",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },