@nanobpm/nano-workforce 0.34.0 → 0.35.1

package/.github/workflows/ci.yml

@@ -44,7 +44,7 @@ jobs:
           deno-version: v2.x
 
       - name: Typecheck (Deno)
-        run: deno check main.ts 'workers/**/*.ts' 'actions/**/*.ts'
+        run: deno check main.ts 'workers/**/*.ts' 'actions/**/*.ts' 'operations/**/*.ts'
 
       # Deploy-safety gate: every model-authored `{{template}}` agent-prompt header must resolve
       # to a declared, non-blank prompt (and no agent prompt may ship blank). A broken/blank token

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.35.1](https://github.com/nanobpm/nano-workforce/compare/v0.35.0...v0.35.1) (2026-08-10)
+
+
+### Bug Fixes
+
+* **api:** move OpenAPI base off the reserved /app page-runtime namespace ([#103](https://github.com/nanobpm/nano-workforce/issues/103)) ([6dfb77f](https://github.com/nanobpm/nano-workforce/commit/6dfb77ff82b532965c4a9823d771d46d4ffa920e)), closes [#102](https://github.com/nanobpm/nano-workforce/issues/102)
+
+# [0.35.0](https://github.com/nanobpm/nano-workforce/compare/v0.34.0...v0.35.0) (2026-08-10)
+
+
+### Features
+
+* migrate externally-facing endpoints to the OpenAPI api surface ([#102](https://github.com/nanobpm/nano-workforce/issues/102)) ([5598e2c](https://github.com/nanobpm/nano-workforce/commit/5598e2ce5a8ec3dc241401714284ce8c94420f7a))
+
 # [0.34.0](https://github.com/nanobpm/nano-workforce/compare/v0.33.1...v0.34.0) (2026-08-09)
 
 

package/SPEC.md

@@ -261,13 +261,21 @@ child grids, a lazily-loaded transcript, and a conditional **answer** form shown
 when the PR has an open escalation (`open_escalation_id`, denormalised onto the
 row by migration `003`).
 
-`main.ts` delegates to the runtime and intercepts only the three actions that
-carry app-specific business logic:
+The app-specific business-logic endpoints are **OpenAPI operations** mounted
+under `api.base` (`/app/api`), each implemented by a delegate module in
+`operations/`, plus a `/hooks/*` webhook. The runtime serves them all; `main.ts`
+only starts the runtime and the review-ready poller. The full, authoritative
+contract is `openapi.json` (Swagger UI at `/app/api-docs`); the OpenAPI rows
+below are the complete set of operations, `/hooks/submit` is one of the `/hooks/*`
+webhooks:
 
 | method | route | purpose |
 |---|---|---|
-| `POST` | `/app/actions/start/convergence-loop` | parse the PR ref → create the aggregate + start the process |
-| `POST` | `/app/actions/message` (`escalation-answered`) | answer an open escalation → publish `escalation-answered` |
+| `GET` | `/app/api/status` | list tracked PRs + count |
+| `GET` | `/app/api/version` | app + engine version |
+| `POST` | `/app/api/actions/start/convergence-loop` | parse the PR ref → create the aggregate + start the process |
+| `POST` | `/app/api/actions/start/plan-fanout` | start a plan fan-out run |
+| `POST` | `/app/api/actions/message` (`escalation-answered`) | answer an open escalation → publish `escalation-answered` |
 | `POST` | `/hooks/submit` | webhook submit (shared-secret auth) → start the process |
 
 Everything else (`GET /`, `GET /app/pages/*`, `GET /app/data/*`, the renderer) is

package/app/plan.ts

@@ -267,10 +267,11 @@ export async function startPlan(data: DataLayer, engine: EngineClient, parsed: P
       blackboardBrief: renderCoordinationBrief(bbUrl),
     },
   });
-  if (processInstanceKey != null) {
-    await table.update(parsed.planKey, { process_key: String(processInstanceKey), updated_at: now() });
+  const processKey = processInstanceKey == null ? null : String(processInstanceKey);
+  if (processKey != null) {
+    await table.update(parsed.planKey, { process_key: processKey, updated_at: now() });
   }
-  return { planKey: parsed.planKey, processKey: processInstanceKey };
+  return { planKey: parsed.planKey, processKey };
 }
 
 /** Re-point a plan's denormalised "open task escalation" fields at its OLDEST

package/app/service.test.ts

@@ -252,3 +252,45 @@ Deno.test("pollIncidents picks the oldest incident by creationTime, sorting a mi
   assertEquals(row.incident_message, "the first fault");
 });
 
+
+// Red/green regression (nano-workforce#102 review): the engine can hand back a numeric
+// `processInstanceKey`, but the OpenAPI `SubmitResult.processKey` contract is `string | null`, so
+// under api `validateResponses:"dev"` a raw number fails response validation. Stringifying at the
+// source also keeps the returned key aligned with the DB-persisted `String(...)` value and dodges
+// JS 53-bit precision limits for large 64-bit keys (which is why keys travel as strings in
+// practice). `submitPr` must stringify it both in the returned body and the persisted row.
+Deno.test("submitPr stringifies a numeric processInstanceKey (contract: string | null)", async () => {
+  await withGithubOff(async () => {
+    const PR_KEY = "owner/repo#7";
+    const stores: Record<string, { rows: unknown[]; key: string }> = {
+      pull_requests: { rows: [], key: "pr_key" },
+      escalations: { rows: [], key: "id" },
+      pr_dependencies: { rows: [], key: "pr_key" },
+    };
+    const data = {
+      table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+      // deno-lint-ignore no-explicit-any
+    } as any;
+    const engine = {
+      // A large key delivered as a JS number — the exact case that breaks dev response validation
+      // (number vs the `string | null` contract). Kept within MAX_SAFE_INTEGER so the fixture
+      // itself is exact; true 64-bit keys travel as strings for the same precision reason.
+      createInstance: () => Promise.resolve({ processInstanceKey: 2251799813685249 }),
+      // deno-lint-ignore no-explicit-any
+    } as any;
+
+    const res = await submitPr(data, engine, {
+      repo: "owner/repo",
+      number: 7,
+      url: "https://github.com/owner/repo/pull/7",
+      prKey: PR_KEY,
+    });
+
+    // deno-lint-ignore no-explicit-any
+    const processKey = (res as any).processKey;
+    assertEquals(typeof processKey, "string");
+    assertEquals(processKey, "2251799813685249");
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.process_key, "2251799813685249");
+  });
+});

package/app/service.ts

@@ -369,10 +369,11 @@ export async function submitPr(
       abandonBrief: renderAbandonBrief(abUrl),
     },
   });
-  if (processInstanceKey != null) {
-    await table.update(parsed.prKey, { process_key: String(processInstanceKey) });
+  const processKey = processInstanceKey == null ? null : String(processInstanceKey);
+  if (processKey != null) {
+    await table.update(parsed.prKey, { process_key: processKey });
   }
-  return { prKey: parsed.prKey, processKey: processInstanceKey };
+  return { prKey: parsed.prKey, processKey };
 }
 
 /** Start the merge-loop for a converged PR (called by the `pr.finalize` worker when AUTO_MERGE

package/app/version.ts

@@ -9,7 +9,7 @@
 // debugging a stuck instance can confirm the process is on the code they think it is.
 //
 // Every probe is best-effort: a missing file or unavailable `.git` yields `null` for that field
-// rather than throwing, so `/app/version` never fails just because one source is absent.
+// rather than throwing, so `/app/api/version` never fails just because one source is absent.
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join, resolve, isAbsolute } from "node:path";
@@ -41,7 +41,7 @@ function readJson(path: string): Record<string, unknown> | null {
  * Read an env var across runtimes: Node exposes `process.env`; Deno may not populate it, so fall
  * back to `Deno.env.get` (guarded — reading env can throw without `--allow-env`).
  */
-function envVar(name: string): string | null {
+export function envVar(name: string): string | null {
   const fromProcess = globalThis.process?.env?.[name];
   if (typeof fromProcess === "string" && fromProcess.trim()) return fromProcess.trim();
   const deno = (globalThis as { Deno?: { env?: { get?(k: string): string | undefined } } }).Deno;

package/deno.json

@@ -6,7 +6,7 @@
     ]
   },
   "imports": {
-    "@nanobpm/urban": "npm:@nanobpm/urban@^0.31.0"
+    "@nanobpm/urban": "npm:@nanobpm/urban@^0.32.0"
   },
   "tasks": {
     "start": "deno run --allow-net --allow-read --allow-write --allow-run=gh --allow-env main.ts",

package/deno.lock

@@ -3,7 +3,6 @@
   "specifiers": {
     "jsr:@std/assert@1": "1.0.19",
     "jsr:@std/internal@^1.0.12": "1.0.14",
-    "npm:@nanobpm/urban@0.31": "0.31.0",
     "npm:@semantic-release/changelog@^6.0.3": "6.0.3_semantic-release@24.2.9__typescript@5.9.3_typescript@5.9.3",
     "npm:@semantic-release/git@^10.0.1": "10.0.1_semantic-release@24.2.9__typescript@5.9.3_typescript@5.9.3",
     "npm:@semantic-release/npm@^13.1.5": "13.1.5_semantic-release@24.2.9__typescript@5.9.3",
@@ -1757,11 +1756,11 @@
   },
   "workspace": {
     "dependencies": [
-      "npm:@nanobpm/urban@0.31"
+      "npm:@nanobpm/urban@0.32"
     ],
     "packageJson": {
       "dependencies": [
-        "npm:@nanobpm/urban@0.31",
+        "npm:@nanobpm/urban@0.32",
         "npm:@semantic-release/changelog@^6.0.3",
         "npm:@semantic-release/git@^10.0.1",
         "npm:@semantic-release/npm@^13.1.5",

package/nano.app.json

@@ -139,29 +139,13 @@
     "label": "Nano Workforce",
     "icon": "assets/icon.svg"
   },
+  "api": {
+    "spec": "openapi.json",
+    "base": "/app/api",
+    "dir": "operations",
+    "validateResponses": "dev"
+  },
   "actions": [
-    {
-      "path": "/app/actions/start/convergence-loop",
-      "module": "actions/start.ts"
-    },
-    {
-      "path": "/app/actions/start/plan-fanout",
-      "module": "actions/plan-start.ts"
-    },
-    {
-      "path": "/app/status",
-      "module": "actions/status.ts",
-      "method": "GET"
-    },
-    {
-      "path": "/app/version",
-      "module": "actions/version.ts",
-      "method": "GET"
-    },
-    {
-      "path": "/app/actions/message",
-      "module": "actions/message.ts"
-    },
     {
       "path": "/hooks/submit",
       "module": "actions/webhook-submit.ts"

package/openapi.json

@@ -0,0 +1,248 @@
+{
+  "openapi": "3.0.3",
+  "info": {
+    "title": "Nano Workforce control API",
+    "version": "1.0.0",
+    "description": "The externally-facing control surface an operator, an automation harness, or an LLM uses to observe and steer PR-convergence and planning runs. Contract-first (ADR 0058): the toolkit derives typed request/response contracts + runtime validators from this document and each `operationId` is implemented by a delegate module in `operations/`. Mounted under base `/app/api`, kept off the framework-reserved `/app` page-runtime namespace (which owns `/app/runtime.js`, `/app/pages/*`, `/app/data/*`). The `/hooks/*` webhook endpoints stay on `actions[]` because they live outside the `/app` namespace."
+  },
+  "components": {
+    "securitySchemes": {
+      "hookSecret": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "x-hook-secret",
+        "description": "Optional shared secret. Enforced by the delegate (NOT the runtime) only when NANO_PR_WEBHOOK_SECRET is set; unset means the endpoint is open. Declared here for documentation."
+      }
+    },
+    "schemas": {
+      "ErrorBody": {
+        "type": "object",
+        "required": ["error"],
+        "properties": { "error": { "type": "string" } }
+      },
+      "ActivePr": {
+        "type": "object",
+        "description": "A tracked PR that is not in a terminal (converged/abandoned) state.",
+        "required": [
+          "prKey", "repo", "number", "url", "title", "status", "round",
+          "processKey", "waitingSince", "openEscalation", "updatedAt",
+          "activeWorker", "leaseUntil"
+        ],
+        "properties": {
+          "prKey": { "type": "string" },
+          "repo": { "type": "string" },
+          "number": { "type": "integer" },
+          "url": { "type": "string" },
+          "title": { "type": ["string", "null"] },
+          "status": { "type": "string" },
+          "round": { "type": "integer" },
+          "processKey": { "type": ["string", "null"], "description": "The engine process instance key; also the keyField the pages processExplorer link uses." },
+          "waitingSince": { "type": ["string", "null"] },
+          "openEscalation": { "type": ["string", "null"] },
+          "updatedAt": { "type": "string" },
+          "activeWorker": { "type": ["string", "null"] },
+          "leaseUntil": { "type": ["string", "null"] }
+        }
+      },
+      "ActivePrList": {
+        "type": "object",
+        "required": ["count", "prs"],
+        "properties": {
+          "count": { "type": "integer" },
+          "prs": { "type": "array", "items": { "$ref": "#/components/schemas/ActivePr" } }
+        }
+      },
+      "VersionInfo": {
+        "type": "object",
+        "description": "The running app's identity (which code is actually live).",
+        "required": [
+          "name", "version", "urbanVersion", "gitSha", "gitBranch",
+          "runtime", "pid", "startedAt", "uptimeSeconds"
+        ],
+        "properties": {
+          "name": { "type": "string" },
+          "version": { "type": ["string", "null"] },
+          "urbanVersion": { "type": ["string", "null"] },
+          "gitSha": { "type": ["string", "null"] },
+          "gitBranch": { "type": ["string", "null"] },
+          "runtime": { "type": "string" },
+          "pid": { "type": ["integer", "null"] },
+          "startedAt": { "type": "string" },
+          "uptimeSeconds": { "type": "integer" }
+        }
+      },
+      "SubmitResult": {
+        "type": "object",
+        "required": ["prKey"],
+        "properties": {
+          "prKey": { "type": "string" },
+          "processKey": { "type": ["string", "null"], "description": "The started convergence-loop instance key (null if the engine did not return one)." },
+          "alreadyRunning": { "type": "boolean", "description": "True when a non-terminal convergence loop for this PR already exists; the aggregate was refreshed and no new instance was started." }
+        }
+      },
+      "StartPlanResult": {
+        "type": "object",
+        "required": ["planKey"],
+        "properties": {
+          "planKey": { "type": "string" },
+          "processKey": { "type": ["string", "null"] },
+          "alreadyRunning": { "type": "boolean", "description": "True when a non-terminal plan for this issue already exists; no new instance was started." }
+        }
+      },
+      "StartVariables": {
+        "type": "object",
+        "description": "Process-start variables. `pr`/`url` (convergence) or `issue`/`url` (planning) name the target; extra keys are forwarded to the engine.",
+        "additionalProperties": true,
+        "properties": {
+          "pr": { "type": "string", "description": "PR reference: owner/repo#123 or a PR URL." },
+          "issue": { "type": "string", "description": "Issue reference: owner/repo#123 or an issue URL." },
+          "url": { "type": "string", "description": "Alias for pr/issue when a bare URL is supplied." },
+          "dependsOn": { "type": "array", "items": { "type": "string" } },
+          "maxRounds": { "type": "integer", "minimum": 1 }
+        }
+      },
+      "MessageResult": {
+        "type": "object",
+        "description": "The result of publishing a message / answering an escalation. Shape varies by message name; `ok` is always present.",
+        "additionalProperties": true,
+        "required": ["ok"],
+        "properties": { "ok": { "type": "boolean" } }
+      }
+    }
+  },
+  "paths": {
+    "/status": {
+      "get": {
+        "operationId": "listActivePrs",
+        "summary": "List every tracked PR currently in flight (not converged/abandoned), newest-updated first.",
+        "security": [{ "hookSecret": [] }, {}],
+        "responses": {
+          "200": {
+            "description": "The active PRs.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivePrList" } } }
+          },
+          "401": {
+            "description": "Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }
+          }
+        }
+      }
+    },
+    "/version": {
+      "get": {
+        "operationId": "getVersion",
+        "summary": "The running app's identity (app/urban versions, git sha/branch, runtime, pid, uptime).",
+        "security": [{ "hookSecret": [] }, {}],
+        "responses": {
+          "200": {
+            "description": "The version/identity payload.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionInfo" } } }
+          },
+          "401": {
+            "description": "Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }
+          }
+        }
+      }
+    },
+    "/actions/start/convergence-loop": {
+      "post": {
+        "operationId": "startConvergenceLoop",
+        "summary": "Register/refresh a PR aggregate (idempotent on prKey) and start its convergence loop.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": true,
+                "required": ["variables"],
+                "properties": { "variables": { "$ref": "#/components/schemas/StartVariables" } }
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "The loop was started (or refreshed).",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResult" } } }
+          },
+          "400": {
+            "description": "The PR reference could not be parsed.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }
+          }
+        }
+      }
+    },
+    "/actions/start/plan-fanout": {
+      "post": {
+        "operationId": "startPlanFanout",
+        "summary": "Register/refresh a plan aggregate (idempotent on planKey) and start the planning fan-out.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": true,
+                "required": ["variables"],
+                "properties": { "variables": { "$ref": "#/components/schemas/StartVariables" } }
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "The plan fan-out was started (or was already running).",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartPlanResult" } } }
+          },
+          "400": {
+            "description": "The issue reference could not be parsed.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }
+          }
+        }
+      }
+    },
+    "/actions/message": {
+      "post": {
+        "operationId": "postMessage",
+        "summary": "Publish a message / answer an escalation. For escalation-answered and feature-escalation-answered names, runs the corresponding answer flow; otherwise a plain publishMessage.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "additionalProperties": true,
+                "required": ["name"],
+                "properties": {
+                  "name": { "type": "string", "description": "The message name (correlates a waiting event)." },
+                  "correlationKey": { "type": "string" },
+                  "variables": {
+                    "type": "object",
+                    "additionalProperties": true,
+                    "properties": { "answer": { "type": "string" } }
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The message was published (or the escalation answered).",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResult" } } }
+          },
+          "400": {
+            "description": "A required field was missing/blank.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } }
+          },
+          "404": {
+            "description": "No matching open escalation / parked token to answer.",
+            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageResult" } } }
+          }
+        }
+      }
+    }
+  }
+}

