@oakgreencc/cambium 0.0.40 → 0.0.41

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 CHANGED
@@ -286,10 +286,26 @@ Written at the end of every tick to `paths.heartbeat` (default `~/.cambium/state
286
286
  "repo": "oakgreencc/monorepo",
287
287
  "issue": 12
288
288
  } // level: "info" | "warn" | "error"; repo/issue optional
289
+ ],
290
+ "engine": "graph", // config.engine: "legacy" | "graph"
291
+ "graphs": [
292
+ // every graph this cambium defines, as describeGraph() writes it (see The graph module); the same every tick
293
+ {
294
+ "name": "task",
295
+ "version": 2,
296
+ "about": "Turns a q:task issue into a published PR; …",
297
+ "entry": { "queue": "q:task", "node": "start-worker" },
298
+ "nodes": [
299
+ { "name": "worker-running", "kind": "wait", "queue": "q:task", "running": true, "about": "Holds while …" }
300
+ ],
301
+ "edges": [{ "from": "start-worker", "to": "worker-running", "when": "started" }] // to: null ends the graph
302
+ }
289
303
  ]
290
304
  }
291
305
  ```
292
306
 
307
+ `engine` and `graphs` were added within `version: 1`; a reader of an older heartbeat finds neither.
308
+
293
309
  The mode lives in the SQLite file (`paths.db`, table `control`), so `cambium status --json` returns `{ "mode", "heartbeat" }` even when the daemon is down. The daemon's own log is `<paths.logs>/cambium.log` (one `.1` kept); launchd's stderr goes to `<paths.logs>/cambium.launchd.err.log`.
294
310
 
295
311
  ## The task graph
@@ -623,6 +639,7 @@ const { transitions, reason, node, input } = await advance(g, { node: 'open-pr',
623
639
  - **`validateGraph(graph)`** returns every problem as a string (`defineGraph` throws on any): unknown edge endpoints, nodes unreachable from `entry.node`, a node with outgoing edges whose last edge is conditional (no fallback), duplicate names, a non-integer `version`.
624
640
  - **`advance(graph, { node, input }, ctx, { maxTransitions = 8, signal })`** runs step nodes and ready waits and returns `{ transitions, reason, node, input, error? }`: `reason` is `waiting` (a wait that is not ready), `end`, `limit`, `aborted` (`signal`, or `ctx.signal`, checked before each node) or `error`; `node`/`input` is where it stopped. Each transition is `{ from, to, edge, input, output, next }`. `ctx` is passed to `run`/`poll` untouched apart from `ctx.signal`; edges see `ctx.subject`.
625
641
  - **`toMermaid(graph)`** renders a flowchart: boxes for steps, hexagons for waits, conditional edges labelled with `when`'s function name.
642
+ - **`describeGraph(graph)`** returns the graph as plain JSON: `{ name, version, about, entry: { queue, node }, nodes: [{ name, kind: 'step' | 'wait', queue, running, about }], edges: [{ from, to, when }] }`. `to: null` ends the graph; `when` is the condition's function name, `null` for the fallback. `about` is the optional one-line description given to `defineGraph` (and, in cambium's graphs, to each node's declaration); `queue`/`running` are the labels a node declares, else `null`/`false`. The heartbeat carries every cambium graph this way.
626
643
  - **`opts.instrument(visit, step)`** (optional) wraps each node visit: `visit` is `{ node, kind: 'node' | 'wait', input }`; `step(extraCtx?)` runs the node (or poll) and picks the edge, returning the transition, or `null` for a wait that is not ready, and throws on a node error. `extraCtx` is merged into that node's `ctx`. Return what `step` returned. Without it, `advance` behaves exactly as before. [`advanceHooks`](#tracing) is the tracing implementation.
627
644
 
628
645
  ### LangGraph interop
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oakgreencc/cambium",
3
- "version": "0.0.40",
3
+ "version": "0.0.41",
4
4
  "description": "The scheduler daemon: reads the q:* queues from GitHub every tick, runs headless claude workers in their own worktrees up to a cap, and makes every queue transition itself.",
5
5
  "license": "AGPL-3.0-only",
6
6
  "type": "module",
@@ -20,7 +20,8 @@ export { END }
20
20
  * @typedef {(out: any, subject: unknown) => unknown} EdgeFn
21
21
  * @typedef {[from: string, to: string, when?: EdgeFn | null, map?: EdgeFn]} Edge
22
22
  * @typedef {{ queue?: string, node: string, input?: (...args: any[]) => unknown }} Entry
23
- * @typedef {{ name: string, version: number, entry: Entry, nodes: GraphNode[], edges: Edge[] }} Graph
23
+ * @typedef {{ name: string, version: number, about?: string, entry: Entry, nodes: GraphNode[], edges: Edge[] }} Graph
24
+ * `about`: one line on what the graph is for, carried into the heartbeat (graph/describe.mjs).
24
25
  */
25
26
 
26
27
  /** A failure inside a node: bad input or output, or a throw from run, poll, when or map. */
@@ -98,6 +99,13 @@ export function defineWait(def) {
98
99
  export function defineGraph(def) {
99
100
  const problems = validateGraph(def)
100
101
  if (problems.length) throw new Error(`graph "${def?.name}" is invalid:\n- ${problems.join('\n- ')}`)
101
- const { name, version, entry, nodes, edges } = def
102
- return Object.freeze({ name, version, entry: { ...entry }, nodes: [...nodes], edges: edges.map((e) => e) })
102
+ const { name, version, about, entry, nodes, edges } = def
103
+ return Object.freeze({
104
+ name,
105
+ version,
106
+ ...(typeof about === 'string' ? { about } : {}),
107
+ entry: { ...entry },
108
+ nodes: [...nodes],
109
+ edges: edges.map((e) => e),
110
+ })
103
111
  }
@@ -0,0 +1,50 @@
1
+ // @ts-check
2
+ /**
3
+ * A graph as plain JSON, for the heartbeat: what a reader (canopy's Graphs tab) needs to draw it without importing
4
+ * cambium. Schemas and functions are dropped; a conditional edge keeps its `when`'s name.
5
+ */
6
+ import { END } from './validate.mjs'
7
+
8
+ /**
9
+ * @typedef {{
10
+ * name: string, kind: 'step' | 'wait', queue: string | null, running: boolean, about: string | null,
11
+ * }} NodeDescription
12
+ * `queue`/`running`: the labels an issue resting at the node carries, when the graph declares them.
13
+ * @typedef {{ from: string, to: string | null, when: string | null }} EdgeDescription
14
+ * `to: null` ends the graph. `when: null` is the unconditional fallback, taken when no condition before it holds.
15
+ * @typedef {{
16
+ * name: string, version: number, about: string | null, entry: { queue: string | null, node: string },
17
+ * nodes: NodeDescription[], edges: EdgeDescription[],
18
+ * }} GraphDescription
19
+ */
20
+
21
+ /** @param {unknown} v */
22
+ const str = (v) => (typeof v === 'string' && v ? v : null)
23
+
24
+ /**
25
+ * @param {import('./define.mjs').Graph} graph
26
+ * @returns {GraphDescription}
27
+ */
28
+ export function describeGraph(graph) {
29
+ return {
30
+ name: graph.name,
31
+ version: graph.version,
32
+ about: str(graph.about),
33
+ entry: { queue: str(graph.entry.queue), node: graph.entry.node },
34
+ nodes: graph.nodes.map((n) => {
35
+ const d = /** @type {{ queue?: unknown, running?: unknown, about?: unknown }} */ (n)
36
+ return {
37
+ name: n.name,
38
+ kind: n.kind === 'wait' ? 'wait' : 'step',
39
+ queue: str(d.queue),
40
+ running: d.running === true,
41
+ about: str(d.about),
42
+ }
43
+ }),
44
+ edges: graph.edges.map(([from, to, when]) => ({
45
+ from,
46
+ to: to === END ? null : to,
47
+ when: when ? when.name || 'when' : null,
48
+ })),
49
+ }
50
+ }
@@ -1,6 +1,7 @@
1
1
  // @ts-check
2
- /** `@oakgreencc/cambium/graph`: typed nodes, data edges, load-time validation, Mermaid and the advance loop. */
2
+ /** `@oakgreencc/cambium/graph`: typed nodes, data edges, load-time validation, Mermaid, JSON and the advance loop. */
3
3
  export { defineGraph, defineNode, defineWait, END, GraphNodeError } from './define.mjs'
4
4
  export { validateGraph } from './validate.mjs'
5
5
  export { toMermaid } from './mermaid.mjs'
6
+ export { describeGraph } from './describe.mjs'
6
7
  export { advance } from './advance.mjs'
@@ -24,7 +24,7 @@ import { task } from './task.mjs'
24
24
  * @typedef {import('../marker.mjs').Marker} Marker
25
25
  * @typedef {import('./task.mjs').Subject} Subject
26
26
  * @typedef {import('./task.mjs').TaskCtx} DispatchCtx
27
- * @typedef {{ queue: string | null, running: boolean }} Declared
27
+ * @typedef {{ queue: string | null, running: boolean, about?: string }} Declared
28
28
  * A stale `running` lease (at `triaging`) goes to `retry-triage` (dispatch-engine.mjs sweep).
29
29
  * @typedef {import('../graph/define.mjs').GraphNode & Declared} DispatchNode
30
30
  */
@@ -235,7 +235,11 @@ const startTriage = declare(
235
235
  return { to: 'running', pid: s.pid, worktree: s.worktree, attempt: marker.attempt }
236
236
  },
237
237
  }),
238
- { queue: Q.intake, running: false },
238
+ {
239
+ queue: Q.intake,
240
+ running: false,
241
+ about: 'Claims the issue and starts a triage worker in a read-only checkout; out of attempts, it goes to a human.',
242
+ },
239
243
  )
240
244
 
241
245
  const triaging = declare(
@@ -289,7 +293,12 @@ const triaging = declare(
289
293
  }
290
294
  },
291
295
  }),
