@oakgreencc/cambium 0.0.41 → 0.0.43
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 +8 -2
- package/package.json +1 -1
- package/src/briefs.mjs +265 -0
- package/src/config.mjs +4 -2
- package/src/daemon.mjs +1 -0
- package/src/github.mjs +4 -3
- package/src/graphs/dispatch.mjs +9 -1
- package/src/marker.mjs +3 -0
- package/src/phases/dispatch.mjs +1 -0
- package/src/tick.mjs +17 -0
- package/src/triage-inputs.mjs +87 -0
- package/src/upkeep.mjs +13 -6
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:
|
|
@@ -123,7 +129,7 @@ One JSON file. Everything but `repos` is optional; these are the defaults:
|
|
|
123
129
|
"priorityLabels": ["priority:critical", "priority:high", "priority:medium", "priority:low"],
|
|
124
130
|
"release": { "enabled": false, "time": "06:00" },
|
|
125
131
|
"reaper": { "everyMinutes": 60, "staleMinutes": 30, "orphanDays": 3 },
|
|
126
|
-
"retriage": { "enabled": false, "time": "05:00" },
|
|
132
|
+
"retriage": { "enabled": false, "time": "05:00", "maxSkipDays": 14 },
|
|
127
133
|
"rescue": {
|
|
128
134
|
"everyMinutes": 60,
|
|
129
135
|
"staleHours": 12,
|
|
@@ -199,7 +205,7 @@ Two clocks in the graph engine's `upkeep` step, after Watch (`src/upkeep.mjs`),
|
|
|
199
205
|
| No issue (none named, or not readable) | Close the PR after `reaper.orphanDays` (default 3) untouched. The branch stays. |
|
|
200
206
|
| A live worker on the issue, or the issue already tracks this PR | Leave it. |
|
|
201
207
|
|
|
202
|
-
**Re-triage** (once a day at `retriage.time` when `retriage.enabled`; off by default). Every `q:human` issue goes back to `q:intake` without its `why:*`, so [triage](#the-dispatch-graph) looks again under its current rubric: done since (obsolete, closed), now checkable (defer), or now a task. Not `why:approve`, a merge only a human may make, where a re-triage would start a duplicate Task. Not one holding `running`. The reaper runs first, so an issue whose PR it adopted is not re-triaged.
|
|
208
|
+
**Re-triage** (once a day at `retriage.time` when `retriage.enabled`; off by default). Every `q:human` issue goes back to `q:intake` without its `why:*`, so [triage](#the-dispatch-graph) looks again under its current rubric: done since (obsolete, closed), now checkable (defer), or now a task. Not `why:approve`, a merge only a human may make, where a re-triage would start a duplicate Task. Not one holding `running`. Not one whose _triage inputs_ are unchanged: `start-triage` records on the marker a `fingerprint` (`{ hash, at }`, `src/triage-inputs.mjs`) of the title and body, the labels other than `q:*` / `why:*` / `wait:*` / `running`, the ids of human comments (as for [human replies](#the-dispatch-graph)), the GitHub "blocked by" issues and their states, the agent PRs naming the issue and their states, and `TRIAGE_RUBRIC`; `to-human` keeps it only for a needs-human verdict. A matching fingerprint younger than `retriage.maxSkipDays` (default 14; `0` never skips) leaves the issue in `q:human` with no worker and no label moves. A marker without one (another route to `q:human`, or written before fingerprints) is re-triaged and gains one. Bump `TRIAGE_RUBRIC` with any change to how triage judges an issue, so everything is looked at again. The log line reads `re-triage: k of n changed; m back to q:intake, s unchanged skipped`. Deferred rechecks are not gated: a defer waits on something outside the issue (a CD run, a release), which the fingerprint cannot see. The reaper runs first, so an issue whose PR it adopted is not re-triaged.
|
|
203
209
|
|
|
204
210
|
## Worktree GC
|
|
205
211
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oakgreencc/cambium",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.43",
|
|
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/config.mjs
CHANGED
|
@@ -41,7 +41,7 @@ import { join, resolve } from 'node:path'
|
|
|
41
41
|
* priorityLabels: string[],
|
|
42
42
|
* release: { enabled: boolean, time: string },
|
|
43
43
|
* reaper: { everyMinutes: number, staleMinutes: number, orphanDays: number },
|
|
44
|
-
* retriage: { enabled: boolean, time: string },
|
|
44
|
+
* retriage: { enabled: boolean, time: string, maxSkipDays: number },
|
|
45
45
|
* rescue: RescueConfig,
|
|
46
46
|
* paths: { home: string, db: string, heartbeat: string, logs: string },
|
|
47
47
|
* logs: { keepPerIssue: number, daemonMaxBytes: number },
|
|
@@ -96,7 +96,7 @@ export function defaults(home = DEFAULT_HOME) {
|
|
|
96
96
|
priorityLabels: ['priority:critical', 'priority:high', 'priority:medium', 'priority:low'],
|
|
97
97
|
release: { enabled: false, time: '06:00' },
|
|
98
98
|
reaper: { everyMinutes: 60, staleMinutes: 30, orphanDays: 3 },
|
|
99
|
-
retriage: { enabled: false, time: '05:00' },
|
|
99
|
+
retriage: { enabled: false, time: '05:00', maxSkipDays: 14 },
|
|
100
100
|
rescue: { everyMinutes: 60, staleHours: 12, graceMinutes: 30, cooldownHours: 24, maxRescues: 2, causeRepo: null },
|
|
101
101
|
paths: {
|
|
102
102
|
home,
|
|
@@ -140,6 +140,8 @@ export function resolveConfig(raw = {}) {
|
|
|
140
140
|
for (const k of /** @type {const} */ (['home', 'db', 'heartbeat', 'logs'])) config.paths[k] = untilde(config.paths[k])
|
|
141
141
|
if (!/^\d{2}:\d{2}$/.test(config.release.time)) throw new Error(`config: release.time must be HH:MM`)
|
|
142
142
|
if (!/^\d{2}:\d{2}$/.test(config.retriage.time)) throw new Error(`config: retriage.time must be HH:MM`)
|
|
143
|
+
if (typeof config.retriage.maxSkipDays !== 'number' || !(config.retriage.maxSkipDays >= 0))
|
|
144
|
+
throw new Error(`config: retriage.maxSkipDays must be a number of days ≥ 0`)
|
|
143
145
|
config.repos = (config.repos ?? []).map((r) => {
|
|
144
146
|
if (!r?.slug || !/^[^/\s]+\/[^/\s]+$/.test(r.slug))
|
|
145
147
|
throw new Error(`config: repo slug must be owner/name, got ${r?.slug}`)
|
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/github.mjs
CHANGED
|
@@ -18,8 +18,8 @@ import { BASE_FIELDS, baseHealthOf } from './base-health.mjs'
|
|
|
18
18
|
* }} Issue
|
|
19
19
|
* `stateComment.author`: the login that wrote the state comment (cambium's). `comments`: the newest 20, oldest
|
|
20
20
|
* first, for human-reply detection (human-reply.mjs).
|
|
21
|
-
* @typedef {{ author: string | null, bot: boolean, createdAt: string, body: string }} Comment
|
|
22
|
-
* `bot`: GitHub says the author is a `Bot` (an App).
|
|
21
|
+
* @typedef {{ id?: number, author: string | null, bot: boolean, createdAt: string, body: string }} Comment
|
|
22
|
+
* `bot`: GitHub says the author is a `Bot` (an App). `id`: GitHub's database id (triage-inputs.mjs).
|
|
23
23
|
* @typedef {{ number: number, state: 'OPEN' | 'CLOSED', closedAt: string | null }} Blocker
|
|
24
24
|
* An issue GitHub records as blocking this one (the "blocked by" relationship).
|
|
25
25
|
* @typedef {{ name: string, url: string | null, summary: string }} FailingCheck
|
|
@@ -117,7 +117,7 @@ fragment I on Issue {
|
|
|
117
117
|
labels(first: 30) { nodes { name } }
|
|
118
118
|
blockedBy(first: 20) { nodes { number state closedAt } }
|
|
119
119
|
comments(first: 100) { nodes { databaseId body author { login } } }
|
|
120
|
-
recent: comments(last: 20) { nodes { createdAt body author { login __typename } } }
|
|
120
|
+
recent: comments(last: 20) { nodes { databaseId createdAt body author { login __typename } } }
|
|
121
121
|
}
|
|
122
122
|
fragment P on PullRequest {
|
|
123
123
|
number url title state createdAt headRefName baseRefName headRefOid reviewDecision
|
|
@@ -251,6 +251,7 @@ function toIssue(n, botLogin) {
|
|
|
251
251
|
closedAt: b.closedAt ?? null,
|
|
252
252
|
})),
|
|
253
253
|
comments: (n.recent?.nodes ?? []).filter(Boolean).map((/** @type {any} */ c) => ({
|
|
254
|
+
...(c.databaseId ? { id: c.databaseId } : {}),
|
|
254
255
|
author: c.author?.login ?? null,
|
|
255
256
|
bot: c.author?.__typename === 'Bot',
|
|
256
257
|
createdAt: c.createdAt ?? '',
|
package/src/graphs/dispatch.mjs
CHANGED
|
@@ -16,6 +16,7 @@ import { newMarker, withHistory } from '../marker.mjs'
|
|
|
16
16
|
import { readTriage, TriageResult, triageComment, triagePrompt } from '../phases/dispatch.mjs'
|
|
17
17
|
import { humanReplies, quoted, replyContextOf } from '../human-reply.mjs'
|
|
18
18
|
import { traceWorker } from '../tracing.mjs'
|
|
19
|
+
import { fingerprintOf } from '../triage-inputs.mjs'
|
|
19
20
|
import { stopOverdue } from '../workers.mjs'
|
|
20
21
|
import { task } from './task.mjs'
|
|
21
22
|
|
|
@@ -164,6 +165,8 @@ const startTriage = declare(
|
|
|
164
165
|
await land(ctx, 'triaging', {
|
|
165
166
|
...m0,
|
|
166
167
|
reply,
|
|
168
|
+
// The inputs this worker sees; to-human keeps them on a needs-human verdict, so re-triage can skip it.
|
|
169
|
+
fingerprint: { hash: fingerprintOf(issue, snap, { botLogin: config.graft.botLogin }), at: iso(ctx.tick.now) },
|
|
167
170
|
deferUntil: null,
|
|
168
171
|
host: config.host,
|
|
169
172
|
start: iso(ctx.tick.now),
|
|
@@ -393,7 +396,11 @@ const toHuman = declare(
|
|
|
393
396
|
name: 'to-human',
|
|
394
397
|
input: Failure,
|
|
395
398
|
output: Empty,
|
|
396
|
-
/**
|
|
399
|
+
/**
|
|
400
|
+
* Into the Human Queue with `why:triage` and the reason in the state comment. A needs-human verdict keeps the
|
|
401
|
+
* triage inputs `start-triage` recorded (re-triage skips the issue while they hold); a spent budget drops them.
|
|
402
|
+
* @param {z.infer<typeof Failure>} what @param {DispatchCtx} ctx
|
|
403
|
+
*/
|
|
397
404
|
run: async (what, ctx) => {
|
|
398
405
|
const issue = issueOf(ctx)
|
|
399
406
|
const m = markerOf(issue)
|
|
@@ -403,6 +410,7 @@ const toHuman = declare(
|
|
|
403
410
|
{
|
|
404
411
|
...withHistory(m, { at: iso(ctx.tick.now), attempt: m.attempt, ...what }),
|
|
405
412
|
lastFailure: what.reason,
|
|
413
|
+
fingerprint: what.outcome === 'needs-human' ? (m.fingerprint ?? null) : null,
|
|
406
414
|
host: null,
|
|
407
415
|
start: null,
|
|
408
416
|
input: null,
|
package/src/marker.mjs
CHANGED
|
@@ -49,6 +49,7 @@
|
|
|
49
49
|
* deferReason?: string | null,
|
|
50
50
|
* blockedBy?: number[] | null,
|
|
51
51
|
* reply?: { since: string, question: string | null } | null,
|
|
52
|
+
* fingerprint?: { hash: string, at: string } | null,
|
|
52
53
|
* }} Marker
|
|
53
54
|
* `mergeRefusal`: the last `graft pr merge` cambium was refused (PR graph `merge`), and on which head.
|
|
54
55
|
* `reworks`: how many times the PR graph sent this issue's PR back to a worker.
|
|
@@ -57,6 +58,8 @@
|
|
|
57
58
|
* GitHub `blockedBy` issues it waits on (no `deferUntil`).
|
|
58
59
|
* `reply`: while triage is pending or running, what a human reply answers (human-reply.mjs): human comments after
|
|
59
60
|
* `since` are quoted in the triage prompt as the answer to `question`. Cleared when triage lands a verdict.
|
|
61
|
+
* `fingerprint`: the triage inputs (triage-inputs.mjs) the last triage saw, taken at `start-triage` and kept by
|
|
62
|
+
* `to-human` only for a needs-human verdict; re-triage skips the issue while they are unchanged.
|
|
60
63
|
* `triage`: what the dispatch graph's triage added when it handed the issue to `q:task`; the task prompt shows it.
|
|
61
64
|
* @typedef {{ graph: string, entryNode: string, nodes?: Iterable<string> }} QueueOwner
|
|
62
65
|
*/
|
package/src/phases/dispatch.mjs
CHANGED
|
@@ -132,6 +132,7 @@ export function readTriage(log, issue) {
|
|
|
132
132
|
* }} input
|
|
133
133
|
* `blocked`: an earlier triage parked it on these issues, all closed now. `replied`: a human commented since the
|
|
134
134
|
* issue last waited; `question` is what it waited on (the needs-human, defer or blocked reason).
|
|
135
|
+
* A change to how triage judges an issue bumps `TRIAGE_RUBRIC` (triage-inputs.mjs), so re-triage looks again.
|
|
135
136
|
*/
|
|
136
137
|
export function triagePrompt({
|
|
137
138
|
repo,
|
package/src/tick.mjs
CHANGED
|
@@ -19,6 +19,7 @@ import { releaseGraphs } from './graphs/release.mjs'
|
|
|
19
19
|
import { DISPATCH_NOT_BUILT, dispatchNotBuilt } from './phases/dispatch.mjs'
|
|
20
20
|
import { isRepair } from './base-health.mjs'
|
|
21
21
|
import { stopOverdue } from './workers.mjs'
|
|
22
|
+
import { syncBriefs } from './briefs.mjs'
|
|
22
23
|
|
|
23
24
|
/**
|
|
24
25
|
* @typedef {import('./github.mjs').Issue} Issue
|
|
@@ -41,6 +42,7 @@ import { stopOverdue } from './workers.mjs'
|
|
|
41
42
|
* telemetry?: import('./tracing.mjs').Telemetry,
|
|
42
43
|
* updater?: import('./update.mjs').Updater,
|
|
43
44
|
* gc?: () => Promise<unknown>,
|
|
45
|
+
* briefs?: { dir: string, fs?: import('./briefs.mjs').BriefFs },
|
|
44
46
|
* daemonStartedAt?: number,
|
|
45
47
|
* pid?: number,
|
|
46
48
|
* }} Deps
|
|
@@ -98,6 +100,7 @@ export async function tick(deps) {
|
|
|
98
100
|
...(paused ? [] : /** @type {[string, any][]} */ ([['release', release]])),
|
|
99
101
|
...(paused || !engine.upkeep ? [] : /** @type {[string, StepFn][]} */ ([['upkeep', engine.upkeep]])),
|
|
100
102
|
...(paused || !deps.gc ? [] : /** @type {[string, StepFn][]} */ ([['gc', gc]])),
|
|
103
|
+
...(deps.briefs ? /** @type {[string, StepFn][]} */ ([['briefs', briefs]]) : []),
|
|
101
104
|
]
|
|
102
105
|
for (const [name, fn] of steps) await runStep(deps, ctx, name, () => fn(deps, ctx))
|
|
103
106
|
const state = heartbeatState(deps, ctx)
|
|
@@ -745,3 +748,17 @@ export function heartbeatState(deps, ctx) {
|
|
|
745
748
|
graphs: graphDescriptions(),
|
|
746
749
|
}
|
|
747
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
|
+
}
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
/**
|
|
3
|
+
* Triage inputs: what a triage verdict was drawn from, hashed, so the daily re-triage can skip a `q:human` issue
|
|
4
|
+
* nothing has changed on since triage answered needs-human (upkeep.mjs `retriage`).
|
|
5
|
+
*
|
|
6
|
+
* The fingerprint covers the issue's title and body, its labels (not cambium's own: `q:*`, `why:*`, `wait:*`,
|
|
7
|
+
* `running`), the ids of its human comments (human-reply.mjs: not cambium, not a bot, not a state marker), its
|
|
8
|
+
* GitHub `blockedBy` issues and their states, the agent PRs that name it and their states, and
|
|
9
|
+
* {@link TRIAGE_RUBRIC}. `start-triage` records it on the marker (the inputs the worker saw), and `to-human` keeps
|
|
10
|
+
* it only for a needs-human verdict.
|
|
11
|
+
*/
|
|
12
|
+
import { createHash } from 'node:crypto'
|
|
13
|
+
import { branchIssue } from './github.mjs'
|
|
14
|
+
import { parseMarker } from './marker.mjs'
|
|
15
|
+
import { RUNNING } from './labels.mjs'
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* @typedef {import('./github.mjs').Issue} Issue
|
|
19
|
+
* @typedef {import('./github.mjs').Snapshot} Snapshot
|
|
20
|
+
* @typedef {{ hash: string, at: string }} Fingerprint
|
|
21
|
+
* `at`: when it was taken, the start of the triage that answered; the backstop counts from it.
|
|
22
|
+
*/
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* The triage prompt and rubric's version. Bump it with any change to how triage judges an issue
|
|
26
|
+
* (phases/dispatch.mjs `triagePrompt`): every fingerprint stops matching, so the next re-triage looks at every
|
|
27
|
+
* `q:human` issue again.
|
|
28
|
+
*/
|
|
29
|
+
export const TRIAGE_RUBRIC = 1
|
|
30
|
+
|
|
31
|
+
const DAY = 24 * 60 * 60_000
|
|
32
|
+
|
|
33
|
+
/** cambium's own labels: moving an issue between queues is not a change triage should see. @param {string} l */
|
|
34
|
+
const cambiumLabel = (l) => l === RUNNING || /^(q|why|wait):/.test(l)
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* The inputs, in a stable order. @param {Issue} issue @param {Snapshot | undefined} snap
|
|
38
|
+
* @param {{ botLogin?: string | null, rubric?: number }} [o]
|
|
39
|
+
*/
|
|
40
|
+
export function triageInputs(issue, snap, { botLogin = null, rubric = TRIAGE_RUBRIC } = {}) {
|
|
41
|
+
const self = new Set([botLogin, issue.stateComment?.author].filter(Boolean))
|
|
42
|
+
return {
|
|
43
|
+
rubric,
|
|
44
|
+
title: issue.title,
|
|
45
|
+
body: issue.body,
|
|
46
|
+
labels: issue.labels.filter((l) => !cambiumLabel(l)).sort(),
|
|
47
|
+
comments: (issue.comments ?? [])
|
|
48
|
+
.filter((c) => !!c.author && !c.bot && !self.has(c.author) && !parseMarker(c.body))
|
|
49
|
+
.map((c) => String(c.id ?? `${c.author}@${c.createdAt}`))
|
|
50
|
+
.sort(),
|
|
51
|
+
blockedBy: (issue.blockedBy ?? []).map((b) => `${b.number}:${b.state}`).sort(),
|
|
52
|
+
// Merged PRs come from the snapshot's newest 30; one that ages out of it changes the hash once.
|
|
53
|
+
prs: (snap?.prs ?? [])
|
|
54
|
+
.filter((p) => p.closes.includes(issue.number) || branchIssue(p.branch) === issue.number)
|
|
55
|
+
.map((p) => `${p.number}:${p.state}`)
|
|
56
|
+
.sort(),
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* @param {Issue} issue @param {Snapshot | undefined} snap @param {{ botLogin?: string | null, rubric?: number }} [o]
|
|
62
|
+
* @returns {string}
|
|
63
|
+
*/
|
|
64
|
+
export const fingerprintOf = (issue, snap, o) =>
|
|
65
|
+
createHash('sha256')
|
|
66
|
+
.update(JSON.stringify(triageInputs(issue, snap, o)))
|
|
67
|
+
.digest('hex')
|
|
68
|
+
.slice(0, 16)
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Whether re-triage sends a `q:human` issue back to triage. Pure.
|
|
72
|
+
* - `unchanged`: the marker's fingerprint matches and is younger than `maxSkipDays`: stays.
|
|
73
|
+
* - `changed`, `no fingerprint` (an issue triage never answered needs-human on, or one from before fingerprints),
|
|
74
|
+
* `backstop` (unchanged for `maxSkipDays`, so a change the fingerprint cannot see is seen eventually): goes.
|
|
75
|
+
*
|
|
76
|
+
* @param {Issue} issue @param {Snapshot | undefined} snap
|
|
77
|
+
* @param {{ now: number, maxSkipDays: number, botLogin?: string | null, rubric?: number }} o
|
|
78
|
+
* @returns {{ retriage: boolean, why: 'unchanged' | 'changed' | 'no fingerprint' | 'backstop' }}
|
|
79
|
+
*/
|
|
80
|
+
export function retriageDecision(issue, snap, { now, maxSkipDays, botLogin, rubric }) {
|
|
81
|
+
const fp = issue.stateComment?.marker?.fingerprint
|
|
82
|
+
const at = fp ? Date.parse(fp.at) : NaN
|
|
83
|
+
if (!fp?.hash || !Number.isFinite(at)) return { retriage: true, why: 'no fingerprint' }
|
|
84
|
+
if (fp.hash !== fingerprintOf(issue, snap, { botLogin, rubric })) return { retriage: true, why: 'changed' }
|
|
85
|
+
if (now - at >= maxSkipDays * DAY) return { retriage: true, why: 'backstop' }
|
|
86
|
+
return { retriage: false, why: 'unchanged' }
|
|
87
|
+
}
|
package/src/upkeep.mjs
CHANGED
|
@@ -11,7 +11,8 @@
|
|
|
11
11
|
* - **Re-triage** (daily at `retriage.time` when `retriage.enabled`): every `q:human` issue goes back to `q:intake`,
|
|
12
12
|
* so triage looks again under its current rubric: done since (obsolete), now checkable (defer), or now a task.
|
|
13
13
|
* Not `why:approve` (a merge only a human may make: a re-triage would start a duplicate Task) and not one holding
|
|
14
|
-
* `running`.
|
|
14
|
+
* `running`. Not one whose triage inputs (triage-inputs.mjs) are unchanged since triage answered needs-human,
|
|
15
|
+
* unless that was `retriage.maxSkipDays` (default 14) or more ago: it stays, no worker, no label moves.
|
|
15
16
|
* - **Rescue** (rescue-engine.mjs, while `phases.rescue.cap > 0`): rescue workers every tick, and every
|
|
16
17
|
* `rescue.everyMinutes` a sweep for stuck items, each diagnosed and unstuck by the rescue graph.
|
|
17
18
|
*/
|
|
@@ -22,6 +23,7 @@ import { move, Q, RUNNING, WHY } from './labels.mjs'
|
|
|
22
23
|
import { releaseDue } from './phases/release.mjs'
|
|
23
24
|
import { rescueStep } from './rescue-engine.mjs'
|
|
24
25
|
import { each } from './tick.mjs'
|
|
26
|
+
import { retriageDecision } from './triage-inputs.mjs'
|
|
25
27
|
|
|
26
28
|
/**
|
|
27
29
|
* @typedef {import('./tick.mjs').Deps} Deps
|
|
@@ -119,7 +121,7 @@ export async function reap(deps, ctx) {
|
|
|
119
121
|
|
|
120
122
|
/** @param {Deps} deps @param {Ctx} ctx */
|
|
121
123
|
export async function retriage(deps, ctx) {
|
|
122
|
-
const { enabled, time } = deps.config.retriage
|
|
124
|
+
const { enabled, time, maxSkipDays } = deps.config.retriage
|
|
123
125
|
if (!enabled) return
|
|
124
126
|
const last = deps.store.get('retriage.lastRun')
|
|
125
127
|
if (!releaseDue(ctx.now, last === null ? null : Number(last), time)) return
|
|
@@ -133,10 +135,12 @@ export async function retriage(deps, ctx) {
|
|
|
133
135
|
!i.labels.includes(RUNNING) &&
|
|
134
136
|
!ctx.touched.has(key(slug, i.number)),
|
|
135
137
|
)
|
|
138
|
+
const o = { now: ctx.now, maxSkipDays, botLogin: deps.config.graft.botLogin }
|
|
139
|
+
const changed = human.filter((i) => retriageDecision(i, snap, o).retriage)
|
|
136
140
|
let moved = 0
|
|
137
141
|
await each(
|
|
138
142
|
deps,
|
|
139
|
-
|
|
143
|
+
changed,
|
|
140
144
|
async (issue) => {
|
|
141
145
|
await setLabels(deps, slug, issue, move(issue.labels, Q.intake))
|
|
142
146
|
moved++
|
|
@@ -144,8 +148,11 @@ export async function retriage(deps, ctx) {
|
|
|
144
148
|
(issue) => ({ repo: slug, issue: issue.number }),
|
|
145
149
|
)
|
|
146
150
|
if (human.length)
|
|
147
|
-
deps.log(
|
|
148
|
-
|
|
149
|
-
|
|
151
|
+
deps.log(
|
|
152
|
+
'info',
|
|
153
|
+
`re-triage: ${changed.length} of ${human.length} changed; ${moved} back to q:intake, ` +
|
|
154
|
+
`${human.length - changed.length} unchanged skipped (${iso(ctx.now)})`,
|
|
155
|
+
{ repo: slug },
|
|
156
|
+
)
|
|
150
157
|
}
|
|
151
158
|
}
|