@nanobpm/nano-workforce 0.37.0 → 0.39.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.39.0](https://github.com/nanobpm/nano-workforce/compare/v0.38.0...v0.39.0) (2026-08-10)
+
+
+### Features
+
+* adopt urban 0.38.0 typed delegate registry for the OpenAPI surface ([#110](https://github.com/nanobpm/nano-workforce/issues/110)) ([fe62908](https://github.com/nanobpm/nano-workforce/commit/fe62908968c0bd707f8e2da58fa550cca9fbab5b))
+
+# [0.38.0](https://github.com/nanobpm/nano-workforce/compare/v0.37.0...v0.38.0) (2026-08-10)
+
+
+### Features
+
+* migrate hooks to OpenAPI operations, one HTTP surface (ADR 0059) ([#109](https://github.com/nanobpm/nano-workforce/issues/109)) ([493d78c](https://github.com/nanobpm/nano-workforce/commit/493d78c5b58ba18098c7d458bd9538660eb2d0f3))
+
 # [0.37.0](https://github.com/nanobpm/nano-workforce/compare/v0.36.0...v0.37.0) (2026-08-10)
 
 

package/README.md

@@ -213,7 +213,7 @@ the UI and the process re-arms and retries.
 ### Fleet mode: hand it an issue (plan → implement → converge)
 
 ```
- issue (UI / POST /hooks/plan) ─► plan-fanout (BPMN)
+ issue (UI / POST /app/api/actions/start/plan-fanout) ─► plan-fanout (BPMN)
     plan (senior:plan) ─► record-plan ─► implement × N (parallel, senior:feature) ─► record-results
                                                                                        │
                                           each opened PR ──► convergence-loop (above)
@@ -222,12 +222,11 @@ the UI and the process re-arms and retries.
 A planning agent decomposes the issue into tasks; a parallel multi-instance activity
 fans them out over implementation agents (one PR per task); `record-results` enrols
 every opened PR into the convergence loop. Submit from the **"Hand an issue to the
-fleet"** form, or:
+fleet"** form, or POST the same operation the form does:
 
 ```bash
-curl -sS -X POST http://localhost:3000/hooks/plan \
+curl -sS -X POST http://localhost:3000/app/api/actions/start/plan-fanout \
   -H 'content-type: application/json' \
-  -H "x-hook-secret: $NANO_PR_WEBHOOK_SECRET" \
   -d '{ "issue": "owner/repo#123" }'
 ```
 
@@ -243,8 +242,8 @@ curl -sS -X POST http://localhost:3000/hooks/plan \
 | `GITHUB_TOKEN` | — | token for the review poller / merge (or use the host `gh` CLI) |
 | `NANO_PR_GITHUB_TRANSPORT` | `auto` | how the poller reads GitHub: `gh` (host CLI), `token` (`GITHUB_TOKEN` over HTTP), or `auto` |
 | `NANO_PR_POLL_MS` | `60000` | review-ready poll interval |
-| `NANO_PR_MAX_ROUNDS` | `20` | default cap: escalate after N rounds (per-submit override via the form / webhook `maxRounds`; clamped 1–100) |
-| `NANO_PR_WEBHOOK_SECRET` | — | shared secret for `POST /hooks/submit` (`X-Hook-Secret`) |
+| `NANO_PR_MAX_ROUNDS` | `20` | default cap: escalate after N rounds (per-submit override via the form / the `maxRounds` field on `start/convergence-loop`; clamped 1–100) |
+| `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret for the `POST /app/api/hooks/feature-answer` webhook operation (`X-Hook-Secret`); unset = open |
 | `NANO_PR_AUTO_MERGE` | `1` | after convergence, run the merge stage; `0` = stop at `converged` (review-only) |
 | `NANO_PR_MERGE_METHOD` | `squash` | merge method: `squash`, `merge`, or `rebase` |
 | `NANO_PR_MERGE_ADMIN` | `0` | pass `--admin` to override failing non-required checks (use with care) |

package/SPEC.md

@@ -56,7 +56,7 @@ surface are proposed and open for adjustment.
 ```
 nano-workforce/
   nano.app.json               # manifest (ADR 0027): sqlite data, domain types, submit webhook trigger
-  main.ts                     # Deno entrypoint: deploy + start workers + Deno.serve (page runtime + action overrides + poller)
+  main.ts                     # Node entrypoint: deploy + start workers + start the runtime (page runtime + OpenAPI operations + poller)
   deno.json
   pages/
     home.page.json            # the screen, authored declaratively (ADR 0042 Page Composer)
@@ -263,20 +263,22 @@ row by migration `003`).
 
 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:
+`operations/`. The webhook endpoints are ordinary operations too (ADR 0059 — the
+`actions[]` array is retired), mounted under `/app/api/hooks/*`. The runtime
+serves them all; `main.ts` only starts the runtime and the review-ready poller.
+The full, authoritative contract is `openapi.yaml` (Swagger UI at
+`/app/api-docs`); the OpenAPI rows below are the complete set of operations:
 
 | method | route | purpose |
 |---|---|---|
 | `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/start/convergence-loop` | parse the PR ref → create the aggregate + start the process (the ONE submit door — page + external callers) |
+| `POST` | `/app/api/actions/start/plan-fanout` | parse the issue ref → start a plan fan-out run (the ONE plan door) |
 | `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 |
+| `POST` | `/app/api/hooks/feature-answer` | answer an implementation-phase task escalation out of band (optional shared-secret) |
+| `GET`/`POST` | `/app/api/hooks/blackboard` | per-plan coordination blackboard (capability-token side-channel) |
+| `GET` | `/app/api/hooks/abandon` | cooperative abandon check (per-PR capability token) |
 
 Everything else (`GET /`, `GET /app/pages/*`, `GET /app/data/*`, the renderer) is
 served by the runtime — including `POST /app/actions/cancel`, which is Urban's
@@ -393,7 +395,7 @@ queries skip (`merging`), so a slow pass can't double-signal.
 | `GITHUB_TOKEN` | — | GitHub API (poller + agent) |
 | `NANO_PR_POLL_MS` | 60000 | poll interval |
 | `NANO_PR_MAX_ROUNDS` | 20 | default round cap (per-submit `maxRounds` override, clamped 1–100) |
-| `NANO_PR_WEBHOOK_SECRET` | — | HMAC for `/hooks/submit` |
+| `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret for the `/app/api/hooks/feature-answer` webhook operation (`X-Hook-Secret`) |
 | `NANO_PR_AUTO_MERGE` | 1 | run the merge stage after convergence (`0` = review-only) |
 | `NANO_PR_MERGE_METHOD` | squash | `squash` \| `merge` \| `rebase` |
 | `NANO_PR_MERGE_ADMIN` | 0 | pass `--admin` on merge |
@@ -443,9 +445,9 @@ scalar-only and cannot express the `tasks`/`results` lists, so the workers self-
 **Domain model** (`db/migrations/004_planning.sql`): `plans` (one row per issue) +
 `plan_tasks` (one row per slice, tracking its `status`/`pr_key`/`summary`).
 
-**Entry points**: the page's "Hand an issue to the fleet" form
-(`startProcess plan-fanout` → `actions/plan-start.ts`), or `POST /hooks/plan`
-(`{ issue | url }`, optional `X-Hook-Secret`).
+**Entry points**: the epic page's "Hand an issue to the fleet" form or
+`POST /app/api/actions/start/plan-fanout` (`{ issue | url }`) — the same flat
+operation the form posts.
 
 **Visibility**: the home page adds a **Plans** grid (Active: planning/dispatched;
 History: done/failed/abandoned) with a `plan_tasks` child grid showing each task's

package/app/abandon.test.ts

@@ -53,7 +53,7 @@ test("mintAbandonToken is url-safe, unpadded, and unique", () => {
 test("abandonUrl carries the token on the query string (url-encoded)", () => {
   assertEquals(
     abandonUrl("tok+/=", "https://host"),
-    "https://host/hooks/abandon?token=tok%2B%2F%3D",
+    "https://host/app/api/hooks/abandon?token=tok%2B%2F%3D",
   );
 });
 
@@ -68,13 +68,13 @@ test("abandonTokenFromUrl returns undefined for absent/tokenless/garbage input",
   assertEquals(abandonTokenFromUrl(undefined), undefined);
   assertEquals(abandonTokenFromUrl(null), undefined);
   assertEquals(abandonTokenFromUrl(""), undefined);
-  assertEquals(abandonTokenFromUrl("https://host/hooks/abandon"), undefined, "no token param");
+  assertEquals(abandonTokenFromUrl("https://host/app/api/hooks/abandon"), undefined, "no token param");
   assertEquals(abandonTokenFromUrl("not a url"), undefined, "unparseable input never throws");
 });
 
 test("renderAbandonBrief embeds the concrete URL and the stop contract", () => {
-  const brief = renderAbandonBrief("https://host/hooks/abandon?token=tok");
-  assertEquals(brief.includes("https://host/hooks/abandon?token=tok"), true);
+  const brief = renderAbandonBrief("https://host/app/api/hooks/abandon?token=tok");
+  assertEquals(brief.includes("https://host/app/api/hooks/abandon?token=tok"), true);
   assertEquals(brief.includes("abandoned"), true);
   assertEquals(brief.includes("Abort"), true);
   // Must use `curl -f` so a 404 (torn-down run) fails the command instead of exiting 0 with an

package/app/abandon.ts

@@ -42,13 +42,13 @@ export function mintAbandonToken(): string {
 /** The capability URL for a PR's abandon check: the token rides the query string so the agent can
  * GET the exact string it was handed with no header assembly. */
 export function abandonUrl(token: string, base: string = publicBaseUrl()): string {
-  return `${base}/hooks/abandon?token=${encodeURIComponent(token)}`;
+  return `${base}/app/api/hooks/abandon?token=${encodeURIComponent(token)}`;
 }
 
 /** Recover the capability token from an abandon URL — the inverse of `abandonUrl`. Returns
  * undefined when the input is absent or carries no `token` query param. A desync-heal uses this to
  * reconstruct a missing `pull_requests` row with the SAME token the running agent was already
- * handed (via the `abandonUrl` process variable), so its `curl -f "…/hooks/abandon?token=…"` abort
+ * handed (via the `abandonUrl` process variable), so its `curl -f "…/app/api/hooks/abandon?token=…"` abort
  * check keeps resolving instead of 404-ing on a freshly-minted token and aborting a live run. */
 export function abandonTokenFromUrl(url: string | null | undefined): string | undefined {
   if (!url) return undefined;

package/app/blackboard.test.ts

@@ -64,7 +64,7 @@ test("publicBaseUrl: a blank/whitespace override falls back instead of yielding
   try {
     assertEquals(publicBaseUrl(""), "http://localhost:3000");
     assertEquals(publicBaseUrl("   "), "http://localhost:3000");
-    assertEquals(blackboardUrl("t", publicBaseUrl("")), "http://localhost:3000/hooks/blackboard?token=t");
+    assertEquals(blackboardUrl("t", publicBaseUrl("")), "http://localhost:3000/app/api/hooks/blackboard?token=t");
   } finally {
     if (prev === undefined) delete process.env.NANO_PR_BASE_URL;
     else process.env.NANO_PR_BASE_URL = prev;
@@ -74,7 +74,7 @@ test("publicBaseUrl: a blank/whitespace override falls back instead of yielding
 test("blackboardUrl: capability token rides the query string", () => {
   assertEquals(
     blackboardUrl("tok+en/x", "https://h"),
-    "https://h/hooks/blackboard?token=tok%2Ben%2Fx",
+    "https://h/app/api/hooks/blackboard?token=tok%2Ben%2Fx",
   );
 });
 
@@ -87,7 +87,7 @@ test("normalizeKind: valid passes through, anything else becomes note", () => {
 });
 
 test("renderCoordinationBrief: leads with a separator and teaches the protocol + URL", () => {
-  const url = "https://h/hooks/blackboard?token=abc";
+  const url = "https://h/app/api/hooks/blackboard?token=abc";
   const brief = renderCoordinationBrief(url);
   assert(brief.startsWith("\n\n---"), "must own a leading separator (appendPrompt adds none)");
   assertStringIncludes(brief, url);

package/app/blackboard.ts

@@ -13,7 +13,7 @@
 //     stable `dedupe_key` is a no-op (backed by a unique index; we also short-circuit here).
 //   - CAPABILITY URL. The per-plan token IS the credential; the agent curls the exact URL it was
 //     handed (delivered in `appendPrompt`). Delivery is in-band (rides the prompt the harness
-//     already forwards); use is out-of-band (a direct side-channel to `/hooks/blackboard`).
+//     already forwards); use is out-of-band (a direct side-channel to `/app/api/hooks/blackboard`).
 //
 // Data access goes through the record gateway (`data.table`), never hand-written SQL — matching
 // app/service.ts and app/plan.ts.
@@ -87,7 +87,7 @@ export function publicBaseUrl(env: string | undefined = process.env.NANO_PR_PUBL
 /** The capability URL for a plan's blackboard: the token rides the query string, so the agent can
  * GET/POST the exact string it was handed with no header assembly. */
 export function blackboardUrl(token: string, base: string = publicBaseUrl()): string {
-  return `${base}/hooks/blackboard?token=${encodeURIComponent(token)}`;
+  return `${base}/app/api/hooks/blackboard?token=${encodeURIComponent(token)}`;
 }
 
 /** The coordination-protocol block appended (verbatim, via `appendPrompt`) to each implementer

package/app/persist-escalation.test.ts

@@ -149,7 +149,7 @@ test("persist-escalation heals from the prKey when repo/prNumber are absent", as
       round: 2,
       status: "needs_input",
       question: "decide",
-      abandonUrl: "https://host/hooks/abandon?token=TOK-en_123",
+      abandonUrl: "https://host/app/api/hooks/abandon?token=TOK-en_123",
     },
   };
   await handler(job as any, app as any);

package/app/persist-round.test.ts

@@ -103,7 +103,7 @@ test("persist-round heals from the prKey when repo/prNumber are absent", async (
       prKey: "o/r#12",
       round: 2,
       status: "addressed",
-      abandonUrl: "https://host/hooks/abandon?token=TOK-en_123",
+      abandonUrl: "https://host/app/api/hooks/abandon?token=TOK-en_123",
     },
   };
   await handler(job as any, app as any);

package/app/service.ts

@@ -129,7 +129,7 @@ interface PullRequest {
   // frugal-CI fresh-head-run remedy. A rebase changes the head and therefore permits a new nudge.
   fresh_head_run_head: string | null;
   // Cooperative abandon check (015_pr_abandon_token.sql, issue #76): the per-PR capability token a
-  // running agent curls (GET /hooks/abandon?token=…) to learn whether this run was cancelled before
+  // running agent curls (GET /app/api/hooks/abandon?token=…) to learn whether this run was cancelled before
   // it performs a side effect. Minted at submit, reused across the convergence + merge instances.
   abandon_token: string | null;
   // Technical-incident surfacing (017_pr_incident.sql, issue #94), written by the poller's

package/biome.json

@@ -4,7 +4,6 @@
     "includes": [
       "app/**/*.ts",
       "operations/**/*.ts",
-      "actions/**/*.ts",
       "workers/**/*.ts",
       "pages/**/*.ts",
       "components/**/*.ts",
@@ -20,7 +19,6 @@
     "includes": [
       "app/**/*.ts",
       "operations/**/*.ts",
-      "actions/**/*.ts",
       "workers/**/*.ts",
       "pages/**/*.ts",
       "components/**/*.ts",

package/main.ts

@@ -1,12 +1,12 @@
 // nano-workforce — Urban App entrypoint (ADR 0055).
 //
 // The whole app is declared in `nano.app.json` (models, sqlite datasource, app-hosted record
-// workers, the schema-driven pages surface, and the action overrides) and materialized by the
+// workers, the schema-driven pages surface, and the OpenAPI control surface) and materialized by the
 // `@nanobpm/urban` runtime via `runFromEnv`:
 //   • deploys the BPMN + hosts the `pr.*` record workers (workers/*/worker.ts),
 //   • serves the schema-driven page runtime (ADR 0042) from `pages/home.page.json`,
-//   • mounts the app-specific action overrides (actions/*.ts) that wrap the generic
-//     start/cancel/message actions, plus the `/hooks/submit` webhook.
+//   • mounts the OpenAPI operations (openapi.yaml → operations/*.ts) — the start/cancel/message
+//     control endpoints plus the webhook operations under `/app/api/hooks/*` (ADR 0059).
 //
 // The only thing that isn't declarative is the review-ready poller: it does arbitrary GitHub
 // polling and then correlates a `review-ready` message. A cron trigger can only fire an engine

package/nano.app.json

@@ -124,6 +124,16 @@
       "handler": "workers/retro-record/worker.ts"
     }
   ],
+  "externalTaskTypes": [
+    "senior:pr-review",
+    "senior:fix-ci",
+    "senior:rebase",
+    "senior:plan",
+    "senior:plan-review",
+    "senior:feature",
+    "senior:trial-merge",
+    "senior:retro"
+  ],
   "surfaces": {
     "pages": {
       "enabled": true,
@@ -140,31 +150,8 @@
     "icon": "assets/icon.svg"
   },
   "api": {
-    "spec": "openapi.json",
+    "spec": "openapi.yaml",
     "dir": "operations",
     "validateResponses": "dev"
-  },
-  "actions": [
-    {
-      "path": "/hooks/submit",
-      "module": "actions/webhook-submit.ts"
-    },
-    {
-      "path": "/hooks/plan",
-      "module": "actions/plan-hook.ts"
-    },
-    {
-      "path": "/hooks/feature-answer",
-      "module": "actions/feature-answer-hook.ts"
-    },
-    {
-      "path": "/hooks/blackboard",
-      "module": "actions/blackboard.ts"
-    },
-    {
-      "path": "/hooks/abandon",
-      "module": "actions/abandon.ts",
-      "method": "GET"
-    }
-  ]
+  }
 }