292
- { queue: Q.intake, running: true },
296
+ {
297
+ queue: Q.intake,
298
+ running: true,
299
+ about:
300
+ 'Holds while the triage worker runs under its wall-clock cap; on exit, reads the typed verdict from its log.',
301
+ },
293
302
  )
294
303
 
295
304
  const retryTriage = declare(
@@ -322,7 +331,11 @@ const retryTriage = declare(
322
331
  return { to: 'start', attempt: m.attempt + 1 }
323
332
  },
324
333
  }),
325
- { queue: Q.intake, running: false },
334
+ {
335
+ queue: Q.intake,
336
+ running: false,
337
+ about: 'Back to q:intake with attempt + 1, or to a human once the attempts are spent.',
338
+ },
326
339
  )
327
340
 
328
341
  const ToTaskIn = z.object({
@@ -367,7 +380,12 @@ const toTask = declare(
367
380
  return {}
368
381
  },
369
382
  }),
370
- { queue: Q.task, running: false },
383
+ {
384
+ queue: Q.task,
385
+ running: false,
386
+ about:
387
+ 'Actionable: posts the triage comment (title, acceptance checks), then hands the issue to the task graph in q:task.',
388
+ },
371
389
  )
372
390
 
373
391
  const toHuman = declare(
@@ -398,7 +416,7 @@ const toHuman = declare(
398
416
  return {}
399
417
  },
400
418
  }),
