@nanobpm/nano-workforce 0.38.0 → 0.39.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.39.1](https://github.com/nanobpm/nano-workforce/compare/v0.39.0...v0.39.1) (2026-08-10)
+
+
+### Bug Fixes
+
+* **openapi:** use 3.0 nullable idiom instead of 3.1 type-arrays ([#111](https://github.com/nanobpm/nano-workforce/issues/111)) ([28f40c8](https://github.com/nanobpm/nano-workforce/commit/28f40c891d48043ef7537158466bafdfb79b9792))
+
+# [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)
 
 

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,

package/openapi.yaml

@@ -38,6 +38,7 @@ components:
     ActivePr:
       type: object
       description: A tracked PR that is not in a terminal (converged/abandoned) state.
+      additionalProperties: false
       required:
         - prKey
         - repo
@@ -62,36 +63,30 @@ components:
         url:
           type: string
         title:
-          type:
-            - string
-            - "null"
+          type: string
+          nullable: true
         status:
           type: string
         round:
           type: integer
         processKey:
-          type:
-            - string
-            - "null"
+          type: string
+          nullable: true
           description: The engine process instance key; also the keyField the pages processExplorer link uses.
         waitingSince:
-          type:
-            - string
-            - "null"
+          type: string
+          nullable: true
         openEscalation:
-          type:
-            - string
-            - "null"
+          type: string
+          nullable: true
         updatedAt:
           type: string
         activeWorker:
-          type:
-            - string
-            - "null"
+          type: string
+          nullable: true
         leaseUntil:
-          type:
-            - string
-            - "null"
+          type: string
+          nullable: true
     ActivePrList:
       type: object
       required:
@@ -107,6 +102,7 @@ components:
     VersionInfo:
       type: object
       description: The running app's identity (which code is actually live).
+      additionalProperties: false
       required:
         - name
         - version
@@ -121,27 +117,22 @@ components:
         name:
           type: string
         version:
-          type:
-            - string
-            - "null"
+          type: string
+          nullable: true
         urbanVersion:
-          type:
-            - string
-            - "null"
+          type: string
+          nullable: true
         gitSha:
-          type:
-            - string
-            - "null"
+          type: string
+          nullable: true
         gitBranch:
-          type:
-            - string
-            - "null"
+          type: string
+          nullable: true
         runtime:
           type: string
         pid:
-          type:
-            - integer
-            - "null"
+          type: integer
+          nullable: true
         startedAt:
           type: string
         uptimeSeconds:
@@ -154,9 +145,8 @@ components:
         prKey:
           type: string
         processKey:
-          type:
-            - string
-            - "null"
+          type: string
+          nullable: true
           description: The started convergence-loop instance key (null if the engine did not return one).
         alreadyRunning:
           type: boolean
@@ -170,9 +160,8 @@ components:
         planKey:
           type: string
         processKey:
-          type:
-            - string
-            - "null"
+          type: string
+          nullable: true
         alreadyRunning:
           type: boolean
           description: True when a non-terminal plan for this issue already exists; no new instance was started.
@@ -232,6 +221,7 @@ components:
           description: The operator's answer that resumes the parked implementation agent.
     BlackboardEntry:
       type: object
+      additionalProperties: false
       required:
         - id
         - author_task
@@ -254,9 +244,8 @@ components:
         body:
           type: string
         wave:
-          type:
-            - integer
-            - "null"
+          type: integer
+          nullable: true
         created_at:
           type: string
     BlackboardPage:
@@ -273,9 +262,8 @@ components:
           items:
             $ref: "#/components/schemas/BlackboardEntry"
         cursor:
-          type:
-            - integer
-            - "null"
+          type: integer
+          nullable: true
           description: The plan's current head id; pass it back as `since` on the next poll (Tier 2).
     BlackboardAppendRequest:
       type: object
@@ -321,6 +309,7 @@ components:
           description: Prior sibling file-claims on the same file(s) (advisory first-writer-wins; never a lock).
           items:
             type: object
+            additionalProperties: false
             required:
               - file
               - author_task

package/operations/answerFeatureEscalation.ts

@@ -10,25 +10,16 @@
 // Body accepts either the raw correlation key or a plan+task pair:
 //   { "corrKey": "owner/repo#12:task-3", "answer": "…" }
 //   { "plan": "owner/repo#12", "task": "task-3", "answer": "…" }
-import { defineOperation } from "@nanobpm/urban";
+
 import { answerTaskEscalation, featureCorrKey } from "../app/plan.ts";
 import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
 
 const WEBHOOK_SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
 
 const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
 
-interface Body {
-  corrKey?: unknown;
-  plan?: unknown;
-  task?: unknown;
-  answer?: unknown;
-}
-
-export default defineOperation<
-  { params: Record<string, string>; query: Record<string, string | string[] | undefined>; body: Body },
-  { ok: boolean } & Record<string, unknown>
->("answerFeatureEscalation", async ({ req, body }, app) => {
+export default defineOperation("answerFeatureEscalation", async ({ req, body }, app) => {
   if (WEBHOOK_SECRET && req.headers.get("x-hook-secret") !== WEBHOOK_SECRET) {
     return { status: 401, body: { ok: false, error: "unauthorized" } };
   }

package/operations/appendBlackboard.ts

@@ -7,19 +7,16 @@
 //   POST → append one entry: { author_task?, kind?, files?, body, wave?, dedupe_key? }. Idempotent
 //          on (plan, dedupe_key). Returns { id, inserted, conflicts } — `conflicts` lists prior
 //          sibling `file-claim`s on the same file(s) (advisory first-writer-wins; never a lock).
-import { defineOperation } from "@nanobpm/urban";
-import type { ClaimConflict } from "../app/blackboard.ts";
+
 import {
   appendEntry,
   detectFileClaimConflicts,
   normalizeKind,
   planKeyForToken,
 } from "../app/blackboard.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
 
-export default defineOperation<
-  { params: Record<string, string>; query: { token?: string }; body: Record<string, unknown> },
-  { id: number; inserted: boolean; conflicts: ClaimConflict[] } | { error: string }
->("appendBlackboard", async ({ req, body }, app) => {
+export default defineOperation("appendBlackboard", async ({ req, body }, app) => {
   const token = (req.query.get("token") ?? req.headers.get("x-blackboard-token") ?? "").trim();
   if (!token) return { status: 400, body: { error: "missing blackboard token" } };
   const planKey = await planKeyForToken(app.data, token);

package/operations/checkAbandon.ts

@@ -9,13 +9,11 @@
 //
 //   GET → { prKey, status, abandoned }  — `abandoned` is derived from `pull_requests.status`,
 //          which Urban's cancel primitive sets to 'abandoned' on cancel. `true` ⇒ the agent must stop.
-import { defineOperation } from "@nanobpm/urban";
+
 import { abandonStatusForToken } from "../app/abandon.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
 
-export default defineOperation<
-  { params: Record<string, string>; query: { token?: string }; body: unknown },
-  { prKey: string; status: string; abandoned: boolean } | { error: string }
->("checkAbandon", async ({ req }, app) => {
+export default defineOperation("checkAbandon", async ({ req }, app) => {
   const token = (req.query.get("token") ?? req.headers.get("x-abandon-token") ?? "").trim();
   if (!token) return { status: 400, body: { error: "missing abandon token" } };
   const state = await abandonStatusForToken(app.data, token);

package/operations/getVersion.ts

@@ -6,17 +6,15 @@
 // 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";
+
+import { buildVersionInfo, envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
 
 // The optional shared-secret guard: when NANO_PR_WEBHOOK_SECRET is set, callers must present it via
 // the x-hook-secret header. 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 }) => {
+export default defineOperation("getVersion", ({ req }) => {
   if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
     return { status: 401, body: { error: "unauthorized" } };
   }

package/operations/listActivePrs.ts

@@ -6,20 +6,16 @@
 // The runtime validates the (empty) request against openapi.yaml; 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 { activePrs } from "../app/service.ts";
 import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
 
 // The optional shared-secret guard: when NANO_PR_WEBHOOK_SECRET is set, callers must present it via
 // the x-hook-secret header. 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) => {
+export default defineOperation("listActivePrs", async ({ req }, app) => {
   if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
     return { status: 401, body: { error: "unauthorized" } };
   }

package/operations/postMessage.ts

@@ -8,20 +8,12 @@
 // The runtime validates the body against openapi.yaml (`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 { answerTaskEscalation, FEATURE_ESCALATION_MESSAGE } from "../app/plan.ts";
 import { answerEscalation } from "../app/service.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
 
-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) => {
+export default defineOperation("postMessage", async ({ body }, app) => {
   const b = body ?? {};
   const name = String(b.name ?? "");
   if (!name) return { status: 400, body: { error: "name is required" } };

package/operations/readBlackboard.ts

@@ -9,14 +9,11 @@
 //   GET → { planKey, entries: [ { id, author_task, kind, files, body, wave, created_at } ], cursor }
 //          optional ?since=<id> returns only entries with id > since (incremental poll). `cursor` is
 //          the plan's current head id; pass it back as `since` on the next poll (Tier 2).
-import { defineOperation } from "@nanobpm/urban";
-import type { BlackboardPage } from "../app/blackboard.ts";
+
 import { planKeyForToken, readBlackboardPage } from "../app/blackboard.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
 
-export default defineOperation<
-  { params: Record<string, string>; query: { token?: string; since?: string }; body: unknown },
-  (BlackboardPage & { planKey: string }) | { error: string }
->("readBlackboard", async ({ req }, app) => {
+export default defineOperation("readBlackboard", async ({ req }, app) => {
   const token = (req.query.get("token") ?? req.headers.get("x-blackboard-token") ?? "").trim();
   if (!token) return { status: 400, body: { error: "missing blackboard token" } };
   const planKey = await planKeyForToken(app.data, token);

package/operations/startConvergenceLoop.ts

@@ -8,20 +8,11 @@
 // not leak the engine's variable-map concept to callers. The runtime validates the body against
 // openapi.yaml; 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 {
-  pr?: string;
-  url?: string;
-  dependsOn?: unknown;
-  maxRounds?: unknown;
-}
+import { clampRounds, MAX_ROUNDS, parsePr, submitPr } from "../app/service.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
 
-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) => {
+export default defineOperation("startConvergenceLoop", async ({ body }, app) => {
   const b = body ?? {};
   const raw = String(b.pr ?? b.url ?? "").trim();
   const parsed = parsePr(raw);

package/operations/startPlanFanout.ts

@@ -7,22 +7,11 @@
 //
 // The request body is FLAT (`{ issue | url }`), not wrapped in a `variables` envelope — this is a
 // purpose-built operation, not a generic engine "start process" call.
-import { defineOperation } from "@nanobpm/urban";
-import { parseIssue, startPlan } from "../app/plan.ts";
-
-interface Body {
-  issue?: string;
-  url?: string;
-}
 
-type Res =
-  | { planKey: string; alreadyRunning?: boolean; processKey?: string | null }
-  | { error: string };
+import { parseIssue, startPlan } from "../app/plan.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
 
-export default defineOperation<
-  { params: Record<string, string>; query: Record<string, string | string[] | undefined>; body: Body },
-  Res
->("startPlanFanout", async ({ body }, app) => {
+export default defineOperation("startPlanFanout", async ({ body }, app) => {
   const b = body ?? {};
   const raw = String(b.issue ?? b.url ?? "").trim();
   const parsed = parseIssue(raw);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.38.0",
+  "version": "0.39.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",
@@ -33,6 +33,7 @@
     "upgrade": "node --experimental-strip-types scripts/upgrade-from-pack.ts",
     "check": "urban check",
     "typecheck": "tsc --noEmit",
+    "pretypecheck": "urban gen",
     "check:prompts": "node --experimental-strip-types scripts/check-agent-prompts.ts",
     "gen": "urban gen",
     "gen:check": "urban gen --check",
@@ -44,7 +45,7 @@
     "lint:fix": "biome check --write app operations workers pages components scripts main.ts"
   },
   "dependencies": {
-    "@nanobpm/urban": "^0.35.0"
+    "@nanobpm/urban": "^0.38.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",

package/tsconfig.json

@@ -39,6 +39,7 @@
     "main.ts",
     "app/**/*.ts",
     "operations/**/*.ts",
+    "nano-generated/**/*.ts",
     "workers/**/*.ts",
     "lib/**/*.ts",
     "src/**/*.ts",