@oakgreencc/cambium 0.0.9 → 0.0.11

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,453 @@
1
+ // @ts-check
2
+ /**
3
+ * The Dispatch phase as a graph: a `q:intake` issue is triaged by a one-shot `claude -p` worker whose final
4
+ * message carries a typed verdict ({@link TriageResult}), then moved to `q:task`, moved to `q:human`, or closed as
5
+ * a duplicate. Same conventions as the task graph (graphs/task.mjs): each node declares its queue label and
6
+ * whether it holds `running`, and a node's write is the marker first, then the labels via `move()`.
7
+ *
8
+ * The triage worker runs in a read-only checkout (workers.mjs `readOnly`): detached at the base branch, no install,
9
+ * no Edit/Write. It reads code to judge the issue, and nothing it could leave behind is worth keeping.
10
+ */
11
+ import { z } from 'zod'
12
+ import { defineGraph, defineNode, defineWait, END } from '../graph/index.mjs'
13
+ import { iso, key, markerOf, MIN, setLabels, setMarker } from '../issue-state.mjs'
14
+ import { move, Q, WHY } from '../labels.mjs'
15
+ import { newMarker, withHistory } from '../marker.mjs'
16
+ import { readTriage, TriageResult, triageComment, triagePrompt } from '../phases/dispatch.mjs'
17
+ import { task } from './task.mjs'
18
+
19
+ /**
20
+ * @typedef {import('../github.mjs').Issue} Issue
21
+ * @typedef {import('../marker.mjs').Marker} Marker
22
+ * @typedef {import('./task.mjs').Subject} Subject
23
+ * @typedef {import('./task.mjs').TaskCtx} DispatchCtx
24
+ * @typedef {{ queue: string | null, running: boolean }} Declared
25
+ * A stale `running` lease (at `triaging`) goes to `retry-triage` (dispatch-engine.mjs sweep).
26
+ * @typedef {import('../graph/define.mjs').GraphNode & Declared} DispatchNode
27
+ */
28
+
29
+ /** The nodes an issue in `q:intake` can rest at; a marker elsewhere starts triage over at attempt 1. */
30
+ const INTAKE_NODES = new Set(['start-triage', 'triaging', 'retry-triage'])
31
+
32
+ /** The pseudo-branch that names an issue's triage checkout (`<root>/triage-<n>`); never created. @param {number} n */
33
+ export const triageBranch = (n) => `cambium/triage-${n}`
34
+
35
+ /**
36
+ * @template {import('../graph/define.mjs').GraphNode} N @param {N} node @param {Declared} decl
37
+ * @returns {N & Declared}
38
+ */
39
+ const declare = (node, decl) => Object.freeze({ ...node, ...decl })
40
+
41
+ /** @param {DispatchCtx} ctx */
42
+ function issueOf(ctx) {
43
+ const { issue } = ctx.subject
44
+ if (!issue) throw new Error(`${ctx.subject.slug}#${ctx.subject.number} is not in the snapshot`)
45
+ return issue
46
+ }
47
+
48
+ /** @param {Marker} m */
49
+ const graphMarker = (m) => /** @type {Marker} */ (Object.fromEntries(Object.entries(m).filter(([k]) => k !== 'stage')))
50
+
51
+ /**
52
+ * Put the issue at `node` of this graph: the marker, then the labels `node` declares.
53
+ * @param {DispatchCtx} ctx @param {string} node @param {Marker} marker
54
+ * @param {{ extra?: string[], status?: Marker['status'] }} [opts]
55
+ */
56
+ async function land(ctx, node, marker, { extra = [], status = 'waiting' } = {}) {
57
+ const { slug } = ctx.subject
58
+ const issue = issueOf(ctx)
59
+ const decl = nodeOf(node)
60
+ await setMarker(ctx, slug, issue, {
61
+ ...graphMarker(marker),
62
+ graph: dispatch.name,
63
+ graphVersion: dispatch.version,
64
+ phase: 'dispatch',
65
+ node,
66
+ status,
67
+ enteredAt: iso(ctx.tick.now),
68
+ })
69
+ await setLabels(ctx, slug, issue, move(issue.labels, decl.queue, { running: decl.running, extra }))
70
+ ctx.tick.touched.add(key(slug, issue.number))
71
+ }
72
+
73
+ /**
74
+ * The marker triage continues from: this graph's own while the issue is still in intake, else a fresh one at
75
+ * attempt 1 that keeps the history (e.g. a human sent a `q:human` issue back to `q:intake`).
76
+ * @param {Issue} issue @returns {Marker}
77
+ */
78
+ function intakeMarker(issue) {
79
+ const m = markerOf(issue)
80
+ if (m.graph === dispatch.name && m.status !== 'done' && INTAKE_NODES.has(m.node)) return m
81
+ return newMarker({
82
+ graph: dispatch.name,
83
+ node: dispatch.entry.node,
84
+ phase: 'dispatch',
85
+ history: m.history,
86
+ traceparent: m.traceparent,
87
+ })
88
+ }
89
+
90
+ // ---- Schemas
91
+
92
+ const failure = { reason: z.string(), outcome: z.string(), log: z.string().optional() }
93
+ const Failure = z.object(failure)
94
+ const Empty = z.object({})
95
+ const Verdict = z.object({ result: TriageResult, log: z.string() })
96
+
97
+ // ---- Edge predicates (their names label the Mermaid edges)
98
+
99
+ const started = (/** @type {{ to: string }} */ o) => o.to === 'running'
100
+ const budgetSpent = (/** @type {{ to: string }} */ o) => o.to === 'human'
101
+ const attemptsLeft = (/** @type {{ to: string }} */ o) => o.to === 'start'
102
+ const issueGone = (/** @type {{ exit: string }} */ o) => o.exit === 'gone'
103
+ const leaseLost = (/** @type {{ exit: string }} */ o) => o.exit === 'lost'
104
+ /** @typedef {{ exit: string, result?: { verdict: string } }} Triaged */
105
+ const verdictOf = (/** @type {Triaged} */ o) => (o.exit === 'triaged' ? o.result?.verdict : undefined)
106
+ const actionable = (/** @type {Triaged} */ o) => verdictOf(o) === 'actionable'
107
+ const needsHuman = (/** @type {Triaged} */ o) => verdictOf(o) === 'needs-human'
108
+ const duplicate = (/** @type {Triaged} */ o) => verdictOf(o) === 'duplicate'
109
+
110
+ /** @param {DispatchCtx} ctx */
111
+ export const lostLeaseOf = (ctx) => ({
112
+ reason: `triage worker lost: \`running\` on ${ctx.config.host} with no live process`,
113
+ outcome: 'lost',
114
+ })
115
+
116
+ // ---- Nodes
117
+
118
+ const startTriage = declare(
119
+ defineNode({
120
+ name: 'start-triage',
121
+ input: Empty,
122
+ output: z.discriminatedUnion('to', [
123
+ z.object({ to: z.literal('running'), pid: z.number().int(), worktree: z.string(), attempt: z.number().int() }),
124
+ z.object({ to: z.literal('retry'), ...failure }),
125
+ z.object({ to: z.literal('human'), ...failure }),
126
+ ]),
127
+ /**
128
+ * Claim the issue (marker, then `running`), then start the triage worker in a read-only checkout.
129
+ * @param {{}} _ @param {DispatchCtx} ctx
130
+ */
131
+ run: async (_, ctx) => {
132
+ const { config, spawner, store } = ctx
133
+ const { slug, snap } = ctx.subject
134
+ const issue = issueOf(ctx)
135
+ const repo = config.repos.find((r) => r.slug === slug)
136
+ if (!repo) throw new Error(`${slug} is not in the config`)
137
+ const caps = config.phases.dispatch
138
+ const m0 = intakeMarker(issue)
139
+ if (m0.attempt > caps.maxAttempts)
140
+ return { to: 'human', reason: `${caps.maxAttempts} triage attempts spent`, outcome: 'budget' }
141
+ /** @type {import('../convention.mjs').Convention} */
142
+ let convention
143
+ try {
144
+ convention = spawner.convention(repo)
145
+ } catch (err) {
146
+ return { to: 'retry', reason: `could not start triage: ${errText(err)}`, outcome: 'spawn-failed' }
147
+ }
148
+ await land(ctx, 'triaging', {
149
+ ...m0,
150
+ host: config.host,
151
+ start: iso(ctx.tick.now),
152
+ input: { attempt: m0.attempt },
153
+ })
154
+ const marker = markerOf(issue)
155
+ const queued = [...(snap?.issues.values() ?? [])]
156
+ .filter((i) => i.state === 'OPEN')
157
+ .map(({ number, title, labels }) => ({ number, title, labels }))
158
+ /** @type {import('../workers.mjs').Started} */
159
+ let s
160
+ try {
161
+ s = await spawner.start({
162
+ repo,
163
+ convention,
164
+ issue: issue.number,
165
+ attempt: marker.attempt,
166
+ branch: triageBranch(issue.number),
167
+ phase: 'dispatch',
168
+ maxTurns: caps.maxTurns,
169
+ readOnly: true,
170
+ // TRACING (follow-up): as start-worker, the triage worker's env gets `TRACEPARENT: ctx.traceparent`
171
+ // (this node's cambium.node span, under the cambium.issue root that continues mycelium's intake span).
172
+ buildPrompt: (agentsMd) => triagePrompt({ repo: slug, baseBranch: repo.baseBranch, issue, queued, agentsMd }),
173
+ })
174
+ } catch (err) {
175
+ return {
176
+ to: 'retry',
177
+ reason: `could not start triage: ${errText(err)}`,
178
+ outcome: 'spawn-failed',
179
+ // The claim already put the marker at triaging; the failure is this node's.
180
+ }
181
+ }
182
+ store.addWorker({
183
+ repo: slug,
184
+ issue: issue.number,
185
+ phase: 'dispatch',
186
+ pid: s.pid,
187
+ worktree: s.worktree,
188
+ branch: triageBranch(issue.number),
189
+ attempt: marker.attempt,
190
+ startedAt: ctx.tick.now,
191
+ host: config.host,
192
+ stdout: s.stdout,
193
+ stderr: s.stderr,
194
+ })
195
+ ctx.log('info', `started triage worker pid ${s.pid} (attempt ${marker.attempt})`, {
196
+ repo: slug,
197
+ issue: issue.number,
198
+ })
199
+ ctx.subject.started = { ...s, attempt: marker.attempt }
200
+ return { to: 'running', pid: s.pid, worktree: s.worktree, attempt: marker.attempt }
201
+ },
202
+ }),
203
+ { queue: Q.intake, running: false },
204
+ )
205
+
206
+ const triaging = declare(
207
+ defineWait({
208
+ name: 'triaging',
209
+ input: z.object({ attempt: z.number().int() }),
210
+ output: z.discriminatedUnion('exit', [
211
+ z.object({ exit: z.literal('triaged'), ...Verdict.shape }),
212
+ z.object({ exit: z.literal('invalid'), ...failure }),
213
+ z.object({ exit: z.literal('lost'), ...failure }),
214
+ z.object({ exit: z.literal('gone') }),
215
+ ]),
216
+ /**
217
+ * Alive and under the wall-clock cap: hold. Over it: kill. Gone: read the verdict from its stdout log; a
218
+ * missing or invalid one is `invalid`, with the error.
219
+ * @param {unknown} _ @param {DispatchCtx} ctx
220
+ */
221
+ poll: async (_, ctx) => {
222
+ const { config, store, procs, spawner } = ctx
223
+ const { slug, number, snap, issue, reaped } = ctx.subject
224
+ const w = store.worker(slug, number)
225
+ if (!w) {
226
+ const host = issue?.stateComment?.marker.host
227
+ if (host && host !== config.host) return { ready: false }
228
+ return { ready: true, output: { exit: 'lost', ...lostLeaseOf(ctx) } }
229
+ }
230
+ const caps = config.phases.dispatch
231
+ if (procs.alive(w.pid) && !reaped?.has(w.pid)) {
232
+ if (!w.killedReason && ctx.tick.now - w.startedAt <= caps.wallClockMinutes * MIN) return { ready: false }
233
+ const reason = w.killedReason ?? `killed: over the ${caps.wallClockMinutes} min wall-clock cap`
234
+ procs.kill(w.pid)
235
+ store.markKilled(w.repo, w.issue, reason)
236
+ w.killedReason = reason
237
+ ctx.log('warn', `${reason} (pid ${w.pid})`, { repo: w.repo, issue: w.issue })
238
+ }
239
+ if (!snap) return { ready: false }
240
+ if (issue?.state !== 'OPEN' || !issue.labels.includes(Q.intake)) {
241
+ ctx.log('info', 'triage worker gone; issue is closed or left q:intake', { repo: w.repo, issue: w.issue })
242
+ return { ready: true, output: { exit: 'gone' } }
243
+ }
244
+ // TRACING (follow-up): the worker has ended; emit its spans here with tracing.mjs
245
+ // `workerSpans(<w.stdout log>, { tracer, parent: <start-triage's traceparent> })`.
246
+ const read = w.killedReason ? { ok: false, error: w.killedReason } : readTriage(spawner.readLog(w.stdout), number)
247
+ if (read.ok && 'result' in read)
248
+ return { ready: true, output: { exit: 'triaged', result: read.result, log: w.stdout } }
249
+ const tail = 'error' in read && !read.error.startsWith('invalid') ? spawner.tail(w.stderr, 15) : ''
250
+ return {
251
+ ready: true,
252
+ output: {
253
+ exit: 'invalid',
254
+ reason: `${'error' in read ? read.error : 'no verdict'}${tail ? `\n--- stderr (last lines, ${w.stderr})\n${tail}` : ''}`,
255
+ outcome: w.killedReason ? 'killed' : 'invalid',
256
+ log: w.stdout,
257
+ },
258
+ }
259
+ },
260
+ }),
261
+ { queue: Q.intake, running: true },
262
+ )
263
+
264
+ const retryTriage = declare(
265
+ defineNode({
266
+ name: 'retry-triage',
267
+ input: Failure,
268
+ output: z.discriminatedUnion('to', [
269
+ z.object({ to: z.literal('start'), attempt: z.number().int() }),
270
+ z.object({ to: z.literal('human'), ...failure }),
271
+ ]),
272
+ /** Back to `q:intake` with attempt + 1, or to a human once the attempts are spent. @param {z.infer<typeof Failure>} what @param {DispatchCtx} ctx */
273
+ run: async (what, ctx) => {
274
+ const issue = issueOf(ctx)
275
+ const m = intakeMarker(issue)
276
+ const max = ctx.config.phases.dispatch.maxAttempts
277
+ if (m.attempt >= max)
278
+ return { ...what, to: 'human', reason: `${max} triage attempts spent. Last: ${what.reason}` }
279
+ await land(ctx, 'start-triage', {
280
+ ...withHistory(m, { at: iso(ctx.tick.now), attempt: m.attempt, ...what }),
281
+ attempt: m.attempt + 1,
282
+ lastFailure: what.reason,
283
+ host: null,
284
+ start: null,
285
+ input: null,
286
+ })
287
+ ctx.log('info', `triage retried (attempt ${m.attempt + 1}/${max}): ${what.reason.split('\n')[0]}`, {
288
+ repo: ctx.subject.slug,
289
+ issue: issue.number,
290
+ })
291
+ return { to: 'start', attempt: m.attempt + 1 }
292
+ },
293
+ }),
294
+ { queue: Q.intake, running: false },
295
+ )
296
+
297
+ const ToTaskIn = z.object({
298
+ reason: z.string(),
299
+ title: z.string().optional(),
300
+ acceptance: z.array(z.string()).optional(),
301
+ log: z.string(),
302
+ })
303
+ const toTask = declare(
304
+ defineNode({
305
+ name: 'to-task',
306
+ input: ToTaskIn,
307
+ output: Empty,
308
+ /**
309
+ * Actionable: the triage comment (task title and acceptance checks, when given), then the hand-off: a task-graph
310
+ * marker at its entry, attempt 1, carrying the history and `triage` for the task prompt; then `q:task`.
311
+ * The issue body is left as its author wrote it.
312
+ * @param {z.infer<typeof ToTaskIn>} t @param {DispatchCtx} ctx
313
+ */
314
+ run: async (t, ctx) => {
315
+ const { slug } = ctx.subject
316
+ const issue = issueOf(ctx)
317
+ const m = markerOf(issue)
318
+ await ctx.github.comment(slug, issue.number, triageComment(t))
319
+ const at = iso(ctx.tick.now)
320
+ await setMarker(ctx, slug, issue, {
321
+ ...newMarker({
322
+ graph: task.name,
323
+ graphVersion: task.version,
324
+ node: task.entry.node,
325
+ phase: 'task',
326
+ enteredAt: at,
327
+ traceparent: m.traceparent,
328
+ history: withHistory(m, { at, attempt: m.attempt, outcome: 'actionable', reason: t.reason, log: t.log })
329
+ .history,
330
+ }),
331
+ triage: t.title || t.acceptance?.length ? { title: t.title, acceptance: t.acceptance } : null,
332
+ })
333
+ await setLabels(ctx, slug, issue, move(issue.labels, Q.task))
334
+ ctx.tick.touched.add(key(slug, issue.number))
335
+ ctx.log('info', `triaged actionable → q:task: ${t.reason.split('\n')[0]}`, { repo: slug, issue: issue.number })
336
+ return {}
337
+ },
338
+ }),
339
+ { queue: Q.task, running: false },
340
+ )
341
+
342
+ const toHuman = declare(
343
+ defineNode({
344
+ name: 'to-human',
345
+ input: Failure,
346
+ output: Empty,
347
+ /** Into the Human Queue with `why:triage` and the reason in the state comment. @param {z.infer<typeof Failure>} what @param {DispatchCtx} ctx */
348
+ run: async (what, ctx) => {
349
+ const issue = issueOf(ctx)
350
+ const m = markerOf(issue)
351
+ await land(
352
+ ctx,
353
+ 'to-human',
354
+ {
355
+ ...withHistory(m, { at: iso(ctx.tick.now), attempt: m.attempt, ...what }),
356
+ lastFailure: what.reason,
357
+ host: null,
358
+ start: null,
359
+ input: null,
360
+ },
361
+ { extra: [WHY.triage] },
362
+ )
363
+ ctx.log('warn', `→ q:human (${WHY.triage}): ${what.reason.split('\n')[0]}`, {
364
+ repo: ctx.subject.slug,
365
+ issue: issue.number,
366
+ })
367
+ return {}
368
+ },
369
+ }),
370
+ { queue: Q.human, running: false },
371
+ )
372
+
373
+ const DupIn = z.object({ duplicateOf: z.number().int(), reason: z.string(), log: z.string() })
374
+ const closeDuplicate = declare(
375
+ defineNode({
376
+ name: 'close-duplicate',
377
+ input: DupIn,
378
+ output: Empty,
379
+ /** Out of every queue, closed as a duplicate with a link to the original. @param {z.infer<typeof DupIn>} d @param {DispatchCtx} ctx */
380
+ run: async (d, ctx) => {
381
+ const { slug } = ctx.subject
382
+ const issue = issueOf(ctx)
383
+ const m = markerOf(issue)
384
+ await land(
385
+ ctx,
386
+ 'close-duplicate',
387
+ {
388
+ ...withHistory(m, {
389
+ at: iso(ctx.tick.now),
390
+ attempt: m.attempt,
391
+ outcome: 'duplicate',
392
+ reason: d.reason,
393
+ log: d.log,
394
+ }),
395
+ host: null,
396
+ start: null,
397
+ input: null,
398
+ },
399
+ { status: 'done' },
400
+ )
401
+ const link = `https://github.com/${slug}/issues/${d.duplicateOf}`
402
+ await ctx.github.close(
403
+ slug,
404
+ issue.number,
405
+ `Duplicate of #${d.duplicateOf} (${link}). ${d.reason}\n\nClosed by cambium.`,
406
+ {
407
+ reason: 'duplicate',
408
+ },
409
+ )
410
+ issue.state = 'CLOSED'
411
+ ctx.log('info', `duplicate of #${d.duplicateOf}; closed`, { repo: slug, issue: issue.number })
412
+ return {}
413
+ },
414
+ }),
415
+ { queue: null, running: false },
416
+ )
417
+
418
+ /** @param {unknown} err */
419
+ const errText = (err) => /** @type {Error} */ (err)?.message ?? String(err)
420
+
421
+ /** The Dispatch phase. Bump `version` when a node is removed or renamed. */
422
+ export const dispatch = defineGraph({
423
+ name: 'dispatch',
424
+ version: 1,
425
+ entry: { queue: Q.intake, node: 'start-triage', input: () => ({}) },
426
+ nodes: [startTriage, triaging, retryTriage, toTask, toHuman, closeDuplicate],
427
+ edges: [
428
+ ['start-triage', 'triaging', started, (o) => ({ attempt: o.attempt })],
429
+ ['start-triage', 'to-human', budgetSpent],
430
+ ['start-triage', 'retry-triage'],
431
+ ['triaging', END, issueGone],
432
+ ['triaging', 'retry-triage', leaseLost],
433
+ ['triaging', 'to-task', actionable, (o) => ({ ...pick(o.result, ['reason', 'title', 'acceptance']), log: o.log })],
434
+ ['triaging', 'close-duplicate', duplicate, (o) => ({ ...pick(o.result, ['duplicateOf', 'reason']), log: o.log })],
435
+ ['triaging', 'to-human', needsHuman, (o) => ({ reason: o.result.reason, outcome: 'needs-human', log: o.log })],
436
+ ['triaging', 'to-human'],
437
+ ['retry-triage', 'start-triage', attemptsLeft, () => ({})],
438
+ ['retry-triage', 'to-human'],
439
+ ['to-task', END],
440
+ ['to-human', END],
441
+ ['close-duplicate', END],
442
+ ],
443
+ })
444
+
445
+ /** @param {Record<string, unknown>} o @param {string[]} keys */
446
+ const pick = (o, keys) => Object.fromEntries(keys.filter((k) => o[k] !== undefined).map((k) => [k, o[k]]))
447
+
448
+ /** @param {string} name @returns {DispatchNode} */
449
+ export function nodeOf(name) {
450
+ const node = dispatch.nodes.find((n) => n.name === name)
451
+ if (!node) throw new Error(`dispatch graph has no node "${name}"`)
452
+ return /** @type {DispatchNode} */ (node)
453
+ }