401
- { queue: Q.human, running: false },
419
+ { queue: Q.human, running: false, about: 'Into q:human with why:triage and the reason in the state comment.' },
402
420
  )
403
421
 
404
422
  const DupIn = z.object({ duplicateOf: z.number().int(), reason: z.string(), log: z.string() })
@@ -443,7 +461,7 @@ const closeDuplicate = declare(
443
461
  return {}
444
462
  },
445
463
  }),
446
- { queue: null, running: false },
464
+ { queue: null, running: false, about: 'Out of every queue, closed as a duplicate with a link to the original.' },
447
465
  )
448
466
 
449
467
  const DeferIn = z.object({ reason: z.string(), recheckHours: z.number().optional(), log: z.string() })
@@ -502,7 +520,11 @@ const deferred = declare(
502
520
  return { to: 'wait', until }
503
521
  },
504
522
  }),
505
- { queue: Q.intake, running: false },
523
+ {
524
+ queue: Q.intake,
525
+ running: false,
526
+ about: 'Rests in q:intake until a condition a machine can check is due, then triages again. Bounded by maxDefers.',
527
+ },
506
528
  )
507
529
 
508
530
  const BlockedIn = z.object({
@@ -573,7 +595,7 @@ const blockedNode = declare(
573
595
  return { to: 'wait', blockedBy: open }
574
596
  },
575
597
  }),
