@oakgreencc/cambium 0.0.40 → 0.0.42

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
@@ -94,6 +94,12 @@ A worker is `claude -p --output-format stream-json --verbose --thinking-display
94
94
 
95
95
  The prompt states the four-point contract (task issue, `pnpm verify`, `graft publish <branch> … --closes <n>`, `graft ci wait`), the attempt, the existing PR if any (`graft advance` onto it), the last failure, the issue's history, the issue body, and the worktree's `AGENTS.md`.
96
96
 
97
+ ## Session briefs
98
+
99
+ A `q:human` item worth an interactive session gets a brief at `<paths.home>/briefs/<owner>__<name>/issue-<n>.md` (src/briefs.mjs). One function, `isSessionCandidate`, decides who: today an open issue with `q:human` and `why:budget`. Every tick (paused too; nothing goes to GitHub) cambium renders each candidate's brief from the snapshot and rewrites the file when the text changed, so it follows the issue into `q:human` and every marker change; any other `issue-<n>.md` in a read repo's directory is deleted (the issue left `q:human`, or closed). A repo whose read failed is left alone.
100
+
101
+ A brief holds the title, link, body (first 4,000 characters) and acceptance checks (triage's, else the body's checkboxes); graph, node, attempts, reworks, `failedSha`, `lastFailure` and the marker history; the issue's agent PRs, plus any the history names; the reasons in the history, as approaches already rejected; the question, options and recommendation when the marker has an `ask`; and the repo path with the verify and publish contract. Token-shaped text (provider tokens, bearer auth, URL credentials, the value of any `*TOKEN*`/`*SECRET*`/`*PASSWORD*`/`*KEY*` assignment) becomes `[redacted]`. Files are written `0600`. canopy shows `cd <repo> && claude "$(cat <brief>)"` for each item with a brief.
102
+
97
103
  ## Configuration
98
104
 
99
105
  One JSON file. Everything but `repos` is optional; these are the defaults:
@@ -286,10 +292,26 @@ Written at the end of every tick to `paths.heartbeat` (default `~/.cambium/state
286
292
  "repo": "oakgreencc/monorepo",
287
293
  "issue": 12
288
294
  } // level: "info" | "warn" | "error"; repo/issue optional
295
+ ],
296
+ "engine": "graph", // config.engine: "legacy" | "graph"
297
+ "graphs": [
298
+ // every graph this cambium defines, as describeGraph() writes it (see The graph module); the same every tick
299
+ {
300
+ "name": "task",
301
+ "version": 2,
302
+ "about": "Turns a q:task issue into a published PR; …",
303
+ "entry": { "queue": "q:task", "node": "start-worker" },
304
+ "nodes": [
305
+ { "name": "worker-running", "kind": "wait", "queue": "q:task", "running": true, "about": "Holds while …" }
306
+ ],
307
+ "edges": [{ "from": "start-worker", "to": "worker-running", "when": "started" }] // to: null ends the graph
308
+ }
289
309
  ]
290
310
  }
291
311
  ```
292
312
 
313
+ `engine` and `graphs` were added within `version: 1`; a reader of an older heartbeat finds neither.
314
+
293
315
  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
316
 
295
317
  ## The task graph
@@ -623,6 +645,7 @@ const { transitions, reason, node, input } = await advance(g, { node: 'open-pr',
623
645
  - **`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
