@nanobpm/urban-pr-review-codefirst 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,299 @@
1
+ import { defineFlow, envelope } from "@nanobpm/workflow";
2
+ import { openDomain, type Domain } from "@nanobpm/domain";
3
+
4
+ // ---------------------------------------------------------------------------
5
+ // Persistence (parity with the model-first `urban-pr-review`). The `w.run`
6
+ // handlers below are the app-owned record steps — the same writes the sibling
7
+ // app makes from `workers/{persist-round,persist-escalation,finalize}` — but
8
+ // hosted in-process by `@nanobpm/workflow`'s Worker instead of as standalone
9
+ // `defineWorker`s. Data access goes through the typed data object
10
+ // (`@nanobpm/domain`), not hand-written SQL.
11
+ //
12
+ // The datasource is opened lazily and memoised on first persist, so the thin
13
+ // CLI scripts (submit/answer/review-ready) can import this flow to start/signal
14
+ // instances without ever touching the DB — only the worker host that actually
15
+ // runs these handlers opens it.
16
+ // ---------------------------------------------------------------------------
17
+ let _db: Domain | null = null;
18
+ async function db(): Promise<Domain> {
19
+ return (_db ??= await openDomain("app"));
20
+ }
21
+
22
+ const nowTs = (): string => new Date().toISOString();
23
+
24
+ /** Read a string variable off a job, coercing/defaulting as the reference does. */
25
+ function str(vars: Record<string, unknown>, key: string, fallback = ""): string {
26
+ const val = vars[key];
27
+ if (typeof val === "string") return val;
28
+ return val == null ? fallback : String(val);
29
+ }
30
+
31
+ /** Read an integer variable off a job. */
32
+ function int(vars: Record<string, unknown>, key: string, fallback = 0): number {
33
+ const val = vars[key];
34
+ if (typeof val === "number") return val;
35
+ const n = Number(val);
36
+ return Number.isFinite(n) ? n : fallback;
37
+ }
38
+
39
+ // The external reviewer harness records its full (byte-capped) stdout on the
40
+ // result envelope; keep it for audit so a human can see what the agent did this
41
+ // round without re-running it.
42
+ const AGENT_RESULT_KEY = "io.nanobpm.agentResult";
43
+ function transcriptOf(vars: Record<string, unknown>): string | null {
44
+ const env = vars[AGENT_RESULT_KEY] as { output?: unknown } | undefined;
45
+ return typeof env?.output === "string" ? env.output : null;
46
+ }
47
+
48
+ // ---------------------------------------------------------------------------
49
+ // Typed data envelopes (ADR 0045). Each is lifted into the generated BPMN as a
50
+ // `nano:shape` + `io.nanobpm.dataEnvelope` property, so this code-first flow can
51
+ // be *ejected* to model-first without losing its I/O contracts. `env.type` is a
52
+ // phantom type — it never exists at runtime.
53
+ // ---------------------------------------------------------------------------
54
+
55
+ /** What the reviewer agent is handed: the PR to review and this round's prompt. */
56
+ const ReviewRoundIn = envelope("ReviewRoundIn", {
57
+ prKey: "string",
58
+ prUrl: "string",
59
+ repo: "string",
60
+ prNumber: "integer",
61
+ round: "integer",
62
+ prompt: "string",
63
+ // Present only after a human answered an escalation and we re-review.
64
+ answer: { type: "string", optional: true },
65
+ });
66
+
67
+ /** What the reviewer agent returns: a verdict plus a human-readable summary. */
68
+ const ReviewRoundOut = envelope("ReviewRoundOut", {
69
+ // "converged" | "addressed" | "needs_input" | "blocked"
70
+ status: "string",
71
+ summary: "string",
72
+ // Only when the agent needs a human decision.
73
+ question: { type: "string", optional: true },
74
+ });
75
+
76
+ /** Recorded when a round is addressed but not yet converged; advances `round`. */
77
+ const PersistRoundIn = envelope("PersistRoundIn", {
78
+ prKey: "string",
79
+ round: "integer",
80
+ status: { type: "string", optional: true },
81
+ summary: { type: "string", optional: true },
82
+ });
83
+
84
+ /** The single output that keeps the loop moving: the next round number. */
85
+ const RoundAdvanced = envelope("RoundAdvanced", {
86
+ round: "integer",
87
+ });
88
+
89
+ /** Recorded when the flow must pause for a human (needs_input / blocked / cap). */
90
+ const PersistEscalationIn = envelope("PersistEscalationIn", {
91
+ prKey: "string",
92
+ round: "integer",
93
+ status: { type: "string", optional: true },
94
+ summary: { type: "string", optional: true },
95
+ question: { type: "string", optional: true },
96
+ });
97
+
98
+ /** Recorded once the reviewer converges; the terminal, idempotent write. */
99
+ const FinalizeIn = envelope("FinalizeIn", {
100
+ prKey: "string",
101
+ round: "integer",
102
+ summary: { type: "string", optional: true },
103
+ });
104
+
105
+ /** The durable signal a poller publishes when a fresh review has landed. */
106
+ const ReviewReady = envelope("ReviewReady", {
107
+ reviewId: "integer",
108
+ reviewState: "string",
109
+ submittedAt: { type: "datetime", optional: true },
110
+ });
111
+
112
+ /** The durable signal a human publishes to unblock an escalated PR. */
113
+ const EscalationAnswered = envelope("EscalationAnswered", {
114
+ answer: "string",
115
+ escalationId: { type: "integer", optional: true },
116
+ });
117
+
118
+ const dataEnvelopes = {
119
+ "review-round": { in: ReviewRoundIn, out: ReviewRoundOut },
120
+ "persist-round": { in: PersistRoundIn, out: RoundAdvanced },
121
+ "persist-escalation": { in: PersistEscalationIn },
122
+ "persist-escalation-maxrounds": { in: PersistEscalationIn },
123
+ "persist-converged": { in: FinalizeIn },
124
+ "wait-review": { in: ReviewReady },
125
+ "wait-answer": { in: EscalationAnswered },
126
+ }
127
+
128
+ // ---------------------------------------------------------------------------
129
+ // The convergence loop. This is the code-first expression of urban-pr-review's
130
+ // `convergence-loop.bpmn`: a durable, multi-round loop that drives a PR to
131
+ // convergence against an automated reviewer, escalating to a human when the
132
+ // reviewer is stuck or a round cap is hit.
133
+ //
134
+ // loop:
135
+ // review-round (EXTERNAL agent) ── the coding-agent harness services this
136
+ // switch status:
137
+ // converged -> persist-converged; break
138
+ // addressed -> if round >= maxRounds:
139
+ // persist-escalation-maxrounds (fall through)
140
+ // else:
141
+ // persist-round (round+1); wait-review; continue
142
+ // default -> persist-escalation (fall through)
143
+ // wait-answer ── reached by both escalation paths
144
+ //
145
+ // Every `wait-*` is a real BPMN catch event — the durable wait a Temporal-style
146
+ // code-first surface cannot draw. Both resume at the loop head (`review-round`):
147
+ // `wait-review` via an explicit `continue`, `wait-answer` via the loop's natural
148
+ // repeat. The two escalation branches converge on the single trailing
149
+ // `wait-answer` (step names must be unique, so we cannot repeat the signal).
150
+ // ---------------------------------------------------------------------------
151
+ export const convergenceLoop = defineFlow(
152
+ "convergence-loop", dataEnvelopes,
153
+ (w) => {
154
+ w.loop((b) => {
155
+ // The reviewer agent. An EXTERNAL worker — a coding-agent harness — services
156
+ // the job type `convergence-loop:review-round`. The app never names it; it
157
+ // only owns the durable orchestration around it.
158
+ b.task("review-round");
159
+
160
+ b.switch("status", {
161
+ // Converged: record the terminal state and leave the loop.
162
+ converged: (c) => {
163
+ c.run("persist-converged", async (job) => {
164
+ // The PR converged — record the final round and close the PR out.
165
+ // This is the terminal, idempotent write (parity: workers/finalize).
166
+ const vars = job.variables as Record<string, unknown>;
167
+ const prKey = str(vars, "prKey");
168
+ const round = int(vars, "round");
169
+ const summary = str(vars, "summary");
170
+ const ts = nowTs();
171
+ const d = await db();
172
+ await d.rounds.insert({
173
+ pr_key: prKey, round_no: round, status: "converged", summary,
174
+ transcript: transcriptOf(vars), started_at: ts, ended_at: ts,
175
+ });
176
+ await d.pull_requests.update(prKey, {
177
+ status: "converged", current_round: round, outcome: summary,
178
+ converged_at: ts, updated_at: ts,
179
+ open_escalation_id: null, open_escalation_question: null,
180
+ });
181
+ console.log(`[persist-converged] ${prKey} converged at round ${round}`);
182
+ return {};
183
+ });
184
+ c.break();
185
+ },
186
+
187
+ // Addressed but not converged: either escalate (round cap) or re-review.
188
+ addressed: (c) =>
189
+ c.branch("round >= maxRounds", {
190
+ then: (g) => {
191
+ g.run("persist-escalation-maxrounds", async (job) => {
192
+ // Round cap hit: force a human decision. Record the capped round
193
+ // and open a blocker escalation (parity: workers/persist-escalation
194
+ // driven by the process's MAX_ROUNDS guard).
195
+ const vars = job.variables as Record<string, unknown>;
196
+ const prKey = str(vars, "prKey");
197
+ const round = int(vars, "round");
198
+ const summary = str(vars, "summary");
199
+ const question = "Round cap reached without convergence — merge as-is, or abandon?";
200
+ const ts = nowTs();
201
+ const transcript = transcriptOf(vars);
202
+ const d = await db();
203
+ await d.rounds.insert({
204
+ pr_key: prKey, round_no: round, status: "blocked", summary,
205
+ transcript, started_at: ts, ended_at: ts,
206
+ });
207
+ const escalationId = await d.escalations.insert({
208
+ pr_key: prKey, round_no: round, kind: "blocker", question,
209
+ transcript, status: "open", asked_at: ts,
210
+ });
211
+ await d.pull_requests.update(prKey, {
212
+ status: "escalated", current_round: round, updated_at: ts,
213
+ open_escalation_id: Number(escalationId), open_escalation_question: question,
214
+ });
215
+ console.log(
216
+ `[persist-escalation-maxrounds] ${prKey} hit the round cap at round ${round}`,
217
+ );
218
+ // Falls through to the trailing `wait-answer` (human required).
219
+ return { status: "blocked", question, escalationId: Number(escalationId) };
220
+ });
221
+ // Falls through to the trailing `wait-answer` (human required).
222
+ },
223
+ else: (g) => {
224
+ g.run("persist-round", async (job) => {
225
+ // An addressed round that hasn't converged: record it and park the
226
+ // PR in `waiting_review` so the poller starts watching for the next
227
+ // review (parity: workers/persist-round).
228
+ const vars = job.variables as Record<string, unknown>;
229
+ const prKey = str(vars, "prKey");
230
+ const round = int(vars, "round");
231
+ const status = str(vars, "status", "addressed");
232
+ const summary = str(vars, "summary");
233
+ const ts = nowTs();
234
+ const d = await db();
235
+ await d.rounds.insert({
236
+ pr_key: prKey, round_no: round, status, summary,
237
+ transcript: transcriptOf(vars), started_at: ts, ended_at: ts,
238
+ });
239
+ await d.pull_requests.update(prKey, {
240
+ status: "waiting_review", current_round: round,
241
+ waiting_since: ts, updated_at: ts,
242
+ });
243
+ console.log(`[persist-round] ${prKey} addressed at round ${round}; advancing`);
244
+ // The loop's only state mutation lives here (not in an ioMapping):
245
+ // advance the round so the next review-round sees round+1.
246
+ return { round: round + 1 };
247
+ });
248
+ // Park until the next review lands, then loop back to review-round.
249
+ g.signal("wait-review", { correlationKey: "prKey" });
250
+ g.continue();
251
+ },
252
+ }),
253
+
254
+ // needs_input / blocked: escalate to a human.
255
+ default: (c) => {
256
+ c.run("persist-escalation", async (job) => {
257
+ // needs_input / blocked: record the round that raised the escalation
258
+ // and open an escalation row for a human to answer (parity:
259
+ // workers/persist-escalation, agent-raised path).
260
+ const vars = job.variables as Record<string, unknown>;
261
+ const prKey = str(vars, "prKey");
262
+ const round = int(vars, "round");
263
+ const status = str(vars, "status", "needs_input");
264
+ const summary = str(vars, "summary");
265
+ const question = str(vars, "question") || "(no question provided)";
266
+ const kind = status === "needs_input" ? "question" : "blocker";
267
+ const ts = nowTs();
268
+ const transcript = transcriptOf(vars);
269
+ const d = await db();
270
+ await d.rounds.insert({
271
+ pr_key: prKey, round_no: round, status, summary,
272
+ transcript, started_at: ts, ended_at: ts,
273
+ });
274
+ const escalationId = await d.escalations.insert({
275
+ pr_key: prKey, round_no: round, kind, question,
276
+ transcript, status: "open", asked_at: ts,
277
+ });
278
+ await d.pull_requests.update(prKey, {
279
+ status: "escalated", current_round: round, updated_at: ts,
280
+ open_escalation_id: Number(escalationId), open_escalation_question: question,
281
+ });
282
+ console.log(
283
+ `[persist-escalation] ${prKey} escalated (${status}) at round ${round}`,
284
+ );
285
+ // Falls through to the trailing `wait-answer` (human required).
286
+ return { escalationId: Number(escalationId) };
287
+ });
288
+ // Falls through to the trailing `wait-answer` (human required).
289
+ },
290
+ });
291
+
292
+ // Both escalation paths (round-cap + needs_input/blocked) converge here:
293
+ // park until a human answers, then loop back to review-round.
294
+ b.signal("wait-answer", { correlationKey: "prKey" });
295
+ });
296
+ },
297
+ );
298
+
299
+ export default convergenceLoop;