@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.
- package/README.md +141 -0
- package/components/review-round.json +69 -0
- package/db/migrations/001_init.sql +46 -0
- package/db/migrations/002_transcript.sql +7 -0
- package/db/migrations/003_open_escalation.sql +8 -0
- package/deno.json +22 -0
- package/deno.lock +77 -0
- package/main.ts +352 -0
- package/nano-generated/app-pages.ts +676 -0
- package/nano-generated/data-cli.ts +552 -0
- package/nano-generated/data-sdk.ts +536 -0
- package/nano-generated/domain-rows.d.ts +87 -0
- package/nano-generated/domain-types.ts +1418 -0
- package/nano-generated/domain.ts +36 -0
- package/nano-generated/llm-worker.ts +403 -0
- package/nano-generated/message-io.d.ts +17 -0
- package/nano-generated/messages.ts +26 -0
- package/nano-generated/meta.ts +18 -0
- package/nano-generated/node-deno-shim.mjs +250 -0
- package/nano-generated/node-loader.mjs +60 -0
- package/nano-generated/node-register.mjs +11 -0
- package/nano-generated/worker-io.d.ts +28 -0
- package/nano-generated/worker-sdk.ts +468 -0
- package/nano-generated/workers.ts +29 -0
- package/nano.app.json +17 -0
- package/nanobpm.project.json +22 -0
- package/package.json +28 -0
- package/pages/home.page.json +127 -0
- package/prompts/review-round.md +119 -0
- package/scripts/answer.ts +20 -0
- package/scripts/purge-db.ts +70 -0
- package/scripts/review-ready.ts +20 -0
- package/scripts/submit.ts +32 -0
- package/tsconfig.json +14 -0
- package/workflows/convergence-loop.ts +299 -0
|
@@ -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;
|