@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 +23 -0
- package/package.json +1 -1
- package/src/briefs.mjs +265 -0
- package/src/daemon.mjs +1 -0
- package/src/graph/define.mjs +11 -3
- package/src/graph/describe.mjs +50 -0
- package/src/graph/index.mjs +2 -1
- package/src/graphs/dispatch.mjs +33 -10
- package/src/graphs/pr.mjs +23 -6
- package/src/graphs/release.mjs +14 -5
- package/src/graphs/rescue.mjs +18 -1
- package/src/graphs/task.mjs +20 -5
- package/src/tick.mjs +31 -1
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.
|
|
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),
|
package/src/graph/define.mjs
CHANGED
|
@@ -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({
|
|
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
|
+
}
|
package/src/graph/index.mjs
CHANGED
|
@@ -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'
|
package/src/graphs/dispatch.mjs
CHANGED
|
@@ -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
|
-
{
|
|
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
|
-
{
|
|
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
|
-
{
|
|
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
|
-
{
|
|
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
|
-
{
|
|
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
|
-
{
|
|
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
|
-
{
|
|
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
|
-
{
|
|
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
|
-
{
|
|
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],
|
package/src/graphs/release.mjs
CHANGED
|
@@ -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
|
-
{
|
|
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
|
-
{
|
|
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: [
|
package/src/graphs/rescue.mjs
CHANGED
|
@@ -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: [
|
|
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],
|
package/src/graphs/task.mjs
CHANGED
|
@@ -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
|
-
{
|
|
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
|
-
{
|
|
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
|
-
{
|
|
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
|
+
}
|