576
- { queue: Q.intake, running: false },
598
+ { queue: Q.intake, running: false, about: 'Rests in q:intake with wait:blocked until every blockedBy issue closes.' },
577
599
  )
578
600
 
579
601
  const ObsIn = z.object({ reason: z.string(), log: z.string() })
@@ -612,7 +634,7 @@ const closeObsolete = declare(
612
634
  return {}
613
635
  },
614
636
  }),
615
- { queue: null, running: false },
637
+ { queue: null, running: false, about: 'Out of every queue, closed as not planned with the evidence triage found.' },
616
638
  )
617
639
 
618
640
  /** @param {unknown} err */
@@ -621,6 +643,7 @@ const errText = (err) => /** @type {Error} */ (err)?.message ?? String(err)
621
643
  /** The Dispatch phase. Bump `version` when a node is removed or renamed. */
622
644
  export const dispatch = defineGraph({
623
645
  name: 'dispatch',
646
+ about: 'Triages a q:intake issue with a one-shot read-only worker, then routes it on its verdict.',
624
647
  version: 1,
625
648
  entry: { queue: Q.intake, node: 'start-triage', input: () => ({}) },
626
649
  nodes: [startTriage, triaging, retryTriage, toTask, toHuman, closeDuplicate, deferred, blockedNode, closeObsolete],
package/src/graphs/pr.mjs CHANGED
@@ -155,7 +155,11 @@ const assess = declare(
155
155
  return hold
156
156
  },
157
157
  }),
158
- { queue: null, running: false },
158
+ {
159
+ queue: null,
160
+ running: false,
161
+ about: 'Reads the PR and decides, in order: merged, close, rework, merge, stall or hold. Writes nothing.',
162
+ },
159
163
  )
160
164
 
161
165
  const merge = declare(
@@ -219,7 +223,11 @@ const merge = declare(
219
223
  return { to: 'done' }
220
224
  },
221
225
  }),
222
- { queue: null, running: false },
226
+ {
227
+ queue: null,
228
+ running: false,
229
+ about: 'Updates a branch that is behind its base; otherwise merges through graft pr merge --auto.',
230
+ },
223
231
  )
224
232
 
225
233
  const ReworkIn = z.object({ ...failure, pr: z.number().int(), failedSha: z.string().nullable() })
@@ -281,7 +289,11 @@ const rework = declare(
281
289
  return { to: 'task' }
282
290
  },
283
291
  }),
284
- { queue: Q.task, running: false },
292
+ {
293
+ queue: Q.task,
294
+ running: false,
295
+ about: 'Back to the task graph in q:task with the PR kept and the reason as lastFailure. Reworks spent: q:human.',
296
+ },
285
297
  )
286
298
 
287
299
  const CloseIn = z.object({ pr: z.number().int(), reason: z.string() })
@@ -317,7 +329,7 @@ const closePr = declare(
317
329
  return {}
318
330
  },
319
331
  }),
320
- { queue: null, running: false },
332
+ { queue: null, running: false, about: 'Closes the PR with the reason. The issue stays where it is.' },
321
333
  )
322
334
 
