@nanobpm/nano-workforce 0.26.0

package/main.ts

@@ -0,0 +1,71 @@
+// 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
+// `@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.
+//
+// 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
+// start/message action, not this custom I/O glue, so it stays app-side here — driving the same
+// engine client the runtime uses, over `app.data`.
+//
+// The reviewer agent (job type `senior:pr-review`) is deliberately NOT hosted here — it is an
+// EXTERNAL worker. Point a coding-agent harness at that job type (the same one that services
+// the code-first twin) so the automated review stays decoupled from the orchestration.
+import { createNanoSdkEngineClient, runFromEnv, selectHost } from "@nanobpm/urban";
+import { MAX_ROUNDS, pollOnce } from "./app/service.ts";
+
+const PORT = Number(process.env.PR_REVIEW_PORT ?? 3000);
+const POLL_MS = Number(process.env.NANO_PR_POLL_MS ?? 60_000);
+const GITHUB_TOKEN = process.env.GITHUB_TOKEN ?? "";
+
+const host = selectHost();
+
+// One engine client, shared by the runtime (surfaces/actions/workers) and the poller. Honour
+// the app's documented NANOBPMN_BASE_URL as well as the runtime's CAMUNDA_REST_ADDRESS.
+const restAddress = process.env.CAMUNDA_REST_ADDRESS ??
+  `${(process.env.NANOBPMN_BASE_URL ?? "http://localhost:8080").replace(/\/+$/, "")}/v2`;
+const engine = await createNanoSdkEngineClient({
+  restAddress,
+  token: process.env.CAMUNDA_TOKEN,
+  transport: process.env.CAMUNDA_TRANSPORT ?? "auto",
+  log: host.log,
+});
+
+// Manage our own shutdown so the poller is stopped and the process exits (the runtime
+// signal handler would only stop the HTTP server, leaving the poller keeping us alive).
+const app = await runFromEnv({ engine, host, port: PORT, handleSignals: false });
+
+// Review-ready poller. Self-scheduling (not setInterval) so a slow GitHub call can never
+// overlap two passes (which could double-signal `review-ready`); the next pass is scheduled
+// only after the previous one settles.
+let shuttingDown = false;
+let pollTimer: ReturnType<typeof setTimeout> | null = null;
+async function pollLoop(): Promise<void> {
+  try {
+    if (app.data) await pollOnce(app.data, engine, GITHUB_TOKEN, { restAddress, token: process.env.CAMUNDA_TOKEN });
+  } catch (err) {
+    console.error("poll error:", err);
+  }
+  if (!shuttingDown) pollTimer = setTimeout(() => void pollLoop(), POLL_MS);
+}
+if (app.data) pollTimer = setTimeout(() => void pollLoop(), POLL_MS);
+
+async function drainAndExit(): Promise<void> {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  if (pollTimer) clearTimeout(pollTimer);
+  try {
+    await app.stop();
+  } catch { /* already stopped */ }
+  process.exit(0);
+}
+for (const sig of ["SIGINT", "SIGTERM"] as const) {
+  process.on(sig, () => void drainAndExit());
+}
+
+console.log(`nano-workforce serving on :${PORT} (poll ${POLL_MS}ms, maxRounds ${MAX_ROUNDS})`);

package/nano-ide.ext.json

@@ -0,0 +1,7 @@
+{
+  "id": "nano-workforce",
+  "kind": "example",
+  "displayName": "Nano Workforce",
+  "appDir": ".",
+  "summary": "Agent Graph Orchestration for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle — planning and fanning a fleet of agents out to implement an issue, driving each pull request to review convergence, and merging, escalating to a human when an agent is stuck or a round cap is hit."
+}

