@nanobpm/nano-workforce 0.64.0 → 0.66.0

package/resources/processes/plan-fanout.bpmn

@@ -12,6 +12,55 @@
           <nano:extend name="repo" type="string" />
           <nano:extend name="baseBranch" type="string" />
         </nano:shape>
+        <nano:shape id="RecordPlanTask" name="Record plan — raw planner task">
+          <nano:extend name="id" type="string" optional="true" />
+          <nano:extend name="title" type="string" optional="true" />
+          <nano:extend name="prompt" type="string" optional="true" />
+          <nano:extend name="dependsOn" type="string" list="true" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordPlanIn" name="Record plan — input">
+          <nano:extend name="planKey" type="string" />
+          <nano:reference name="tasks" ref="RecordPlanTask" list="true" />
+          <nano:extend name="note" type="string" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordWaveTaskRef" name="Record wave — task ref">
+          <nano:extend name="id" type="string" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordWaveDelta" name="Record wave — task delta">
+          <nano:extend name="contractChange" type="string" optional="true" />
+          <nano:extend name="newlyTouches" type="string" list="true" optional="true" />
+          <nano:extend name="affectsTasks" type="string" list="true" optional="true" />
+          <nano:extend name="constraint" type="string" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordWaveResult" name="Record wave — agent result">
+          <nano:extend name="status" type="string" optional="true" />
+          <nano:extend name="summary" type="string" optional="true" />
+          <nano:extend name="pr" type="string" optional="true" />
+          <nano:extend name="delta" type="RecordWaveDelta" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordWaveIn" name="Record wave — input">
+          <nano:extend name="planKey" type="string" />
+          <nano:extend name="currentWave" type="integer" />
+          <nano:extend name="waveCount" type="integer" />
+          <nano:reference name="waveTasks" ref="RecordWaveTaskRef" list="true" />
+          <nano:reference name="waveResults" ref="RecordWaveResult" list="true" />
+        </nano:shape>
+        <nano:shape id="RecordTrialMergeHead" name="Record trial merge — open head">
+          <nano:extend name="repo" type="string" />
+          <nano:extend name="prNumber" type="integer" />
+          <nano:extend name="headRef" type="string" optional="true" />
+          <nano:extend name="headSha" type="string" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordTrialMergeIn" name="Record trial merge — input">
+          <nano:extend name="planKey" type="string" />
+          <nano:extend name="currentWave" type="integer" optional="true" />
+          <nano:extend name="trialMergeWave" type="integer" optional="true" />
+          <nano:reference name="waveOpenHeads" ref="RecordTrialMergeHead" list="true" />
+          <nano:extend name="result" type="string" optional="true" />
+          <nano:extend name="conflicts" type="string" list="true" optional="true" />
+          <nano:extend name="failing" type="string" list="true" optional="true" />
+          <nano:extend name="summary" type="string" optional="true" />
+        </nano:shape>
         <nano:shape id="RecordPlanReviewIn" name="Record plan review — input">
           <nano:extend name="planKey" type="string" />
           <nano:extend name="approved" type="boolean" optional="true" />
@@ -68,6 +117,9 @@
     <bpmn:serviceTask id="record-plan" name="Record plan &#38; levelize">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.record-plan" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RecordPlanIn" />
+        </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_toRecordPlan</bpmn:incoming>
       <bpmn:outgoing>f_toReviewPlan</bpmn:outgoing>
@@ -215,6 +267,9 @@
     <bpmn:serviceTask id="record-wave" name="Record wave &#38; hand off">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.record-wave" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RecordWaveIn" />
+        </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_toRecordWave</bpmn:incoming>
       <bpmn:outgoing>f_toTrialNeeded</bpmn:outgoing>
@@ -246,6 +301,9 @@
     <bpmn:serviceTask id="record-trial-merge" name="Record trial merge">
       <bpmn:extensionElements>
         <zeebe:taskDefinition type="pr.record-trial-merge" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RecordTrialMergeIn" />