323
335
  /** Delete a merged PR's branch once per tick. @param {TaskCtx} ctx @param {PullRequest} pr */
@@ -362,7 +374,11 @@ const closeOut = declare(
362
374
  return {}
363
375
  },
364
376
  }),
365
- { queue: null, running: false },
377
+ {
378
+ queue: null,
379
+ running: false,
380
+ about: 'Merged: the issue is closed and leaves every queue, and the branch is deleted.',
381
+ },
366
382
  )
367
383
 
368
384
  const toHuman = declare(
@@ -393,12 +409,13 @@ const toHuman = declare(
393
409
  return {}
394
410
  },
395
411
  }),
396
- { queue: Q.human, running: false },
412
+ { queue: Q.human, running: false, about: 'Into q:human with a why:* reason label.' },
397
413
  )
398
414
 
399
415
  /** The PR graph. Bump `version` when a node is removed or renamed. */
400
416
  export const prGraph = defineGraph({
401
417
  name: 'pr',
418
+ about: 'Takes an agent PR whose CI has settled to merged, reworked, closed or a human.',
402
419
  version: 1,
403
420
  entry: { node: 'assess', input: () => ({}) },
404
421
  nodes: [assess, merge, rework, closePr, closeOut, toHuman],
@@ -31,7 +31,7 @@ import { markerTrace, turnTracer } from '../tracing.mjs'
31
31
  * One repo's turn; `pr` is the promotion PR a `release-promote` turn is about; `traceparent` the turn's trace
32
32
  * while it is traced (tracing.mjs `turnTracer`), which markers written in the turn take when they have none.
33
33
  * @typedef {import('../tick.mjs').Deps & { tick: import('../tick.mjs').Ctx, subject: ReleaseSubject }} ReleaseCtx
34
- * @typedef {{ queue: string | null, enter?: (input: any, ctx: ReleaseCtx) => Promise<void> }} Declared
34
+ * @typedef {{ queue: string | null, about?: string, enter?: (input: any, ctx: ReleaseCtx) => Promise<void> }} Declared
35
35
  * `queue`: the label a PR resting here carries. `enter`: the write that lands a PR on this wait.
36
36
  */
37
37
 
@@ -141,7 +141,7 @@ const cleanup = declare(
141
141
  return { closed }
142
142
  },
143
143
  }),
144
- { queue: null },
144
+ { queue: null, about: 'Closes every open promotion PR older than 24 h, with a comment.' },
145
145
  )
146
146
 
147
147
  const prepare = declare(
@@ -215,12 +215,16 @@ const prepare = declare(
215
215
  },
216
216
  }),
217
217
  // The PR it opens waits in `q:promote`, release-promote's queue.
218
- { queue: Q.promote },
218
+ {
219
+ queue: Q.promote,
220
+ about: 'When from is ahead of to, opens the promotion PR (or refreshes the open one) and labels it q:promote.',
221
+ },
219
222
  )
220
223
 
221
224
  /** Bump `version` when a node is removed or renamed. */
222
225
  export const releasePrepare = defineGraph({
223
226
  name: 'release-prepare',
227
+ about: 'Once a day, opens or refreshes the promotion PR from the integration branch to the release branch.',
224
228
  version: 1,
225
229
  entry: { node: 'cleanup', input: () => ({}) },
226
230
  nodes: [cleanup, prepare],
@@ -269,7 +273,10 @@ const merge = declare(
269
273
  return { to: 'armed', pr: input.pr }
270
274
  },
271
275
  }),
272
- { queue: Q.promote },
276
+ {
277
+ queue: Q.promote,
278
+ about: 'The promotion PR is approved: merges it through graft pr merge --auto. A refused head is not retried.',
279
+ },
273
280
  )
274
281
 
275
282
  const merging = declare(
@@ -287,6 +294,7 @@ const merging = declare(
287
294
  }),