646
  - **`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
647
  - **`toMermaid(graph)`** renders a flowchart: boxes for steps, hexagons for waits, conditional edges labelled with `when`'s function name.
648
+ - **`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
649
  - **`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
650
 
628
651
  ### 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.42",
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",
package/src/briefs.mjs ADDED
@@ -0,0 +1,265 @@
1
+ // @ts-check
2
+ /**
3
+ * Session briefs: for a `q:human` item worth an interactive session, a Markdown file that seeds a fresh
4
+ * `claude` session with what cambium knows (the issue, its marker history, the last failure, its PRs, what earlier
5
+ * attempts tried) so a human does not rebuild that by hand.
6
+ *
7
+ * Written to `<home>/briefs/<owner>__<repo>/issue-<n>.md`. Every tick {@link syncBriefs} renders each candidate's
8
+ * brief and rewrites the file only when the text changed (so it is regenerated when the issue enters `q:human` or
9
+ * its marker changes), and deletes every other brief in a repo's directory (the issue left `q:human` or closed).
10
+ * A repo whose snapshot failed this tick is left alone. Briefs are local files: they never go to GitHub.
11
+ *
12
+ * {@link redact} runs over the whole brief: nothing token-shaped leaves cambium's memory in one.
13
+ */
14
+ import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
15
+ import { join } from 'node:path'
16
+ import { Q, WHY } from './labels.mjs'
17
+ import { branchIssue } from './github.mjs'
18
+
19
+ /**
20
+ * @typedef {import('./github.mjs').Issue} Issue
21
+ * @typedef {import('./github.mjs').PullRequest} PullRequest
22
+ * @typedef {{ question?: string, options?: string[], recommendation?: string }} Ask
23
+ * What a typed escalation asks the human; read from the marker's `ask` when it has one.
24
+ * @typedef {{
25
+ * read(path: string): string | null, write(path: string, text: string): void, remove(path: string): void,
26
+ * list(dir: string): string[],
27
+ * }} BriefFs
28
+ * `read`: null when the file does not exist. `list`: the file names in `dir`, [] when it does not exist.
29
+ */
30
+
31
+ const BODY_KEPT = 4000
32
+
33
+ /**
34
+ * Whether an issue gets a brief: in `q:human` for a reason worth an interactive session. The one place that
35
+ * decides; today `why:budget` (attempts or reworks spent).
36
+ * @param {{ labels: string[] }} issue
37
+ */
38
+ export const isSessionCandidate = (issue) => issue.labels.includes(Q.human) && issue.labels.includes(WHY.budget)
39
+
40
+ /** `owner/name` → the brief directory's name. @param {string} slug */
41
+ export const repoDir = (slug) => slug.replace('/', '__')
42
+
43
+ /** @param {string} dir the briefs root @param {string} slug @param {number} n */
44
+ export const briefPath = (dir, slug, n) => join(dir, repoDir(slug), `issue-${n}.md`)
45
+
46
+ /**
47
+ * Token-shaped text, replaced by `[redacted]`: provider tokens by their prefixes, bearer/basic auth, credentials in
48
+ * URLs, and the value of any `NAME=value` / `name: value` whose name says it is a secret.
49
+ */
50
+ const SECRET_PATTERNS = [
51
+ /\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})/g,
52
+ /\bsk-(?:ant-)?[A-Za-z0-9_-]{16,}/g,
53
+ /\bxox[abposr]-[A-Za-z0-9-]{10,}/g,
54
+ /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g,
55
+ /\bAIza[A-Za-z0-9_-]{30,}/g,
56
+ /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g,
57
+ /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(?:-----END [A-Z ]*PRIVATE KEY-----|$)/g,
58
+ ]
59
+ const AUTH_HEADER = /\b(Bearer|Basic|token)\s+[A-Za-z0-9._~+/=-]{12,}/gi
60
+ const URL_CREDENTIALS = /(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/:@]+:[^\s/@]+@/gi
61
+ const SECRET_ASSIGNMENT =
62
+ /\b([A-Za-z0-9_.-]*(?:TOKEN|SECRET|PASSWORD|PASSWD|API_?KEY|ACCESS_?KEY|PRIVATE_?KEY|CREDENTIALS?)[A-Za-z0-9_.-]*)(["']?\s*[:=]\s*["']?)([^\s"'`,;]+)/gi
63
+
64
+ /** @param {string} text */
65
+ export function redact(text) {
66
+ let out = text
67
+ for (const re of SECRET_PATTERNS) out = out.replace(re, '[redacted]')
68
+ return out
69
+ .replace(AUTH_HEADER, '$1 [redacted]')
70
+ .replace(URL_CREDENTIALS, '$1[redacted]@')
71
+ .replace(SECRET_ASSIGNMENT, (all, name, sep, value) => (value === '[redacted]' ? all : `${name}${sep}[redacted]`))
72
+ }
73
+
74
+ /** Acceptance checks: triage's, else the issue body's checkboxes. @param {Issue} issue @param {any} marker */
75
+ function acceptanceOf(issue, marker) {
76
+ const fromTriage = marker.triage?.acceptance ?? []
77
+ if (fromTriage.length) return fromTriage.map((/** @type {string} */ a) => String(a))
78
+ return [...(issue.body ?? '').matchAll(/^\s*[-*] \[[ xX]\] (.+)$/gm)].map((m) => m[1].trim())
79
+ }
80
+
81
+ /** The body, cut at {@link BODY_KEPT} characters. @param {string} body */
82
+ function bodySummary(body) {
83
+ const b = (body ?? '').trim()
84
+ if (!b) return '_No description._'
85
+ return b.length > BODY_KEPT
86
+ ? `${b.slice(0, BODY_KEPT)}\n\n_(cut at ${BODY_KEPT} characters; read the rest on GitHub)_`
87
+ : b
88
+ }
89
+
90
+ /** One line for a Markdown list. @param {string} s */
91
+ const oneLine = (s) => s.replace(/\s*\n\s*/g, ' ').trim()
92
+
93
+ /** @param {string} s */
94
+ const fence = (s) => ['```', s.replace(/```/g, "'''"), '```']
95
+
96
+ /** @param {unknown} v @returns {Ask | null} */
97
+ function askOf(v) {
98
+ if (!v || typeof v !== 'object') return null
99
+ const a = /** @type {Record<string, unknown>} */ (v)
100
+ const ask = {
101
+ ...(typeof a.question === 'string' && a.question ? { question: a.question } : {}),
102
+ ...(Array.isArray(a.options) && a.options.length ? { options: a.options.map(String) } : {}),
103
+ ...(typeof a.recommendation === 'string' && a.recommendation ? { recommendation: a.recommendation } : {}),
104
+ }
105
+ return Object.keys(ask).length ? ask : null
106
+ }
107
+
108
+ /**
109
+ * The brief's text. Pure: everything comes from the snapshot and config; no time of writing, so an unchanged issue
110
+ * renders the same text and is not rewritten.
111
+ *
112
+ * @param {{ slug: string, repoPath: string, issue: Issue, prs: PullRequest[], maxAttempts: number, maxReworks: number }} input
113
+ * @returns {string}
114
+ */
115
+ export function renderBrief({ slug, repoPath, issue, prs, maxAttempts, maxReworks }) {
116
+ const marker = /** @type {any} */ (issue.stateComment?.marker ?? {})
117
+ const history = /** @type {import('./marker.mjs').HistoryEntry[]} */ (marker.history ?? [])
118
+ const why = issue.labels.filter((l) => l.startsWith('why:')).join(', ') || 'none'
119
+ const mine = prs
120
+ .filter((p) => p.closes.includes(issue.number) || branchIssue(p.branch) === issue.number)
121
+ .sort((a, b) => a.number - b.number)
122
+ const seen = new Set(mine.map((p) => p.number))
123
+ const earlier = [...new Set(history.map((h) => h.pr).filter((n) => typeof n === 'number' && !seen.has(n)))]
124
+ const branch = mine.find((p) => p.state === 'OPEN')?.branch ?? marker.branch ?? `agent/${issue.number}-<topic>`
125
+ const acceptance = acceptanceOf(issue, marker)
126
+ const ask = askOf(marker.ask)
127
+ const rejected = history.filter((h) => h.reason)
128
+
129
+ const out = [
130
+ `# Session brief: ${slug}#${issue.number}: ${issue.title}`,
131
+ '',
132
+ `You are picking up ${issue.url} with a human in an interactive session. cambium, the scheduler, could not`,
133
+ `finish it on its own and moved it to the Human Queue (q:human, ${why}). Below is what cambium knows.`,
134
+ 'Start by saying what you think went wrong and what you would try differently; do not repeat a rejected approach.',
135
+ '',
136
+ '## Issue',
137
+ '',
138
+ `- Link: ${issue.url}`,
139
+ `- Labels: ${issue.labels.join(', ') || 'none'}`,
140
+ ...(marker.triage?.title ? [`- Task (from triage): ${oneLine(String(marker.triage.title))}`] : []),
141
+ '',
142
+ bodySummary(issue.body),
143
+ '',
144
+ '## Acceptance checks',
145
+ '',
146
+ ...(acceptance.length ? acceptance.map((a) => `- [ ] ${oneLine(a)}`) : ['None written down.']),
147
+ ]
148
+ if (ask) {
149
+ out.push('', '## The question')
150
+ if (ask.question) out.push('', ask.question)
151
+ if (ask.options) out.push('', 'Options:', '', ...ask.options.map((o, i) => `${i + 1}. ${oneLine(o)}`))
152
+ if (ask.recommendation) out.push('', `Recommendation: ${ask.recommendation}`)
153
+ }
154
+ out.push(
155
+ '',
156
+ '## Where cambium left it',
157
+ '',
158
+ `- Graph: ${marker.graph ?? 'task'} · node ${marker.node ?? 'unknown'}`,
159
+ `- Attempts: ${marker.attempt ?? 1} of ${maxAttempts}`,
160
+ `- Reworks: ${marker.reworks ?? 0} of ${maxReworks}`,
161
+ `- Failed SHA: ${marker.failedSha ?? 'none'}`,
162
+ )
163
+ if (marker.lastFailure) out.push('', 'Last failure:', '', ...fence(String(marker.lastFailure)))
164
+ out.push('', '## Pull requests', '')
165
+ if (!mine.length && !earlier.length) out.push('None.')
166
+ for (const p of mine)
167
+ out.push(
168
+ `- #${p.number} ${p.state.toLowerCase()} on \`${p.branch}\`${p.headSha ? ` at ${p.headSha.slice(0, 7)}` : ''}` +
169
+ `${p.checks ? ` · checks ${p.checks.toLowerCase()}` : ''} · ${p.url}`,
170
+ )
171
+ for (const n of earlier) out.push(`- #${n} (named in the history; closed or no longer read)`)
172
+ out.push('', '## Approaches already rejected', '')
173
+ if (!rejected.length) out.push('None recorded.')
174
+ for (const h of rejected)
175
+ out.push(
176
+ `- Attempt ${h.attempt}${h.node ? ` at ${h.node}` : ''} (${h.outcome})${h.pr ? `, PR #${h.pr}` : ''}: ${oneLine(String(h.reason))}`,
177
+ )
178
+ out.push('', '## Marker history', '')
179
+ if (!history.length) out.push('Empty.')
180
+ for (const h of history)
181
+ out.push(`- ${[h.at, h.node, `attempt ${h.attempt}`, h.outcome].filter(Boolean).join(' · ')}`)
182
+ out.push(
183
+ '',
184
+ '## Repository and contract',
185
+ '',
186
+ `- Repo: ${slug}, checked out at ${repoPath}`,
187
+ `- Work in a worktree under \`.claude/worktrees/\`, on the branch \`${branch}\`.`,
188
+ '- Verify: `pnpm verify` (lint + tests). Green means committable.',
189
+ `- Publish: \`graft publish ${branch} "<conventional commit message>" --paths <a,b> --pr "<title>" --closes ${issue.number}\`.`,
190
+ ' Never `git commit`, `git push`, `git fetch` or `git pull`.',
191
+ `- Done: \`graft ci wait ${branch}\`. Red: \`graft jobs <run>\`, fix, publish again.`,
192
+ "- Labels are cambium's: once the PR is up, a human moves the issue out of q:human (or cambium picks up the green PR).",
193
+ '',
194
+ )
195
+ return redact(out.join('\n'))
196
+ }
197
+
198
+ /** @type {BriefFs} */
199
+ export const realBriefFs = {
200
+ read(path) {
201
+ try {
202
+ return readFileSync(path, 'utf8')
203
+ } catch {
204
+ return null
205
+ }
206
+ },
207
+ write(path, text) {
208
+ mkdirSync(join(path, '..'), { recursive: true })
209
+ writeFileSync(path, text, { mode: 0o600 })
210
+ },
211
+ remove: (path) => rmSync(path, { force: true }),
212
+ list(dir) {
213
+ try {
214
+ return readdirSync(dir)
215
+ } catch {
216
+ return []
217
+ }
218
+ },
219
+ }
220
+
221
+ /**
222
+ * Bring the briefs directory in line with the snapshots: write (or rewrite, when the text changed) each candidate's
223
+ * brief; delete any other `issue-<n>.md` in a read repo's directory.
224
+ *
225
+ * @param {{
226
+ * dir: string, fs?: BriefFs, config: import('./config.mjs').Config,
227
+ * snaps: Map<string, import('./github.mjs').Snapshot>,
228
+ * }} input
229
+ * @returns {{ written: string[], removed: string[] }} paths
230
+ */
231
+ export function syncBriefs({ dir, fs = realBriefFs, config, snaps }) {
232
+ /** @type {string[]} */
233
+ const written = []
234
+ /** @type {string[]} */
235
+ const removed = []
236
+ for (const repo of config.repos) {
237
+ const snap = snaps.get(repo.slug)
238
+ if (!snap) continue
239
+ const keep = new Set()
240
+ for (const issue of snap.issues.values()) {
241
+ if (issue.state !== 'OPEN' || !isSessionCandidate(issue)) continue
242
+ const path = briefPath(dir, repo.slug, issue.number)
243
+ keep.add(path)
244
+ const text = renderBrief({
245
+ slug: repo.slug,
246
+ repoPath: repo.path,
247
+ issue,
248
+ prs: snap.prs,
249
+ maxAttempts: config.phases.task.maxAttempts,
250
+ maxReworks: config.phases.task.maxReworks,
251
+ })
252
+ if (fs.read(path) === text) continue
253
+ fs.write(path, text)
254
+ written.push(path)
255
+ }
256
+ const repoBriefs = join(dir, repoDir(repo.slug))
257
+ for (const name of fs.list(repoBriefs)) {
258
+ const path = join(repoBriefs, name)
259
+ if (!/^issue-\d+\.md$/.test(name) || keep.has(path)) continue
260
+ fs.remove(path)
261
+ removed.push(path)
262
+ }
263
+ }
264
+ return { written, removed }
265
+ }
package/src/daemon.mjs CHANGED
@@ -79,6 +79,7 @@ export function realDeps(config, { echo } = {}) {
79
79
  spawner,
80
80
  procs: realProcs,
81
81
  gc: gcRunner({ config, store, spawner, procs: realProcs, now: Date.now }, log),
82
+ briefs: { dir: join(config.paths.home, 'briefs') },
82
83
  log,
83
84
  events,
84
85
  heartbeat: (state) => writeHeartbeat(config.paths.heartbeat, state),
@@ -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'
@@ -18,6 +19,7 @@ import { releaseGraphs } from './graphs/release.mjs'
18
19
  import { DISPATCH_NOT_BUILT, dispatchNotBuilt } from './phases/dispatch.mjs'
19
20
  import { isRepair } from './base-health.mjs'
20
21
  import { stopOverdue } from './workers.mjs'
22
+ import { syncBriefs } from './briefs.mjs'
21
23
 
22
24
  /**
23
25
  * @typedef {import('./github.mjs').Issue} Issue
@@ -40,6 +42,7 @@ import { stopOverdue } from './workers.mjs'
40
42
  * telemetry?: import('./tracing.mjs').Telemetry,
41
43
  * updater?: import('./update.mjs').Updater,
42
44
  * gc?: () => Promise<unknown>,
45
+ * briefs?: { dir: string, fs?: import('./briefs.mjs').BriefFs },
43
46
  * daemonStartedAt?: number,
44
47
  * pid?: number,
45
48
  * }} Deps
@@ -97,6 +100,7 @@ export async function tick(deps) {
97
100
  ...(paused ? [] : /** @type {[string, any][]} */ ([['release', release]])),
98
101
  ...(paused || !engine.upkeep ? [] : /** @type {[string, StepFn][]} */ ([['upkeep', engine.upkeep]])),
99
102
  ...(paused || !deps.gc ? [] : /** @type {[string, StepFn][]} */ ([['gc', gc]])),
103
+ ...(deps.briefs ? /** @type {[string, StepFn][]} */ ([['briefs', briefs]]) : []),
100
104
  ]
101
105
  for (const [name, fn] of steps) await runStep(deps, ctx, name, () => fn(deps, ctx))
102
106
  const state = heartbeatState(deps, ctx)
@@ -653,6 +657,8 @@ async function release(deps, ctx) {
653
657
  * logs: { stdout: string, stderr: string },
654
658
  * }[],
655
659
  * events: Event[],
660
+ * engine: 'legacy' | 'graph',
661
+ * graphs: import('./graph/describe.mjs').GraphDescription[],
656
662
  * }} HeartbeatState
