@oakgreencc/cambium 0.0.26 → 0.0.28
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 +80 -59
- package/package.json +1 -1
- package/src/cli.mjs +1 -1
- package/src/config.mjs +5 -2
- package/src/github.mjs +8 -1
- package/src/graph-engine.mjs +95 -39
- package/src/graphs/pr.mjs +420 -0
- package/src/graphs/task.mjs +61 -313
- package/src/marker.mjs +3 -1
- package/src/phases/dispatch.mjs +1 -0
- package/src/phases/task.mjs +4 -0
package/README.md
CHANGED
|
@@ -19,18 +19,18 @@ cambium status
|
|
|
19
19
|
|
|
20
20
|
## Commands
|
|
21
21
|
|
|
22
|
-
| Command
|
|
23
|
-
|
|
|
24
|
-
| `cambium start [--once]`
|
|
25
|
-
| `cambium status [--json]`
|
|
26
|
-
| `cambium pause`
|
|
27
|
-
| `cambium drain`
|
|
28
|
-
| `cambium resume`
|
|
29
|
-
| `cambium run task --issue <n> [--repo <owner/name>]`
|
|
30
|
-
| `cambium run <
|
|
31
|
-
| `cambium gc [--dry-run] [--repo <owner/name>]`
|
|
32
|
-
| `cambium install [--dry-run]`
|
|
33
|
-
| `cambium update [--check] [--version <v>]`
|
|
22
|
+
| Command | What |
|
|
23
|
+
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
24
|
+
| `cambium start [--once]` | Foreground daemon, one tick every `tickSeconds`. SIGTERM/SIGINT stop it after the current tick; workers keep running and are re-adopted on restart. One daemon per database. |
|
|
25
|
+
| `cambium status [--json]` | Mode, last tick, queue counts, workers, failed steps. Exit 1 when there is no heartbeat or it is older than 3 ticks. |
|
|
26
|
+
| `cambium pause` | Read and heartbeat only: no transitions, no starts. Running workers are left alone. |
|
|
27
|
+
| `cambium drain` | Reconcile, watch and sweep as usual; start nothing new. |
|
|
28
|
+
| `cambium resume` | Back to `running`. |
|
|
29
|
+
| `cambium run task --issue <n> [--repo <owner/name>]` | Claim one open `q:task` issue, run its worker in the foreground, then make the same transition the daemon would. |
|
|
30
|
+
| `cambium run <task | pr> --issue <n> [--repo <owner/name>] [--follow]` | `engine: "graph"` only. `pr`: the [PR graph](#the-pr-graph) for the issue's PR. `task`: Advance one issue through the graph runtime in the foreground: a `q:task` issue without a lease starts with a foreground worker; anything else resumes where its marker rests. Stops at the first wait that is not ready; `--follow` re-reads and polls every `tickSeconds` until the graph ends. |
|
|
31
|
+
| `cambium gc [--dry-run] [--repo <owner/name>]` | Collect worktrees now; `--dry-run` only reports. See [Worktree GC](#worktree-gc). |
|
|
32
|
+
| `cambium install [--dry-run]` | Write the launchd agent (`KeepAlive`, `RunAtLoad`) for `start --config <this config>`; `--dry-run` prints it. It does not call `launchctl`; it prints the command. |
|
|
33
|
+
| `cambium update [--check] [--version <v>]` | Install the latest version (or `<v>`, even an older one) from npm into this global install, then SIGTERM the launchd agent so it finishes its tick and KeepAlive starts the new version. `--check` only reports. No config file needed. See [Self-update](#self-update). |
|
|
34
34
|
|
|
35
35
|
Every command takes `--config <file>`; the default is `$CAMBIUM_CONFIG`, then `~/.cambium/config.json`.
|
|
36
36
|
|
|
@@ -38,15 +38,15 @@ Every command takes `--config <file>`; the default is `$CAMBIUM_CONFIG`, then `~
|
|
|
38
38
|
|
|
39
39
|
Each step is bounded by `stepTimeoutSeconds`. A step that throws or times out is logged and recorded in the heartbeat, and the tick moves on. Nothing waits on a worker.
|
|
40
40
|
|
|
41
|
-
1. **Read.** One GraphQL query per repo (`graft graphql`): open issues with any `q:` label, open and recently merged PRs on `agent/*` with their check rollup, merge-queue state and the issues they close. GitHub links closing references only for a PR into the default branch, so cambium also reads `Closes/Fixes/Resolves #n` from the PR body, fetching issues the first query did not read in one more. A worker's PR that names no issue (found by its branch) gets `Closes #n` added at submission.
|
|
41
|
+
1. **Read.** One GraphQL query per repo (`graft graphql`): open issues with any `q:` label, open and recently merged PRs on `agent/*` with their check rollup, merge-queue state, `mergeable`, `reviewDecision` and the issues they close. GitHub links closing references only for a PR into the default branch, so cambium also reads `Closes/Fixes/Resolves #n` from the PR body, fetching issues the first query did not read in one more. A worker's PR that names no issue (found by its branch) gets `Closes #n` added at submission.
|
|
42
42
|
2. **Reconcile.** For each tracked worker: alive and under its wall-clock cap → nothing. Over the cap → kill its process group and every descendant (Claude Code runs each Bash command in a group of its own, so a group kill alone left a test run loading the next attempt). 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.
|
|
43
|
-
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`.
|
|
43
|
+
3. **Watch** (no agent). Graph engine: the [PR graph](#the-pr-graph), once per tick for each agent PR whose CI has settled and whose issue has no Task queued or running: merge, rework, close, or `q:human`. Legacy, 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`.
|
|
44
44
|
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.
|
|
45
45
|
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)).
|
|
46
46
|
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.
|
|
47
47
|
7. **Heartbeat.** Write the state file.
|
|
48
48
|
|
|
49
|
-
A requeue is `q:task` with attempt + 1, or, once `maxAttempts` are spent, `q:human` + `why:budget`. Who merges a Task PR is the repo's `merge` setting ([
|
|
49
|
+
A requeue is `q:task` with attempt + 1, or, once `maxAttempts` are spent, `q:human` + `why:budget`. Who merges a Task PR is the repo's `merge` setting ([The PR graph](#the-pr-graph)): by default not cambium (a merge queue, auto-merge or a human); with `"merge": "green"` cambium merges it once CI is green. The other merge cambium asks for is an approved promotion PR, through `graft pr merge`; see [The release graphs](#the-release-graphs).
|
|
50
50
|
|
|
51
51
|
## State on GitHub
|
|
52
52
|
|
|
@@ -100,7 +100,7 @@ One JSON file. Everything but `repos` is optional; these are the defaults:
|
|
|
100
100
|
"stepTimeoutSeconds": 20,
|
|
101
101
|
"repos": [{ "slug": "oakgreencc/monorepo", "path": "~/OGCC/monorepo", "baseBranch": "main" }],
|
|
102
102
|
"phases": {
|
|
103
|
-
"task": { "cap": 2, "wallClockMinutes": 60, "maxTurns": 200, "maxAttempts": 3 },
|
|
103
|
+
"task": { "cap": 2, "wallClockMinutes": 60, "maxTurns": 200, "maxAttempts": 3, "maxReworks": 3 },
|
|
104
104
|
"dispatch": {
|
|
105
105
|
"cap": 0,
|
|
106
106
|
"wallClockMinutes": 15,
|
|
@@ -134,7 +134,7 @@ One JSON file. Everything but `repos` is optional; these are the defaults:
|
|
|
134
134
|
- The daemon re-reads the file before every tick, so caps, limits, `tickSeconds`, `repos`, priority labels, `release` and `worker` take effect without a restart (logged as `config reloaded: <keys>`). `host`, `engine`, `paths`, `logs` and `graft` are baked in at start: a change to them logs `restart cambium to apply` once and is not applied. A file that does not load, or has no `repos`, keeps the running config and logs one warning until it is fixed.
|
|
135
135
|
- `repos[].path` is a local clone; worktrees are added from it and `graft` runs in it.
|
|
136
136
|
- `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.
|
|
137
|
-
- `merge` (top level, or per repo in `repos[]`): who merges a Task PR. See [
|
|
137
|
+
- `merge` (top level, or per repo in `repos[]`): who merges a Task PR. See [The PR graph](#the-pr-graph).
|
|
138
138
|
- `repos[].requiredCheck` (default `"ci"`): the check whose runs on `baseBranch` say whether the base is green; `null` turns the [red-base](#red-base) gate and repair off for that repo.
|
|
139
139
|
- `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.
|
|
140
140
|
- Setting `paths.home` moves every default path under it.
|
|
@@ -261,45 +261,28 @@ The mode lives in the SQLite file (`paths.db`, table `control`), so `cambium sta
|
|
|
261
261
|
|
|
262
262
|
## The task graph
|
|
263
263
|
|
|
264
|
-
With `"engine": "graph"` the tick's Task-phase steps (Reconcile,
|
|
264
|
+
With `"engine": "graph"` the tick's Task-phase steps (Reconcile, Sweep, Schedule) drive the `task` graph (`src/graphs/task.mjs`) instead of the stage tick in `src/tick.mjs`. The default stays `"legacy"`; flipping it and deleting the legacy path is a follow-up. The task graph turns a `q:task` issue into a published PR and **ends there** (`submit`); the PR is then the [PR graph](#the-pr-graph)'s.
|
|
265
265
|
|
|
266
266
|
```mermaid
|
|
267
267
|
flowchart TD
|
|
268
268
|
start_(["q:task"])
|
|
269
269
|
n0["start-worker"]
|
|
270
270
|
n1{{"worker-running"}}
|
|
271
|
-
n2
|
|
272
|
-
n3["
|
|
273
|
-
n4
|
|
274
|
-
n5{{"merge-queue"}}
|
|
275
|
-
n6["close-out"]
|
|
276
|
-
n7["requeue"]
|
|
277
|
-
n8["to-human"]
|
|
271
|
+
n2["submit"]
|
|
272
|
+
n3["requeue"]
|
|
273
|
+
n4["to-human"]
|
|
278
274
|
end_(("end"))
|
|
279
275
|
start_ --> n0
|
|
280
276
|
n0 -->|"started"| n1
|
|
281
|
-
n0 -->|"budgetSpent"|
|
|
282
|
-
n0 -->
|
|
277
|
+
n0 -->|"budgetSpent"| n4
|
|
278
|
+
n0 --> n3
|
|
283
279
|
n1 -->|"issueGone"| end_
|
|
284
280
|
n1 -->|"submitted"| n2
|
|
285
|
-
n1 -->
|
|
286
|
-
n2
|
|
287
|
-
|
|
288
|
-
n2 -->|"green"| n3
|
|
289
|
-
n2 -->|"stalled"| n8
|
|
290
|
-
n2 --> n7
|
|
281
|
+
n1 --> n3
|
|
282
|
+
n2 --> end_
|
|
283
|
+
n3 -->|"attemptsLeft"| n0
|
|
291
284
|
n3 --> n4
|
|
292
|
-
n4
|
|
293
|
-
n4 -->|"green"| n3
|
|
294
|
-
n4 -->|"stalled"| n8
|
|
295
|
-
n4 --> n7
|
|
296
|
-
n5 -->|"merged"| n6
|
|
297
|
-
n5 -->|"stalled"| n8
|
|
298
|
-
n5 --> n7
|
|
299
|
-
n7 -->|"attemptsLeft"| n0
|
|
300
|
-
n7 --> n8
|
|
301
|
-
n6 --> end_
|
|
302
|
-
n8 --> end_
|
|
285
|
+
n4 --> end_
|
|
303
286
|
```
|
|
304
287
|
|
|
305
288
|
Generated by `toMermaid(task)`; a test keeps this copy current. Boxes are step nodes, hexagons are waits.
|
|
@@ -308,29 +291,67 @@ Generated by `toMermaid(task)`; a test keeps this copy current. Boxes are step n
|
|
|
308
291
|
| ---------------- | ---- | ----------- | --------------- |
|
|
309
292
|
| `start-worker` | step | `q:task` | no |
|
|
310
293
|
| `worker-running` | wait | `q:task` | yes |
|
|
311
|
-
| `
|
|
312
|
-
| `merge` | step | none | no |
|
|
313
|
-
| `merging` | wait | none | no |
|
|
314
|
-
| `merge-queue` | wait | none | no |
|
|
315
|
-
| `close-out` | step | none | no |
|
|
294
|
+
| `submit` | step | none | no |
|
|
316
295
|
| `requeue` | step | `q:task` | no |
|
|
317
296
|
| `to-human` | step | `q:human` | no |
|
|
318
297
|
|
|
319
298
|
- **Labels are a projection.** Each node declares its queue label and whether it holds `running`. When an issue lands on a node, the marker is written first, then the labels come from `move()` (`labels.mjs`) with that declaration.
|
|
320
|
-
- **Where a turn starts.** Reconcile polls `worker-running` for every tracked worker.
|
|
321
|
-
- **Where a turn stops.** At a wait that is not ready, on entering a wait (it is polled next tick
|
|
322
|
-
-
|
|
323
|
-
- **
|
|
299
|
+
- **Where a turn starts.** Reconcile polls `worker-running` for every tracked worker. Sweep sends a stale `running` lease to its node's `recover` (default: `requeue`). Schedule is the gate on the entry node: caps and priority pick the issues, each starts at `start-worker`.
|
|
300
|
+
- **Where a turn stops.** At a wait that is not ready, on entering a wait (it is polled next tick), on reaching `start-worker` again (only Schedule admits it), or at the end.
|
|
301
|
+
- **`submit`.** The worker exited with an open (or merged) PR: history `submitted`, `submittedAt`, the PR on the marker (`status: done`), the issue out of every queue, and `Closes #n` added to a PR found only by its branch. A worker that exits without one, or is killed at `wallClockMinutes`, is a `requeue` (attempt + 1, then `q:human` + `why:budget`).
|
|
302
|
+
- **Markers.** The graph writes marker v2 without `stage`: `node` is where the issue rests. v2 of the graph moved `ci-running`, `merge`, `merging`, `merge-queue` and `close-out` to the PR graph: a marker resting at one of them (or a stage-era `submitted`) is the PR graph's, not a restart. A marker at any other node the current version no longer has restarts at `start-worker` with a `graph-changed` history entry.
|
|
303
|
+
- **Same moves.** Every scenario in `test/tick.test.mjs` up to a PR's submission 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. Past submission the engines differ by design; those scenarios are legacy only, and `test/pr-graph.test.mjs` is the graph side.
|
|
304
|
+
|
|
305
|
+
## The PR graph
|
|
306
|
+
|
|
307
|
+
Every tick, Watch starts one turn of the `pr` graph (`src/graphs/pr.mjs`) at `assess` for each agent PR (head `agent/*`) that closes a cambium-owned issue, when
|
|
324
308
|
|
|
325
|
-
|
|
309
|
+
- the PR is merged and its issue still open (→ `close-out`), or
|
|
310
|
+
- the PR is open, its CI has settled (not `PENDING`/`EXPECTED`), and its issue has no Task queued or running: no `q:task`, `q:intake` or `q:promote`, no `running`, no tracked worker.
|
|
326
311
|
|
|
327
|
-
|
|
312
|
+
`assess` decides from the PR as the snapshot reads it, one step acts, and the turn ends. There are no waits: the next tick assesses again.
|
|
328
313
|
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
314
|
+
```mermaid
|
|
315
|
+
flowchart TD
|
|
316
|
+
start_(["start"])
|
|
317
|
+
n0["assess"]
|
|
318
|
+
n1["merge"]
|
|
319
|
+
n2["rework"]
|
|
320
|
+
n3["close-pr"]
|
|
321
|
+
n4["close-out"]
|
|
322
|
+
n5["to-human"]
|
|
323
|
+
end_(("end"))
|
|
324
|
+
start_ --> n0
|
|
325
|
+
n0 -->|"merged"| n4
|
|
326
|
+
n0 -->|"toMerge"| n1
|
|
327
|
+
n0 -->|"toRework"| n2
|
|
328
|
+
n0 -->|"toClose"| n3
|
|
329
|
+
n0 -->|"toHumanInbox"| n5
|
|
330
|
+
n0 --> end_
|
|
331
|
+
n1 -->|"needsApproval"| n5
|
|
332
|
+
n1 --> end_
|
|
333
|
+
n2 -->|"reworksSpent"| n5
|
|
334
|
+
n2 --> end_
|
|
335
|
+
n3 --> end_
|
|
336
|
+
n4 --> end_
|
|
337
|
+
n5 --> end_
|
|
338
|
+
```
|
|
332
339
|
|
|
333
|
-
|
|
340
|
+
| Node | What it does |
|
|
341
|
+
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
342
|
+
| `assess` | In order: merged → `close-out`; issue closed → `close-pr`; a newer open agent PR closes the same issue → `close-pr` (superseded); red CI, a conflict (`mergeable: CONFLICTING`) or `CHANGES_REQUESTED` → `rework`; green, clean and the repo's `merge` is `"green"`, nothing armed, no refusal on this head within 10 min → `merge`; not merged `mergeQueueMinutes` after submission → `to-human` (`why:approve`); else nothing this tick. |
|
|
343
|
+
| `merge` | Behind its base (read live, so a merge earlier in the tick counts) → `graft pr update` instead (history `branch-updated`, held like a refusal on the old head; the new head merges once its CI is green). Otherwise `graft pr merge --auto` (history `merge-armed`), so graft's merge policy decides. A refusal is recorded (`mergeRefusal`, history `merge-refused`) and asked again on a new head or after 10 min; one only a human can clear (protected paths, a base agents may not merge into, a broken policy) → `to-human` (`why:approve`). |
|
|
344
|
+
| `rework` | Back to the task graph at `start-worker` in `q:task`: attempt 1 of a fresh `maxAttempts`, `reworks` + 1, the reason (the failing checks, the conflict, the review) as `lastFailure`, the head as `failedSha` (a worker that pushes nothing new has not reworked it). The worker's prompt names the rework and the PR; it resumes the branch. Past `phases.task.maxReworks` (default 3) → `to-human` (`why:budget`). |
|
|
345
|
+
| `close-pr` | Closes the PR with the reason and `Closed by cambium.`; an open issue gets a `pr-closed` history entry. |
|
|
346
|
+
| `close-out` | Merged: marker done, out of every queue, the issue closed (`Merged in #n. Closed by cambium.`), the branch deleted. |
|
|
347
|
+
| `to-human` | `q:human` with the `why:` label and the reason as the last failure. |
|
|
348
|
+
|
|
349
|
+
- **The Human Queue is the human's.** For an issue in `q:human` the PR graph only merges a PR that is green and clean (e.g. a worker's PR published after its issue was handed over, as sektorapp/monorepo#4627 was), and not on a head a human-only refusal sent there. It never reworks or closes one.
|
|
350
|
+
- **State.** The PR graph's state is the issue's marker (`graph: "pr"`), like the task graph's; `rework` writes a task-graph marker.
|
|
351
|
+
- **Who merges.** `repos[].merge` (falling back to the top-level `merge`): `"none"` (default) leaves a green PR to a merge queue, auto-merge or a human, and stalls it to `q:human` after `mergeQueueMinutes`; `"green"` lets the PR graph merge it (needs `engine: "graph"`). Neither of our repos runs a GitHub merge queue (it costs); updating a PR that is behind before merging is the merge queue without the cost: two PRs green on the same base can be red together (sektorapp/monorepo#4624 + #4625 broke develop 8 s apart).
|
|
352
|
+
- **Foreground.** `cambium run pr --issue <n> [--follow]` runs the same turn for one issue's PR; `--follow` repeats it every `tickSeconds` until the issue is closed.
|
|
353
|
+
|
|
354
|
+
The worker prompt says who merges: "Green: stop; cambium merges the PR once CI is green" or "…the PR is merged outside this session".
|
|
334
355
|
|
|
335
356
|
## Red base
|
|
336
357
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oakgreencc/cambium",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.28",
|
|
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/cli.mjs
CHANGED
|
@@ -29,7 +29,7 @@ export const HELP = `cambium ${VERSION} — the scheduler daemon
|
|
|
29
29
|
cambium drain reconcile and watch, start no new workers
|
|
30
30
|
cambium run task --issue <n> [--repo <owner/name>]
|
|
31
31
|
claim one q:task issue, run its worker in the foreground, transition
|
|
32
|
-
cambium run <
|
|
32
|
+
cambium run <task|pr> --issue <n> [--repo <owner/name>] [--follow]
|
|
33
33
|
engine "graph": advance the issue in the foreground to the first wait
|
|
34
34
|
that is not ready; --follow keeps polling until the graph ends
|
|
35
35
|
cambium gc [--dry-run] [--repo <owner/name>]
|
package/src/config.mjs
CHANGED
|
@@ -23,13 +23,16 @@ import { join, resolve } from 'node:path'
|
|
|
23
23
|
* `requiredCheck` (default `ci`): the check whose runs on `baseBranch` say whether the base is green (see
|
|
24
24
|
* base-health.mjs); `null` turns the red-base gate and repair off for the repo.
|
|
25
25
|
* @typedef {{ cap: number, wallClockMinutes: number, maxTurns: number, maxAttempts: number }} PhaseCaps
|
|
26
|
+
* @typedef {PhaseCaps & { maxReworks: number }} TaskCaps
|
|
27
|
+
* `maxReworks`: how many times the PR graph sends one PR back to a worker (red CI, a conflict, changes
|
|
28
|
+
* requested) before it goes to `q:human`. Each rework gets a fresh `maxAttempts`.
|
|
26
29
|
* @typedef {{
|
|
27
30
|
* host: string,
|
|
28
31
|
* engine: 'legacy' | 'graph',
|
|
29
32
|
* tickSeconds: number,
|
|
30
33
|
* stepTimeoutSeconds: number,
|
|
31
34
|
* repos: Repo[],
|
|
32
|
-
* phases: { task:
|
|
35
|
+
* phases: { task: TaskCaps, dispatch: PhaseCaps & { maxRounds: number, deferHours: number, maxDefers: number } },
|
|
33
36
|
* mergeQueueMinutes: number,
|
|
34
37
|
* merge: MergePolicy,
|
|
35
38
|
* priorityLabels: string[],
|
|
@@ -61,7 +64,7 @@ export function defaults(home = DEFAULT_HOME) {
|
|
|
61
64
|
stepTimeoutSeconds: 20,
|
|
62
65
|
repos: [],
|
|
63
66
|
phases: {
|
|
64
|
-
task: { cap: 2, wallClockMinutes: 60, maxTurns: 200, maxAttempts: 3 },
|
|
67
|
+
task: { cap: 2, wallClockMinutes: 60, maxTurns: 200, maxAttempts: 3, maxReworks: 3 },
|
|
65
68
|
dispatch: {
|
|
66
69
|
cap: 0,
|
|
67
70
|
wallClockMinutes: 15,
|
package/src/github.mjs
CHANGED
|
@@ -20,7 +20,11 @@ import { BASE_FIELDS, baseHealthOf } from './base-health.mjs'
|
|
|
20
20
|
* number: number, url: string, branch: string, state: 'OPEN' | 'MERGED' | 'CLOSED', headSha: string | null,
|
|
21
21
|
* branchExists: boolean, inMergeQueue: boolean, autoMerge: boolean,
|
|
22
22
|
* checks: 'SUCCESS' | 'FAILURE' | 'ERROR' | 'PENDING' | 'EXPECTED' | null, failing: FailingCheck[], closes: number[],
|
|
23
|
+
* mergeable: 'MERGEABLE' | 'CONFLICTING' | 'UNKNOWN' | null,
|
|
24
|
+
* reviewDecision: 'APPROVED' | 'CHANGES_REQUESTED' | 'REVIEW_REQUIRED' | null, createdAt: string | null,
|
|
23
25
|
* }} PullRequest
|
|
26
|
+
* `mergeable`: GitHub's conflict check against the base (UNKNOWN while it computes). `reviewDecision`: null
|
|
27
|
+
* when the base requires no review.
|
|
24
28
|
* @typedef {{
|
|
25
29
|
* number: number, url: string, title: string, state: 'OPEN' | 'MERGED' | 'CLOSED', createdAt: string,
|
|
26
30
|
* head: string, base: string, headSha: string | null, labels: string[], approved: boolean, autoMerge: boolean,
|
|
@@ -62,7 +66,7 @@ import { BASE_FIELDS, baseHealthOf } from './base-health.mjs'
|
|
|
62
66
|
* `linkIssue`: put `Closes #<issue>` at the top of the PR's body, so the PR names the issue it closes.
|
|
63
67
|
*/
|
|
64
68
|
|
|
65
|
-
const PR_FIELDS = `number url headRefName state headRefOid isInMergeQueue body
|
|
69
|
+
const PR_FIELDS = `number url headRefName state headRefOid isInMergeQueue body mergeable reviewDecision createdAt
|
|
66
70
|
headRef { id }
|
|
67
71
|
autoMergeRequest { enabledAt }
|
|
68
72
|
closingIssuesReferences(first: 5) { nodes { ...I } }
|
|
@@ -263,6 +267,9 @@ export function normalize(data, { botLogin = null, release = null, health = null
|
|
|
263
267
|
checks: rollup?.state ?? null,
|
|
264
268
|
failing,
|
|
265
269
|
closes: [...new Set([...(p.closingIssuesReferences?.nodes ?? []).map(addIssue), ...bodyCloses(p.body)])],
|
|
270
|
+
mergeable: p.mergeable ?? null,
|
|
271
|
+
reviewDecision: p.reviewDecision ?? null,
|
|
272
|
+
createdAt: p.createdAt ?? null,
|
|
266
273
|
})
|
|
267
274
|
}
|
|
268
275
|
return {
|
package/src/graph-engine.mjs
CHANGED
|
@@ -1,27 +1,28 @@
|
|
|
1
1
|
// @ts-check
|
|
2
2
|
/**
|
|
3
|
-
* `engine: "graph"`: the Task-phase steps of the tick, driven through the `task` graph (graphs/task.mjs)
|
|
3
|
+
* `engine: "graph"`: the Task-phase steps of the tick, driven through the `task` graph (graphs/task.mjs) and the
|
|
4
|
+
* `pr` graph (graphs/pr.mjs).
|
|
4
5
|
*
|
|
5
|
-
* The tick keeps its shape (Reconcile → Watch → Sweep → Schedule)
|
|
6
|
-
* same order; each step only chooses where an issue's turn starts:
|
|
6
|
+
* The tick keeps its shape (Reconcile → Watch → Sweep → Schedule); each step only chooses where a turn starts:
|
|
7
7
|
*
|
|
8
|
-
* - Reconcile: every tracked worker's issue at `worker-running
|
|
9
|
-
* - Watch:
|
|
10
|
-
* an open
|
|
11
|
-
* merged PR goes to `close-out` from wherever the issue is.
|
|
8
|
+
* - Reconcile: every tracked worker's issue at `worker-running` (task graph, which ends at `submit`).
|
|
9
|
+
* - Watch: every agent PR paired with a cambium-owned issue, at the PR graph's `assess`: a merged one (its issue
|
|
10
|
+
* open) to close out, an open one once its CI has settled and its issue has no Task queued or running.
|
|
12
11
|
* - Sweep: a stale `running` lease runs its node's `recover` (default: `requeue`).
|
|
13
|
-
* - Schedule: the gate on the entry
|
|
12
|
+
* - Schedule: the gate on the task entry. Caps and priority pick the issues; each starts at `start-worker`.
|
|
14
13
|
*
|
|
15
14
|
* A turn ({@link drive}) advances one transition at a time and stops when it reaches the entry node again (only
|
|
16
15
|
* Schedule admits entries), when it enters a wait (polled next tick, unless the wait is `pollOnEntry`), at END,
|
|
17
16
|
* or at a wait that is not ready.
|
|
18
17
|
*/
|
|
19
18
|
import { advance, END } from './graph/index.mjs'
|
|
20
|
-
import { deleteMergedBranch,
|
|
19
|
+
import { deleteMergedBranch, prGraph } from './graphs/pr.mjs'
|
|
20
|
+
import { HANDED_OFF, inputFor, lostLeaseOf, task, TASK_QUEUES, TERMINAL } from './graphs/task.mjs'
|
|
21
|
+
import { prFor } from './phases/task.mjs'
|
|
21
22
|
import { iso, key, markerOf, setLabels, setMarker } from './issue-state.mjs'
|
|
22
23
|
import { effectivePosition, graphVersionDecision, withHistory } from './marker.mjs'
|
|
23
|
-
import { each, newCtx, staleLeases, taskCandidates,
|
|
24
|
-
import { move, Q } from './labels.mjs'
|
|
24
|
+
import { each, newCtx, staleLeases, taskCandidates, watchPairs } from './tick.mjs'
|
|
25
|
+
import { move, Q, RUNNING } from './labels.mjs'
|
|
25
26
|
import { markerTrace, turnTracer } from './tracing.mjs'
|
|
26
27
|
import { DISPATCH_STEPS } from './dispatch-engine.mjs'
|
|
27
28
|
import { trackPromotion } from './promotion.mjs'
|
|
@@ -39,18 +40,27 @@ import { trackBaseHealth } from './base-health.mjs'
|
|
|
39
40
|
/** @param {Deps} deps @param {Ctx} ctx @param {Subject} subject @returns {import('./graphs/task.mjs').TaskCtx} */
|
|
40
41
|
const taskCtx = (deps, ctx, subject) => ({ ...deps, tick: ctx, subject })
|
|
41
42
|
|
|
43
|
+
/** @param {import('./graph/define.mjs').Graph} g @param {string} name @returns {import('./graphs/task.mjs').TaskNode} */
|
|
44
|
+
function nodeIn(g, name) {
|
|
45
|
+
const node = g.nodes.find((n) => n.name === name)
|
|
46
|
+
if (!node) throw new Error(`${g.name} graph has no node "${name}"`)
|
|
47
|
+
return /** @type {import('./graphs/task.mjs').TaskNode} */ (node)
|
|
48
|
+
}
|
|
49
|
+
|
|
42
50
|
/**
|
|
43
|
-
* One issue's turn from `at
|
|
44
|
-
* tick does); a worker whose `worker-running` was left is torn down only
|
|
51
|
+
* One issue's turn from `at` in graph `g` (the task graph unless given). A node error is rethrown as the node's own
|
|
52
|
+
* error (the step logs it, as the legacy tick does); a worker whose `worker-running` was left is torn down only
|
|
53
|
+
* after the turn's writes succeeded.
|
|
45
54
|
*
|
|
46
55
|
* @param {Deps} deps @param {Ctx} ctx @param {Subject} subject @param {Position} at
|
|
56
|
+
* @param {import('./graph/define.mjs').Graph} [g]
|
|
47
57
|
* @returns {Promise<Turn>}
|
|
48
58
|
*/
|
|
49
|
-
export async function drive(deps, ctx, subject, at) {
|
|
59
|
+
export async function drive(deps, ctx, subject, at, g = task) {
|
|
50
60
|
const c = taskCtx(deps, ctx, subject)
|
|
51
61
|
const traced = turnTracer(deps.telemetry, subject, {
|
|
52
|
-
graph:
|
|
53
|
-
graphVersion:
|
|
62
|
+
graph: g.name,
|
|
63
|
+
graphVersion: g.version,
|
|
54
64
|
repo: subject.slug,
|
|
55
65
|
issue: subject.number,
|
|
56
66
|
issueBody: subject.issue?.body ?? null,
|
|
@@ -62,22 +72,22 @@ export async function drive(deps, ctx, subject, at) {
|
|
|
62
72
|
/** @type {Turn['reason']} */
|
|
63
73
|
let reason
|
|
64
74
|
for (;;) {
|
|
65
|
-
const r = await advance(
|
|
75
|
+
const r = await advance(g, pos, c, { maxTransitions: 1, instrument: traced.instrument })
|
|
66
76
|
if (r.error) throw r.error.cause instanceof Error ? r.error.cause : r.error
|
|
67
77
|
transitions.push(...r.transitions)
|
|
68
78
|
const t = r.transitions[0]
|
|
69
79
|
traced.sync()
|
|
70
|
-
if (t && t.to !== END) await
|
|
80
|
+
if (t && t.to !== END) await nodeIn(g, t.to).enter?.(t.next, c)
|
|
71
81
|
pos = { node: r.node, input: r.input }
|
|
72
82
|
if (r.reason !== 'limit') {
|
|
73
83
|
reason = r.reason === 'waiting' ? 'waiting' : 'end'
|
|
74
84
|
break
|
|
75
85
|
}
|
|
76
|
-
if (r.node ===
|
|
86
|
+
if (r.node === g.entry.node) {
|
|
77
87
|
reason = 'gated'
|
|
78
88
|
break
|
|
79
89
|
}
|
|
80
|
-
const next =
|
|
90
|
+
const next = nodeIn(g, r.node)
|
|
81
91
|
if (next.kind === 'wait' && !next.pollOnEntry) {
|
|
82
92
|
reason = 'waiting'
|
|
83
93
|
break
|
|
@@ -100,8 +110,9 @@ async function releaseWorker(deps, s) {
|
|
|
100
110
|
|
|
101
111
|
/**
|
|
102
112
|
* Where an issue rests in the task graph, from its labels and marker: the label wins (marker.mjs
|
|
103
|
-
* `effectivePosition`), a
|
|
104
|
-
* current graph version no longer has restarts at the entry (with
|
|
113
|
+
* `effectivePosition`), a node the PR graph now owns (v1's `ci-running` … `close-out`, a stage-era `submitted`)
|
|
114
|
+
* is not the task graph's, and any other node the current graph version no longer has restarts at the entry (with
|
|
115
|
+
* a `graph-changed` history note).
|
|
105
116
|
*
|
|
106
117
|
* @param {import('./github.mjs').Issue} issue @param {number} now
|
|
107
118
|
* @returns {(Position & { note?: import('./marker.mjs').HistoryEntry }) | null} null: not in the task graph
|
|
@@ -111,6 +122,7 @@ export function locate(issue, now) {
|
|
|
111
122
|
const pos = effectivePosition(issue.labels, marker, TASK_QUEUES)
|
|
112
123
|
if (!pos || pos.graph !== task.name) return null
|
|
113
124
|
if (pos.reset || !marker) return { node: task.entry.node, input: {} }
|
|
125
|
+
if (!issue.labels.includes(Q.task) && HANDED_OFF.has(pos.node)) return null
|
|
114
126
|
const v = graphVersionDecision(marker, {
|
|
115
127
|
version: task.version,
|
|
116
128
|
nodes: task.nodes.map((n) => n.name),
|
|
@@ -118,8 +130,7 @@ export function locate(issue, now) {
|
|
|
118
130
|
at: iso(now),
|
|
119
131
|
})
|
|
120
132
|
if (v.action === 'restart') return { node: v.node, input: {}, note: v.note }
|
|
121
|
-
|
|
122
|
-
return { node, input: inputFor(node, marker) }
|
|
133
|
+
return { node: pos.node, input: inputFor(pos.node, marker) }
|
|
123
134
|
}
|
|
124
135
|
|
|
125
136
|
/**
|
|
@@ -160,8 +171,20 @@ async function reconcile(deps, ctx) {
|
|
|
160
171
|
)
|
|
161
172
|
}
|
|
162
173
|
|
|
163
|
-
/**
|
|
164
|
-
const
|
|
174
|
+
/** Queues that mean a Task is still to run (or a triage, or a promotion): the PR graph leaves the PR alone. */
|
|
175
|
+
const BUSY = new Set([Q.task, Q.intake, Q.promote])
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* The PR graph may assess this pair: its CI has settled and its issue has no Task queued or running (no lease, no
|
|
179
|
+
* tracked worker). `q:human` is allowed; `assess` only takes such an issue back to merge a green PR.
|
|
180
|
+
* @param {Deps} deps @param {string} slug @param {import('./github.mjs').PullRequest} pr @param {import('./github.mjs').Issue} issue
|
|
181
|
+
*/
|
|
182
|
+
export const assessable = (deps, slug, pr, issue) =>
|
|
183
|
+
pr.state === 'OPEN' &&
|
|
184
|
+
pr.checks !== 'PENDING' &&
|
|
185
|
+
pr.checks !== 'EXPECTED' &&
|
|
186
|
+
!issue.labels.some((l) => BUSY.has(l) || l === RUNNING) &&
|
|
187
|
+
!deps.store.worker(slug, issue.number)
|
|
165
188
|
|
|
166
189
|
/** @param {Deps} deps @param {Ctx} ctx */
|
|
167
190
|
async function watch(deps, ctx) {
|
|
@@ -175,20 +198,13 @@ async function watch(deps, ctx) {
|
|
|
175
198
|
if (ctx.touched.has(key(slug, issue.number))) return
|
|
176
199
|
/** @type {Subject} */
|
|
177
200
|
const subject = { slug, number: issue.number, snap, issue, pr, deleted }
|
|
201
|
+
const entry = { node: prGraph.entry.node, input: {} }
|
|
178
202
|
if (pr.state === 'MERGED') {
|
|
179
|
-
if (issue.state === 'OPEN') await drive(deps, ctx, subject,
|
|
203
|
+
if (issue.state === 'OPEN') await drive(deps, ctx, subject, entry, prGraph)
|
|
180
204
|
else await deleteMergedBranch(taskCtx(deps, ctx, subject), pr)
|
|
181
205
|
return
|
|
182
206
|
}
|
|
183
|
-
if (
|
|
184
|
-
const at = locate(issue, ctx.now)
|
|
185
|
-
if (!at) return
|
|
186
|
-
if (at.note) return restart(deps, ctx, slug, issue, at.note)
|
|
187
|
-
if (WATCHED.has(at.node)) return drive(deps, ctx, subject, at)
|
|
188
|
-
// Out of every queue with an open PR, but resting elsewhere (a queue label removed by hand): watch the PR
|
|
189
|
-
// from where it is, as the legacy Watch does.
|
|
190
|
-
const node = markerOf(issue).queued ? 'merge-queue' : 'ci-running'
|
|
191
|
-
await drive(deps, ctx, subject, { node, input: { pr: pr.number, branch: pr.branch } })
|
|
207
|
+
if (assessable(deps, slug, pr, issue)) await drive(deps, ctx, subject, entry, prGraph)
|
|
192
208
|
},
|
|
193
209
|
([, issue]) => ({ repo: slug, issue: issue.number }),
|
|
194
210
|
)
|
|
@@ -205,7 +221,7 @@ async function sweep(deps, ctx) {
|
|
|
205
221
|
const subject = { slug, number: issue.number, snap, issue }
|
|
206
222
|
const c = taskCtx(deps, ctx, subject)
|
|
207
223
|
const at = locate(issue, ctx.now)
|
|
208
|
-
const recover = (at &&
|
|
224
|
+
const recover = (at && nodeIn(task, at.node).recover) || defaultRecover
|
|
209
225
|
await drive(deps, ctx, subject, recover(c))
|
|
210
226
|
},
|
|
211
227
|
(issue) => ({ repo: slug, issue: issue.number }),
|
|
@@ -247,7 +263,9 @@ export const GRAPH_ENGINE = {
|
|
|
247
263
|
// ---- `cambium run <graph> --issue <n> [--follow]`
|
|
248
264
|
|
|
249
265
|
/** Graphs `cambium run` knows, by name. */
|
|
250
|
-
export const GRAPHS = { [task.name]: task }
|
|
266
|
+
export const GRAPHS = { [task.name]: task, [prGraph.name]: prGraph }
|
|
267
|
+
|
|
268
|
+
export { prGraph }
|
|
251
269
|
|
|
252
270
|
/**
|
|
253
271
|
* The graph runtime in the foreground for one issue. A `q:task` issue without a lease starts at the entry with a
|
|
@@ -264,6 +282,7 @@ export const GRAPHS = { [task.name]: task }
|
|
|
264
282
|
export async function runIssue(deps, { graph, slug, number, follow = false, out, sleep = delay, signal }) {
|
|
265
283
|
if (!Object.hasOwn(GRAPHS, graph))
|
|
266
284
|
return { ok: false, error: `unknown graph "${graph}"; known: ${Object.keys(GRAPHS).join(', ')}` }
|
|
285
|
+
if (graph === prGraph.name) return runPr(deps, { slug, number, follow, out, sleep, signal })
|
|
267
286
|
/** @type {Set<number>} */
|
|
268
287
|
const reaped = new Set()
|
|
269
288
|
let first = true
|
|
@@ -284,7 +303,13 @@ export async function runIssue(deps, { graph, slug, number, follow = false, out,
|
|
|
284
303
|
? { node: 'worker-running', input: { branch: worker.branch, attempt: worker.attempt } }
|
|
285
304
|
: locate(issue, ctx.now)
|
|
286
305
|
if (!located || TERMINAL.has(located.node)) {
|
|
287
|
-
if (first)
|
|
306
|
+
if (first)
|
|
307
|
+
return {
|
|
308
|
+
ok: false,
|
|
309
|
+
error: `${slug}#${number} has nothing to run in the ${graph} graph${
|
|
310
|
+
located ? '' : `; a submitted PR is the pr graph's: cambium run pr --issue ${number}`
|
|
311
|
+
}`,
|
|
312
|
+
}
|
|
288
313
|
return report(out, slug, number, issue)
|
|
289
314
|
}
|
|
290
315
|
if (located.note) await restart(deps, ctx, slug, issue, located.note)
|
|
@@ -309,6 +334,37 @@ export async function runIssue(deps, { graph, slug, number, follow = false, out,
|
|
|
309
334
|
}
|
|
310
335
|
}
|
|
311
336
|
|
|
337
|
+
/**
|
|
338
|
+
* `cambium run pr --issue N [--follow]`: the PR graph for the issue's agent PR, as Watch would run it: one turn
|
|
339
|
+
* when its CI has settled and no Task is queued or running, else a report. `--follow` re-reads every `tickSeconds`
|
|
340
|
+
* until the issue is closed.
|
|
341
|
+
* @param {Deps} deps
|
|
342
|
+
* @param {{ slug: string, number: number, follow: boolean, out: (line: string) => void, sleep: (ms: number) => Promise<void>, signal?: AbortSignal }} o
|
|
343
|
+
* @returns {Promise<{ ok: boolean, error?: string }>}
|
|
344
|
+
*/
|
|
345
|
+
async function runPr(deps, { slug, number, follow, out, sleep, signal }) {
|
|
346
|
+
for (let first = true; ; first = false) {
|
|
347
|
+
const ctx = newCtx(deps)
|
|
348
|
+
const snap = await deps.github.read(slug)
|
|
349
|
+
ctx.snaps.set(slug, snap)
|
|
350
|
+
const issue = snap.issues.get(number)
|
|
351
|
+
const pr = issue ? prFor(snap, { issue: number, branch: issue.stateComment?.marker.branch ?? null }) : null
|
|
352
|
+
if (first && (!issue || !pr)) return { ok: false, error: `${slug}#${number} has no agent PR to assess` }
|
|
353
|
+
if (issue && pr && issue.stateComment) {
|
|
354
|
+
/** @type {Subject} */
|
|
355
|
+
const subject = { slug, number, snap, issue, pr }
|
|
356
|
+
const entry = { node: prGraph.entry.node, input: {} }
|
|
357
|
+
if ((pr.state === 'MERGED' && issue.state === 'OPEN') || assessable(deps, slug, pr, issue)) {
|
|
358
|
+
const turn = await drive(deps, ctx, subject, entry, prGraph)
|
|
359
|
+
out(`PR #${pr.number}: ${turn.transitions.map((t) => String(t.to)).join(' → ') || 'assessed'}`)
|
|
360
|
+
} else out(`PR #${pr.number}: not assessed (CI ${pr.checks ?? 'none'}, ${pr.state.toLowerCase()})`)
|
|
361
|
+
}
|
|
362
|
+
if (!follow || issue?.state !== 'OPEN' || signal?.aborted) return report(out, slug, number, issue)
|
|
363
|
+
await sleep(deps.config.tickSeconds * 1000)
|
|
364
|
+
if (signal?.aborted) return report(out, slug, number, issue)
|
|
365
|
+
}
|
|
366
|
+
}
|
|
367
|
+
|
|
312
368
|
/** @param {number} ms */
|
|
313
369
|
const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
|
|
314
370
|
|