package/operations/getVersion.test.ts

@@ -0,0 +1,60 @@
+// Tests for GET /app/api/version → operation `getVersion` (ADR 0058 OpenAPI surface).
+// Ported from the previous actions/version.test.ts. Method handling now belongs to the router
+// (only GET is routed here), so there is no 405 case to test at the delegate level.
+import { assert, assertEquals } from "jsr:@std/assert@1";
+import type { AppApi } from "@nanobpm/urban";
+import handler from "./getVersion.ts";
+
+// deno-lint-ignore no-explicit-any
+const app = {} as any as AppApi;
+
+function input(headers: Record<string, string> = {}) {
+  return {
+    req: {
+      method: "GET",
+      path: "/app/api/version",
+      query: new URLSearchParams(),
+      headers: new Headers(headers),
+      text: async () => "",
+      // deno-lint-ignore no-explicit-any
+    } as any,
+    params: {},
+    query: {},
+    body: undefined,
+  };
+}
+
+Deno.test("returns 200 with the app identity", async () => {
+  const res = await handler(input(), app);
+  // deno-lint-ignore no-explicit-any
+  const r = res as any;
+  assertEquals(r.status, 200);
+  assertEquals(r.body.name, "nano-workforce");
+  // These are always present; their values are environment-dependent so we only assert shape.
+  assert("version" in r.body);
+  assert("urbanVersion" in r.body);
+  assert("gitSha" in r.body);
+  assert("gitBranch" in r.body);
+  assert(typeof r.body.runtime === "string" && r.body.runtime.length > 0);
+  assert(typeof r.body.startedAt === "string");
+  assert(typeof r.body.uptimeSeconds === "number");
+});
+
+Deno.test("shared-secret guard rejects a missing/wrong secret when configured", async () => {
+  const prev = Deno.env.get("NANO_PR_WEBHOOK_SECRET");
+  Deno.env.set("NANO_PR_WEBHOOK_SECRET", "s3cr3t");
+  try {
+    // SECRET is bound at import time, so import a cache-busted copy to observe the guard.
+    const mod = await import(`./getVersion.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    // deno-lint-ignore no-explicit-any
+    const bad = (await guarded(input(), app)) as any;
+    assertEquals(bad.status, 401);
+    // deno-lint-ignore no-explicit-any
+    const ok = (await guarded(input({ "x-hook-secret": "s3cr3t" }), app)) as any;
+    assertEquals(ok.status, 200);
+  } finally {
+    if (prev === undefined) Deno.env.delete("NANO_PR_WEBHOOK_SECRET");
+    else Deno.env.set("NANO_PR_WEBHOOK_SECRET", prev);
+  }
+});

package/operations/getVersion.ts

@@ -0,0 +1,25 @@
+// GET /app/api/version → operationId `getVersion` (ADR 0058 OpenAPI surface, mounted under base /app/api).
+// The running app's identity (app + resolved @nanobpm/urban versions, git commit/branch, JS runtime,
+// pid, uptime). Because the app runs its `.ts` sources directly from a checkout with no build step,
+// restarts alone don't tell you whether a fix is live; this endpoint does.
+//
+// Read-only and unauthenticated by design (no secrets in the payload). The optional shared-secret
+// guard stays HERE (the runtime does not enforce OpenAPI `security`); the OpenAPI document only
+// routes GET to this operation, so a wrong method is a 404 from the router (no explicit 405 needed).
+import { defineOperation } from "@nanobpm/urban";
+import { buildVersionInfo, envVar, type VersionInfo } from "../app/version.ts";
+
+// Cross-runtime env read (Node `process.env` OR Deno `Deno.env`): reading via `process.env` alone
+// would silently disable the guard under Deno/compiled runtimes where `process` is absent, leaving
+// the endpoint open even when NANO_PR_WEBHOOK_SECRET is set. Captured once, at module load.
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation<
+  { params: Record<string, string>; query: Record<string, string | string[] | undefined>; body: undefined },
+  VersionInfo | { error: string }
+>("getVersion", ({ req }) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  return { status: 200, body: buildVersionInfo() };
+});

package/operations/listActivePrs.test.ts

@@ -0,0 +1,70 @@
+// Tests for GET /app/api/status → operation `listActivePrs` (ADR 0058 OpenAPI surface).
+// Covers the happy path (count/prs projection) and the optional shared-secret guard. A minimal
+// in-memory DataLayer backs `activePrs` (it reads the `pull_requests` table via `.all()`).
+import { assert, assertEquals } from "jsr:@std/assert@1";
+import type { AppApi } from "@nanobpm/urban";
+import handler from "./listActivePrs.ts";
+
+// deno-lint-ignore no-explicit-any
+function memApp(rows: any[]): AppApi {
+  const tbl = {
+    // deno-lint-ignore require-await
+    async all() {
+      return rows;
+    },
+  };
+  // deno-lint-ignore no-explicit-any
+  return { data: { table: () => tbl } } as any as AppApi;
+}
+
+function input(headers: Record<string, string> = {}) {
+  return {
+    req: {
+      method: "GET",
+      path: "/app/api/status",
+      query: new URLSearchParams(),
+      headers: new Headers(headers),
+      text: async () => "",
+      // deno-lint-ignore no-explicit-any
+    } as any,
+    params: {},
+    query: {},
+    body: undefined,
+  };
+}
+
+Deno.test("returns 200 with a count + projected active PRs", async () => {
+  const app = memApp([
+    { pr_key: "o/r#1", repo: "o/r", number: 1, url: "u1", title: "t", status: "converging", current_round: 2, process_key: "9", updated_at: "2026-01-02" },
+    { pr_key: "o/r#2", repo: "o/r", number: 2, url: "u2", title: null, status: "converged", current_round: 1, process_key: null, updated_at: "2026-01-01" },
+  ]);
+  const res = await handler(input(), app);
+  // deno-lint-ignore no-explicit-any
+  const r = res as any;
+  assertEquals(r.status, 200);
+  // `converged` is terminal → filtered out, leaving one active PR.
+  assertEquals(r.body.count, 1);
+  assertEquals(r.body.prs.length, 1);
+  assertEquals(r.body.prs[0].prKey, "o/r#1");
+  assertEquals(r.body.prs[0].processKey, "9");
+});
+
+Deno.test("shared-secret guard rejects a missing secret when configured", async () => {
+  const prev = Deno.env.get("NANO_PR_WEBHOOK_SECRET");
+  Deno.env.set("NANO_PR_WEBHOOK_SECRET", "s3cr3t");
+  try {
+    const mod = await import(`./listActivePrs.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    const app = memApp([]);
+    // deno-lint-ignore no-explicit-any
+    const bad = (await guarded(input(), app)) as any;
+    assertEquals(bad.status, 401);
+    // deno-lint-ignore no-explicit-any
+    const ok = (await guarded(input({ "x-hook-secret": "s3cr3t" }), app)) as any;
+    assertEquals(ok.status, 200);
+    assert("count" in ok.body);
+  } finally {
+    if (prev === undefined) Deno.env.delete("NANO_PR_WEBHOOK_SECRET");
+    else Deno.env.set("NANO_PR_WEBHOOK_SECRET", prev);
+  }
+});

package/operations/listActivePrs.ts

@@ -0,0 +1,29 @@
+// GET /app/api/status → operationId `listActivePrs` (ADR 0058 OpenAPI surface, mounted under base /app/api).
+// List the PRs currently in flight (every tracked PR not converged/abandoned) so an operator or an
+// external automation harness can see active work — and grab a `processKey` to cancel — without
+// opening the DB or the UI. Read-only projection over the datasource.
+//
+// The runtime validates the (empty) request against openapi.json; the optional shared-secret guard
+// stays HERE (the runtime does not enforce OpenAPI `security`): when NANO_PR_WEBHOOK_SECRET is set,
+// callers must present it via the x-hook-secret header. Unset → open (unchanged default).
+import { defineOperation } from "@nanobpm/urban";
+import { type ActivePr, activePrs } from "../app/service.ts";
+import { envVar } from "../app/version.ts";
+
+// Cross-runtime env read (Node `process.env` OR Deno `Deno.env`): reading via `process.env` alone
+// would silently disable the guard under Deno/compiled runtimes where `process` is absent, leaving
+// the endpoint open even when NANO_PR_WEBHOOK_SECRET is set. Captured once, at module load.
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+type Res = { count: number; prs: ActivePr[] } | { error: string };
+
+export default defineOperation<
+  { params: Record<string, string>; query: Record<string, string | string[] | undefined>; body: undefined },
+  Res
+>("listActivePrs", async ({ req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const prs = await activePrs(app.data);
+  return { status: 200, body: { count: prs.length, prs } };
+});

package/{actions/message.ts → operations/postMessage.ts}

@@ -1,19 +1,28 @@
-// POST /app/actions/message — override the generic publishMessage action. For the
-// `escalation-answered` message we run the review answer flow, and for
-// `feature-escalation-answered` the implementation-phase (per-task) answer flow
-// (issue #25): record the answer, resume the parked token, then re-surface the
-// next open escalation. Any other message falls back to a plain publishMessage
-// (this override shadows the generic route entirely, so the fallback preserves it).
-import type { ActionHandler } from "@nanobpm/urban";
+// POST /app/api/actions/message → operationId `postMessage` (ADR 0058, base /app/api).
+// Replaces the hand-rolled action that overrode the generic publishMessage action. For the
+// `escalation-answered` message we run the review answer flow, and for `feature-escalation-answered`
+// (issue #25) the implementation-phase (per-task) answer flow: record the answer, resume the parked
+// token, then re-surface the next open escalation. Any other message falls back to a plain
+// publishMessage.
+//
+// The runtime validates the body against openapi.json (`name` is required, so a missing name is a 400
+// for free); this delegate keeps the message-name dispatch — the discriminator + downstream behavior
+// is app logic, not something the JSON schema can express.
+import { defineOperation } from "@nanobpm/urban";
 import { answerEscalation } from "../app/service.ts";
 import { answerTaskEscalation, FEATURE_ESCALATION_MESSAGE } from "../app/plan.ts";
 
-const handler: ActionHandler = async ({ body }, app) => {
-  const b = (body ?? {}) as {
-    name?: unknown;
-    correlationKey?: unknown;
-    variables?: Record<string, unknown>;
-  };
+interface Body {
+  name?: unknown;
+  correlationKey?: unknown;
+  variables?: Record<string, unknown>;
+}
+
+export default defineOperation<
+  { params: Record<string, string>; query: Record<string, string | string[] | undefined>; body: Body },
+  Record<string, unknown>
+>("postMessage", async ({ body }, app) => {
+  const b = body ?? {};
   const name = String(b.name ?? "");
   if (!name) return { status: 400, body: { error: "name is required" } };
 
@@ -27,9 +36,9 @@ const handler: ActionHandler = async ({ body }, app) => {
   }
 
   if (name === FEATURE_ESCALATION_MESSAGE) {
-    // Implementation-phase task escalation (issue #25): correlationKey is the
-    // task's `<plan_key>:<task_id>`; record the answer, resume the parked child,
-    // and re-surface the next open escalation.
+    // Implementation-phase task escalation (issue #25): correlationKey is the task's
+    // `<plan_key>:<task_id>`; record the answer, resume the parked child, and re-surface the next
+    // open escalation.
     const corrKey = String(b.correlationKey ?? "");
     const answer = String((b.variables?.answer ?? "") as string).trim();
     if (!corrKey) return { status: 400, body: { error: "correlationKey is required" } };
@@ -44,6 +53,4 @@ const handler: ActionHandler = async ({ body }, app) => {
     variables: b.variables,
   });
   return { status: 200, body: { ok: true } };
-};
-
-export default handler;
+});

package/operations/startAndMessage.test.ts

@@ -0,0 +1,55 @@
+// Tests for the start/message operation delegates (ADR 0058 OpenAPI surface).
+// These cover the app-logic guards the JSON schema can't express (reference parsing, message-name
+// dispatch); the runtime's schema validation (required `variables`/`name`) is exercised by urban's
+// own api runtime tests.
+import { assertEquals } from "jsr:@std/assert@1";
+import type { AppApi } from "@nanobpm/urban";
+import startConvergenceLoop from "./startConvergenceLoop.ts";
+import startPlanFanout from "./startPlanFanout.ts";
+import postMessage from "./postMessage.ts";
+
+// deno-lint-ignore no-explicit-any
+const app = {} as any as AppApi;
+
+// deno-lint-ignore no-explicit-any
+function input(body: any) {
+  return {
+    // deno-lint-ignore no-explicit-any
+    req: { method: "POST", path: "/", query: new URLSearchParams(), headers: new Headers(), text: async () => "" } as any,
+    params: {},
+    query: {},
+    body,
+  };
+}
+
+Deno.test("startConvergenceLoop → 400 on an unparseable PR reference", async () => {
+  const res = await startConvergenceLoop(input({ variables: { pr: "not a pr" } }), app);
+  // deno-lint-ignore no-explicit-any
+  const r = res as any;
+  assertEquals(r.status, 400);
+  assertEquals(typeof r.body.error, "string");
+});
+
+Deno.test("startPlanFanout → 400 on an unparseable issue reference", async () => {
+  const res = await startPlanFanout(input({ variables: { issue: "" } }), app);
+  // deno-lint-ignore no-explicit-any
+  const r = res as any;
+  assertEquals(r.status, 400);
+  assertEquals(typeof r.body.error, "string");
+});
+
+Deno.test("postMessage → 400 when name is blank", async () => {
+  const res = await postMessage(input({ name: "" }), app);
+  // deno-lint-ignore no-explicit-any
+  const r = res as any;
+  assertEquals(r.status, 400);
+  assertEquals(r.body.error, "name is required");
+});
+
+Deno.test("postMessage → 400 when escalation-answered lacks a correlationKey", async () => {
+  const res = await postMessage(input({ name: "escalation-answered", variables: { answer: "yes" } }), app);
+  // deno-lint-ignore no-explicit-any
+  const r = res as any;
+  assertEquals(r.status, 400);
+  assertEquals(r.body.error, "correlationKey is required");
+});

package/operations/startConvergenceLoop.ts

@@ -0,0 +1,28 @@
+// POST /app/api/actions/start/convergence-loop → operationId `startConvergenceLoop` (ADR 0058, base /app/api).
+// Replaces the hand-rolled action that overrode the generic "start process" palette action: parse the
+// PR reference and register/refresh the PR aggregate (idempotent on prKey) before starting the loop.
+//
+// The runtime validates the body against openapi.json (a `variables` object is required); this
+// delegate keeps the PR-parse guard because the reference format (owner/repo#123 or a URL) is app
+// logic, not something the JSON schema can express — an unparseable reference is a 400.
+import { defineOperation } from "@nanobpm/urban";
+import { clampRounds, MAX_ROUNDS, parsePr, submitPr } from "../app/service.ts";
+
+interface Body {
+  variables?: { pr?: string; url?: string; dependsOn?: unknown; maxRounds?: unknown };
+}
+
+export default defineOperation<
+  { params: Record<string, string>; query: Record<string, string | string[] | undefined>; body: Body },
+  { prKey: string; alreadyRunning?: boolean; processKey?: string | null } | { error: string }
+>("startConvergenceLoop", async ({ body }, app) => {
+  const vars = body?.variables ?? {};
+  const raw = String(vars.pr ?? vars.url ?? "").trim();
+  const parsed = parsePr(raw);
+  if (!parsed) {
+    return { status: 400, body: { error: "could not parse PR (use owner/repo#123 or a PR URL)" } };
+  }
+  const dependsOn = Array.isArray(vars.dependsOn) ? vars.dependsOn.map((d) => String(d)) : [];
+  const maxRounds = clampRounds(vars.maxRounds, MAX_ROUNDS);
+  return { status: 202, body: await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds) };
+});

package/operations/startPlanFanout.ts

@@ -0,0 +1,27 @@
+// POST /app/api/actions/start/plan-fanout → operationId `startPlanFanout` (ADR 0058, base /app/api).
+// Replaces the hand-rolled action that overrode the generic "start process" palette action: parse the
+// issue reference and register/refresh the plan aggregate (idempotent on planKey) before starting the
+// planning fan-out. An unparseable reference is a 400; an already-running plan short-circuits.
+import { defineOperation } from "@nanobpm/urban";
+import { parseIssue, startPlan } from "../app/plan.ts";
+
+interface Body {
+  variables?: { issue?: string; url?: string };
+}
+
+type Res =
+  | { planKey: string; alreadyRunning?: boolean; processKey?: string | null }
+  | { error: string };
+
+export default defineOperation<
+  { params: Record<string, string>; query: Record<string, string | string[] | undefined>; body: Body },
+  Res
+>("startPlanFanout", async ({ body }, app) => {
+  const vars = body?.variables ?? {};
+  const raw = String(vars.issue ?? vars.url ?? "").trim();
+  const parsed = parseIssue(raw);
+  if (!parsed) {
+    return { status: 400, body: { error: "could not parse issue (use owner/repo#123 or an issue URL)" } };
+  }
+  return { status: 202, body: await startPlan(app.data, app.engine, parsed) };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.34.0",
+  "version": "0.35.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",
@@ -40,7 +40,7 @@
     "test": "deno test -A"
   },
   "dependencies": {
-    "@nanobpm/urban": "^0.31.0"
+    "@nanobpm/urban": "^0.32.0"
   },
   "devDependencies": {
     "@semantic-release/changelog": "^6.0.3",

package/actions/plan-start.ts

@@ -1,17 +0,0 @@
-// POST /app/actions/start/plan-fanout — override the generic "start process" action for the
-// planning fan-out. We parse the issue reference and register/refresh the plan aggregate
-// (idempotent on planKey) before starting the process.
-import type { ActionHandler } from "@nanobpm/urban";
-import { parseIssue, startPlan } from "../app/plan.ts";
-
-const handler: ActionHandler = async ({ body }, app) => {
-  const vars = ((body as { variables?: Record<string, unknown> })?.variables ?? {}) as Record<string, unknown>;
-  const raw = String((vars.issue ?? vars.url ?? "") as string).trim();
-  const parsed = parseIssue(raw);
-  if (!parsed) {
-    return { status: 400, body: { error: "could not parse issue (use owner/repo#123 or an issue URL)" } };
-  }
-  return { status: 202, body: await startPlan(app.data, app.engine, parsed) };
-};
-
-export default handler;

package/actions/start.ts

@@ -1,19 +0,0 @@
-// POST /app/actions/start/convergence-loop — override the generic "start process" action.
-// The generic runtime would just createInstance; we first parse the PR reference and
-// register/refresh the PR aggregate (idempotent on prKey) before starting the loop.
-import type { ActionHandler } from "@nanobpm/urban";
-import { clampRounds, MAX_ROUNDS, parsePr, submitPr } from "../app/service.ts";
-
-const handler: ActionHandler = async ({ body }, app) => {
-  const vars = ((body as { variables?: Record<string, unknown> })?.variables ?? {}) as Record<string, unknown>;
-  const raw = String((vars.pr ?? vars.url ?? "") as string).trim();
-  const parsed = parsePr(raw);
-  if (!parsed) {
-    return { status: 400, body: { error: "could not parse PR (use owner/repo#123 or a PR URL)" } };
-  }
-  const dependsOn = Array.isArray(vars.dependsOn) ? vars.dependsOn.map((d) => String(d)) : [];
-  const maxRounds = clampRounds(vars.maxRounds, MAX_ROUNDS);
-  return { status: 202, body: await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds) };
-};
-
-export default handler;

package/actions/status.ts

@@ -1,22 +0,0 @@
-// GET /app/status — list the PRs currently in flight (every tracked PR not converged/abandoned).
-// A read-only projection over the app datasource so an operator or an external automation
-// harness can see active work — and grab a `processKey` to cancel — without opening the DB or the UI.
-//
-// Optional shared-secret guard, mirroring /hooks/submit: when NANO_PR_WEBHOOK_SECRET is set,
-// callers must present it via the x-hook-secret header. Unset → open (unchanged default). The
-// pages UI does not call this endpoint (its grid reads the datasource directly), so the guard
-// never affects the UI.
-import type { ActionHandler } from "@nanobpm/urban";
-import { activePrs } from "../app/service.ts";
-
-const SECRET = process.env.NANO_PR_WEBHOOK_SECRET ?? "";
-
-const handler: ActionHandler = async ({ req }, app) => {
-  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
-    return { status: 401, body: { error: "unauthorized" } };
-  }
-  const prs = await activePrs(app.data);
-  return { status: 200, body: { count: prs.length, prs } };
-};
-
-export default handler;

package/actions/version.test.ts

@@ -1,85 +0,0 @@
-// Tests for GET /app/version (version/identity endpoint).
-import { assert, assertEquals } from "jsr:@std/assert@1";
-import type { AppApi } from "@nanobpm/urban";
-import handler from "./version.ts";
-import { buildVersionInfo } from "../app/version.ts";
-
-// deno-lint-ignore no-explicit-any
-const app = {} as any as AppApi;
-
-function req(method: string, headers: Record<string, string> = {}) {
-  return {
-    method,
-    path: "/app/version",
-    query: new URLSearchParams(),
-    headers: new Headers(headers),
-    text: async () => "",
-  };
-}
-
-async function call(method: string, headers: Record<string, string> = {}) {
-  // deno-lint-ignore no-explicit-any
-  const res = await handler({ req: req(method, headers) as any, body: undefined }, app);
-  // deno-lint-ignore no-explicit-any
-  return res as any;
-}
-
-Deno.test("GET returns 200 with the app identity", async () => {
-  const res = await call("GET");
-  assertEquals(res.status, 200);
-  assertEquals(res.body.name, "nano-workforce");
-  // These are always present; their values are environment-dependent so we only assert shape.
-  assert("version" in res.body);
-  assert("urbanVersion" in res.body);
-  assert("gitSha" in res.body);
-  assert("gitBranch" in res.body);
-  assert(typeof res.body.runtime === "string" && res.body.runtime.length > 0);
-  assert(typeof res.body.startedAt === "string");
-  assert(typeof res.body.uptimeSeconds === "number");
-});
-
-Deno.test("non-GET is rejected with 405", async () => {
-  const res = await call("POST");
-  assertEquals(res.status, 405);
-});
-
-Deno.test("shared-secret guard rejects a missing/wrong secret when configured", async () => {
-  const prev = Deno.env.get("NANO_PR_WEBHOOK_SECRET");
-  Deno.env.set("NANO_PR_WEBHOOK_SECRET", "s3cr3t");
-  try {
-    // The handler binds SECRET at import time, so a freshly-imported module is needed to observe
-    // the guard. Import a cache-busted copy so this test is independent of import order.
-    const mod = await import(`./version.ts?guard=${Date.now()}`);
-    const guarded = mod.default as typeof handler;
-    // deno-lint-ignore no-explicit-any
-    const bad = (await guarded({ req: req("GET") as any, body: undefined }, app)) as any;
-    assertEquals(bad.status, 401);
-    // deno-lint-ignore no-explicit-any
-    const ok = (await guarded(
-      // deno-lint-ignore no-explicit-any
-      { req: req("GET", { "x-hook-secret": "s3cr3t" }) as any, body: undefined },
-      app,
-    )) as any;
-    assertEquals(ok.status, 200);
-  } finally {
-    if (prev === undefined) Deno.env.delete("NANO_PR_WEBHOOK_SECRET");
-    else Deno.env.set("NANO_PR_WEBHOOK_SECRET", prev);
-  }
-});
-
-Deno.test("buildVersionInfo is side-effect free and stable in shape", () => {
-  const a = buildVersionInfo();
-  const b = buildVersionInfo();
-  assertEquals(a.name, b.name);
-  assertEquals(Object.keys(a).sort(), [
-    "gitBranch",
-    "gitSha",
-    "name",
-    "pid",
-    "runtime",
-    "startedAt",
-    "uptimeSeconds",
-    "urbanVersion",
-    "version",
-  ]);
-});

package/actions/version.ts

@@ -1,25 +0,0 @@
-// GET /app/version — the running app's identity (ADR: version endpoint for debugging).
-//
-// Answers "which code is this process actually running?" — the app version, the resolved
-// `@nanobpm/urban` runtime version, the git commit/branch of the working tree, the JS runtime,
-// pid, and how long it has been up. Because the app runs its `.ts` sources directly from a
-// checkout with no build step, restarts alone don't tell you whether the fix you shipped is live;
-// this endpoint does.
-//
-// Read-only and unauthenticated by design (no secrets in the payload); it mirrors the open
-// posture of the pages surface. Optional shared-secret guard when NANO_PR_WEBHOOK_SECRET is set,
-// mirroring /app/status.
-import type { ActionHandler } from "@nanobpm/urban";
-import { buildVersionInfo } from "../app/version.ts";
-
-const SECRET = process.env.NANO_PR_WEBHOOK_SECRET ?? "";
-
-const handler: ActionHandler = ({ req }) => {
-  if (req.method !== "GET") return { status: 405, body: { error: "method not allowed (use GET)" } };
-  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
-    return { status: 401, body: { error: "unauthorized" } };
-  }
-  return { status: 200, body: buildVersionInfo() };
-};
-
-export default handler;