288
295
  {
289
296
  queue: Q.promote,
297
+ about: 'Holds while the promotion PR is open; moves on once it merges or closes unmerged.',
290
298
  /** @param {{ pr: number }} input @param {ReleaseCtx} ctx */
291
299
  enter: async (input, ctx) => {
292
300
  const pr = prOf(ctx)
@@ -324,12 +332,13 @@ const exit = (name, outcome, said) =>
324
332
  return {}
325
333
  },
326
334
  }),
327
- { queue: null },
335
+ { queue: null, about: `The promotion PR ${said}.` },
328
336
  )
329
337
 
330
338
  /** Bump `version` when a node is removed or renamed. */
331
339
  export const releasePromote = defineGraph({
332
340
  name: 'release-promote',
341
+ about: 'Merges an approved q:promote promotion PR and closes it out.',
333
342
  version: 1,
334
343
  entry: { queue: Q.promote, node: 'merge' },
335
344
  nodes: [
@@ -466,12 +466,29 @@ const toHuman = defineNode({
466
466
  },
467
467
  })
468
468
 
469
+ /** A node with its one-line description, which the heartbeat carries (graph/describe.mjs). @template N @param {N} node @param {string} text */
470
+ const about = (node, text) => Object.freeze({ ...node, about: text })
471
+
469
472
  /** The rescue graph. Bump `version` when a node is removed or renamed. */
470
473
  export const rescue = defineGraph({
471
474
  name: 'rescue',
472
475
  version: 1,
476
+ about: 'Diagnoses a stuck item with a one-shot read-only worker, unsticks it and files its root causes in q:intake.',
473
477
  entry: { node: 'start-rescue', input: () => ({}) },
474
- nodes: [startRescue, diagnosing, unstick, fileCauses, report, toHuman],
478
+ nodes: [
479
+ about(
480
+ startRescue,
481
+ 'Starts the rescue worker in a read-only checkout; over the weekly budget, the item goes to a human.',
482
+ ),
483
+ about(diagnosing, 'Holds while the worker diagnoses the item; on exit, checks its verdict against the item.'),
484
+ about(unstick, "Carries out the verdict's actions, in order."),
485
+ about(
486
+ fileCauses,
487
+ 'Files each root cause as a q:intake ticket labelled rescue, or notes a recurrence on the open one.',
488
+ ),
489
+ about(report, 'Comments on the item: what was seen, how it got stuck, what was done, the root causes.'),
490
+ about(toHuman, 'Into q:human with why:rescue and what cambium saw.'),
491
+ ],
475
492
  edges: [
476
493
  ['start-rescue', 'diagnosing', started, (o) => ({ attempt: o.attempt })],
477
494
  ['start-rescue', 'to-human', budgetSpent],
@@ -39,7 +39,7 @@ import { stopOverdue } from '../workers.mjs'
39
39
  * `traceparent`: the running step node's span, when advance is instrumented (tracing.mjs).
40
40
  * @typedef {{ node: string, input: unknown }} Position
41
41
  * @typedef {{
42
- * queue: string | null, running: boolean, pollOnEntry?: boolean,
42
+ * queue: string | null, running: boolean, about?: string, pollOnEntry?: boolean,
43
43
  * enter?: (input: any, ctx: TaskCtx) => Promise<void>,
44
44
  * recover?: (ctx: TaskCtx) => Position,
45
45
  * }} Declared
@@ -240,7 +240,11 @@ const startWorker = declare(
240
240
  return { to: 'running', pid: s.pid, branch, worktree: s.worktree, attempt: marker.attempt }
241
241
  },
242
242
  }),
243
- { queue: Q.task, running: false },
243
+ {
244
+ queue: Q.task,
245
+ running: false,
246
+ about: 'Claims the issue and starts a Claude worker on its branch; out of attempts, it goes to a human.',
247
+ },
244
248
  )
245
249
 
246
250
  const workerRunning = declare(
@@ -303,6 +307,7 @@ const workerRunning = declare(
303
307
  }),
304
308
  {
305
309
  queue: Q.task,
310
+ about: 'Holds while the worker runs under its wall-clock cap; on exit, looks for the PR it published.',
306
311
  running: true,
307
312
  recover: (ctx) => ({ node: 'requeue', input: lostLeaseOf(ctx) }),
308
313
  },
@@ -350,7 +355,11 @@ const submit = declare(
350
355
  return {}
351
356
  },
352
357
  }),