657
663
  */
658
664
 
@@ -676,6 +682,14 @@ function countsOf(snap) {
676
682
  return c
677
683
  }
678
684
 
685
+ /** @type {import('./graph/describe.mjs').GraphDescription[] | undefined} */
686
+ let described
687
+ /** Every graph cambium defines, as plain JSON; built once, on first use (graph-engine.mjs imports this file). */
688
+ const graphDescriptions = () => {
689
+ described ??= Object.values(GRAPHS).map(describeGraph)
690
+ return described
691
+ }
692
+
679
693
  /** @param {Deps} deps @param {Ctx} ctx @returns {HeartbeatState} */
680
694
  export function heartbeatState(deps, ctx) {
681
695
  const { config } = deps
@@ -730,5 +744,21 @@ export function heartbeatState(deps, ctx) {
730
744
  repos,
731
745
  workers,
732
746
  events: deps.events?.() ?? [],
747
+ engine: config.engine,
748
+ graphs: graphDescriptions(),
733
749
  }
734
750
  }
751
+
752
+ // ---- Briefs
753
+
754
+ /**
755
+ * Session briefs (briefs.mjs) for the `q:human` items worth an interactive session, from this tick's snapshots.
756
+ * Local files only; runs while paused too, since it changes nothing on GitHub.
757
+ * @param {Deps} deps @param {Ctx} ctx
758
+ */
759
+ async function briefs(deps, ctx) {
760
+ if (!deps.briefs) return
761
+ const { written, removed } = syncBriefs({ ...deps.briefs, config: deps.config, snaps: ctx.snaps })
762
+ for (const p of written) deps.log('info', `session brief written: ${p}`)
763
+ for (const p of removed) deps.log('info', `session brief removed: ${p}`)
764
+ }