@nanobpm/nano-workforce 0.70.2 → 0.71.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.71.0](https://github.com/nanobpm/nano-workforce/compare/v0.70.2...v0.71.0) (2026-08-15)
+
+
+### Features
+
+* add a Tasks page to resolve native user-task escalations in the UI ([#238](https://github.com/nanobpm/nano-workforce/issues/238)) ([4dcd1a1](https://github.com/nanobpm/nano-workforce/commit/4dcd1a1ca1756bec45997ce619ed92bff31d03d6)), closes [210/#220](https://github.com/nanobpm/nano-workforce/issues/220)
+
 ## [0.70.2](https://github.com/nanobpm/nano-workforce/compare/v0.70.1...v0.70.2) (2026-08-15)
 
 

package/SPEC.md

@@ -264,8 +264,12 @@ generic Urban **page runtime** (`@nanobpm/app`, ADR 0042) — no hand-written SP
 The page defines status-filtered tabs (active vs. history), a submit form, a
 per-row **Cancel** action, and an expandable detail with the round/escalation
 child grids and a lazily-loaded transcript. The round/escalation grids are
-read-only audit; escalations are answered through the **task inbox** surface at
-`/tasks` (native `userTask`s), not an inline form on this page.
+read-only audit. Open native user-task escalations are additionally resolved
+app-side from the **Tasks** page (`pages/tasks.page.json`, issue #236) — a nav
+tab whose per-kind `dataGrid`s list every open escalation (feature / plan-review
+/ trial-merge / PR review / blocked-run) off the `user_tasks` read-model and
+submit the typed decision to the canonical human completer — so an operator no
+longer depends on Urban's read-only `taskInbox` stub at `/tasks`.
 
 The app-specific business-logic endpoints are **OpenAPI operations** mounted
 under `api.base` (`/app/api`), each implemented by a delegate module in
@@ -282,6 +286,7 @@ The full, authoritative contract is `openapi.yaml` (Swagger UI at
 | `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 merge-loop escalation → publish `escalation-answered` (the four #156 escalation kinds are native user tasks answered via the task inbox) |
+| `POST` | `/app/api/actions/complete-user-task` | complete an open native user-task escalation from the Tasks page (plan-review / trial-merge / PR `wait-answer`) → `completeEscalationAsHuman` (the same resume path the task inbox uses) |
 | `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) |
 

package/app/agentCompletion.test.ts

@@ -21,6 +21,7 @@ import {
   latestCompletion,
   revertAgentCompletion,
   type TaskCompletion,
+  validateEscalationVariables,
 } from "./agentCompletion.ts";
 
 /** A minimal in-memory `Table<T>`: AUTOINCREMENT ids on insert, structural `find`, `get`, `update`. */
@@ -386,3 +387,71 @@ test("latestCompletion returns the newest row by id regardless of insertion orde
   assertEquals(newest.id, 3, "the highest-id row for the key wins, not the first found");
   assertEquals(stores.task_completions.rows[0].id, 3, "the backing array is not reordered");
 });
+
+// --- Form-contract enforcement (issue #236 review advisory): a completion must satisfy the linked
+// `.form`'s required-field + select allowed-value contract BEFORE the engine resumes, so a missing or
+// invalid decision can never park the process in an invalid state. Derived from the canonical `.form`,
+// exercised through BOTH completers so agent and human paths reject invalid input identically.
+
+test("completer rejects a completion missing a required form field (no engine resume, no ledger row)", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-1", elementId: "wait-answer" }]);
+
+  const r = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-1",
+    operatorId: "alice",
+    variables: { answer: "   " }, // required, but blank
+  });
+
+  assertEquals(r.ok, false);
+  assert(String(r.reason).includes("answer"), "the reason names the missing required field");
+  assertEquals(completed.length, 0, "an invalid completion never resumes the process");
+  assertEquals(stores.task_completions.rows.length, 0, "and no attribution row is written");
+});
+
+test("completer rejects a select value outside the form's allowed set", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-2", elementId: "trial-merge-decision" }]);
+
+  const r = await completeEscalationAsAgent(data, engine, {
+    userTaskKey: "ut-2",
+    agentId: "bot",
+    variables: { action: "explode" }, // not one of proceed/rebase/abandon
+  });
+
+  assertEquals(r.ok, false);
+  assert(String(r.reason).includes("action"), "the reason names the invalid select field");
+  assertEquals(completed.length, 0, "an out-of-range decision never resumes the process");
+});
+
+test("completer accepts variables that satisfy the form contract (required present + allowed value)", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-3", elementId: "plan-review-decision" }]);
+
+  const r = await completeEscalationAsHuman(data, engine, {
+    userTaskKey: "ut-3",
+    operatorId: "alice",
+    variables: { directive: "revise", notes: "narrow scope" },
+  });
+
+  assertEquals(r.ok, true);
+  assertEquals(completed.length, 1, "a contract-valid completion resumes the process");
+  assertEquals(completed[0].variables, { directive: "revise", notes: "narrow scope" });
+});
+
+test("validateEscalationVariables derives its contract from the canonical .form files", async () => {
+  // wait-answer -> pr-escalation.form (answer required)
+  assertEquals(validateEscalationVariables("wait-answer", { answer: "ok" }), null);
+  assert(validateEscalationVariables("wait-answer", {}) !== null);
+  // trial-merge-decision -> action required, allowed proceed/rebase/abandon
+  assertEquals(validateEscalationVariables("trial-merge-decision", { action: "abandon" }), null);
+  assert(validateEscalationVariables("trial-merge-decision", { action: "nope" }) !== null);
+  // plan-review-decision -> directive required, allowed proceed/revise
+  assertEquals(validateEscalationVariables("plan-review-decision", { directive: "proceed" }), null);
+  assert(validateEscalationVariables("plan-review-decision", { directive: "" }) !== null);
+  // an element with no linked form contract is not enforced
+  assertEquals(validateEscalationVariables("some-other-task", { whatever: 1 }), null);
+});