+        </zeebe:properties>
       </bpmn:extensionElements>
       <bpmn:incoming>f_toRecordTrialMerge</bpmn:incoming>
       <bpmn:outgoing>f_toGwTrial</bpmn:outgoing>

package/scripts/pages-contract.test.ts

@@ -267,7 +267,7 @@ test("issue #205: overview is the landing page and first nav item", async () =>
       "merging",
     ],
     plans: ["planning", "dispatched"],
-    feature_runs: ["running", "awaiting_operator"],
+    feature_runs: ["running", "escalated", "awaiting_operator"],
   };
   const grids = (overview.nodes ?? []).filter((n: Json) => n.type === "dataGrid");
   for (const [table, statuses] of Object.entries(expected)) {

package/workers/record-feature/worker.ts

@@ -54,6 +54,12 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
     status: rowStatus,
     pr_key: prKey,
     outcome: summary ?? null,
+    // The run has left the `feature-escalation` wait (answered → abandon, SLA auto-abandon, or the
+    // agent finished without escalating), so clear the denormalised escalation pointer the pages gate
+    // on. pollFeatureEscalations only sweeps `running`/`escalated` runs, so a terminal-ward transition
+    // through here must clear it itself or the stale question would linger on the row.
+    escalation_question: null,
+    escalation_user_task_key: null,
     updated_at: ts,
   });
   app.log.info("record-feature", { featureKey, featureStatus, rowStatus, prKey });

package/workers/record-feature-escalation/worker.test.ts