package/nano.app.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://nanobpm.io/spec-app/nano-app.schema.json",
+  "schemaVersion": 1,
+  "id": "nano-workforce",
+  "name": "Nano Workforce",
+  "codename": "nano-workforce",
+  "models": {
+    "processes": [
+      "resources/processes/*.bpmn"
+    ],
+    "templates": [
+      "prompts/*.md"
+    ]
+  },
+  "data": {
+    "default": "app",
+    "sources": {
+      "app": {
+        "driver": "sqlite",
+        "url": "${NANO_APP_DB_URL:-file:./app.db}",
+        "migrations": "db/migrations"
+      }
+    }
+  },
+  "workers": [
+    {
+      "taskType": "pr.persist-round",
+      "handler": "workers/persist-round/worker.ts"
+    },
+    {
+      "taskType": "pr.persist-escalation",
+      "handler": "workers/persist-escalation/worker.ts"
+    },
+    {
+      "taskType": "pr.finalize",
+      "handler": "workers/finalize/worker.ts"
+    },
+    {
+      "taskType": "pr.arm-merge",
+      "handler": "workers/arm-merge/worker.ts"
+    },
+    {
+      "taskType": "pr.merge",
+      "handler": "workers/merge/worker.ts"
+    },
+    {
+      "taskType": "pr.mark-merged",
+      "handler": "workers/mark-merged/worker.ts"
+    },
+    {
+      "taskType": "pr.record-plan",
+      "handler": "workers/record-plan/worker.ts"
+    },
+    {
+      "taskType": "pr.record-plan-review",
+      "handler": "workers/record-plan-review/worker.ts"
+    },
+    {
+      "taskType": "pr.select-wave",
+      "handler": "workers/select-wave/worker.ts"
+    },
+    {
+      "taskType": "pr.record-wave",
+      "handler": "workers/record-wave/worker.ts"
+    },
+    {
+      "taskType": "pr.record-trial-merge",
+      "handler": "workers/record-trial-merge/worker.ts"
+    },
+    {
+      "taskType": "pr.record-results",
+      "handler": "workers/record-results/worker.ts"
+    },
+    {
+      "taskType": "pr.persist-task-escalation",
+      "handler": "workers/persist-task-escalation/worker.ts"
+    }
+  ],
+  "surfaces": {
+    "pages": {
+      "enabled": true,
+      "pagesDir": "pages",
+      "homePage": "home",
+      "sourceName": "app"
+    }
+  },
+  "ui": {
+    "enabled": true,
+    "portEnv": "PR_REVIEW_PORT",
+    "path": "/",
+    "label": "Nano Workforce",
+    "icon": "assets/icon.svg"
+  },
+  "actions": [
+    {
+      "path": "/app/actions/start/convergence-loop",
+      "module": "actions/start.ts"
+    },
+    {
+      "path": "/app/actions/start/plan-fanout",
+      "module": "actions/plan-start.ts"
+    },
+    {
+      "path": "/app/actions/cancel",
+      "module": "actions/cancel.ts"
+    },
+    {
+      "path": "/app/status",
+      "module": "actions/status.ts",
+      "method": "GET"
+    },
+    {
+      "path": "/app/actions/message",
+      "module": "actions/message.ts"
+    },
+    {
+      "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"
+    }
+  ]
+}

package/nanobpm.project.json