package/app/agentCompletion.ts

@@ -20,6 +20,7 @@
 // SAME `completeUserTaskAttributed` (as `human`), so there is exactly one implementation of "complete
 // an escalation user task" — the agent path is an extension of it, not a parallel copy.
 
+import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 
 const now = () => new Date().toISOString();
@@ -69,6 +70,77 @@ export const ESCALATION_TASK_ELEMENTS: ReadonlySet<string> = new Set([
   "wait-answer", // PR review-loop escalation (convergence-loop.bpmn, U3)
 ]);
 
+/** Each escalation `elementId` → the `.form` whose contract governs its completion variables (the
+ *  BPMN `zeebe:formDefinition formId`). Kept beside `ESCALATION_TASK_ELEMENTS` so the completer
+ *  validates against the SAME `.form` the task inbox renders — one contract, no second field list. */
+const ESCALATION_FORM_BY_ELEMENT: Readonly<Record<string, string>> = {
+  "feature-escalation": "feature-escalation",
+  "plan-review-decision": "plan-review-decision",
+  "trial-merge-decision": "trial-merge-decision",
+  "wait-answer": "pr-escalation",
+};
+
+interface FormContract {
+  /** Field keys marked `validate.required` in the `.form`. */
+  required: string[];
+  /** `select` field key → its allowed `values`. */
+  allowed: Record<string, string[]>;
+}
+
+const formContractCache = new Map<string, FormContract>();
+
+/** Derive a `.form`'s required-field + select allowed-value contract, cached per formId. The `.form`
+ *  files (`resources/forms/*.form`, deployed via nano.app.json) are the CANONICAL contract, so this
+ *  reads them rather than re-encoding the field lists — no drift surface. */
+function formContract(formId: string): FormContract {
+  const cached = formContractCache.get(formId);
+  if (cached) return cached;
+  const raw: {
+    components?: { key?: string; validate?: { required?: boolean }; values?: { value?: string }[] }[];
+  } = JSON.parse(readFileSync(new URL(`../resources/forms/${formId}.form`, import.meta.url), "utf8"));
+  const required: string[] = [];
+  const allowed: Record<string, string[]> = {};
+  for (const c of raw.components ?? []) {
+    if (!c.key) continue;
+    if (c.validate?.required) required.push(c.key);
+    if (c.values?.length) {
+      allowed[c.key] = c.values.map((v) => v.value ?? "").filter((v) => v !== "");
+    }
+  }
+  const contract: FormContract = { required, allowed };
+  formContractCache.set(formId, contract);
+  return contract;
+}
+
+/** Validate completion `variables` against the escalation's `.form` contract (required fields present
+ *  + `select` values within the allowed set), so a completion can never resume the process with a
+ *  missing/invalid decision (e.g. a `wait-answer` with no `answer`, or a `trial-merge-decision` with
+ *  an `action` outside proceed/rebase/abandon). Returns a human-readable reason on violation, or
+ *  `null` when the variables satisfy the contract. Derived from the canonical `.form` — the same
+ *  contract the task inbox renders — so both the agent and human completers reject invalid input the
+ *  exact same way, with one implementation. An element with no linked form contract is not enforced. */
+export function validateEscalationVariables(
+  elementId: string,
+  variables: Record<string, unknown>,
+): string | null {
+  const formId = ESCALATION_FORM_BY_ELEMENT[elementId];
+  if (!formId) return null;
+  const { required, allowed } = formContract(formId);
+  for (const key of required) {
+    const v = variables[key];
+    if (v === undefined || v === null || (typeof v === "string" && v.trim() === "")) {
+      return `${elementId}: "${key}" is required`;
+    }
+  }
+  for (const [key, values] of Object.entries(allowed)) {
+    const v = variables[key];
+    if (v !== undefined && v !== null && !values.includes(String(v))) {
+      return `${elementId}: "${key}" must be one of ${values.join(", ")}`;
+    }
+  }
+  return null;
+}
+
 /** The canonical attributed completer. Records an attribution row in `task_completions` (reversible
  *  iff the actor is an agent) and THEN completes the user task with the exact typed `variables` — so
  *  the ledger row can never be lost by a resume that fires before the write. If the engine
@@ -183,6 +255,9 @@ export async function completeEscalationAsAgent(
   const resolved = await resolveEscalationTask(engine, userTaskKey);
   if (!resolved.ok) return resolved;
 
+  const invalid = validateEscalationVariables(resolved.elementId, input.variables);
+  if (invalid) return { ok: false, reason: invalid };
+
   const { completionId } = await completeUserTaskAttributed(
     data,
     engine,
@@ -212,6 +287,9 @@ export async function completeEscalationAsHuman(
   const resolved = await resolveEscalationTask(engine, userTaskKey);
   if (!resolved.ok) return resolved;
 
+  const invalid = validateEscalationVariables(resolved.elementId, input.variables);
+  if (invalid) return { ok: false, reason: invalid };
+
   const { completionId } = await completeUserTaskAttributed(
     data,
     engine,

package/app/instance-tracking.test.ts

@@ -7,8 +7,9 @@
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import { readFileSync } from "node:fs";
-import { TERMINAL_STATUSES } from "./service.ts";
+import { PR_ACTIVE_STATUSES, PLAN_ACTIVE_STATUSES, FEATURE_ACTIVE_STATUSES, TERMINAL_STATUSES } from "./service.ts";
 import { PLAN_TERMINAL_STATUSES } from "./plan.ts";
+import { FEATURE_TERMINAL_STATUSES } from "./feature.ts";
 
 interface Binding {
   table: string;
@@ -73,3 +74,45 @@ test("instanceTracking: plans activeStatuses covers every in-flight status", asy
   const b = bindingFor(await bindings(), "plans");
   assertEquals([...(b.activeStatuses ?? [])].sort(), [...inFlight].sort());
 });
+
+// The app-side `pollUserTasks` scan constant is DERIVED from the manifest at load time (no hand-kept
+// duplicate), so it must match the manifest binding exactly — this closes the drift surface Copilot
+// flagged (a second hard-coded list that could silently diverge from the reconciler's activeStatuses).
+test("PR_ACTIVE_STATUSES is derived from the manifest binding (no drift)", async () => {
+  const b = bindingFor(await bindings(), "pull_requests");
+  assertEquals([...PR_ACTIVE_STATUSES].sort(), [...(b.activeStatuses ?? [])].sort());
+});
+
+// Same guard for the plan scan: `pollUserTasks` no longer hard-codes ["planning","dispatched"] but
+// derives PLAN_ACTIVE_STATUSES from the manifest, so the plan-escalation scan can't drift from the
+// reconciler's activeStatuses any more than the PR scan can.
+test("PLAN_ACTIVE_STATUSES is derived from the manifest binding (no drift)", async () => {
+  const b = bindingFor(await bindings(), "plans");
+  assertEquals([...PLAN_ACTIVE_STATUSES].sort(), [...(b.activeStatuses ?? [])].sort());
+});
+
+test("instanceTracking: feature_runs activeStatuses excludes every terminal status", async () => {
+  const b = bindingFor(await bindings(), "feature_runs");
+  for (const terminal of FEATURE_TERMINAL_STATUSES) {
+    assert(!b.activeStatuses?.includes(terminal), `terminal status "${terminal}" must not be active`);
+  }
+});
+
+// Every instance-alive feature status must be reconcilable: a run parked at `feature-blocked`
+// (awaiting_operator) or `feature-escalation` (escalated) — or still running — keeps a live engine
+// instance, so onTerminated must be able to flip it to `abandoned` if that instance terminates.
+// Notably includes `awaiting_operator`: without it a run that terminates while blocked strands at
+// `awaiting_operator` forever and blocks re-dispatch (the drift Copilot flagged on #238).
+test("instanceTracking: feature_runs activeStatuses covers every in-flight status", async () => {
+  const inFlight = ["running", "escalated", "awaiting_operator"];
+  const b = bindingFor(await bindings(), "feature_runs");
+  assertEquals([...(b.activeStatuses ?? [])].sort(), [...inFlight].sort());
+});
+
+// Same no-drift guard for the feature scan: `pollUserTasks` no longer hard-codes
+// ["running","escalated","awaiting_operator"] but derives FEATURE_ACTIVE_STATUSES from the manifest,
+// so the feature-escalation scan can't drift from the reconciler's activeStatuses.
+test("FEATURE_ACTIVE_STATUSES is derived from the manifest binding (no drift)", async () => {
+  const b = bindingFor(await bindings(), "feature_runs");
+  assertEquals([...FEATURE_ACTIVE_STATUSES].sort(), [...(b.activeStatuses ?? [])].sort());
+});

package/app/pollUserTasks.test.ts

@@ -0,0 +1,151 @@
+// Integration test for `pollUserTasks` (issue #236) — the reconcile that projects the engine's
+// currently-open native user-task escalations onto the unified `user_tasks` read-model the Tasks page
+// reads. It generalises the two feature pollers across every subject: feature runs (denormalised
+// keys), in-flight plans (`plan-review-decision` / `trial-merge-decision`), and in-flight PRs
+// (`wait-answer`). A completed task's row is removed on the next pass so `showCount` tracks live work.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { pollUserTasks } from "./service.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: in-memory table double, mirrors featureEscalation.test.ts
+function memData(seed: Record<string, any[]> = {}): { data: DataLayer; stores: Record<string, any[]> } {
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  const stores: Record<string, any[]> = {};
+  for (const [k, v] of Object.entries(seed)) stores[k] = v.map((r) => ({ ...r }));
+  function tbl(name: string, pk = "id") {
+    // biome-ignore lint/suspicious/noExplicitAny: see above
+    const rows = (stores[name] ??= [] as any[]);
+    // biome-ignore lint/suspicious/noExplicitAny: see above
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      async all() {
+        return rows.slice();
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async insert(r: any) {
+        rows.push({ ...r });
+        return r[pk];
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: see above
+      async delete(id: any) {
+        const i = rows.findIndex((r) => r[pk] === id);
+        if (i >= 0) rows.splice(i, 1);
+      },
+    };
+  }
+  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as unknown as DataLayer;
+  return { data, stores };
+}
+
+/** A fake engine whose open user tasks are keyed by processInstanceKey (the only field the poller
+ *  queries on for plan / PR instances). */
+function fakeEngine(byInstance: Record<string, { userTaskKey: string; elementId?: string }[]>): EngineClient {
+  return {
+    searchUserTasks: (filter?: { processInstanceKey?: string }) =>
+      Promise.resolve(filter?.processInstanceKey ? (byInstance[filter.processInstanceKey] ?? []) : []),
+  } as unknown as EngineClient;
+}
+
+test("pollUserTasks: projects feature / plan-review / trial-merge / PR-wait escalations into user_tasks", async () => {
+  const { data, stores } = memData({
+    feature_runs: [
+      {
+        feature_key: "o/r#10",
+        status: "escalated",
+        process_key: "fp-10",
+        issue_url: "https://github.com/o/r/issues/10",
+        escalation_user_task_key: "ut-feat",
+        escalation_question: "which framework?",
+        blocked_user_task_key: null,
+        delivery_label: null,
+      },
+    ],
+    plans: [
+      { plan_key: "o/r#20", status: "dispatched", process_key: "pp-20", issue_url: "https://github.com/o/r/issues/20" },
+      { plan_key: "o/r#21", status: "done", process_key: "pp-21", issue_url: "https://github.com/o/r/issues/21" },
+    ],
+    plan_reviews: [
+      { plan_key: "o/r#20", epoch: 0, round: 0, approved: 0, findings: "scope was fine", created_at: "2025-01-01T00:00:00.000Z" },
+      { plan_key: "o/r#20", epoch: 0, round: 1, approved: 0, findings: "scope too broad", created_at: "2025-01-02T00:00:00.000Z" },
+    ],
+    plan_trial_merges: [
+      { id: 1, plan_key: "o/r#20", wave: 0, result: "suite-failed", summary: "wave 0 red", resolved: 0 },
+    ],
+    pull_requests: [
+      { pr_key: "o/r#30", status: "escalated", process_key: "rp-30", url: "https://github.com/o/r/pull/30" },
+    ],
+    escalations: [{ id: 1, pr_key: "o/r#30", status: "open", question: "conflicting reviews" }],
+  });
+  const engine = fakeEngine({
+    "pp-20": [
+      { userTaskKey: "ut-plan", elementId: "plan-review-decision" },
+      { userTaskKey: "ut-trial", elementId: "trial-merge-decision" },
+    ],
+    "pp-21": [{ userTaskKey: "ut-terminal", elementId: "plan-review-decision" }],
+    "rp-30": [{ userTaskKey: "ut-pr", elementId: "wait-answer" }],
+  });
+
+  await pollUserTasks(data, engine);
+
+  const byKey = Object.fromEntries((stores.user_tasks ?? []).map((r) => [r.user_task_key, r]));
+  assertEquals(Object.keys(byKey).sort(), ["ut-feat", "ut-plan", "ut-pr", "ut-trial"]);
+  assertEquals(byKey["ut-feat"].kind_label, "Feature escalation");
+  assertEquals(byKey["ut-feat"].question, "which framework?");
+  assertEquals(byKey["ut-plan"].kind_label, "Plan review");
+  assertEquals(byKey["ut-plan"].question, "scope too broad");
+  assertEquals(byKey["ut-trial"].kind_label, "Trial merge");
+  assertEquals(byKey["ut-trial"].question, "wave 0 red");
+  assertEquals(byKey["ut-pr"].kind_label, "PR review");
+  assertEquals(byKey["ut-pr"].subject_type, "pr");
+  assertEquals(byKey["ut-pr"].question, "conflicting reviews");
+});
+
+test("pollUserTasks: removes a row once its task is no longer open (completed / out-of-band)", async () => {
+  const { data, stores } = memData({
+    user_tasks: [
+      {
+        user_task_key: "ut-old",
+        element_id: "wait-answer",
+        kind_label: "PR review",
+        subject_type: "pr",
+        subject_key: "o/r#30",
+        subject_url: null,
+        question: null,
+        process_key: "rp-30",
+        created_at: "2025-01-01T00:00:00.000Z",
+        updated_at: "2025-01-01T00:00:00.000Z",
+      },
+    ],
+    pull_requests: [{ pr_key: "o/r#30", status: "converging", process_key: "rp-30", url: "https://github.com/o/r/pull/30" }],
+  });
+  const engine = fakeEngine({ "rp-30": [] });
+
+  await pollUserTasks(data, engine);
+
+  assertEquals(stores.user_tasks, []);
+});
+
+test("pollUserTasks: skips terminal plans and PRs without a process key", async () => {
+  const { data, stores } = memData({
+    plans: [{ plan_key: "o/r#40", status: "planning", process_key: null, issue_url: "https://github.com/o/r/issues/40" }],
+  });
+  const engine = fakeEngine({});
+
+  await pollUserTasks(data, engine);
+
+  assertEquals(stores.user_tasks ?? [], []);
+});