@@ -0,0 +1,74 @@
+// Unit coverage for pr.record-feature-escalation — a feature run parked on the native
+// `feature-escalation` user task (issue #210). Runs on the `escalated` arm, before the user task
+// exists, and must flip the row to the non-terminal `escalated` status and persist the agent's
+// `question` so the nwf UI can surface it (the poller can't read task-local vars, so this is the
+// question's source of truth). It clears the completable-task pointer to NULL (the task does not
+// exist yet, so any non-null value is stale); the poller fills the real key once it is observable.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import handler from "./worker.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: tiny in-memory app double, mirrors record-blocked-ack.worker.test
+function fakeApp(rows: Record<string, unknown>[]): any {
+  const stores: Record<string, Record<string, unknown>[]> = { feature_runs: rows };
+  return {
+    data: {
+      table(name: string, key: string) {
+        const store = (stores[name] ??= []);
+        return {
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          get: (k: any) => Promise.resolve(store.find((r) => r[key] === k)),
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          find: (q: any) => Promise.resolve(store.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          insert: (row: any) => {
+            store.push(row);
+            return Promise.resolve(store.length);
+          },
+          // biome-ignore lint/suspicious/noExplicitAny: test double
+          update: (k: any, patch: any) => {
+            const row = store.find((r) => r[key] === k);
+            if (row) Object.assign(row, patch);
+            return Promise.resolve(row);
+          },
+        };
+      },
+    },
+    log: noopLog(),
+  };
+}
+
+test("record-feature-escalation: flips the run to escalated and persists the question", async () => {
+  const rows = [{ feature_key: "owner/repo#7", status: "running", escalation_question: null, escalation_user_task_key: null }];
+  const app = fakeApp(rows);
+  const out = await handler(
+    { variables: { featureKey: "owner/repo#7", question: "Which API should I use?" } } as never,
+    app,
+  );
+  assertEquals(out, {});
+  assertEquals(rows[0].status, "escalated");
+  assertEquals(rows[0].escalation_question, "Which API should I use?");
+  // The user task does not exist yet — the pointer is cleared to NULL here (poller fills the real key).
+  assertEquals(rows[0].escalation_user_task_key, null);
+});
+
+test("record-feature-escalation: clears a stale completable-task pointer at escalation entry", async () => {
+  // The task does not exist yet here, so a non-null key can only be stale (a prior escalation's key
+  // left behind, a manual DB repair, etc). Leaving it would bind the pages' answer/abandon affordance
+  // to the wrong task until the poller overwrites it; clear it so the row reads "key unknown here".
+  const rows = [{ feature_key: "owner/repo#9", status: "running", escalation_question: null, escalation_user_task_key: "stale-ut" }];
+  const app = fakeApp(rows);
+  await handler({ variables: { featureKey: "owner/repo#9", question: "Q?" } } as never, app);
+  assertEquals(rows[0].status, "escalated");
+  assertEquals(rows[0].escalation_question, "Q?");
+  assertEquals(rows[0].escalation_user_task_key, null);
+});
+
+test("record-feature-escalation: a blank/absent question is persisted as NULL (badge/affordance stay off)", async () => {
+  const rows = [{ feature_key: "owner/repo#8", status: "running", escalation_question: null }];
+  const app = fakeApp(rows);
+  await handler({ variables: { featureKey: "owner/repo#8", question: "   " } } as never, app);
+  assertEquals(rows[0].status, "escalated");
+  assertEquals(rows[0].escalation_question, null);
+});

package/workers/record-feature-escalation/worker.ts

@@ -0,0 +1,42 @@
+// pr.record-feature-escalation — a feature run has parked on the native `feature-escalation`
+// user task (the agent reported `status:"escalated"` with a non-blank `question`). This service
+// task runs on the `escalated` arm, immediately BEFORE the user task is created, and persists the
+// escalation onto the `feature_runs` row so the nwf UI can surface it (issue #210):
+//   • flips `status` to the non-terminal `escalated` so status-based views and counts flag it, and
+//   • denormalises the agent's `question` for the Escalation column + the answer affordance.
+//
+// It deliberately does NOT record a REAL completable `userTaskKey` — the task does not exist yet at
+// this point — and clears any stale pointer so the row reads "key unknown until observed".
+// `pollFeatureEscalations` (app/service.ts) fills that pointer in once the user task is
+// observable via `searchUserTasks`, which is also the reason the question is captured HERE rather
+// than by the poller: the WASM testkit engine does not surface a user task's ioMapping-mapped local
+// variables through `searchUserTasks`, so the process variable must be persisted while it is still
+// in scope on the job.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { featureRuns } from "../../app/feature.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
+
+// Input typed off the model data envelope (`RecordFeatureEscalationIn` in feature.bpmn) — ADR 0040.
+type In = WorkerInputs["pr.record-feature-escalation"];
+
+const nonBlank = (v: unknown): string | null =>
+  typeof v === "string" && v.trim().length > 0 ? v.trim() : null;
+
+const handler: AppJobHandler<In> = async (job, app) => {
+  const featureKey = job.variables.featureKey;
+  const question = nonBlank(job.variables.question);
+  await featureRuns(app.data).update(featureKey, {
+    status: "escalated",
+    escalation_question: question,
+    // The user task does not exist yet, so any non-null pointer here can only be stale (a prior
+    // escalation's key, a manual DB repair). Clear it so the row reads "key unknown until observed"
+    // and the pages don't bind the answer/abandon affordance to a dead task; the poller re-fills the
+    // real key (it can always re-derive it from `searchUserTasks`), so this clear is never lossy.
+    escalation_user_task_key: null,
+    updated_at: new Date().toISOString(),
+  });
+  app.log.info("record-feature-escalation", { featureKey, hasQuestion: question !== null });
+  return {};
+};
+
+export default handler;

package/workers/record-plan/worker.ts

@@ -18,21 +18,12 @@
 import type { AppJobHandler } from "@nanobpm/urban";
 import { planTaskDeps, planTasks } from "../../app/plan.ts";
 import { computeWaves, WaveError, type WaveTask } from "../../app/waves.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface RawTask {
-  id?: unknown;
-  title?: unknown;
-  prompt?: unknown;
-  dependsOn?: unknown;
-}
-// NOTE (issue #211): this worker reads an ARRAY input (`tasks: RawTask[]`), which the scalar-only
-// `nano:dataEnvelope` cannot express, so it keeps a hand-written `interface In` pending a decision
-// on extending the envelope schema to arrays. See the PR body's "array inputs" escalation.
-interface In extends Record<string, unknown> {
-  planKey: string;
-  tasks?: RawTask[];
-  note?: string;
-}
+// Input typed off the model data envelope (`RecordPlanIn` in plan-fanout.bpmn) — ADR 0040. The
+// `tasks[]` array field is a `nano:reference` to the `RecordPlanTask` shape (`list="true"`), so it
+// resolves to `RecordPlanTask[]` with no hand-written interface.
+type In = WorkerInputs["pr.record-plan"];
 interface NormalTask {
   id: string;
   title: string;

package/workers/record-trial-merge/worker.ts

@@ -8,21 +8,13 @@ import {
   trialMergeDecision,
   trialMergeTaskId,
 } from "../../app/trialMerge.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-// NOTE (issue #211): this worker reads ARRAY inputs (`waveOpenHeads`, `conflicts`, `failing`), which
-// the scalar-only `nano:dataEnvelope` cannot express, so it keeps a hand-written `interface In`
-// pending a decision on extending the envelope schema to arrays. See the PR body's "array inputs"
-// escalation.
-interface In extends Record<string, unknown> {
-  planKey: string;
-  currentWave?: unknown;
-  trialMergeWave?: unknown;
-  waveOpenHeads?: unknown;
-  result?: unknown;
-  conflicts?: unknown;
-  failing?: unknown;
-  summary?: unknown;
-}
+// Input typed off the model data envelope (`RecordTrialMergeIn` in plan-fanout.bpmn) — ADR 0040.
+// The `waveOpenHeads[]` array field is a `nano:reference` to the `RecordTrialMergeHead` shape, and
+// `conflicts[]` / `failing[]` are scalar `list="true"` extends, so all three resolve from the model
+// with no hand-written interface.
+type In = WorkerInputs["pr.record-trial-merge"];
 interface Out extends Record<string, unknown> {
   trialMergeRed: boolean;
   question?: string;

package/workers/record-wave/worker.ts

@@ -28,26 +28,13 @@ import {
 import { parsePr, submitPr } from "../../app/service.ts";
 import { parseTaskDelta, readTaskDeltas, recordTaskDelta } from "../../app/taskDelta.ts";
 import { shouldRunTrialMerge, type TrialMergeHead } from "../../app/trialMerge.ts";
+import type { WorkerInputs } from "../../nano-generated/worker-io.d.ts";
 
-interface Result {
-  status?: unknown;
-  summary?: unknown;
-  pr?: unknown;
-  delta?: unknown;
-}
-interface WaveTaskIn {
-  id?: unknown;
-}
-// NOTE (issue #211): this worker reads ARRAY inputs (`waveTasks[]`, `waveResults[]`), which the
-// scalar-only `nano:dataEnvelope` cannot express, so it keeps a hand-written `interface In` pending
-// a decision on extending the envelope schema to arrays. See the PR body's "array inputs" escalation.
-interface In extends Record<string, unknown> {
-  planKey: string;
-  currentWave: number;
-  waveCount: number;
-  waveTasks?: WaveTaskIn[];
-  waveResults?: Result[];
-}
+// Input typed off the model data envelope (`RecordWaveIn` in plan-fanout.bpmn) — ADR 0040. The
+// `waveTasks[]` / `waveResults[]` array fields are `nano:reference`s to the `RecordWaveTaskRef` /
+// `RecordWaveResult` shapes (`list="true"`), so they resolve to `<Shape>[]` with no hand-written
+// interface.
+type In = WorkerInputs["pr.record-wave"];
 interface Out extends Record<string, unknown> {
   currentWave: number;
   hasMoreWaves: boolean;