353
- { queue: null, running: false },
358
+ {
359
+ queue: null,
360
+ running: false,
361
+ about: 'The worker published its PR: the issue leaves every queue and the PR graph takes over.',
362
+ },
354
363
  )
355
364
 
356
365
  const requeue = declare(
@@ -397,7 +406,12 @@ const requeue = declare(
397
406
  return { to: 'start', attempt: next }
398
407
  },
399
408
  }),
400
- { queue: Q.task, running: false },
409
+ {
410
+ queue: Q.task,
411
+ running: false,
412
+ about:
413
+ 'Back to q:task with attempt + 1, or to a human once the attempts are spent. Not charged while the base is red.',
414
+ },
401
415
  )
402
416
 
403
417
  const HumanIn = z.object({ ...failure, why: z.string().optional() })
@@ -428,7 +442,7 @@ const toHuman = declare(
428
442
  return {}
429
443
  },
430
444
  }),
431
- { queue: Q.human, running: false },
445
+ { queue: Q.human, running: false, about: 'Into q:human with a why:* reason label.' },
432
446
  )
433
447
 
434
448
  /**
@@ -438,6 +452,7 @@ const toHuman = declare(
438
452
  */
439
453
  export const task = defineGraph({
440
454
  name: 'task',
455
+ about: 'Turns a q:task issue into a published PR; a failed attempt is retried until the budget is spent.',
441
456
  version: 2,
442
457
  entry: { queue: Q.task, node: 'start-worker', input: () => ({}) },
443
458
  nodes: [startWorker, workerRunning, submit, requeue, toHuman],
package/src/tick.mjs CHANGED
@@ -9,7 +9,8 @@
9
9
  import { byPriorityThenAge, move, Q, queueOf, RUNNING, WHY } from './labels.mjs'
10
10
  import { withHistory } from './marker.mjs'
11
11
  import { failureSummary, iso, key, markerOf, MIN, setLabels, setMarker } from './issue-state.mjs'
12
- import { GRAPH_ENGINE } from './graph-engine.mjs'
12
+ import { GRAPH_ENGINE, GRAPHS } from './graph-engine.mjs'
13
+ import { describeGraph } from './graph/describe.mjs'
13
14
  import { linkIssue, prFor, taskExit, taskPrompt } from './phases/task.mjs'
14
15
  import { branchName } from './convention.mjs'
15
16
  import { PREPARE_FAILED_LINE } from './prepare.mjs'
@@ -653,6 +654,8 @@ async function release(deps, ctx) {
653
654
  * logs: { stdout: string, stderr: string },
654
655
  * }[],
655
656
  * events: Event[],
657
+ * engine: 'legacy' | 'graph',
658
+ * graphs: import('./graph/describe.mjs').GraphDescription[],
656
659
  * }} HeartbeatState
657
660
  */
658
661
 
@@ -676,6 +679,14 @@ function countsOf(snap) {
676
679
  return c
677
680
  }
678
681
 
682
+ /** @type {import('./graph/describe.mjs').GraphDescription[] | undefined} */
683
+ let described
684
+ /** Every graph cambium defines, as plain JSON; built once, on first use (graph-engine.mjs imports this file). */
685
+ const graphDescriptions = () => {
686
+ described ??= Object.values(GRAPHS).map(describeGraph)
687
+ return described
688
+ }
689
+
679
690
  /** @param {Deps} deps @param {Ctx} ctx @returns {HeartbeatState} */
680
691
  export function heartbeatState(deps, ctx) {
681
692
  const { config } = deps
@@ -730,5 +741,7 @@ export function heartbeatState(deps, ctx) {
730
741
  repos,
731
742
  workers,
732
743
  events: deps.events?.() ?? [],
744
+ engine: config.engine,
745
+ graphs: graphDescriptions(),
733
746
  }
734
747
  }