@oakgreencc/cambium 0.0.41 → 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:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oakgreencc/cambium",
3
- "version": "0.0.41",
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/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
+ }