@nanobpm/nano-workforce 0.168.2 → 0.169.0

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.169.0](https://github.com/nanobpm/nano-workforce/compare/v0.168.2...v0.169.0) (2026-08-31)
+
+### Features
+
+* add getPrHistory read tool for PR escalation/round history ([#670](https://github.com/nanobpm/nano-workforce/issues/670)) ([22bd6f9](https://github.com/nanobpm/nano-workforce/commit/22bd6f9d28b891a2b4c157d21bad94cb11af1eb4)), closes [#668](https://github.com/nanobpm/nano-workforce/issues/668)
+
 ## [0.168.2](https://github.com/nanobpm/nano-workforce/compare/v0.168.1...v0.168.2) (2026-08-31)
 
 ### Bug Fixes

package/app/prHistory.ts

@@ -0,0 +1,117 @@
+// PR round + escalation history read model (issue #668, N4 of epic #664).
+//
+// "Why did this PR escalate?" / "what happened in prior rounds?" lives in the `rounds` and
+// `escalations` tables — the SAME two tables the Convergence page (`pages/home.page.json`, the PR
+// detail's "Rounds" and "Escalations" child grids) reads directly. Until now the only way to answer
+// those questions off the UI was to ssh into the instance and query the DB by hand. This module is
+// the ONE canonical reader over those tables so an MCP read tool (`getPrHistory`) can surface the
+// same history without DB access.
+//
+// Derivation over duplication (AGENTS.md): this does NOT introduce a new projection table or a
+// second source of truth. The Convergence page's "query" is declarative datasource JSON over the
+// `rounds`/`escalations` tables (ordered rounds-by-round_no, escalations-by-id); this function reads
+// those exact tables with the exact same orderings, so the tool and the page cannot drift onto
+// different data.
+import type { DataLayer } from "@nanobpm/urban";
+
+/** A `rounds` row — the per-round convergence record the Convergence page's "Rounds" grid reads. */
+interface RoundRow {
+  id: number;
+  pr_key: string;
+  round_no: number;
+  status: string | null;
+  summary: string | null;
+  worker: string | null;
+  started_at: string;
+  ended_at: string | null;
+}
+
+/** An `escalations` row — the escalation record the Convergence page's "Escalations" grid reads. */
+interface EscalationRow {
+  id: number;
+  pr_key: string;
+  round_no: number;
+  kind: string;
+  question: string;
+  answer: string | null;
+  status: string;
+  worker: string | null;
+  asked_at: string;
+  answered_at: string | null;
+}
+
+/** The subset of a `pull_requests` row this module needs to resolve a processKey → prKey. */
+interface PrKeyRow {
+  pr_key: string;
+  process_key: string | null;
+}
+
+/** One round in a PR's timeline: its status transition/outcome, owning worker, and timestamps. */
+export interface PrHistoryRound {
+  roundNo: number;
+  status: string | null;
+  worker: string | null;
+  summary: string | null;
+  startedAt: string;
+  endedAt: string | null;
+}
+
+/** One escalation in a PR's history: its kind, question/answer, status, and timestamps. */
+export interface PrHistoryEscalation {
+  roundNo: number;
+  kind: string;
+  worker: string | null;
+  question: string;
+  answer: string | null;
+  status: string;
+  askedAt: string;
+  answeredAt: string | null;
+}
+
+/** A PR's full escalation + round history, as surfaced by the Convergence page's PR detail. */
+export interface PrHistory {
+  prKey: string;
+  rounds: PrHistoryRound[];
+  escalations: PrHistoryEscalation[];
+}
+
+const rounds = (data: DataLayer) => data.table<RoundRow>("rounds", "id");
+const escs = (data: DataLayer) => data.table<EscalationRow>("escalations", "id");
+const prs = (data: DataLayer) => data.table<PrKeyRow>("pull_requests", "pr_key");
+
+/** Resolve an engine process-instance key to the PR it drives (unique per instance), or null. */
+export async function prKeyForProcess(data: DataLayer, processKey: string): Promise<string | null> {
+  const matches = await prs(data).find({ process_key: processKey });
+  return matches[0]?.pr_key ?? null;
+}
+
+/** The canonical PR history read: rounds (round_no asc) + escalations (id asc, i.e. asked order) for
+ * one PR, projected to the wire shape. An unknown `prKey` yields an empty history (no throw), so a
+ * caller can distinguish "no history yet" from an error without a 404 round-trip. */
+export async function prHistory(data: DataLayer, prKey: string): Promise<PrHistory> {
+  const roundRows = (await rounds(data).find({ pr_key: prKey })).sort(
+    (a, b) => a.round_no - b.round_no || a.id - b.id,
+  );
+  const escRows = (await escs(data).find({ pr_key: prKey })).sort((a, b) => a.id - b.id);
+  return {
+    prKey,
+    rounds: roundRows.map((r) => ({
+      roundNo: r.round_no,
+      status: r.status ?? null,
+      worker: r.worker ?? null,
+      summary: r.summary ?? null,
+      startedAt: r.started_at,
+      endedAt: r.ended_at ?? null,
+    })),
+    escalations: escRows.map((e) => ({
+      roundNo: e.round_no,
+      kind: e.kind,
+      worker: e.worker ?? null,
+      question: e.question,
+      answer: e.answer ?? null,
+      status: e.status,
+      askedAt: e.asked_at,
+      answeredAt: e.answered_at ?? null,
+    })),
+  };
+}

package/openapi.yaml

@@ -223,6 +223,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).
@@ -2997,6 +3084,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.168.2",
+  "version": "0.169.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",