@nanobpm/nano-workforce 0.168.2 → 0.170.0

package/openapi.yaml

@@ -108,8 +108,31 @@ components:
           type: string
           nullable: true
         openEscalation:
-          type: string
+          type: object
           nullable: true
+          additionalProperties: false
+          description: >-
+            The structured pointer to this PR's OPEN escalation when it is parked awaiting a human/agent
+            answer (issue #666), else null. Derived from the same `user_tasks` read model as
+            `listEscalations`, so `userTaskKey` is the completable key an agent answers via
+            `completeUserTask` / `agentCompleteEscalation` (no `/tasks/api/tasks` curl needed). `kind`
+            is the BPMN escalation elementId (e.g. `wait-answer`, `wait-merge-answer`); `summary` is the
+            raised question/findings (null when none was recorded).
+          required:
+            - userTaskKey
+            - kind
+            - summary
+          properties:
+            userTaskKey:
+              type: string
+              description: The completable engine user-task key (answer via completeUserTask / agentCompleteEscalation).
+            kind:
+              type: string
+              description: The BPMN escalation elementId (the escalation kind).
+            summary:
+              type: string
+              nullable: true
+              description: The raised question / findings, denormalised for display; null when none.
         updatedAt:
           type: string
         activeWorker:
@@ -130,6 +153,85 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/ActivePr"
+    Escalation:
+      type: object
+      description: >-
+        One OPEN native user-task escalation awaiting a human/agent decision (issue #666), projected
+        from the `user_tasks` read model. `userTaskKey` is the completable key an agent answers via
+        `completeUserTask` / `agentCompleteEscalation`; `kind` is the BPMN escalation elementId.
+      additionalProperties: false
+      required:
+        - userTaskKey
+        - kind
+        - kindLabel
+        - prKey
+        - subjectType
+        - subjectKey
+        - subjectTitle
+        - subjectUrl
+        - question
+        - formKey
+        - processKey
+        - formVariables
+      properties:
+        userTaskKey:
+          type: string
+          description: The completable engine user-task key (answer via completeUserTask / agentCompleteEscalation).
+        kind:
+          type: string
+          description: The BPMN escalation elementId (e.g. wait-answer, wait-merge-answer, plan-review-decision, trial-merge-decision, feature-escalation).
+        kindLabel:
+          type: string
+          description: Human-readable kind label (e.g. "PR review", "Plan review", "Trial merge").
+        prKey:
+          type: string
+          nullable: true
+          description: The PR key when this escalation belongs to a PR (review/merge loop); null for feature / plan / delivery / agent subjects.
+        subjectType:
+          type: string
+          description: The domain subject kind — feature | plan | pr | delivery | agent.
+        subjectKey:
+          type: string
+          description: The subject aggregate key (feature_key / plan_key / pr_key).
+        subjectTitle:
+          type: string
+          description: The subject's human-readable title (coalesced to subjectKey when unknown).
+        subjectUrl:
+          type: string
+          nullable: true
+          description: An optional external link (the issue/PR URL); null when none.
+        question:
+          type: string
+          nullable: true
+          description: The raised question / findings / task text the loop or agent recorded; null when none.
+        formKey:
+          type: string
+          nullable: true
+          description: The deployed `.form` key of the parked user task, for rendering/answering; null when unresolved.
+        processKey:
+          type: string
+          nullable: true
+          description: The owning engine process-instance key; null when unknown.
+        formVariables:
+          type: object
+          additionalProperties: true
+          description: >-
+            The denormalised decision/form context the Tasks inbox renders for this task (the same
+            question + subject the deployed form is seeded with). The typed answer fields an agent
+            submits depend on `kind` (e.g. a PR `{ answer }`, a plan-review `{ directive, notes }`).
+    EscalationList:
+      type: object
+      additionalProperties: false
+      required:
+        - count
+        - escalations
+      properties:
+        count:
+          type: integer
+        escalations:
+          type: array
+          items:
+            $ref: "#/components/schemas/Escalation"
     LineagePrView:
       type: object
       description: A member PR of a lineage thread (issue #245).
@@ -223,6 +325,93 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/LineageThreadView"
+    PrHistoryRound:
+      type: object
+      description: One convergence round in a PR's timeline (issue #668) — its status transition/outcome, owning worker, and timestamps. Sourced from the `rounds` table the Convergence page reads.
+      additionalProperties: false
+      required:
+        - roundNo
+        - status
+        - worker
+        - summary
+        - startedAt
+        - endedAt
+      properties:
+        roundNo:
+          type: integer
+        status:
+          type: string
+          nullable: true
+          description: The round's result/status transition (converged|addressed|waiting|needs_input|blocked).
+        worker:
+          type: string
+          nullable: true
+          description: The worker that ran this round.
+        summary:
+          type: string
+          nullable: true
+          description: The round outcome summary.
+        startedAt:
+          type: string
+        endedAt:
+          type: string
+          nullable: true
+    PrHistoryEscalation:
+      type: object
+      description: One escalation in a PR's history (issue #668) — its kind, question/answer, status, and timestamps. Sourced from the `escalations` table the Convergence page reads.
+      additionalProperties: false
+      required:
+        - roundNo
+        - kind
+        - worker
+        - question
+        - answer
+        - status
+        - askedAt
+        - answeredAt
+      properties:
+        roundNo:
+          type: integer
+        kind:
+          type: string
+          description: The escalation kind (question|blocker).
+        worker:
+          type: string
+          nullable: true
+          description: The worker that raised this escalation.
+        question:
+          type: string
+        answer:
+          type: string
+          nullable: true
+          description: The human's answer; null while the escalation is still open.
+        status:
+          type: string
+          description: open | answered | stale.
+        askedAt:
+          type: string
+        answeredAt:
+          type: string
+          nullable: true
+    PrHistory:
+      type: object
+      description: A PR's full escalation + round history (issue #668), as surfaced read-only on the Convergence page's PR detail. Empty arrays when the PR has no history (or is unknown).
+      additionalProperties: false
+      required:
+        - prKey
+        - rounds
+        - escalations
+      properties:
+        prKey:
+          type: string
+        rounds:
+          type: array
+          items:
+            $ref: "#/components/schemas/PrHistoryRound"
+        escalations:
+          type: array
+          items:
+            $ref: "#/components/schemas/PrHistoryEscalation"
     AgenticSupplyWorker:
       type: object
       description: One connected worker in the supply mirror (H5 cockpit; sourced from the H1 presence registry).
@@ -2970,6 +3159,36 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /escalations:
+    get:
+      operationId: listEscalations
+      summary: List every OPEN escalation awaiting a human/agent decision, with the completable userTaskKey.
+      description: >-
+        Discovery for the escalation-answer path (epic #664, issue #666): across every surfaced
+        escalation kind (PR review/merge loop, plan-review, empty-plan, trial-merge,
+        conformance-review, delivery human-step, feature/blocked, agent-permission and the shared
+        human-escalation cell), list each currently-open native user-task escalation with the
+        completable `userTaskKey` an agent then answers via `completeUserTask` /
+        `agentCompleteEscalation` — so a tool-aware agent never has to curl the un-projected
+        `/tasks/api/tasks` inbox to find keys. Read-only projection over the ONE `user_tasks` read
+        model the Tasks inbox and Convergence page consume (no second source of truth); a row is
+        present iff its task is open, so the list reflects live pending work.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The open escalations.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EscalationList"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /lineage:
     get:
       operationId: getLineage
@@ -2997,6 +3216,45 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /prs/history:
+    get:
+      operationId: getPrHistory
+      summary: "A PR's escalation + round history (issue #668): per-round status transitions and outcome, plus each escalation's kind, question/answer, and timestamps — the read that retires the DB-over-ssh fallback. Identify the PR by prKey, or by processKey. Reads the same rounds/escalations tables the Convergence page surfaces."
+      security:
+        - hookSecret: []
+        - {}
+      parameters:
+        - name: prKey
+          in: query
+          required: false
+          schema:
+            type: string
+          description: The PR key ("<owner>/<repo>#<number>"). Provide this or processKey.
+        - name: processKey
+          in: query
+          required: false
+          schema:
+            type: string
+          description: The engine process-instance key driving the PR; resolved to its prKey. Provide this or prKey.
+      responses:
+        "200":
+          description: The PR's round + escalation history (empty arrays when there is none).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PrHistory"
+        "400":
+          description: Neither prKey nor processKey supplied.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /agentic/supply:
     get:
       operationId: getAgenticSupply

package/operations/getPrHistory.test.ts

@@ -0,0 +1,137 @@
+// Tests for GET /app/api/prs/history → operation `getPrHistory` (issue #668, N4 of epic #664).
+// The headline scenario: a PR that escalated and then RESUMED (its escalation answered, a fresh round
+// recorded) exposes its full history — every round's status/outcome plus the answered escalation's
+// question/answer — through the tool, with NO DB access (the handler reads the same `rounds`/
+// `escalations` tables the Convergence page surfaces, via a minimal in-memory DataLayer). Also covers
+// the processKey → prKey resolution, the prKey/processKey-required 400, and the shared-secret guard.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import handler from "./getPrHistory.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: test-only dynamic row shapes.
+type Row = any;
+
+function memApp(tables: { rounds?: Row[]; escalations?: Row[]; pull_requests?: Row[] }): AppApi {
+  const stores: Record<string, Row[]> = {
+    rounds: tables.rounds ?? [],
+    escalations: tables.escalations ?? [],
+    pull_requests: tables.pull_requests ?? [],
+  };
+  const table = (name: string) => ({
+    async find(where: Record<string, unknown>) {
+      return (stores[name] ?? []).filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
+    },
+  });
+  return { data: { table }, log: noopLog() } as unknown as AppApi;
+}
+
+function input(query: Record<string, string>, headers: Record<string, string> = {}) {
+  return {
+    req: {
+      method: "GET",
+      path: "/app/api/prs/history",
+      query: new URLSearchParams(query),
+      headers: new Headers(headers),
+      text: async () => "",
+    } as unknown,
+    params: {},
+    query,
+    body: undefined,
+  };
+}
+
+// A PR that escalated in round 1 (blocker), had that escalation answered, and RESUMED into round 2.
+function escalatedThenResumed() {
+  return memApp({
+    pull_requests: [{ pr_key: "o/r#7", process_key: "proc-7" }],
+    rounds: [
+      { id: 10, pr_key: "o/r#7", round_no: 1, status: "needs_input", summary: "hit an ambiguity", worker: "senior-a", started_at: "2026-03-01T00:00:00Z", ended_at: "2026-03-01T00:05:00Z" },
+      { id: 11, pr_key: "o/r#7", round_no: 2, status: "converged", summary: "resolved after the answer", worker: "senior-a", started_at: "2026-03-01T01:00:00Z", ended_at: "2026-03-01T01:05:00Z" },
+    ],
+    escalations: [
+      { id: 20, pr_key: "o/r#7", round_no: 1, kind: "blocker", question: "Which base branch?", answer: "main", status: "answered", worker: "senior-a", asked_at: "2026-03-01T00:03:00Z", answered_at: "2026-03-01T00:50:00Z" },
+    ],
+  });
+}
+
+test("an escalated-then-resumed PR exposes its round + escalation history by prKey", async () => {
+  const res = (await handler(input({ prKey: "o/r#7" }), escalatedThenResumed())) as Row;
+  assertEquals(res.status, 200);
+  assertEquals(res.body.prKey, "o/r#7");
+
+  // Both rounds surface, in round order, with their status transition + outcome summary.
+  assertEquals(res.body.rounds.length, 2);
+  assertEquals(res.body.rounds[0].roundNo, 1);
+  assertEquals(res.body.rounds[0].status, "needs_input");
+  assertEquals(res.body.rounds[1].roundNo, 2);
+  assertEquals(res.body.rounds[1].status, "converged");
+  assertEquals(res.body.rounds[1].summary, "resolved after the answer");
+
+  // The escalation surfaces with its kind, question, answer, and timestamps — the "why did it
+  // escalate / what was answered" the tool exists to expose.
+  assertEquals(res.body.escalations.length, 1);
+  const e = res.body.escalations[0];
+  assertEquals(e.kind, "blocker");
+  assertEquals(e.question, "Which base branch?");
+  assertEquals(e.answer, "main");
+  assertEquals(e.status, "answered");
+  assertEquals(e.roundNo, 1);
+  assertEquals(e.askedAt, "2026-03-01T00:03:00Z");
+  assertEquals(e.answeredAt, "2026-03-01T00:50:00Z");
+});
+
+test("resolves the PR by processKey when no prKey is given", async () => {
+  const res = (await handler(input({ processKey: "proc-7" }), escalatedThenResumed())) as Row;
+  assertEquals(res.status, 200);
+  assertEquals(res.body.prKey, "o/r#7");
+  assertEquals(res.body.rounds.length, 2);
+  assertEquals(res.body.escalations.length, 1);
+});
+
+test("orders rounds by round_no and escalations in asked order", async () => {
+  const app = memApp({
+    rounds: [
+      { id: 2, pr_key: "o/r#9", round_no: 2, status: "converged", summary: null, worker: null, started_at: "b", ended_at: null },
+      { id: 1, pr_key: "o/r#9", round_no: 1, status: "addressed", summary: null, worker: null, started_at: "a", ended_at: null },
+    ],
+    escalations: [
+      { id: 5, pr_key: "o/r#9", round_no: 2, kind: "question", question: "second", answer: null, status: "open", worker: null, asked_at: "b", answered_at: null },
+      { id: 4, pr_key: "o/r#9", round_no: 1, kind: "question", question: "first", answer: null, status: "answered", worker: null, asked_at: "a", answered_at: "a2" },
+    ],
+  });
+  const res = (await handler(input({ prKey: "o/r#9" }), app)) as Row;
+  assertEquals(res.body.rounds.map((r: Row) => r.roundNo), [1, 2]);
+  assertEquals(res.body.escalations.map((e: Row) => e.question), ["first", "second"]);
+});
+
+test("an unknown PR returns an empty history (not a 404)", async () => {
+  const res = (await handler(input({ prKey: "o/r#404" }), memApp({}))) as Row;
+  assertEquals(res.status, 200);
+  assertEquals(res.body.prKey, "o/r#404");
+  assertEquals(res.body.rounds, []);
+  assertEquals(res.body.escalations, []);
+});
+
+test("neither prKey nor processKey → 400", async () => {
+  const res = (await handler(input({}), memApp({}))) as Row;
+  assertEquals(res.status, 400);
+});
+
+test("shared-secret guard rejects a missing/wrong secret when configured", async () => {
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    const mod = await import(`./getPrHistory.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    const bad = (await guarded(input({ prKey: "o/r#7" }), escalatedThenResumed())) as Row;
+    assertEquals(bad.status, 401);
+    const ok = (await guarded(input({ prKey: "o/r#7" }, { "x-hook-secret": "s3cr3t" }), escalatedThenResumed())) as Row;
+    assertEquals(ok.status, 200);
+    assert(Array.isArray(ok.body.rounds));
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});

package/operations/getPrHistory.ts

@@ -0,0 +1,41 @@
+// GET /app/api/prs/history → operationId `getPrHistory` (issue #668, N4 of epic #664). Surface a PR's
+// escalation + round history — "why did this escalate?" / "what happened in prior rounds?" — as an
+// MCP read tool, so an operator or external harness no longer has to ssh into the instance and query
+// the `escalations`/`rounds` tables by hand.
+//
+// Read-only projection over the SAME `rounds`/`escalations` tables the Convergence page's PR detail
+// reads (see app/prHistory.ts). Identify the PR by `prKey` directly, or by `processKey` (resolved to
+// its pr_key). At least one is required; neither → 400.
+//
+// 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.
+import { prHistory, prKeyForProcess } from "../app/prHistory.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("getPrHistory", async ({ query, req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("getPrHistory rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const rawPrKey = query.prKey;
+  const rawProcessKey = query.processKey;
+  const prKeyArg = typeof rawPrKey === "string" ? rawPrKey.trim() : "";
+  const processKeyArg = typeof rawProcessKey === "string" ? rawProcessKey.trim() : "";
+
+  if (!prKeyArg && !processKeyArg) {
+    return { status: 400, body: { error: "prKey or processKey is required" } };
+  }
+
+  const prKey = prKeyArg || (await prKeyForProcess(app.data, processKeyArg));
+  if (!prKey) {
+    // A processKey with no tracked PR: report an empty history for a stable, echoable identity
+    // rather than a 404, mirroring getLineage's "empty if unknown" read semantics.
+    return { status: 200, body: { prKey: processKeyArg, rounds: [], escalations: [] } };
+  }
+
+  const history = await prHistory(app.data, prKey);
+  return { status: 200, body: history };
+});

package/operations/listActivePrs.test.ts

@@ -8,14 +8,15 @@ import { noopLog } from "../test/log.ts";
 import { withTrackingViews } from "../test/trackingViews.ts";
 import handler from "./listActivePrs.ts";
 
-function memApp(rows: any[], escalations: any[] = []): AppApi {
+function memApp(rows: any[], userTaskRows: any[] = []): AppApi {
   const table = (name: string) => {
-    if (name === "escalations") {
+    if (name === "user_tasks") {
       return {
+        async all() {
+          return userTaskRows;
+        },
         async find(where: Record<string, unknown>) {
-          return escalations.filter((e) =>
-            Object.entries(where).every(([k, v]) => e[k] === v)
-          );
+          return userTaskRows.filter((t) => Object.entries(where).every(([k, v]) => t[k] === v));
         },
       };
     }
@@ -58,25 +59,42 @@ test("returns 200 with a count + projected active PRs", async () => {
   assertEquals(r.body.prs[0].processKey, "9");
 });
 
-test("surfaces openEscalation for an escalated PR from its open escalations row (both loops)", async () => {
-  // Regression: a merge-loop escalation parks on a message catch (no user task), so deriving
-  // openEscalation from a user-task probe hid it. Deriving from the canonical `escalations` row
-  // surfaces it. Two escalated PRs — one with an open row (visible), one already answered (null).
+test("surfaces the structured openEscalation from the user_tasks read model (both loops)", async () => {
+  // Issue #666: openEscalation is derived from the ONE `user_tasks` read model (the same surface
+  // `listEscalations` and the Convergence page consume), so `/status` carries the completable
+  // userTaskKey. A `user_tasks` row for a PR subject exists iff its review/merge-loop escalation task
+  // is currently open; a PR with no such row derives null. Cover a review-loop and a merge-loop PR.
   const app = memApp(
     [
       { pr_key: "o/r#10", repo: "o/r", number: 10, url: "u10", title: "merge blocked", status: "escalated", current_round: 3, process_key: "m1", updated_at: "2026-02-02" },
-      { pr_key: "o/r#11", repo: "o/r", number: 11, url: "u11", title: "answered", status: "escalated", current_round: 4, process_key: "m2", updated_at: "2026-02-01" },
+      { pr_key: "o/r#11", repo: "o/r", number: 11, url: "u11", title: "no open task", status: "escalated", current_round: 4, process_key: "m2", updated_at: "2026-02-01" },
     ],
     [
-      { id: 1, pr_key: "o/r#10", status: "open", question: "Resolve the conflict on the branch, then retry?" },
-      { id: 2, pr_key: "o/r#11", status: "answered", question: "old question" },
+      {
+        user_task_key: "ut-10",
+        element_id: "wait-merge-answer",
+        kind_label: "PR merge",
+        subject_type: "pr",
+        subject_key: "o/r#10",
+        subject_title: "merge blocked",
+        subject_url: null,
+        question: "Resolve the conflict on the branch, then retry?",
+        process_key: "m1",
+        form_key: null,
+        created_at: "2026-02-02",
+        updated_at: "2026-02-02",
+      },
     ],
   );
   const res = (await handler(input(), app)) as any;
   assertEquals(res.status, 200);
   const p10 = res.body.prs.find((p: any) => p.prKey === "o/r#10");
   const p11 = res.body.prs.find((p: any) => p.prKey === "o/r#11");
-  assertEquals(p10.openEscalation, "Resolve the conflict on the branch, then retry?");
+  assertEquals(p10.openEscalation, {
+    userTaskKey: "ut-10",
+    kind: "wait-merge-answer",
+    summary: "Resolve the conflict on the branch, then retry?",
+  });
   assertEquals(p11.openEscalation, null);
 });