@@ -0,0 +1,20 @@
+{
+  "name": "nano-workforce",
+  "description": "Nano Workforce — Agent Graph Orchestration for Agentic SDLC, orchestrated by Nano.",
+  "main": "main.ts",
+  "lang": "node",
+  "app": "urban",
+  "autoDeploy": [],
+  "toolchain": {
+    "run": [
+      "node",
+      "--experimental-strip-types",
+      "main.ts"
+    ],
+    "compile": [
+      "deno",
+      "task",
+      "compile"
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@nanobpm/nano-workforce",
+  "version": "0.26.0",
+  "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",
+  "engines": {
+    "node": ">=22.6"
+  },
+  "author": "Josh Wulf <josh.wulf@camunda.com>",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/nanobpm/nano-workforce#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nanobpm/nano-workforce.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nanobpm/nano-workforce/issues"
+  },
+  "keywords": [
+    "nano-ide-ext",
+    "nano-ide-agentic-sdlc"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node --experimental-strip-types main.ts",
+    "purge": "node --experimental-strip-types scripts/purge-db.ts",
+    "upgrade": "node --experimental-strip-types scripts/upgrade-from-pack.ts",
+    "check": "urban check",
+    "typecheck": "tsc --noEmit",
+    "check:prompts": "deno run -A scripts/check-agent-prompts.ts",
+    "gen": "urban gen",
+    "gen:check": "urban gen --check",
+    "layout": "node --experimental-strip-types scripts/layout-bpmn.ts",
+    "layout:check": "node --experimental-strip-types scripts/layout-bpmn.ts --check",
+    "dev": "urban dev",
+    "compile": "deno task compile",
+    "test": "deno test -A"
+  },
+  "dependencies": {
+    "@nanobpm/urban": "^0.24.0"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/npm": "^13.1.5",
+    "@types/node": "^22",
+    "semantic-release": "^24.2.9",
+    "typescript": "^5.6.0"
+  },
+  "overrides": {
+    "@semantic-release/npm": "^13.1.5"
+  }
+}

package/pages/epic.page.json

@@ -0,0 +1,195 @@
+{
+  "schemaVersion": "1.0",
+  "title": "Epic Coordination",
+  "nodes": [
+    {
+      "type": "text",
+      "id": "title",
+      "props": { "text": "Epic Coordination", "variant": "heading" }
+    },
+    {
+      "type": "text",
+      "id": "subtitle",
+      "props": {
+        "text": "Read-only observability over each plan's wave state, merge-exclusion graph, coordination notes, and trial-merge gate results.",
+        "variant": "sub"
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "epic-plans",
+      "props": {
+        "title": "Plans",
+        "rowKey": "plan_key",
+        "refreshMs": 5000,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "plans",
+          "orderBy": { "field": "updated_at", "dir": "desc" },
+          "filter": [{ "field": "status", "in": ["planning", "dispatched"] }]
+        },
+        "tabs": [
+          {
+            "label": "Active",
+            "filter": [{ "field": "status", "in": ["planning", "dispatched"] }]
+          },
+          {
+            "label": "History",
+            "filter": [{ "field": "status", "in": ["done", "failed", "abandoned"] }]
+          },
+          { "label": "All", "filter": [] }
+        ],
+        "columns": [
+          { "field": "plan_key", "header": "Issue", "linkField": "issue_url" },
+          { "field": "status", "header": "Status" },
+          { "field": "task_count", "header": "Tasks" },
+          { "field": "open_task_id", "header": "Open escalation" },
+          { "field": "updated_at", "header": "Updated" }
+        ],
+        "detail": {
+          "linkField": "issue_url",
+          "fields": [
+            { "field": "repo", "label": "Repository" },
+            { "field": "issue_number", "label": "Issue number" },
+            { "field": "outcome", "label": "Outcome" },
+            { "field": "open_task_question", "label": "Open escalation question" }
+          ]
+        }
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "wave-state",
+      "props": {
+        "title": "Wave state",
+        "rowKey": "id",
+        "refreshMs": 5000,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "plan_tasks",
+          "orderBy": { "field": "wave", "dir": "asc" },
+          "filter": [
+            { "field": "status", "in": ["pending", "opened", "escalated", "waiting-for-lane", "blocked"] }
+          ]
+        },
+        "tabs": [
+          {
+            "label": "Active",
+            "filter": [
+              { "field": "status", "in": ["pending", "opened", "escalated", "waiting-for-lane", "blocked"] }
+            ]
+          },
+          {
+            "label": "Skipped",
+            "filter": [{ "field": "status", "in": ["skipped"] }]
+          },
+          { "label": "All", "filter": [] }
+        ],
+        "columns": [
+          { "field": "plan_key", "header": "Plan" },
+          { "field": "wave", "header": "Wave" },
+          { "field": "task_id", "header": "Task" },
+          { "field": "title", "header": "Title" },
+          { "field": "status", "header": "Status" },
+          { "field": "pr_key", "header": "PR" },
+          { "field": "summary", "header": "Summary" },
+          { "field": "updated_at", "header": "Updated" }
+        ],
+        "detail": {
+          "fields": [
+            { "field": "open_question", "label": "Open question" },
+            { "field": "answer", "label": "Answer" },
+            { "field": "draft_pr_key", "label": "Draft PR" },
+            { "field": "prompt", "label": "Prompt" }
+          ]
+        }
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "merge-exclusions",
+      "props": {
+        "title": "Conflict graph / who blocks whom",
+        "rowKey": "id",
+        "refreshMs": 5000,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "plan_merge_exclusions",
+          "orderBy": { "field": "id", "dir": "asc" }
+        },
+        "columns": [
+          { "field": "plan_key", "header": "Plan" },
+          { "field": "task_a", "header": "Task A" },
+          { "field": "task_b", "header": "Task B" },
+          { "field": "files", "header": "Shared files" },
+          { "field": "source", "header": "Source" },
+          { "field": "updated_at", "header": "Updated" }
+        ]
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "coordination-notes",
+      "props": {
+        "title": "Coordination notes",
+        "rowKey": "id",
+        "refreshMs": 5000,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "plan_blackboard",
+          "orderBy": { "field": "id", "dir": "asc" }
+        },
+        "columns": [
+          { "field": "plan_key", "header": "Plan" },
+          { "field": "wave", "header": "Wave" },
+          { "field": "author_task", "header": "Agent" },
+          { "field": "kind", "header": "Kind" },
+          { "field": "files", "header": "Files" },
+          { "field": "body", "header": "Note" },
+          { "field": "created_at", "header": "Posted" }
+        ]
+      }
+    },
+    {
+      "type": "dataGrid",
+      "id": "trial-merge-results",
+      "props": {
+        "title": "Trial-merge results",
+        "rowKey": "id",
+        "refreshMs": 5000,
+        "data": {
+          "kind": "datasource",
+          "source": "app",
+          "table": "plan_trial_merges",
+          "orderBy": { "field": "created_at", "dir": "desc" },
+          "filter": [{ "field": "result", "in": ["merge-conflict", "suite-failed"] }]
+        },
+        "tabs": [
+          {
+            "label": "Needs attention",
+            "filter": [{ "field": "result", "in": ["merge-conflict", "suite-failed"] }]
+          },
+          {
+            "label": "Clean",
+            "filter": [{ "field": "result", "in": ["clean"] }]
+          },
+          { "label": "All", "filter": [] }
+        ],
+        "columns": [
+          { "field": "plan_key", "header": "Plan" },
+          { "field": "wave", "header": "Wave" },
+          { "field": "result", "header": "Result" },
+          { "field": "heads", "header": "Heads" },
+          { "field": "conflicts", "header": "Conflicts" },
+          { "field": "failing", "header": "Failing" },
+          { "field": "summary", "header": "Summary" },
+          { "field": "created_at", "header": "Recorded" }
+        ]
+      }
+    }
+  ]
+}