@oakgreencc/cambium 0.0.10 → 0.0.12

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
@@ -2,7 +2,7 @@
2
2
 
3
3
  The scheduler daemon. Every tick it reads the `q:*` queues from GitHub, starts headless `claude -p` workers in their own worktrees up to a cap, watches their PRs through CI and the merge queue, and makes every queue transition itself. GitHub is the truth; local SQLite only remembers which processes it started.
4
4
 
5
- This is the **Task phase** MVP. Dispatch is a seam; Release runs as graphs on `engine: "graph"` and is a seam on the legacy engine (see [Follow-ups](#follow-ups)).
5
+ This is the **Task phase** MVP. With `engine: "graph"`, `q:intake` issues are triaged by the [`dispatch` graph](#the-dispatch-graph) and Release runs as graphs; on the legacy engine both are seams (see [Follow-ups](#follow-ups)).
6
6
 
7
7
  Runtime dependencies: `zod` (the [graph module](#graph-module-preview)) and OpenTelemetry via `@oakgreencc/mycelium` (loaded only when [tracing](#tracing) is on); Node ≥ 22.13 (`node:sqlite`). GitHub access goes through [`graft`](../graft), which must be on `PATH`.
8
8
 
@@ -40,7 +40,7 @@ Each step is bounded by `stepTimeoutSeconds`. A step that throws or times out is
40
40
  2. **Reconcile.** For each tracked worker: alive and under its wall-clock cap → nothing. Over the cap → kill its process group. Gone → exit check (a PR on its branch, or closing its issue, that is open or merged and not still on the commit CI already failed) → `submitted`; otherwise requeue with the stderr tail (a failed prepare step requeues as `spawn-failed`). Then the worktree is torn down if `graft status` says GitHub holds everything in it, else kept with a `warn` saying why.
41
41
  3. **Watch** (no agent), for agent PRs whose issue is in no queue: merged → close the issue, delete the branch; red → requeue with the failing checks' summaries; left the merge queue without merging → requeue; not merged `mergeQueueMinutes` after submission → `q:human`.
42
42
  4. **Sweep.** An issue labelled `running` with this host (or no host) in its marker and no tracked worker → requeue. This is what makes losing the SQLite file cost one requeue.
43
- 5. **Schedule.** Start Task workers for `q:task` issues without `running`, by priority label then age, up to `phases.task.cap` counted from live workers. A task requeued earlier in the same tick can start in that tick.
43
+ 5. **Schedule.** Start Task workers for `q:task` issues without `running`, by priority label then age, up to `phases.task.cap` counted from live workers. A task requeued earlier in the same tick can start in that tick. Then, with `engine: "graph"` and `phases.dispatch.cap > 0`, start triage workers for `q:intake` issues the same way ([the dispatch graph](#the-dispatch-graph)).
44
44
  6. **Release.** Legacy: once a day at `release.time` when `release.enabled`; the run itself is a seam. Graph: the [release graphs](#the-release-graphs), per repo.
45
45
  7. **Heartbeat.** Write the state file.
46
46
 
@@ -52,7 +52,7 @@ A requeue is `q:task` with attempt + 1, or, once `maxAttempts` are spent, `q:hum
52
52
  | --------------------------------------------------- | ------------------------------------------------------------------------------ |
53
53
  | `q:intake`, `q:task`, `q:human`, `q:promote` | The queue. At most one per open issue. |
54
54
  | `running` | A worker holds the lease (with `q:task`). |
55
- | `why:budget` (also `why:reject`, `why:approve`) | Why it is in `q:human`. |
55
+ | `why:budget`, `why:triage` (also `why:reject`, …) | Why it is in `q:human` (`why:triage`: sent there by triage, see below). |
56
56
  | _no `q:` label_, cambium comment, open `agent/*` PR | Submitted: in the Release Queue, which is the PR's merge-queue state. |
57
57
  | `priority:critical` … `priority:low` | Scheduling order (configurable). Unlabelled sorts after every listed priority. |
58
58
 
@@ -117,7 +117,7 @@ One JSON file. Everything but `repos` is optional; these are the defaults:
117
117
 
118
118
  - `repos[].path` is a local clone; worktrees are added from it and `graft` runs in it.
119
119
  - `graft.app` is the App cambium acts as (`GRAFT_APP` for its own `graft` calls); `worker.graftApp` the one workers act as. Neither leaks into the other.
120
- - `engine` picks how the Task phase runs: `"legacy"` (the stage tick, the default) or `"graph"` (the [`task` graph](#the-task-graph)). Both make the same moves; see [The task graph](#the-task-graph).
120
+ - `engine` picks how the Task phase runs: `"legacy"` (the stage tick, the default) or `"graph"` (the [`task` graph](#the-task-graph)). Both make the same moves; see [The task graph](#the-task-graph). Only `"graph"` runs the [`dispatch` graph](#the-dispatch-graph) (gated by `phases.dispatch.cap`); legacy leaves `q:intake` alone.
121
121
  - Setting `paths.home` moves every default path under it.
122
122
  - `release.time` is host-local `HH:MM`.
123
123
  - `repos[].release` (`engine: "graph"`): `{ "enabled", "time", "from", "to" }`. `enabled` and `time` default to the top-level `release`, `from` to the repo's `baseBranch`, `to` to `"main"`. A repo whose `from` equals `to` has no promotion PR. Example: `{ "slug": "o/app", "path": "~/app", "baseBranch": "develop", "release": { "enabled": true, "time": "06:00", "from": "develop", "to": "main" } }`.
@@ -275,6 +275,53 @@ Generated by `toMermaid(task)`; a test keeps this copy current. Boxes are step n
275
275
  - **Markers.** The graph writes marker v2 without `stage`: `node` is where the issue rests. `merge-queue` is the stage tick's `submitted` with `queued: true`, and a stage-era marker in that state resumes at `merge-queue`. A marker whose node the current graph version no longer has restarts at `start-worker` with a `graph-changed` history entry.
276
276
  - **Same moves.** Every scenario in `test/tick.test.mjs` runs on both engines; the test compares their GitHub calls in order (markers semantically, not by rendered text), worker starts with their prompts, kills, teardowns and logs.
277
277
 
278
+ ## The dispatch graph
279
+
280
+ With `"engine": "graph"` and `phases.dispatch.cap > 0`, each `q:intake` issue is triaged by a one-shot `claude -p` worker (`src/graphs/dispatch.mjs`, steps in `src/dispatch-engine.mjs`, prompt and result in `src/phases/dispatch.mjs`), then moved to `q:task`, moved to `q:human`, or closed as a duplicate.
281
+
282
+ ```mermaid
283
+ flowchart TD
284
+ start_(["q:intake"])
285
+ n0["start-triage"]
286
+ n1{{"triaging"}}
287
+ n2["retry-triage"]
288
+ n3["to-task"]
289
+ n4["to-human"]
290
+ n5["close-duplicate"]
291
+ end_(("end"))
292
+ start_ --> n0
293
+ n0 -->|"started"| n1
294
+ n0 -->|"budgetSpent"| n4
295
+ n0 --> n2
296
+ n1 -->|"issueGone"| end_
297
+ n1 -->|"leaseLost"| n2
298
+ n1 -->|"actionable"| n3
299
+ n1 -->|"duplicate"| n5
300
+ n1 -->|"needsHuman"| n4
301
+ n1 --> n4
302
+ n2 -->|"attemptsLeft"| n0
303
+ n2 --> n4
304
+ n3 --> end_
305
+ n4 --> end_
306
+ n5 --> end_
307
+ ```
308
+
309
+ | Node | Kind | Queue label | Holds `running` |
310
+ | ----------------- | ---- | ----------- | --------------- |
311
+ | `start-triage` | step | `q:intake` | no |
312
+ | `triaging` | wait | `q:intake` | yes |
313
+ | `retry-triage` | step | `q:intake` | no |
314
+ | `to-task` | step | `q:task` | no |
315
+ | `to-human` | step | `q:human` | no |
316
+ | `close-duplicate` | step | none | no |
317
+
318
+ - **The verdict.** The worker's final message must end with a JSON block, validated by zod (`TriageResult`): `{ verdict: 'actionable' | 'needs-human' | 'duplicate', duplicateOf?, reason, title?, acceptance? }` (`duplicateOf` is required on a duplicate and cannot be the issue itself). cambium reads it from the worker's stdout log: the last `result` event's `result` text, its last fenced block (else the bare JSON).
319
+ - **Outcomes.** `actionable` → a comment with the reason, the task title and acceptance checks (when given), then `q:task` with a task-graph marker at `start-worker`, attempt 1, history kept; the checks also ride in the marker (`triage`) into the task worker's prompt. The issue body is never rewritten: cambium's write path has no issue edit, and the author's text stays as written. `needs-human` → `q:human` + `why:triage`, the reason as the state comment's last failure. `duplicate` → closed with reason `duplicate` and `Duplicate of #n (<link>). <reason>`. A missing or invalid verdict (no `result` event, no JSON, a schema error) or a worker killed at `wallClockMinutes` (the unlabelled `triaging → to-human` edge) → `q:human` + `why:triage` with the error.
320
+ - **Read-only checkout.** Triage reads code to judge feasibility and duplicates, so it gets a checkout, but a disposable one: a detached worktree at `<root>/triage-<n>` on `origin/<base>` (the repo's worktree root), no install, hydrate or `prepare`, tools `Read,Glob,Grep,Bash` with Edit/Write and every graft/git write verb denied. It is removed outright after the verdict (no `graft status`: nothing in it is worth keeping).
321
+ - **Retries.** A worker that cannot start, or a lost `running` lease on a `q:intake` issue (Sweep), goes back to `q:intake` with attempt + 1, then to `q:human` once `phases.dispatch.maxAttempts` are spent. A marker from another graph or a finished triage starts over at attempt 1.
322
+ - **Leaving intake.** If the issue is closed or relabelled while triage runs, the verdict is dropped and the checkout removed.
323
+ - **Tracing.** Call sites are marked (`TRACING (follow-up)`) as in the task graph: the worker's `TRACEPARENT`, its stream-json spans, and `advanceHooks` in the driver, whose `cambium.issue` root continues mycelium's intake span from the issue body.
324
+
278
325
  ## The release graphs
279
326
 
280
327
  With `"engine": "graph"` the tick's Release step runs two graphs (`src/graphs/release.mjs`) for every repo whose `release` is on. Their subject is the **promotion PR**, which promotes the repo's integration branch to its release branch (`release.from` → `release.to`, e.g. `develop` → `main`). The marker (v2) is cambium's state comment on that PR, written through the same path as an issue's.
@@ -501,7 +548,7 @@ Without Jaeger running the collector still writes the files; the Jaeger exporter
501
548
 
502
549
  Seams that exist, typed, and do nothing yet:
503
550
 
504
- - **Dispatch** (`src/phases/dispatch.mjs`): `Dispatch(input: { repo, intake, capacity, now }) → { started }`. Reached only when `phases.dispatch.cap > 0`; the stub starts nothing and logs that `q:intake` waits.
551
+ - **Dispatch on the legacy engine** (`src/phases/dispatch.mjs`): `Dispatch(input: { repo, intake, capacity, now }) → { started }`. Reached only when `phases.dispatch.cap > 0`; the stub starts nothing and logs that `q:intake` waits. The graph engine runs [the dispatch graph](#the-dispatch-graph) instead; `cambium run dispatch` is not wired yet.
505
552
  - **Release**, legacy engine only (`src/phases/release.mjs`): `Release(input: { repo, now }) → { done, note }`. The once-a-day schedule (`releaseDue`) is real and recorded in the store; the run returns `{ done: false }`. The graph engine runs the [release graphs](#the-release-graphs).
506
553
  - Conditional (ETag) reads, so an unchanged poll is free against the rate limit; GraphQL has no ETag, so this needs a REST probe in front of the query.
507
554
  - More than 100 queued issues or open PRs per repo, and state comments beyond an issue's first 100 comments: the read is one page.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oakgreencc/cambium",
3
- "version": "0.0.10",
3
+ "version": "0.0.12",
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",
@@ -0,0 +1,135 @@
1
+ // @ts-check
2
+ /**
3
+ * `engine: "graph"`: the Dispatch-phase steps of the tick, driven through the `dispatch` graph
4
+ * (graphs/dispatch.mjs). The legacy engine keeps the stub (phases/dispatch.mjs) and leaves `q:intake` alone.
5
+ *
6
+ * - Reconcile: every tracked triage worker's issue at `triaging`.
7
+ * - Sweep: a stale `running` lease on a `q:intake` issue runs `retry-triage`.
8
+ * - Schedule: `q:intake` issues without a lease, by priority then age, up to `phases.dispatch.cap` counted from
9
+ * live triage workers; each starts at `start-triage`.
10
+ *
11
+ * A turn advances one transition at a time and stops on entering a wait, at the entry node again (only Schedule
12
+ * admits entries), at a wait that is not ready, or at the end.
13
+ */
14
+ import { advance } from './graph/index.mjs'
15
+ import { dispatch, lostLeaseOf, nodeOf } from './graphs/dispatch.mjs'
16
+ import { byPriorityThenAge, Q, RUNNING } from './labels.mjs'
17
+ import { each, staleLeases } from './tick.mjs'
18
+
19
+ /**
20
+ * @typedef {import('./tick.mjs').Deps} Deps
21
+ * @typedef {import('./tick.mjs').Ctx} Ctx
22
+ * @typedef {import('./graphs/task.mjs').Subject} Subject
23
+ * @typedef {import('./graph/advance.mjs').Transition} Transition
24
+ */
25
+
26
+ export const PHASE = 'dispatch'
27
+
28
+ /**
29
+ * One issue's turn through the dispatch graph from `at`. A node error is rethrown (the step logs it); a triage
30
+ * worker whose `triaging` was left is torn down only after the turn's writes succeeded.
31
+ *
32
+ * @param {Deps} deps @param {Ctx} ctx @param {Subject} subject @param {{ node: string, input: unknown }} at
33
+ */
34
+ export async function driveDispatch(deps, ctx, subject, at) {
35
+ const c = { ...deps, tick: ctx, subject }
36
+ /** @type {Transition[]} */
37
+ const transitions = []
38
+ let pos = at
39
+ for (;;) {
40
+ // TRACING (follow-up): pass `instrument: advanceHooks(telemetry, { graph: 'dispatch', …, issueBody }).instrument`
41
+ // here; the issue's cambium.issue root continues mycelium's intake span from the body, so these node and wait
42
+ // spans join the intake trace (tracing.mjs `issueTrace`).
43
+ const r = await advance(dispatch, pos, c, { maxTransitions: 1 })
44
+ if (r.error) throw r.error.cause instanceof Error ? r.error.cause : r.error
45
+ transitions.push(...r.transitions)
46
+ pos = { node: r.node, input: r.input }
47
+ if (r.reason !== 'limit' || r.node === dispatch.entry.node) break
48
+ if (nodeOf(r.node).kind === 'wait') break
49
+ }
50
+ if (transitions.some((t) => t.from === 'triaging')) await releaseWorker(deps, subject)
51
+ return { transitions, ...pos }
52
+ }
53
+
54
+ /** The triage worker's row goes, then its read-only checkout. @param {Deps} deps @param {Subject} s */
55
+ async function releaseWorker(deps, s) {
56
+ const w = deps.store.worker(s.slug, s.number)
57
+ if (!w) return
58
+ deps.store.removeWorker(s.slug, s.number)
59
+ const repo = deps.config.repos.find((r) => r.slug === s.slug)
60
+ if (!repo) return
61
+ const t = await deps.spawner.cleanup({ repo, worktree: w.worktree, branch: w.branch, readOnly: true })
62
+ if (!t.removed) deps.log('warn', `kept worktree ${w.worktree}: ${t.reason}`, { repo: s.slug, issue: s.number })
63
+ }
64
+
65
+ /** @param {Deps} deps @param {Ctx} ctx */
66
+ async function reconcile(deps, ctx) {
67
+ await each(
68
+ deps,
69
+ deps.store.workers().filter((w) => w.phase === PHASE),
70
+ async (w) => {
71
+ const snap = ctx.snaps.get(w.repo)
72
+ const subject = { slug: w.repo, number: w.issue, snap, issue: snap?.issues.get(w.issue) }
73
+ await driveDispatch(deps, ctx, subject, { node: 'triaging', input: { attempt: w.attempt } })
74
+ },
75
+ (w) => ({ repo: w.repo, issue: w.issue }),
76
+ )
77
+ }
78
+
79
+ /** @param {Deps} deps @param {Ctx} ctx */
80
+ async function sweep(deps, ctx) {
81
+ for (const [slug, snap] of ctx.snaps)
82
+ await each(
83
+ deps,
84
+ staleLeases(deps, ctx, slug, snap).filter((i) => i.labels.includes(Q.intake)),
85
+ async (issue) => {
86
+ const subject = { slug, number: issue.number, snap, issue }
87
+ await driveDispatch(deps, ctx, subject, {
88
+ node: 'retry-triage',
89
+ input: lostLeaseOf({ ...deps, tick: ctx, subject }),
90
+ })
91
+ },
92
+ (issue) => ({ repo: slug, issue: issue.number }),
93
+ )
94
+ }
95
+
96
+ /**
97
+ * The `q:intake` issues to triage this tick: no `running`, no tracked worker, by priority then age, up to the free
98
+ * slots counted from live triage workers.
99
+ * @param {Deps} deps @param {Ctx} ctx
100
+ */
101
+ export function intakeCandidates(deps, ctx) {
102
+ const { config, store } = deps
103
+ const free = config.phases.dispatch.cap - store.workers().filter((w) => w.phase === PHASE).length
104
+ if (free <= 0) return []
105
+ /** @type {{ slug: string, issue: import('./github.mjs').Issue, snap: import('./github.mjs').Snapshot }[]} */
106
+ const candidates = []
107
+ for (const [slug, snap] of ctx.snaps)
108
+ for (const issue of snap.issues.values())
109
+ if (
110
+ issue.state === 'OPEN' &&
111
+ issue.labels.includes(Q.intake) &&
112
+ !issue.labels.includes(RUNNING) &&
113
+ !store.worker(slug, issue.number)
114
+ )
115
+ candidates.push({ slug, issue, snap })
116
+ const order = byPriorityThenAge(config.priorityLabels)
117
+ candidates.sort((a, b) => order(a.issue, b.issue))
118
+ return candidates.slice(0, free)
119
+ }
120
+
121
+ /** @param {Deps} deps @param {Ctx} ctx */
122
+ async function schedule(deps, ctx) {
123
+ await each(
124
+ deps,
125
+ intakeCandidates(deps, ctx),
126
+ async (c) => {
127
+ const subject = { slug: c.slug, number: c.issue.number, snap: c.snap, issue: c.issue }
128
+ await driveDispatch(deps, ctx, subject, { node: dispatch.entry.node, input: {} })
129
+ },
130
+ (c) => ({ repo: c.slug, issue: c.issue.number }),
131
+ )
132
+ }
133
+
134
+ /** The Dispatch phase's steps for the graph engine. */
135
+ export const DISPATCH_STEPS = { reconcile, sweep, schedule }
package/src/github.mjs CHANGED
@@ -40,7 +40,8 @@ import { Q, QUEUE_LABELS } from './labels.mjs'
40
40
  * read(slug: string): Promise<Snapshot>,
41
41
  * label(slug: string, number: number, change: { add: string[], remove: string[] }): Promise<void>,
42
42
  * writeState(slug: string, number: number, commentId: number | null, body: string): Promise<number>,
43
- * close(slug: string, number: number, body: string): Promise<void>,
43
+ * close(slug: string, number: number, body: string, opts?: { reason?: 'completed' | 'not_planned' | 'duplicate' }): Promise<void>,
44
+ * comment(slug: string, number: number, body: string): Promise<void>,
44
45
  * deleteBranch(slug: string, branch: string): Promise<void>,
45
46
  * openPull(slug: string, pr: { head: string, base: string, title: string, body: string }): Promise<{ number: number, url: string }>,
46
47
  * editPull(slug: string, number: number, change: { title: string, body: string }): Promise<void>,
@@ -279,8 +280,15 @@ export function graftGitHub({ config, exec: run = exec }) {
279
280
  const made = await json(graft(slug, ['issue', 'comment', String(number), '--body-file', '-'], body))
280
281
  return made.id
281
282
  },
282
- async close(slug, number, body) {
283
- await graft(slug, ['issue', 'close', String(number), '--body-file', '-'], body)
283
+ async close(slug, number, body, { reason } = {}) {
284
+ await graft(
285
+ slug,
286
+ ['issue', 'close', String(number), '--body-file', '-', ...(reason ? ['--reason', reason] : [])],
287
+ body,
288
+ )
289
+ },
290
+ async comment(slug, number, body) {
291
+ await graft(slug, ['issue', 'comment', String(number), '--body-file', '-'], body)
284
292
  },
285
293
  async deleteBranch(slug, branch) {
286
294
  await graft(slug, ['api', 'DELETE', `/repos/${slug}/git/refs/heads/${branch}`])
@@ -6,8 +6,9 @@
6
6
  * same order; each step only chooses where an issue's turn starts:
7
7
  *
8
8
  * - Reconcile: every tracked worker's issue at `worker-running`.
9
- * - Watch: issues resting at `ci-running` / `merge-queue` (from the marker); a merged PR goes to `close-out`
10
- * from wherever the issue is.
9
+ * - Watch: issues resting at `ci-running` / `merge-queue` (from the marker), and any task issue in no queue with
10
+ * an open PR (a queue label removed by hand), which starts at `ci-running` (`merge-queue` if `queued`); a
11
+ * merged PR goes to `close-out` from wherever the issue is.
11
12
  * - Sweep: a stale `running` lease runs its node's `recover` (default: `requeue`).
12
13
  * - Schedule: the gate on the entry node. Caps and priority pick the issues; each starts at `start-worker`.
13
14
  *
@@ -21,6 +22,7 @@ import { iso, key, markerOf, setLabels, setMarker } from './issue-state.mjs'
21
22
  import { effectivePosition, graphVersionDecision, withHistory } from './marker.mjs'
22
23
  import { each, newCtx, staleLeases, taskCandidates, watched, watchPairs } from './tick.mjs'
23
24
  import { move, Q } from './labels.mjs'
25
+ import { DISPATCH_STEPS } from './dispatch-engine.mjs'
24
26
 
25
27
  /**
26
28
  * @typedef {import('./tick.mjs').Deps} Deps
@@ -136,7 +138,7 @@ async function restart(deps, ctx, slug, issue, note) {
136
138
  async function reconcile(deps, ctx) {
137
139
  await each(
138
140
  deps,
139
- deps.store.workers(),
141
+ deps.store.workers().filter((w) => w.phase === 'task'),
140
142
  async (w) => {
141
143
  const snap = ctx.snaps.get(w.repo)
142
144
  const subject = { slug: w.repo, number: w.issue, snap, issue: snap?.issues.get(w.issue) }
@@ -165,8 +167,13 @@ async function watch(deps, ctx) {
165
167
  }
166
168
  if (pr.state !== 'OPEN' || issue.state !== 'OPEN' || !watched(deps, slug, issue)) return
167
169
  const at = locate(issue, ctx.now)
168
- if (at?.note) return restart(deps, ctx, slug, issue, at.note)
169
- if (at?.node === 'ci-running' || at?.node === 'merge-queue') await drive(deps, ctx, subject, at)
170
+ if (!at) return
171
+ if (at.note) return restart(deps, ctx, slug, issue, at.note)
172
+ if (at.node === 'ci-running' || at.node === 'merge-queue') return drive(deps, ctx, subject, at)
173
+ // Out of every queue with an open PR, but resting elsewhere (a queue label removed by hand): watch the PR
174
+ // from where it is, as the legacy Watch does.
175
+ const node = markerOf(issue).queued ? 'merge-queue' : 'ci-running'
176
+ await drive(deps, ctx, subject, { node, input: { pr: pr.number, branch: pr.branch } })
170
177
  },
171
178
  ([, issue]) => ({ repo: slug, issue: issue.number }),
172
179
  )
@@ -178,7 +185,7 @@ async function sweep(deps, ctx) {
178
185
  for (const [slug, snap] of ctx.snaps)
179
186
  await each(
180
187
  deps,
181
- staleLeases(deps, ctx, slug, snap),
188
+ staleLeases(deps, ctx, slug, snap).filter((issue) => !issue.labels.includes(Q.intake)),
182
189
  async (issue) => {
183
190
  const subject = { slug, number: issue.number, snap, issue }
184
191
  const c = taskCtx(deps, ctx, subject)
@@ -206,8 +213,21 @@ async function scheduleTasks(deps, ctx) {
206
213
  /** A stale lease at a node without its own `recover`: requeue. @param {import('./graphs/task.mjs').TaskCtx} c */
207
214
  const defaultRecover = (c) => ({ node: 'requeue', input: lostLeaseOf(c) })
208
215
 
216
+ /** @param {import('./tick.mjs').StepFn[]} steps @returns {import('./tick.mjs').StepFn} */
217
+ const inOrder =
218
+ (...steps) =>
219
+ async (deps, ctx) => {
220
+ for (const step of steps) await step(deps, ctx)
221
+ }
222
+
209
223
  /** @type {import('./tick.mjs').Engine} */
210
- export const GRAPH_ENGINE = { reconcile, watch, sweep, scheduleTasks }
224
+ export const GRAPH_ENGINE = {
225
+ reconcile: inOrder(reconcile, DISPATCH_STEPS.reconcile),
226
+ watch,
227
+ sweep: inOrder(sweep, DISPATCH_STEPS.sweep),
228
+ scheduleTasks,
229
+ scheduleDispatch: DISPATCH_STEPS.schedule,
230
+ }
211
231
 
212
232
  // ---- `cambium run <graph> --issue <n> [--follow]`
213
233
 
@@ -0,0 +1,453 @@
1
+ // @ts-check
2
+ /**
3
+ * The Dispatch phase as a graph: a `q:intake` issue is triaged by a one-shot `claude -p` worker whose final
4
+ * message carries a typed verdict ({@link TriageResult}), then moved to `q:task`, moved to `q:human`, or closed as
5
+ * a duplicate. Same conventions as the task graph (graphs/task.mjs): each node declares its queue label and
6
+ * whether it holds `running`, and a node's write is the marker first, then the labels via `move()`.
7
+ *
8
+ * The triage worker runs in a read-only checkout (workers.mjs `readOnly`): detached at the base branch, no install,
9
+ * no Edit/Write. It reads code to judge the issue, and nothing it could leave behind is worth keeping.
10
+ */
11
+ import { z } from 'zod'
12
+ import { defineGraph, defineNode, defineWait, END } from '../graph/index.mjs'
13
+ import { iso, key, markerOf, MIN, setLabels, setMarker } from '../issue-state.mjs'
14
+ import { move, Q, WHY } from '../labels.mjs'
15
+ import { newMarker, withHistory } from '../marker.mjs'
16
+ import { readTriage, TriageResult, triageComment, triagePrompt } from '../phases/dispatch.mjs'
17
+ import { task } from './task.mjs'
18
+
19
+ /**
20
+ * @typedef {import('../github.mjs').Issue} Issue
21
+ * @typedef {import('../marker.mjs').Marker} Marker
22
+ * @typedef {import('./task.mjs').Subject} Subject
23
+ * @typedef {import('./task.mjs').TaskCtx} DispatchCtx
24
+ * @typedef {{ queue: string | null, running: boolean }} Declared
25
+ * A stale `running` lease (at `triaging`) goes to `retry-triage` (dispatch-engine.mjs sweep).
26
+ * @typedef {import('../graph/define.mjs').GraphNode & Declared} DispatchNode
27
+ */
28
+
29
+ /** The nodes an issue in `q:intake` can rest at; a marker elsewhere starts triage over at attempt 1. */
30
+ const INTAKE_NODES = new Set(['start-triage', 'triaging', 'retry-triage'])
31
+
32
+ /** The pseudo-branch that names an issue's triage checkout (`<root>/triage-<n>`); never created. @param {number} n */
33
+ export const triageBranch = (n) => `cambium/triage-${n}`
34
+
35
+ /**
36
+ * @template {import('../graph/define.mjs').GraphNode} N @param {N} node @param {Declared} decl
37
+ * @returns {N & Declared}
38
+ */
39
+ const declare = (node, decl) => Object.freeze({ ...node, ...decl })
40
+
41
+ /** @param {DispatchCtx} ctx */
42
+ function issueOf(ctx) {
43
+ const { issue } = ctx.subject
44
+ if (!issue) throw new Error(`${ctx.subject.slug}#${ctx.subject.number} is not in the snapshot`)
45
+ return issue
46
+ }
47
+
48
+ /** @param {Marker} m */
49
+ const graphMarker = (m) => /** @type {Marker} */ (Object.fromEntries(Object.entries(m).filter(([k]) => k !== 'stage')))
50
+
51
+ /**
52
+ * Put the issue at `node` of this graph: the marker, then the labels `node` declares.
53
+ * @param {DispatchCtx} ctx @param {string} node @param {Marker} marker
54
+ * @param {{ extra?: string[], status?: Marker['status'] }} [opts]
55
+ */
56
+ async function land(ctx, node, marker, { extra = [], status = 'waiting' } = {}) {
57
+ const { slug } = ctx.subject
58
+ const issue = issueOf(ctx)
59
+ const decl = nodeOf(node)
60
+ await setMarker(ctx, slug, issue, {
61
+ ...graphMarker(marker),
62
+ graph: dispatch.name,
63
+ graphVersion: dispatch.version,
64
+ phase: 'dispatch',
65
+ node,
66
+ status,
67
+ enteredAt: iso(ctx.tick.now),
68
+ })
69
+ await setLabels(ctx, slug, issue, move(issue.labels, decl.queue, { running: decl.running, extra }))
70
+ ctx.tick.touched.add(key(slug, issue.number))
71
+ }
72
+
73
+ /**
74
+ * The marker triage continues from: this graph's own while the issue is still in intake, else a fresh one at
75
+ * attempt 1 that keeps the history (e.g. a human sent a `q:human` issue back to `q:intake`).
76
+ * @param {Issue} issue @returns {Marker}
77
+ */
78
+ function intakeMarker(issue) {
79
+ const m = markerOf(issue)
80
+ if (m.graph === dispatch.name && m.status !== 'done' && INTAKE_NODES.has(m.node)) return m
81
+ return newMarker({
82
+ graph: dispatch.name,
83
+ node: dispatch.entry.node,
84
+ phase: 'dispatch',
85
+ history: m.history,
86
+ traceparent: m.traceparent,
87
+ })
88
+ }
89
+
90
+ // ---- Schemas
91
+
92
+ const failure = { reason: z.string(), outcome: z.string(), log: z.string().optional() }
93
+ const Failure = z.object(failure)
94
+ const Empty = z.object({})
95
+ const Verdict = z.object({ result: TriageResult, log: z.string() })
96
+
97
+ // ---- Edge predicates (their names label the Mermaid edges)
98
+
99
+ const started = (/** @type {{ to: string }} */ o) => o.to === 'running'
100
+ const budgetSpent = (/** @type {{ to: string }} */ o) => o.to === 'human'
101
+ const attemptsLeft = (/** @type {{ to: string }} */ o) => o.to === 'start'
102
+ const issueGone = (/** @type {{ exit: string }} */ o) => o.exit === 'gone'
103
+ const leaseLost = (/** @type {{ exit: string }} */ o) => o.exit === 'lost'
104
+ /** @typedef {{ exit: string, result?: { verdict: string } }} Triaged */
105
+ const verdictOf = (/** @type {Triaged} */ o) => (o.exit === 'triaged' ? o.result?.verdict : undefined)
106
+ const actionable = (/** @type {Triaged} */ o) => verdictOf(o) === 'actionable'
107
+ const needsHuman = (/** @type {Triaged} */ o) => verdictOf(o) === 'needs-human'
108
+ const duplicate = (/** @type {Triaged} */ o) => verdictOf(o) === 'duplicate'
109
+
110
+ /** @param {DispatchCtx} ctx */
111
+ export const lostLeaseOf = (ctx) => ({
112
+ reason: `triage worker lost: \`running\` on ${ctx.config.host} with no live process`,
113
+ outcome: 'lost',
114
+ })
115
+
116
+ // ---- Nodes
117
+
118
+ const startTriage = declare(
119
+ defineNode({
120
+ name: 'start-triage',
121
+ input: Empty,
122
+ output: z.discriminatedUnion('to', [
123
+ z.object({ to: z.literal('running'), pid: z.number().int(), worktree: z.string(), attempt: z.number().int() }),
124
+ z.object({ to: z.literal('retry'), ...failure }),
125
+ z.object({ to: z.literal('human'), ...failure }),
126
+ ]),
127
+ /**
128
+ * Claim the issue (marker, then `running`), then start the triage worker in a read-only checkout.
129
+ * @param {{}} _ @param {DispatchCtx} ctx
130
+ */
131
+ run: async (_, ctx) => {
132
+ const { config, spawner, store } = ctx
133
+ const { slug, snap } = ctx.subject
134
+ const issue = issueOf(ctx)
135
+ const repo = config.repos.find((r) => r.slug === slug)
136
+ if (!repo) throw new Error(`${slug} is not in the config`)
137
+ const caps = config.phases.dispatch
138
+ const m0 = intakeMarker(issue)
139
+ if (m0.attempt > caps.maxAttempts)
140
+ return { to: 'human', reason: `${caps.maxAttempts} triage attempts spent`, outcome: 'budget' }
141
+ /** @type {import('../convention.mjs').Convention} */
142
+ let convention
143
+ try {
144
+ convention = spawner.convention(repo)
145
+ } catch (err) {
146
+ return { to: 'retry', reason: `could not start triage: ${errText(err)}`, outcome: 'spawn-failed' }
147
+ }
148
+ await land(ctx, 'triaging', {
149
+ ...m0,
150
+ host: config.host,
151
+ start: iso(ctx.tick.now),
152
+ input: { attempt: m0.attempt },
153
+ })
154
+ const marker = markerOf(issue)
155
+ const queued = [...(snap?.issues.values() ?? [])]
156
+ .filter((i) => i.state === 'OPEN')
157
+ .map(({ number, title, labels }) => ({ number, title, labels }))
158
+ /** @type {import('../workers.mjs').Started} */
159
+ let s
160
+ try {
161
+ s = await spawner.start({
162
+ repo,
163
+ convention,
164
+ issue: issue.number,
165
+ attempt: marker.attempt,
166
+ branch: triageBranch(issue.number),
167
+ phase: 'dispatch',
168
+ maxTurns: caps.maxTurns,
169
+ readOnly: true,
170
+ // TRACING (follow-up): as start-worker, the triage worker's env gets `TRACEPARENT: ctx.traceparent`
171
+ // (this node's cambium.node span, under the cambium.issue root that continues mycelium's intake span).
172
+ buildPrompt: (agentsMd) => triagePrompt({ repo: slug, baseBranch: repo.baseBranch, issue, queued, agentsMd }),
173
+ })
174
+ } catch (err) {
175
+ return {
176
+ to: 'retry',
177
+ reason: `could not start triage: ${errText(err)}`,
178
+ outcome: 'spawn-failed',
179
+ // The claim already put the marker at triaging; the failure is this node's.
180
+ }
181
+ }
182
+ store.addWorker({
183
+ repo: slug,
184
+ issue: issue.number,
185
+ phase: 'dispatch',
186
+ pid: s.pid,
187
+ worktree: s.worktree,
188
+ branch: triageBranch(issue.number),
189
+ attempt: marker.attempt,
190
+ startedAt: ctx.tick.now,
191
+ host: config.host,
192
+ stdout: s.stdout,
193
+ stderr: s.stderr,
194
+ })
195
+ ctx.log('info', `started triage worker pid ${s.pid} (attempt ${marker.attempt})`, {
196
+ repo: slug,
197
+ issue: issue.number,
198
+ })
199
+ ctx.subject.started = { ...s, attempt: marker.attempt }
200
+ return { to: 'running', pid: s.pid, worktree: s.worktree, attempt: marker.attempt }
201
+ },
202
+ }),
203
+ { queue: Q.intake, running: false },
204
+ )
205
+
206
+ const triaging = declare(
207
+ defineWait({
208
+ name: 'triaging',
209
+ input: z.object({ attempt: z.number().int() }),
210
+ output: z.discriminatedUnion('exit', [
211
+ z.object({ exit: z.literal('triaged'), ...Verdict.shape }),
212
+ z.object({ exit: z.literal('invalid'), ...failure }),
213
+ z.object({ exit: z.literal('lost'), ...failure }),
214
+ z.object({ exit: z.literal('gone') }),
215
+ ]),
216
+ /**
217
+ * Alive and under the wall-clock cap: hold. Over it: kill. Gone: read the verdict from its stdout log; a
218
+ * missing or invalid one is `invalid`, with the error.
219
+ * @param {unknown} _ @param {DispatchCtx} ctx
220
+ */
221
+ poll: async (_, ctx) => {
222
+ const { config, store, procs, spawner } = ctx
223
+ const { slug, number, snap, issue, reaped } = ctx.subject
224
+ const w = store.worker(slug, number)
225
+ if (!w) {
226
+ const host = issue?.stateComment?.marker.host
227
+ if (host && host !== config.host) return { ready: false }
228
+ return { ready: true, output: { exit: 'lost', ...lostLeaseOf(ctx) } }
229
+ }
230
+ const caps = config.phases.dispatch
231
+ if (procs.alive(w.pid) && !reaped?.has(w.pid)) {
232
+ if (!w.killedReason && ctx.tick.now - w.startedAt <= caps.wallClockMinutes * MIN) return { ready: false }
233
+ const reason = w.killedReason ?? `killed: over the ${caps.wallClockMinutes} min wall-clock cap`
234
+ procs.kill(w.pid)
235
+ store.markKilled(w.repo, w.issue, reason)
236
+ w.killedReason = reason
237
+ ctx.log('warn', `${reason} (pid ${w.pid})`, { repo: w.repo, issue: w.issue })
238
+ }
239
+ if (!snap) return { ready: false }
240
+ if (issue?.state !== 'OPEN' || !issue.labels.includes(Q.intake)) {
241
+ ctx.log('info', 'triage worker gone; issue is closed or left q:intake', { repo: w.repo, issue: w.issue })
242
+ return { ready: true, output: { exit: 'gone' } }
243
+ }
244
+ // TRACING (follow-up): the worker has ended; emit its spans here with tracing.mjs
245
+ // `workerSpans(<w.stdout log>, { tracer, parent: <start-triage's traceparent> })`.
246
+ const read = w.killedReason ? { ok: false, error: w.killedReason } : readTriage(spawner.readLog(w.stdout), number)
247
+ if (read.ok && 'result' in read)
248
+ return { ready: true, output: { exit: 'triaged', result: read.result, log: w.stdout } }
249
+ const tail = 'error' in read && !read.error.startsWith('invalid') ? spawner.tail(w.stderr, 15) : ''
250
+ return {
251
+ ready: true,
252
+ output: {
253
+ exit: 'invalid',
254
+ reason: `${'error' in read ? read.error : 'no verdict'}${tail ? `\n--- stderr (last lines, ${w.stderr})\n${tail}` : ''}`,
255
+ outcome: w.killedReason ? 'killed' : 'invalid',
256
+ log: w.stdout,
257
+ },
258
+ }
259
+ },
260
+ }),
261
+ { queue: Q.intake, running: true },
262
+ )
263
+
264
+ const retryTriage = declare(
265
+ defineNode({
266
+ name: 'retry-triage',
267
+ input: Failure,
268
+ output: z.discriminatedUnion('to', [
269
+ z.object({ to: z.literal('start'), attempt: z.number().int() }),
270
+ z.object({ to: z.literal('human'), ...failure }),
271
+ ]),
272
+ /** Back to `q:intake` with attempt + 1, or to a human once the attempts are spent. @param {z.infer<typeof Failure>} what @param {DispatchCtx} ctx */
273
+ run: async (what, ctx) => {
274
+ const issue = issueOf(ctx)
275
+ const m = intakeMarker(issue)
276
+ const max = ctx.config.phases.dispatch.maxAttempts
277
+ if (m.attempt >= max)
278
+ return { ...what, to: 'human', reason: `${max} triage attempts spent. Last: ${what.reason}` }
279
+ await land(ctx, 'start-triage', {
280
+ ...withHistory(m, { at: iso(ctx.tick.now), attempt: m.attempt, ...what }),
281
+ attempt: m.attempt + 1,
282
+ lastFailure: what.reason,
283
+ host: null,
284
+ start: null,
285
+ input: null,
286
+ })
287
+ ctx.log('info', `triage retried (attempt ${m.attempt + 1}/${max}): ${what.reason.split('\n')[0]}`, {
288
+ repo: ctx.subject.slug,
289
+ issue: issue.number,
290
+ })
291
+ return { to: 'start', attempt: m.attempt + 1 }
292
+ },
293
+ }),
294
+ { queue: Q.intake, running: false },
295
+ )
296
+
297
+ const ToTaskIn = z.object({
298
+ reason: z.string(),
299
+ title: z.string().optional(),
300
+ acceptance: z.array(z.string()).optional(),
301
+ log: z.string(),
302
+ })
303
+ const toTask = declare(
304
+ defineNode({
305
+ name: 'to-task',
306
+ input: ToTaskIn,
307
+ output: Empty,
308
+ /**
309
+ * Actionable: the triage comment (task title and acceptance checks, when given), then the hand-off: a task-graph
310
+ * marker at its entry, attempt 1, carrying the history and `triage` for the task prompt; then `q:task`.
311
+ * The issue body is left as its author wrote it.
312
+ * @param {z.infer<typeof ToTaskIn>} t @param {DispatchCtx} ctx
313
+ */
314
+ run: async (t, ctx) => {
315
+ const { slug } = ctx.subject
316
+ const issue = issueOf(ctx)
317
+ const m = markerOf(issue)
318
+ await ctx.github.comment(slug, issue.number, triageComment(t))
319
+ const at = iso(ctx.tick.now)
320
+ await setMarker(ctx, slug, issue, {
321
+ ...newMarker({
322
+ graph: task.name,
323
+ graphVersion: task.version,
324
+ node: task.entry.node,
325
+ phase: 'task',
326
+ enteredAt: at,
327
+ traceparent: m.traceparent,
328
+ history: withHistory(m, { at, attempt: m.attempt, outcome: 'actionable', reason: t.reason, log: t.log })
329
+ .history,
330
+ }),
331
+ triage: t.title || t.acceptance?.length ? { title: t.title, acceptance: t.acceptance } : null,
332
+ })
333
+ await setLabels(ctx, slug, issue, move(issue.labels, Q.task))
334
+ ctx.tick.touched.add(key(slug, issue.number))
335
+ ctx.log('info', `triaged actionable → q:task: ${t.reason.split('\n')[0]}`, { repo: slug, issue: issue.number })
336
+ return {}
337
+ },
338
+ }),
339
+ { queue: Q.task, running: false },
340
+ )
341
+
342
+ const toHuman = declare(
343
+ defineNode({
344
+ name: 'to-human',
345
+ input: Failure,
346
+ output: Empty,
347
+ /** Into the Human Queue with `why:triage` and the reason in the state comment. @param {z.infer<typeof Failure>} what @param {DispatchCtx} ctx */
348
+ run: async (what, ctx) => {
349
+ const issue = issueOf(ctx)
350
+ const m = markerOf(issue)
351
+ await land(
352
+ ctx,
353
+ 'to-human',
354
+ {
355
+ ...withHistory(m, { at: iso(ctx.tick.now), attempt: m.attempt, ...what }),
356
+ lastFailure: what.reason,
357
+ host: null,
358
+ start: null,
359
+ input: null,
360
+ },
361
+ { extra: [WHY.triage] },
362
+ )
363
+ ctx.log('warn', `→ q:human (${WHY.triage}): ${what.reason.split('\n')[0]}`, {
364
+ repo: ctx.subject.slug,
365
+ issue: issue.number,
366
+ })
367
+ return {}
368
+ },
369
+ }),
370
+ { queue: Q.human, running: false },
371
+ )
372
+
373
+ const DupIn = z.object({ duplicateOf: z.number().int(), reason: z.string(), log: z.string() })
374
+ const closeDuplicate = declare(
375
+ defineNode({
376
+ name: 'close-duplicate',
377
+ input: DupIn,
378
+ output: Empty,
379
+ /** Out of every queue, closed as a duplicate with a link to the original. @param {z.infer<typeof DupIn>} d @param {DispatchCtx} ctx */
380
+ run: async (d, ctx) => {
381
+ const { slug } = ctx.subject
382
+ const issue = issueOf(ctx)
383
+ const m = markerOf(issue)
384
+ await land(
385
+ ctx,
386
+ 'close-duplicate',
387
+ {
388
+ ...withHistory(m, {
389
+ at: iso(ctx.tick.now),
390
+ attempt: m.attempt,
391
+ outcome: 'duplicate',
392
+ reason: d.reason,
393
+ log: d.log,
394
+ }),
395
+ host: null,
396
+ start: null,
397
+ input: null,
398
+ },
399
+ { status: 'done' },
400
+ )
401
+ const link = `https://github.com/${slug}/issues/${d.duplicateOf}`
402
+ await ctx.github.close(
403
+ slug,
404
+ issue.number,
405
+ `Duplicate of #${d.duplicateOf} (${link}). ${d.reason}\n\nClosed by cambium.`,
406
+ {
407
+ reason: 'duplicate',
408
+ },
409
+ )
410
+ issue.state = 'CLOSED'
411
+ ctx.log('info', `duplicate of #${d.duplicateOf}; closed`, { repo: slug, issue: issue.number })
412
+ return {}
413
+ },
414
+ }),
415
+ { queue: null, running: false },
416
+ )
417
+
418
+ /** @param {unknown} err */
419
+ const errText = (err) => /** @type {Error} */ (err)?.message ?? String(err)
420
+
421
+ /** The Dispatch phase. Bump `version` when a node is removed or renamed. */
422
+ export const dispatch = defineGraph({
423
+ name: 'dispatch',
424
+ version: 1,
425
+ entry: { queue: Q.intake, node: 'start-triage', input: () => ({}) },
426
+ nodes: [startTriage, triaging, retryTriage, toTask, toHuman, closeDuplicate],
427
+ edges: [
428
+ ['start-triage', 'triaging', started, (o) => ({ attempt: o.attempt })],
429
+ ['start-triage', 'to-human', budgetSpent],
430
+ ['start-triage', 'retry-triage'],
431
+ ['triaging', END, issueGone],
432
+ ['triaging', 'retry-triage', leaseLost],
433
+ ['triaging', 'to-task', actionable, (o) => ({ ...pick(o.result, ['reason', 'title', 'acceptance']), log: o.log })],
434
+ ['triaging', 'close-duplicate', duplicate, (o) => ({ ...pick(o.result, ['duplicateOf', 'reason']), log: o.log })],
435
+ ['triaging', 'to-human', needsHuman, (o) => ({ reason: o.result.reason, outcome: 'needs-human', log: o.log })],
436
+ ['triaging', 'to-human'],
437
+ ['retry-triage', 'start-triage', attemptsLeft, () => ({})],
438
+ ['retry-triage', 'to-human'],
439
+ ['to-task', END],
440
+ ['to-human', END],
441
+ ['close-duplicate', END],
442
+ ],
443
+ })
444
+
445
+ /** @param {Record<string, unknown>} o @param {string[]} keys */
446
+ const pick = (o, keys) => Object.fromEntries(keys.filter((k) => o[k] !== undefined).map((k) => [k, o[k]]))
447
+
448
+ /** @param {string} name @returns {DispatchNode} */
449
+ export function nodeOf(name) {
450
+ const node = dispatch.nodes.find((n) => n.name === name)
451
+ if (!node) throw new Error(`dispatch graph has no node "${name}"`)
452
+ return /** @type {DispatchNode} */ (node)
453
+ }
package/src/labels.mjs CHANGED
@@ -11,6 +11,7 @@ export const WHY = /** @type {const} */ ({
11
11
  budget: 'why:budget',
12
12
  reject: 'why:reject',
13
13
  approve: 'why:approve',
14
+ triage: 'why:triage',
14
15
  })
15
16
 
16
17
  /** @param {string[]} labels */
package/src/marker.mjs CHANGED
@@ -41,7 +41,9 @@
41
41
  * queued?: boolean,
42
42
  * failedSha?: string | null,
43
43
  * lastFailure?: string | null,
44
+ * triage?: { title?: string, acceptance?: string[] } | null,
44
45
  * }} Marker
46
+ * `triage`: what the dispatch graph's triage added when it handed the issue to `q:task`; the task prompt shows it.
45
47
  * @typedef {{ graph: string, entryNode: string, nodes?: Iterable<string> }} QueueOwner
46
48
  */
47
49
 
@@ -1,4 +1,11 @@
1
1
  // @ts-check
2
+ /**
3
+ * The Dispatch phase's parts: the triage worker's prompt, its typed result and how cambium reads it from the
4
+ * worker's stream-json log. The `dispatch` graph (graphs/dispatch.mjs) runs them; the legacy engine keeps the
5
+ * stub below and leaves `q:intake` alone.
6
+ */
7
+ import { z } from 'zod'
8
+
2
9
  /**
3
10
  * @typedef {{ repo: string, intake: import('../github.mjs').Issue[], capacity: number, now: number }} DispatchInput
4
11
  * @typedef {(input: DispatchInput) => Promise<{ started: number[] }>} Dispatch
@@ -10,3 +17,141 @@ export async function dispatchNotBuilt() {
10
17
  }
11
18
 
12
19
  export const DISPATCH_NOT_BUILT = 'dispatch phase is not built yet; q:intake issues wait'
20
+
21
+ /** The verdict a triage worker ends with, as the last JSON block of its final message. */
22
+ export const TriageResult = z
23
+ .object({
24
+ verdict: z.enum(['actionable', 'needs-human', 'duplicate']),
25
+ duplicateOf: z.number().int().positive().optional(),
26
+ reason: z.string().trim().min(1),
27
+ title: z.string().trim().min(1).optional(),
28
+ acceptance: z.array(z.string().trim().min(1)).optional(),
29
+ })
30
+ .refine((r) => r.verdict !== 'duplicate' || r.duplicateOf !== undefined, {
31
+ message: 'a duplicate verdict needs duplicateOf',
32
+ path: ['duplicateOf'],
33
+ })
34
+
35
+ /** @typedef {z.infer<typeof TriageResult>} Triage */
36
+
37
+ /** @param {z.core.$ZodIssue} i */
38
+ const formatIssue = (i) => (i.path.length ? `${i.path.join('.')}: ${i.message}` : i.message)
39
+
40
+ /**
41
+ * The JSON in a final message: its last fenced block, else the whole text, else its outermost `{…}`.
42
+ * @param {string} text @returns {unknown} throws a SyntaxError-like Error when there is none
43
+ */
44
+ function jsonIn(text) {
45
+ const fenced = [...text.matchAll(/```[a-zA-Z]*[ \t]*\n([\s\S]*?)```/g)].map((m) => m[1])
46
+ const candidates = fenced.length
47
+ ? [fenced[fenced.length - 1]]
48
+ : [text, text.slice(text.indexOf('{'), text.lastIndexOf('}') + 1)]
49
+ /** @type {unknown} */
50
+ let last
51
+ for (const c of candidates) {
52
+ try {
53
+ return JSON.parse(c.trim())
54
+ } catch (err) {
55
+ last = err
56
+ }
57
+ }
58
+ throw new Error(
59
+ `no JSON result in the final message (${/** @type {Error} */ (last)?.message ?? 'empty'}): ${clip(text)}`,
60
+ )
61
+ }
62
+
63
+ /** @param {string} s */
64
+ const clip = (s, n = 300) => {
65
+ const one = s.replace(/\s+/g, ' ').trim()
66
+ return one.length > n ? `${one.slice(0, n)}…` : one || '(empty)'
67
+ }
68
+
69
+ /**
70
+ * The triage verdict from a worker's stdout (`claude -p --output-format stream-json`): the last `result` event's
71
+ * `result` text, its JSON, validated by {@link TriageResult}. Anything else is an error saying what was wrong.
72
+ *
73
+ * @param {string} log the stdout log text
74
+ * @param {number} issue the triaged issue, which cannot be its own duplicate
75
+ * @returns {{ ok: true, result: Triage } | { ok: false, error: string }}
76
+ */
77
+ export function readTriage(log, issue) {
78
+ /** @type {any} */
79
+ let result = null
80
+ for (const line of log.split('\n')) {
81
+ if (!line.trim()) continue
82
+ try {
83
+ const e = JSON.parse(line)
84
+ if (e?.type === 'result') result = e
85
+ } catch {}
86
+ }
87
+ if (!result) return { ok: false, error: 'no result event in the worker log (killed, crashed or truncated)' }
88
+ if (typeof result.result !== 'string')
89
+ return { ok: false, error: `the worker ended without a final message (${result.subtype ?? 'no subtype'})` }
90
+ /** @type {unknown} */
91
+ let json
92
+ try {
93
+ json = jsonIn(result.result)
94
+ } catch (err) {
95
+ return { ok: false, error: /** @type {Error} */ (err).message }
96
+ }
97
+ const parsed = TriageResult.safeParse(json)
98
+ if (!parsed.success)
99
+ return { ok: false, error: `invalid triage result: ${parsed.error.issues.map(formatIssue).join('; ')}` }
100
+ if (parsed.data.verdict === 'duplicate' && parsed.data.duplicateOf === issue)
101
+ return { ok: false, error: `invalid triage result: duplicateOf: #${issue} cannot duplicate itself` }
102
+ return { ok: true, result: parsed.data }
103
+ }
104
+
105
+ /**
106
+ * The triage worker's prompt: one issue, one verdict. Adapted from the OpenRig seed's `inbox` and `intent-lead`
107
+ * roles and its culture (unattended, never ask and wait, CI is the acceptance gate, never `gh`).
108
+ *
109
+ * @param {{
110
+ * repo: string, baseBranch: string, issue: import('../github.mjs').Issue,
111
+ * queued: { number: number, title: string, labels: string[] }[], agentsMd: string | null,
112
+ * }} input
113
+ */
114
+ export function triagePrompt({ repo, baseBranch, issue, queued, agentsMd }) {
115
+ const others = queued
116
+ .filter((q) => q.number !== issue.number)
117
+ .map((q) => `- #${q.number} ${q.title} (${q.labels.filter((l) => l.startsWith('q:')).join(', ') || 'no queue'})`)
118
+ .join('\n')
119
+ return `You are a triage worker started by cambium, the scheduler, in a read-only checkout of ${repo} at origin/${baseBranch}.
120
+ Nobody is watching this session and nobody will answer a question: never ask one and wait. Where you would ask a human, that is your verdict (needs-human).
121
+
122
+ Your one job: decide what happens to GitHub issue #${issue.number} (below), which is waiting in the intake queue. You do not do the work. You do not edit files, commit, publish, comment, label or close anything; cambium makes every move on your verdict.
123
+
124
+ Verdicts:
125
+ - actionable: a worker could do it unattended from what is written (plus what you add), and would know when it is done. It goes to the task queue. When the issue lacks a clear task or checkable acceptance criteria, give \`title\` (an imperative task title) and \`acceptance\` (checks a reviewer can verify; CI green is always required, so do not list only that). cambium posts them on the issue and hands them to the task worker.
126
+ - needs-human: too foggy to ticket; a decision only a human can make (direction, priority, money, access, policy); information you cannot find; or work that is not a code change in this repository. \`reason\` says exactly what the human must decide or supply.
127
+ - duplicate: the same work as another issue, open or closed. \`duplicateOf\` is that issue's number (never #${issue.number}); \`reason\` says why they are the same.
128
+
129
+ How to look:
130
+ - Read the code here (Read, Glob, Grep) to judge what the change touches and whether it already exists.
131
+ - Read an issue with \`graft issue read <n>\`; search with \`graft api GET '/search/issues?q=repo:${repo}+is:issue+<words>'\`. Never \`gh\`.
132
+ - Be quick: a verdict, not an investigation. When in doubt between actionable and needs-human, choose needs-human.
133
+
134
+ End your final message with exactly one fenced JSON block, and nothing after it:
135
+ \`\`\`json
136
+ { "verdict": "actionable" | "needs-human" | "duplicate", "duplicateOf": 123, "reason": "…", "title": "…", "acceptance": ["…"] }
137
+ \`\`\`
138
+ \`duplicateOf\` only for duplicate; \`title\` and \`acceptance\` only for actionable, and optional. A missing or malformed block sends the issue to a human with the error.
139
+ ${others ? `\nOther issues in cambium's queues right now:\n${others}\n` : ''}
140
+ --- Issue #${issue.number}: ${issue.title} (${issue.url})
141
+ ${issue.body}
142
+ ${agentsMd ? `\n--- AGENTS.md (the contract a task worker will follow)\n${agentsMd}` : ''}`
143
+ }
144
+
145
+ /**
146
+ * The comment triage leaves on an actionable issue.
147
+ * @param {{ reason: string, title?: string, acceptance?: string[] }} t
148
+ */
149
+ export function triageComment({ reason, title, acceptance }) {
150
+ return [
151
+ `**Triage: actionable.** ${reason}`,
152
+ ...(title ? ['', `**Task:** ${title}`] : []),
153
+ ...(acceptance?.length ? ['', '**Acceptance checks**', ...acceptance.map((a) => `- [ ] ${a}`)] : []),
154
+ '',
155
+ '_Triaged by cambium; the task worker gets these with the issue body._',
156
+ ].join('\n')
157
+ }
@@ -32,7 +32,14 @@ ${
32
32
  }${marker.lastFailure ? `\nWhy the last attempt failed:\n\`\`\`\n${marker.lastFailure}\n\`\`\`\n` : ''}${history ? `\nHistory of this issue:\n${history}\n` : ''}
33
33
  --- Issue #${issue.number}: ${issue.title} (${issue.url})
34
34
  ${issue.body}
35
- ${agentsMd ? `\n--- AGENTS.md\n${agentsMd}` : ''}`
35
+ ${triageSection(marker.triage)}${agentsMd ? `\n--- AGENTS.md\n${agentsMd}` : ''}`
36
+ }
37
+
38
+ /** What triage added (dispatch graph), when it added anything. @param {import('../marker.mjs').Marker['triage']} t */
39
+ function triageSection(t) {
40
+ if (!t || (!t.title && !t.acceptance?.length)) return ''
41
+ const checks = (t.acceptance ?? []).map((a) => `- [ ] ${a}`).join('\n')
42
+ return `\n--- From triage (cambium's dispatch, also posted on the issue)\n${t.title ? `Task: ${t.title}\n` : ''}${checks ? `Acceptance checks:\n${checks}\n` : ''}`
36
43
  }
37
44
 
38
45
  /**
package/src/tick.mjs CHANGED
@@ -47,9 +47,10 @@ import { DISPATCH_NOT_BUILT, dispatchNotBuilt } from './phases/dispatch.mjs'
47
47
 
48
48
  /**
49
49
  * @typedef {(deps: Deps, ctx: Ctx) => Promise<void>} StepFn
50
- * @typedef {{ reconcile: StepFn, watch: StepFn, sweep: StepFn, scheduleTasks: StepFn }} Engine
50
+ * @typedef {{ reconcile: StepFn, watch: StepFn, sweep: StepFn, scheduleTasks: StepFn, scheduleDispatch?: StepFn }} Engine
51
51
  * The Task-phase steps. `config.engine` picks the legacy stage tick (this file) or the `task` graph
52
- * (graph-engine.mjs); Read, dispatch, Release and Heartbeat are shared.
52
+ * (graph-engine.mjs). The graph engine also folds the Dispatch phase into reconcile and sweep and brings its own
53
+ * `scheduleDispatch` (without one, the dispatch stub runs). Read and Heartbeat are shared.
53
54
  */
54
55
 
55
56
  /** @param {Deps} deps @returns {Ctx} */
@@ -75,7 +76,7 @@ export async function tick(deps) {
75
76
  /** @type {StepFn} */
76
77
  const schedule = async (d, c) => {
77
78
  await engine.scheduleTasks(d, c)
78
- await scheduleDispatch(d, c)
79
+ await (engine.scheduleDispatch ?? scheduleDispatch)(d, c)
79
80
  }
80
81
  /** @type {[string, StepFn][]} */
81
82
  const steps = [
@@ -339,7 +340,8 @@ async function watch(deps, ctx) {
339
340
  pr: pr.number,
340
341
  failedSha: pr.headSha,
341
342
  })
342
- if (pr.inMergeQueue && !m.queued) await setMarker(deps, slug, issue, { ...m, queued: true })
343
+ // `submitted` too: an issue whose queue label was removed by hand is still at its old stage (#38).
344
+ if (pr.inMergeQueue && !m.queued) await setMarker(deps, slug, issue, { ...m, stage: 'submitted', queued: true })
343
345
  const settled = pr.checks !== 'PENDING' && pr.checks !== 'EXPECTED'
344
346
  if (m.queued && !pr.inMergeQueue && !pr.autoMerge && settled)
345
347
  return requeue(deps, ctx, slug, issue, {
package/src/workers.mjs CHANGED
@@ -28,7 +28,10 @@ import { exec as defaultExec } from './github.mjs'
28
28
  * @typedef {{
29
29
  * repo: import('./config.mjs').Repo, convention: Convention, issue: number, attempt: number, branch: string,
30
30
  * phase: string, maxTurns: number, buildPrompt: (agentsMd: string | null) => string, foreground?: boolean,
31
+ * readOnly?: boolean,
31
32
  * }} StartSpec
33
+ * `readOnly`: a disposable checkout for a worker that only reads (triage): detached at the base branch, no
34
+ * install, hydrate or prepare, no Edit/Write; `branch` only names its directory (see {@link topicOf}).
32
35
  * @typedef {{
33
36
  * pid: number, worktree: string, stdout: string, stderr: string, prompt: string, exited: Promise<number | null>,
34
37
  * reused: string | null,
@@ -37,8 +40,9 @@ import { exec as defaultExec } from './github.mjs'
37
40
  * @typedef {{
38
41
  * convention(repo: import('./config.mjs').Repo): Convention,
39
42
  * start(spec: StartSpec): Promise<Started>,
40
- * cleanup(w: { repo: import('./config.mjs').Repo, worktree: string, branch: string }): Promise<Teardown>,
43
+ * cleanup(w: { repo: import('./config.mjs').Repo, worktree: string, branch: string, readOnly?: boolean }): Promise<Teardown>,
41
44
  * tail(path: string, lines?: number): string,
45
+ * readLog(path: string): string,
42
46
  * }} Spawner
43
47
  * @typedef {{ alive(pid: number): boolean, kill(pid: number): void }} Procs
44
48
  */
@@ -47,8 +51,26 @@ import { exec as defaultExec } from './github.mjs'
47
51
  export const WORKER_TOOLS = ['Read', 'Edit', 'Write', 'Glob', 'Grep', 'Bash']
48
52
  export const WORKER_DENIED = ['Bash(graft issue label:*)', 'Bash(graft issue edit:*)', 'Bash(gh:*)']
49
53
 
50
- /** @param {import('./config.mjs').Config} config @param {number} maxTurns */
51
- export const workerArgs = (config, maxTurns) => [
54
+ /** A read-only worker's tools: it reads code and issues; cambium makes every write on its verdict. */
55
+ export const READONLY_TOOLS = ['Read', 'Glob', 'Grep', 'Bash']
56
+ export const READONLY_DENIED = [
57
+ ...WORKER_DENIED,
58
+ 'Edit',
59
+ 'Write',
60
+ 'NotebookEdit',
61
+ 'Bash(graft publish:*)',
62
+ 'Bash(graft merge:*)',
63
+ 'Bash(graft pr:*)',
64
+ 'Bash(graft issue create:*)',
65
+ 'Bash(graft issue comment:*)',
66
+ 'Bash(graft issue close:*)',
67
+ 'Bash(graft issue assign:*)',
68
+ 'Bash(git commit:*)',
69
+ 'Bash(git push:*)',
70
+ ]
71
+
72
+ /** @param {import('./config.mjs').Config} config @param {number} maxTurns @param {{ readOnly?: boolean }} [opts] */
73
+ export const workerArgs = (config, maxTurns, { readOnly = false } = {}) => [
52
74
  '-p',
53
75
  '--output-format',
54
76
  'stream-json',
@@ -56,9 +78,9 @@ export const workerArgs = (config, maxTurns) => [
56
78
  '--max-turns',
57
79
  String(maxTurns),
58
80
  '--allowedTools',
59
- WORKER_TOOLS.join(','),
81
+ (readOnly ? READONLY_TOOLS : WORKER_TOOLS).join(','),
60
82
  '--disallowedTools',
61
- WORKER_DENIED.join(','),
83
+ (readOnly ? READONLY_DENIED : WORKER_DENIED).join(','),
62
84
  ...config.worker.args,
63
85
  ]
64
86
 
@@ -104,6 +126,15 @@ export function tailFile(path, lines = 30) {
104
126
  }
105
127
  }
106
128
 
129
+ /** A whole log file, or '' when it cannot be read. @param {string} path */
130
+ export function readLogFile(path) {
131
+ try {
132
+ return readFileSync(path, 'utf8')
133
+ } catch {
134
+ return ''
135
+ }
136
+ }
137
+
107
138
  /**
108
139
  * @param {{ config: import('./config.mjs').Config, exec?: import('./github.mjs').Exec,
109
140
  * spawnFn?: typeof spawn, stamp?: () => string }} opts
@@ -125,7 +156,8 @@ export function processSpawner({
125
156
  * @param {{ repo: import('./config.mjs').Repo, worktree: string, branch: string }} w
126
157
  * @returns {Promise<Teardown>}
127
158
  */
128
- async function teardown({ repo, worktree, branch }) {
159
+ async function teardown({ repo, worktree, branch, readOnly = false }) {
160
+ if (readOnly) return dispose(repo, worktree)
129
161
  if (!existsSync(worktree)) {
130
162
  await git(repo.path, ['worktree', 'prune']).catch(() => {})
131
163
  return { removed: true, reason: null }
@@ -147,21 +179,52 @@ export function processSpawner({
147
179
  return { removed: true, reason: null }
148
180
  }
149
181
 
182
+ /**
183
+ * A read-only checkout holds nothing of value: it is removed outright, never checked with `graft status`.
184
+ * @param {import('./config.mjs').Repo} repo @param {string} worktree @returns {Promise<Teardown>}
185
+ */
186
+ async function dispose(repo, worktree) {
187
+ if (existsSync(join(worktree, '.git'))) await git(repo.path, ['worktree', 'remove', '--force', worktree])
188
+ else {
189
+ rmSync(worktree, { recursive: true, force: true })
190
+ await git(repo.path, ['worktree', 'prune']).catch(() => {})
191
+ }
192
+ return { removed: true, reason: null }
193
+ }
194
+
150
195
  return {
151
196
  convention: (repo) => readConvention(repo.path),
152
- async start({ repo, convention, issue, attempt, branch, phase, maxTurns, buildPrompt, foreground = false }) {
197
+ async start({
198
+ repo,
199
+ convention,
200
+ issue,
201
+ attempt,
202
+ branch,
203
+ phase,
204
+ maxTurns,
205
+ buildPrompt,
206
+ foreground = false,
207
+ readOnly = false,
208
+ }) {
153
209
  const worktree = join(convention.root, topicOf(branch))
154
210
  if (config.worker.fetch) await git(repo.path, ['fetch', 'origin', repo.baseBranch])
155
211
  /** @type {string | null} */
156
212
  let reused = null
213
+ if (readOnly) await dispose(repo, worktree)
157
214
  // The same topic every attempt: a leftover is removed if GitHub holds it all, else continued in.
158
- if (existsSync(join(worktree, '.git'))) {
215
+ else if (existsSync(join(worktree, '.git'))) {
159
216
  const left = await teardown({ repo, worktree, branch })
160
217
  if (!left.removed) reused = left.reason
161
218
  } else rmSync(worktree, { recursive: true, force: true })
162
219
  if (!reused) {
163
220
  mkdirSync(dirname(worktree), { recursive: true })
164
- await git(repo.path, ['worktree', 'add', '--no-track', '-B', branch, worktree, `origin/${repo.baseBranch}`])
221
+ const at = `origin/${repo.baseBranch}`
222
+ await git(
223
+ repo.path,
224
+ readOnly
225
+ ? ['worktree', 'add', '--detach', worktree, at]
226
+ : ['worktree', 'add', '--no-track', '-B', branch, worktree, at],
227
+ )
165
228
  }
166
229
  const agentsPath = join(worktree, 'AGENTS.md')
167
230
  const agentsMd = existsSync(agentsPath) ? readFileSync(agentsPath, 'utf8') : null
@@ -179,14 +242,18 @@ export function processSpawner({
179
242
  CAMBIUM_REPO: repo.slug,
180
243
  CAMBIUM_ISSUE: String(issue),
181
244
  CAMBIUM_PHASE: phase,
182
- CAMBIUM_BRANCH: branch,
183
- CAMBIUM_PREPARE: JSON.stringify({
184
- worktree,
185
- source: repo.path,
186
- install: convention.install,
187
- hydrate: convention.hydrate,
188
- prepare: convention.prepare,
189
- }),
245
+ ...(readOnly ? {} : { CAMBIUM_BRANCH: branch }),
246
+ CAMBIUM_PREPARE: JSON.stringify(
247
+ readOnly
248
+ ? { worktree, source: repo.path, install: null, hydrate: { dirs: [], files: [] }, prepare: [] }
249
+ : {
250
+ worktree,
251
+ source: repo.path,
252
+ install: convention.install,
253
+ hydrate: convention.hydrate,
254
+ prepare: convention.prepare,
255
+ },
256
+ ),
190
257
  ...(config.worker.graftApp ? { GRAFT_APP: config.worker.graftApp } : {}),
191
258
  }
192
259
  /** @type {import('node:child_process').ChildProcess} */
@@ -194,7 +261,7 @@ export function processSpawner({
194
261
  try {
195
262
  child = spawnFn(
196
263
  process.execPath,
197
- [PREPARE_MAIN, '--', config.worker.command, ...workerArgs(config, maxTurns)],
264
+ [PREPARE_MAIN, '--', config.worker.command, ...workerArgs(config, maxTurns, { readOnly })],
198
265
  { cwd: worktree, detached: !foreground, stdio: [fds[0], fds[1], fds[2]], env },
199
266
  )
200
267
  } finally {
@@ -210,6 +277,7 @@ export function processSpawner({
210
277
  },
211
278
  cleanup: teardown,
212
279
  tail: tailFile,
280
+ readLog: readLogFile,
213
281
  }
214
282
  }
215
283