@oakgreencc/cambium 0.0.36 → 0.0.38
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 +15 -7
- package/package.json +1 -1
- package/src/dispatch-engine.mjs +139 -5
- package/src/github.mjs +31 -5
- package/src/graphs/dispatch.mjs +119 -20
- package/src/human-reply.mjs +78 -0
- package/src/labels.mjs +10 -1
- package/src/marker.mjs +10 -2
- package/src/phases/dispatch.mjs +45 -6
package/README.md
CHANGED
|
@@ -40,11 +40,11 @@ Every command takes `--config <file>`; the default is `$CAMBIUM_CONFIG`, then `~
|
|
|
40
40
|
|
|
41
41
|
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.
|
|
42
42
|
|
|
43
|
-
1. **Read.** One GraphQL query per repo (`graft graphql`): open issues with any `q:` label (100 per page; more pages follow the cursor, so a busy queue's newest issues are not invisible), 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 (also the issue an open PR that closes none names by its branch, `agent/<n>-…`, for the [reaper](#upkeep)). A worker's PR that names no issue (found by its branch) gets `Closes #n` added at submission.
|
|
43
|
+
1. **Read.** One GraphQL query per repo (`graft graphql`): open issues with any `q:` label (100 per page; more pages follow the cursor, so a busy queue's newest issues are not invisible), open and recently merged PRs on `agent/*` with their check rollup, merge-queue state, `mergeable`, `reviewDecision` and the issues they close. Each issue's newest 20 comments come with their time and author type, for [human replies](#the-dispatch-graph). 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 (also the issue an open PR that closes none names by its branch, `agent/<n>-…`, for the [reaper](#upkeep)). A worker's PR that names no issue (found by its branch) gets `Closes #n` added at submission.
|
|
44
44
|
2. **Reconcile.** For each tracked worker: alive and under its wall-clock cap → nothing. Over the cap → terminate it: every process below `claude` (its Bash tools, a test run) is SIGKILLed at once, and `claude` gets SIGTERM, on which Claude Code ends its interaction span and flushes its exporter (a bare SIGKILL left `claude_code.*` spans orphaned under a root that was never exported). It usually exits within a second; still alive 30 s past the cap (and at least one tick later) → 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 and no process has its cwd inside it (`lsof`; the worktree's own nx daemon excepted), else kept with a `warn` saying why. Teardown stops the worktree's nx daemon (nx keys each daemon to its workspace root, so no other checkout's is touched; left running, it served the next client from a deleted tree until `nx reset`), moves the tree to `<paths.home>/trash` with one rename, prunes git's record, and erases the trash in the background: a worktree with CocoaPods in it took `git worktree remove` past the step timeout.
|
|
45
45
|
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`.
|
|
46
46
|
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.
|
|
47
|
-
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)).
|
|
47
|
+
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`, first wake `q:human` and parked intake issues that have a human reply, then start triage workers for `q:intake` issues the same way ([the dispatch graph](#the-dispatch-graph)).
|
|
48
48
|
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.
|
|
49
49
|
7. **Upkeep** (graph engine). The hourly [reaper](#upkeep) of untracked agent PRs, then the daily [re-triage](#upkeep) of `q:human`.
|
|
50
50
|
8. **Heartbeat.** Write the state file.
|
|
@@ -395,7 +395,8 @@ flowchart TD
|
|
|
395
395
|
n4["to-human"]
|
|
396
396
|
n5["close-duplicate"]
|
|
397
397
|
n6["deferred"]
|
|
398
|
-
n7["
|
|
398
|
+
n7["blocked"]
|
|
399
|
+
n8["close-obsolete"]
|
|
399
400
|
end_(("end"))
|
|
400
401
|
start_ --> n0
|
|
401
402
|
n0 -->|"started"| n1
|
|
@@ -406,7 +407,8 @@ flowchart TD
|
|
|
406
407
|
n1 -->|"actionable"| n3
|
|
407
408
|
n1 -->|"duplicate"| n5
|
|
408
409
|
n1 -->|"defer"| n6
|
|
409
|
-
n1 -->|"
|
|
410
|
+
n1 -->|"blocked"| n7
|
|
411
|
+
n1 -->|"obsolete"| n8
|
|
410
412
|
n1 -->|"needsHuman"| n4
|
|
411
413
|
n1 --> n4
|
|
412
414
|
n2 -->|"attemptsLeft"| n0
|
|
@@ -416,7 +418,9 @@ flowchart TD
|
|
|
416
418
|
n5 --> end_
|
|
417
419
|
n6 -->|"budgetSpent"| n4
|
|
418
420
|
n6 --> end_
|
|
421
|
+
n7 -->|"noneOpen"| n6
|
|
419
422
|
n7 --> end_
|
|
423
|
+
n8 --> end_
|
|
420
424
|
```
|
|
421
425
|
|
|
422
426
|
| Node | Kind | Queue label | Holds `running` |
|
|
@@ -428,13 +432,17 @@ flowchart TD
|
|
|
428
432
|
| `to-human` | step | `q:human` | no |
|
|
429
433
|
| `close-duplicate` | step | none | no |
|
|
430
434
|
| `deferred` | step | `q:intake` | no |
|
|
435
|
+
| `blocked` | step | `q:intake` | no |
|
|
431
436
|
| `close-obsolete` | step | none | no |
|
|
432
437
|
|
|
433
|
-
- **The verdict.** The worker's final message must end with a JSON block, validated by zod (`TriageResult`): `{ verdict: 'actionable' | 'needs-human' | 'duplicate' | 'obsolete' | 'defer', duplicateOf?, recheckHours?, 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).
|
|
434
|
-
- **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>`. `obsolete` (the work no longer applies, verified: the code path is gone, already fixed, its check already passed) → closed as `not_planned` with `Obsolete: <reason>`. `defer` → stays in `q:intake` at `deferred` (see below). 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.
|
|
438
|
+
- **The verdict.** The worker's final message must end with a JSON block, validated by zod (`TriageResult`): `{ verdict: 'actionable' | 'needs-human' | 'duplicate' | 'obsolete' | 'defer' | 'blocked', duplicateOf?, blockedBy?, recheckHours?, reason, title?, acceptance? }` (`duplicateOf` is required on a duplicate and cannot be the issue itself; `blockedBy`, issue numbers, likewise on blocked). cambium reads it from the worker's stdout log: the last `result` event's `result` text, its last fenced block (else the bare JSON).
|
|
439
|
+
- **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>`. `obsolete` (the work no longer applies, verified: the code path is gone, already fixed, its check already passed) → closed as `not_planned` with `Obsolete: <reason>`. `defer` → stays in `q:intake` at `deferred`, `blocked` → stays in `q:intake` at `blocked` (see below). 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.
|
|
435
440
|
- **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).
|
|
436
441
|
- **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.
|
|
437
|
-
- **Defer, not a human.** A verdict that hangs on something a machine can check later (a CD run that has not happened, a release, a merge, a deploy) is `defer`, never `needs-human`: asking a human to verify what a machine can is what the factory exists to avoid. The issue rests at `deferred` with `deferUntil` (now + `recheckHours`, else `phases.dispatch.deferHours`, default 6) and `deferReason` in its marker; Schedule skips it until then, and the next triage gets the reason in its prompt ("check it now"). A defer is not a failed attempt. A deferred issue whose GitHub "blocked by" issues are all closed, at least one after it was deferred, is triaged again at the next tick instead of waiting for `deferUntil`. After `phases.dispatch.maxDefers` (default 8) it goes to `q:human` + `why:triage` with the last reason.
|
|
442
|
+
- **Defer, not a human.** A verdict that hangs on something a machine can check later (a CD run that has not happened, a release, a merge, a deploy) is `defer`, never `needs-human`: asking a human to verify what a machine can is what the factory exists to avoid. The issue rests at `deferred` with `deferUntil` (now + `recheckHours`, else `phases.dispatch.deferHours`, default 6) and `deferReason` in its marker; Schedule skips it until then, and the next triage gets the reason in its prompt ("check it now"). A defer is not a failed attempt. A deferred issue whose GitHub "blocked by" issues are all closed, at least one after it was deferred, is triaged again at the next tick instead of waiting for `deferUntil`. After `phases.dispatch.maxDefers` (default 8) it goes to `q:human` + `why:triage` with the last reason. While it waits it carries `wait:deferred`.
|
|
443
|
+
- **Blocked by issues, not a timer.** A verdict that waits on other issues is `blocked` with `blockedBy: [n, …]`. cambium adds each as a GitHub "blocked by" link on the issue when it is missing, then parks it at `blocked` with `wait:blocked`, the open blockers in the marker's `blockedBy` and no `deferUntil`. Schedule never triages an intake issue with an open `blockedBy` issue, whoever linked it: one not yet at `blocked` (new, or deferred) is parked there first. The tick after the last blocker closes, the label comes off and the issue is triaged again, its earlier reason in the prompt. A blocked wait is not a defer and does not count toward `maxDefers`; a `blocked` verdict none of whose issues is open (closed, or the link failed) is a defer.
|
|
444
|
+
- **`wait:*` labels.** Intake holds two kinds of issue: awaiting triage, and parked by it. `wait:deferred` and `wait:blocked` mark the parked ones (canopy shows them apart from Intake); Schedule adds or removes them each tick to match the marker and the blockers, and any queue move drops them.
|
|
445
|
+
- **A human reply wakes it.** Canopy's Inbox is read-only, so a human answers by commenting on the issue. A _human reply_ is a comment written after the issue entered its current state (the later of the marker's `enteredAt` and its last history `at`) whose author is not `graft.botLogin`, not the login that wrote the state comment, and not a `Bot`-type account; a comment carrying a state marker never counts. Read takes each issue's newest 20 comments with their `createdAt` and author type (`src/human-reply.mjs`). At Schedule, before parking: a `q:human` issue with any `why:*` but `why:approve` (as re-triage), no `running` and no tracked worker, with a human reply, goes back to `q:intake` without its `why:*`, at `start-triage`, attempt 1, history kept with a `human-reply` entry, and is triaged in the same tick when a slot is free. A parked issue (`deferred` / `blocked`) with a human reply is triaged now, whatever its `deferUntil` or open blockers: the human may be saying it is not waiting on anything. The triage prompt quotes the replies since the issue last waited (author, time, body; the newest 5, each cut at 2000 characters) as the answer to the needs-human, defer or blocked reason, which it quotes too; the rubric says such a reply usually makes it actionable, folded into `title` / `acceptance`, and needs-human again (saying what is still missing) if it leaves the question open. The marker carries that context (`reply`) until triage lands a verdict. No loops: cambium's own comments never count, and the verdict starts a new state, so a triage that answers needs-human again rests until the next human reply or the daily re-triage. The daily re-triage and a hand move to `q:intake` get the same quoting.
|
|
438
446
|
- **Leaving intake.** If the issue is closed or relabelled while triage runs, the verdict is dropped and the checkout removed.
|
|
439
447
|
- **Tracing.** Wired as in the task graph (see [Tracing](#tracing)): the driver's node and wait spans under a `cambium.issue` root that continues mycelium's intake span from the issue body, the triage worker's `TRACEPARENT` (its `start-triage` span), and its stream-json spans when `triaging` ends.
|
|
440
448
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oakgreencc/cambium",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.38",
|
|
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/dispatch-engine.mjs
CHANGED
|
@@ -5,15 +5,24 @@
|
|
|
5
5
|
*
|
|
6
6
|
* - Reconcile: every tracked triage worker's issue at `triaging`.
|
|
7
7
|
* - Sweep: a stale `running` lease on a `q:intake` issue runs `retry-triage`.
|
|
8
|
-
* - Schedule: `q:
|
|
9
|
-
*
|
|
8
|
+
* - Schedule: first wakes: a `q:human` issue (not `why:approve`) without a lease that has a human reply since it
|
|
9
|
+
* entered its state (human-reply.mjs) goes back to `q:intake` at `start-triage`, attempt 1, history kept (outcome
|
|
10
|
+
* `human-reply`); a parked intake issue (`deferred` / `blocked`) with one is triaged now, whatever its blockers or
|
|
11
|
+
* `deferUntil`. Then parks: a `q:intake` issue without a lease that has an open GitHub `blockedBy` issue goes to the
|
|
12
|
+
* `blocked` node (`wait:blocked`) if it is not there yet, and every other one gets the `wait:*` label its marker
|
|
13
|
+
* calls for (`wait:deferred` while its `deferUntil` is ahead, none once due or unblocked). Then `q:intake` issues
|
|
14
|
+
* without a lease, by priority then age, up to `phases.dispatch.cap` counted from live triage workers, skipping
|
|
15
|
+
* one deferred until later or blocked; each starts at `start-triage`.
|
|
10
16
|
*
|
|
11
17
|
* A turn advances one transition at a time and stops on entering a wait, at the entry node again (only Schedule
|
|
12
18
|
* admits entries), at a wait that is not ready, or at the end.
|
|
13
19
|
*/
|
|
14
20
|
import { advance } from './graph/index.mjs'
|
|
15
|
-
import { dispatch, lostLeaseOf, nodeOf } from './graphs/dispatch.mjs'
|
|
16
|
-
import {
|
|
21
|
+
import { dispatch, lostLeaseOf, nodeOf, openBlockers } from './graphs/dispatch.mjs'
|
|
22
|
+
import { iso, key, markerOf, setLabels, setMarker } from './issue-state.mjs'
|
|
23
|
+
import { byPriorityThenAge, move, Q, RUNNING, WAIT, WHY } from './labels.mjs'
|
|
24
|
+
import { newMarker, withHistory } from './marker.mjs'
|
|
25
|
+
import { humanReplies, stateSince } from './human-reply.mjs'
|
|
17
26
|
import { each, staleLeases } from './tick.mjs'
|
|
18
27
|
import { markerTrace, turnTracer } from './tracing.mjs'
|
|
19
28
|
|
|
@@ -120,7 +129,7 @@ export function intakeCandidates(deps, ctx) {
|
|
|
120
129
|
issue.labels.includes(Q.intake) &&
|
|
121
130
|
!issue.labels.includes(RUNNING) &&
|
|
122
131
|
!store.worker(slug, issue.number) &&
|
|
123
|
-
!deferredPast(issue, ctx.now)
|
|
132
|
+
(replied(deps, issue) || (!deferredPast(issue, ctx.now) && !openBlockers(issue).length))
|
|
124
133
|
)
|
|
125
134
|
candidates.push({ slug, issue, snap })
|
|
126
135
|
const order = byPriorityThenAge(config.priorityLabels)
|
|
@@ -141,6 +150,68 @@ const deferredPast = (issue, now) => {
|
|
|
141
150
|
return !unblockedSince(issue.blockedBy ?? [], m.enteredAt)
|
|
142
151
|
}
|
|
143
152
|
|
|
153
|
+
/**
|
|
154
|
+
* The `q:intake` issues at rest (no `running`, no tracked worker), whatever the cap: these are parked or unparked.
|
|
155
|
+
* @param {Deps} deps @param {Ctx} ctx
|
|
156
|
+
*/
|
|
157
|
+
function restingIntake(deps, ctx) {
|
|
158
|
+
/** @type {{ slug: string, issue: import('./github.mjs').Issue, snap: import('./github.mjs').Snapshot }[]} */
|
|
159
|
+
const out = []
|
|
160
|
+
for (const [slug, snap] of ctx.snaps)
|
|
161
|
+
for (const issue of snap.issues.values())
|
|
162
|
+
if (
|
|
163
|
+
issue.state === 'OPEN' &&
|
|
164
|
+
issue.labels.includes(Q.intake) &&
|
|
165
|
+
!issue.labels.includes(RUNNING) &&
|
|
166
|
+
!deps.store.worker(slug, issue.number)
|
|
167
|
+
)
|
|
168
|
+
out.push({ slug, issue, snap })
|
|
169
|
+
return out
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
/**
|
|
173
|
+
* The `wait:*` label a resting `q:intake` issue should carry, open blockers aside: `wait:deferred` while its
|
|
174
|
+
* `deferUntil` is ahead, else none (it awaits triage).
|
|
175
|
+
* @param {import('./github.mjs').Issue} issue @param {number} now
|
|
176
|
+
*/
|
|
177
|
+
const waitLabelOf = (issue, now) => (deferredPast(issue, now) ? WAIT.deferred : null)
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* Park and unpark: an issue with an open `blockedBy` goes to the `blocked` node unless it rests there already with
|
|
181
|
+
* `wait:blocked`; any other gets the `wait:*` label {@link waitLabelOf} says, and loses the rest.
|
|
182
|
+
* @param {Deps} deps @param {Ctx} ctx
|
|
183
|
+
*/
|
|
184
|
+
async function park(deps, ctx) {
|
|
185
|
+
await each(
|
|
186
|
+
deps,
|
|
187
|
+
restingIntake(deps, ctx),
|
|
188
|
+
async (c) => {
|
|
189
|
+
const { issue } = c
|
|
190
|
+
if (replied(deps, issue)) return
|
|
191
|
+
const open = openBlockers(issue)
|
|
192
|
+
const m = issue.stateComment?.marker
|
|
193
|
+
const atBlocked = m?.graph === dispatch.name && m.node === 'blocked'
|
|
194
|
+
if (open.length) {
|
|
195
|
+
if (atBlocked && issue.labels.includes(WAIT.blocked)) return
|
|
196
|
+
const subject = { slug: c.slug, number: issue.number, snap: c.snap, issue }
|
|
197
|
+
const reason =
|
|
198
|
+
m?.graph === dispatch.name && m.node === 'deferred' && m.deferReason
|
|
199
|
+
? m.deferReason
|
|
200
|
+
: `GitHub shows it blocked by ${open.map((n) => `#${n}`).join(', ')}.`
|
|
201
|
+
await driveDispatch(deps, ctx, subject, { node: 'blocked', input: { blockedBy: open, reason } })
|
|
202
|
+
return
|
|
203
|
+
}
|
|
204
|
+
const want = waitLabelOf(issue, ctx.now)
|
|
205
|
+
const has = issue.labels.filter((l) => l.startsWith('wait:'))
|
|
206
|
+
await setLabels(deps, c.slug, issue, {
|
|
207
|
+
add: want && !has.includes(want) ? [want] : [],
|
|
208
|
+
remove: has.filter((l) => l !== want),
|
|
209
|
+
})
|
|
210
|
+
},
|
|
211
|
+
(c) => ({ repo: c.slug, issue: c.issue.number }),
|
|
212
|
+
)
|
|
213
|
+
}
|
|
214
|
+
|
|
144
215
|
/**
|
|
145
216
|
* All blockers closed, at least one after `since`.
|
|
146
217
|
* @param {import('./github.mjs').Blocker[]} blockers @param {string | null} since
|
|
@@ -150,8 +221,71 @@ const unblockedSince = (blockers, since) =>
|
|
|
150
221
|
blockers.every((b) => b.state === 'CLOSED') &&
|
|
151
222
|
blockers.some((b) => !since || (!!b.closedAt && Date.parse(b.closedAt) > Date.parse(since)))
|
|
152
223
|
|
|
224
|
+
/**
|
|
225
|
+
* Parked at `deferred` or `blocked` with a human reply since: the human may be saying it is not waiting on anything,
|
|
226
|
+
* so triage looks now. Starting triage moves the marker on, so the same reply wakes it once.
|
|
227
|
+
* @param {Deps} deps @param {import('./github.mjs').Issue} issue
|
|
228
|
+
*/
|
|
229
|
+
function replied(deps, issue) {
|
|
230
|
+
const m = issue.stateComment?.marker
|
|
231
|
+
if (!(m?.graph === dispatch.name && (m.node === 'deferred' || m.node === 'blocked'))) return false
|
|
232
|
+
return humanReplies(issue, { since: stateSince(m), botLogin: deps.config.graft.botLogin }).length > 0
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/**
|
|
236
|
+
* Wake: every `q:human` issue (any `why:*` but `why:approve`, as re-triage) with no lease, no tracked worker and a
|
|
237
|
+
* human reply since it entered its state goes back to `q:intake` at `start-triage`, attempt 1, its history kept with
|
|
238
|
+
* a `human-reply` entry and the `reply` context the triage prompt quotes. The new state starts now, so the same
|
|
239
|
+
* reply never wakes it again: a triage that answers needs-human again rests until the next reply.
|
|
240
|
+
* @param {Deps} deps @param {Ctx} ctx
|
|
241
|
+
*/
|
|
242
|
+
async function wake(deps, ctx) {
|
|
243
|
+
const botLogin = deps.config.graft.botLogin
|
|
244
|
+
for (const [slug, snap] of ctx.snaps)
|
|
245
|
+
await each(
|
|
246
|
+
deps,
|
|
247
|
+
[...snap.issues.values()].filter(
|
|
248
|
+
(i) =>
|
|
249
|
+
i.state === 'OPEN' &&
|
|
250
|
+
i.labels.includes(Q.human) &&
|
|
251
|
+
!i.labels.includes(WHY.approve) &&
|
|
252
|
+
!i.labels.includes(RUNNING) &&
|
|
253
|
+
!deps.store.worker(slug, i.number) &&
|
|
254
|
+
!ctx.touched.has(key(slug, i.number)),
|
|
255
|
+
),
|
|
256
|
+
async (issue) => {
|
|
257
|
+
const m = markerOf(issue)
|
|
258
|
+
const since = stateSince(issue.stateComment?.marker)
|
|
259
|
+
const replies = humanReplies(issue, { since, botLogin })
|
|
260
|
+
if (!since || !replies.length) return
|
|
261
|
+
const at = iso(ctx.now)
|
|
262
|
+
const who = [...new Set(replies.map((r) => `@${r.author}`))].join(', ')
|
|
263
|
+
await setMarker(deps, slug, issue, {
|
|
264
|
+
...newMarker({
|
|
265
|
+
graph: dispatch.name,
|
|
266
|
+
graphVersion: dispatch.version,
|
|
267
|
+
node: dispatch.entry.node,
|
|
268
|
+
phase: 'dispatch',
|
|
269
|
+
enteredAt: at,
|
|
270
|
+
traceparent: m.traceparent,
|
|
271
|
+
history: withHistory(m, { at, attempt: m.attempt, outcome: 'human-reply', reason: `reply from ${who}` })
|
|
272
|
+
.history,
|
|
273
|
+
}),
|
|
274
|
+
reply: { since, question: m.lastFailure ?? m.history.at(-1)?.reason ?? null },
|
|
275
|
+
})
|
|
276
|
+
await setLabels(deps, slug, issue, move(issue.labels, Q.intake))
|
|
277
|
+
ctx.touched.add(key(slug, issue.number))
|
|
278
|
+
deps.log('info', `human reply from ${who}: q:human → q:intake for triage`, { repo: slug, issue: issue.number })
|
|
279
|
+
},
|
|
280
|
+
(issue) => ({ repo: slug, issue: issue.number }),
|
|
281
|
+
)
|
|
282
|
+
}
|
|
283
|
+
|
|
153
284
|
/** @param {Deps} deps @param {Ctx} ctx */
|
|
154
285
|
async function schedule(deps, ctx) {
|
|
286
|
+
if (deps.config.phases.dispatch.cap <= 0) return
|
|
287
|
+
await wake(deps, ctx)
|
|
288
|
+
await park(deps, ctx)
|
|
155
289
|
await each(
|
|
156
290
|
deps,
|
|
157
291
|
intakeCandidates(deps, ctx),
|
package/src/github.mjs
CHANGED
|
@@ -13,9 +13,13 @@ import { BASE_FIELDS, baseHealthOf } from './base-health.mjs'
|
|
|
13
13
|
/**
|
|
14
14
|
* @typedef {{
|
|
15
15
|
* number: number, title: string, url: string, state: 'OPEN' | 'CLOSED', createdAt: string, body: string,
|
|
16
|
-
* labels: string[], stateComment: { id: number, marker: import('./marker.mjs').Marker } | null,
|
|
17
|
-
* blockedBy: Blocker[],
|
|
16
|
+
* labels: string[], stateComment: { id: number, marker: import('./marker.mjs').Marker, author?: string | null } | null,
|
|
17
|
+
* blockedBy: Blocker[], comments?: Comment[],
|
|
18
18
|
* }} Issue
|
|
19
|
+
* `stateComment.author`: the login that wrote the state comment (cambium's). `comments`: the newest 20, oldest
|
|
20
|
+
* first, for human-reply detection (human-reply.mjs).
|
|
21
|
+
* @typedef {{ author: string | null, bot: boolean, createdAt: string, body: string }} Comment
|
|
22
|
+
* `bot`: GitHub says the author is a `Bot` (an App).
|
|
19
23
|
* @typedef {{ number: number, state: 'OPEN' | 'CLOSED', closedAt: string | null }} Blocker
|
|
20
24
|
* An issue GitHub records as blocking this one (the "blocked by" relationship).
|
|
21
25
|
* @typedef {{ name: string, url: string | null, summary: string }} FailingCheck
|
|
@@ -64,10 +68,12 @@ import { BASE_FIELDS, baseHealthOf } from './base-health.mjs'
|
|
|
64
68
|
* behindBase(slug: string, number: number): Promise<{ behind: number, base: string }>,
|
|
65
69
|
* updatePull(slug: string, number: number): Promise<void>,
|
|
66
70
|
* linkIssue(slug: string, pr: number, issue: number): Promise<void>,
|
|
71
|
+
* addBlockedBy(slug: string, number: number, blocker: number): Promise<{ state: 'OPEN' | 'CLOSED' }>,
|
|
67
72
|
* }} GitHub
|
|
68
73
|
* `behindBase`: how many commits of its base the PR's head lacks, read live (not from the tick's snapshot), so a
|
|
69
74
|
* merge earlier in the same tick counts. `updatePull`: merge the base into the PR (`graft pr update`).
|
|
70
75
|
* `linkIssue`: put `Closes #<issue>` at the top of the PR's body, so the PR names the issue it closes.
|
|
76
|
+
* `addBlockedBy`: record GitHub's "blocked by" dependency of issue `number` on `blocker`; resolves the blocker's state.
|
|
71
77
|
*/
|
|
72
78
|
|
|
73
79
|
const PR_FIELDS = `number url headRefName state headRefOid isInMergeQueue body mergeable reviewDecision createdAt updatedAt
|
|
@@ -106,6 +112,7 @@ fragment I on Issue {
|
|
|
106
112
|
labels(first: 30) { nodes { name } }
|
|
107
113
|
blockedBy(first: 20) { nodes { number state closedAt } }
|
|
108
114
|
comments(first: 100) { nodes { databaseId body author { login } } }
|
|
115
|
+
recent: comments(last: 20) { nodes { createdAt body author { login __typename } } }
|
|
109
116
|
}
|
|
110
117
|
fragment P on PullRequest {
|
|
111
118
|
number url title state createdAt headRefName baseRefName headRefOid reviewDecision
|
|
@@ -149,13 +156,19 @@ const FAILED = new Set(['FAILURE', 'ERROR', 'TIMED_OUT', 'CANCELLED', 'ACTION_RE
|
|
|
149
156
|
/**
|
|
150
157
|
* The first comment holding a marker (from `botLogin` only, when set). Issues and PRs alike.
|
|
151
158
|
* @param {any} n an issue or PR node with `comments` @param {string | null} botLogin
|
|
152
|
-
* @returns {{ id: number, marker: import('./marker.mjs').Marker } | null}
|
|
159
|
+
* @returns {{ id: number, marker: import('./marker.mjs').Marker, author: string | null } | null}
|
|
153
160
|
*/
|
|
154
161
|
function stateCommentOf(n, botLogin) {
|
|
155
162
|
const comment = (n.comments?.nodes ?? []).find(
|
|
156
163
|
(/** @type {any} */ c) => parseMarker(c.body) && (!botLogin || c.author?.login === botLogin),
|
|
157
164
|
)
|
|
158
|
-
return comment
|
|
165
|
+
return comment
|
|
166
|
+
? {
|
|
167
|
+
id: comment.databaseId,
|
|
168
|
+
marker: /** @type {any} */ (parseMarker(comment.body)),
|
|
169
|
+
author: comment.author?.login ?? null,
|
|
170
|
+
}
|
|
171
|
+
: null
|
|
159
172
|
}
|
|
160
173
|
|
|
161
174
|
/** @param {any} n @returns {string[]} */
|
|
@@ -220,9 +233,15 @@ function toIssue(n, botLogin) {
|
|
|
220
233
|
stateComment: stateCommentOf(n, botLogin),
|
|
221
234
|
blockedBy: (n.blockedBy?.nodes ?? []).filter(Boolean).map((/** @type {any} */ b) => ({
|
|
222
235
|
number: b.number,
|
|
223
|
-
state: b.state,
|
|
236
|
+
state: b.state === 'OPEN' ? 'OPEN' : 'CLOSED',
|
|
224
237
|
closedAt: b.closedAt ?? null,
|
|
225
238
|
})),
|
|
239
|
+
comments: (n.recent?.nodes ?? []).filter(Boolean).map((/** @type {any} */ c) => ({
|
|
240
|
+
author: c.author?.login ?? null,
|
|
241
|
+
bot: c.author?.__typename === 'Bot',
|
|
242
|
+
createdAt: c.createdAt ?? '',
|
|
243
|
+
body: c.body ?? '',
|
|
244
|
+
})),
|
|
226
245
|
}
|
|
227
246
|
}
|
|
228
247
|
|
|
@@ -475,5 +494,12 @@ export function graftGitHub({ config, exec: run = exec }) {
|
|
|
475
494
|
const linked = `Closes #${issue}${body ? `\n\n${body}` : ''}`
|
|
476
495
|
await graft(slug, ['api', 'PATCH', path, '--body', JSON.stringify({ body: linked })])
|
|
477
496
|
},
|
|
497
|
+
async addBlockedBy(slug, number, blocker) {
|
|
498
|
+
// The dependencies API takes the blocker's database id, not its number.
|
|
499
|
+
const b = await json(graft(slug, ['api', 'GET', `/repos/${slug}/issues/${blocker}`]))
|
|
500
|
+
const path = `/repos/${slug}/issues/${number}/dependencies/blocked_by`
|
|
501
|
+
await graft(slug, ['api', 'POST', path, '--body', JSON.stringify({ issue_id: b.id })])
|
|
502
|
+
return { state: b.state === 'open' ? 'OPEN' : 'CLOSED' }
|
|
503
|
+
},
|
|
478
504
|
}
|
|
479
505
|
}
|
package/src/graphs/dispatch.mjs
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
/**
|
|
3
3
|
* The Dispatch phase as a graph: a `q:intake` issue is triaged by a one-shot `claude -p` worker whose final
|
|
4
4
|
* message carries a typed verdict ({@link TriageResult}), then moved to `q:task`, moved to `q:human`, or closed as
|
|
5
|
-
* a duplicate or obsolete,
|
|
5
|
+
* a duplicate or obsolete, deferred to be triaged again later, or parked as blocked until its GitHub `blockedBy` issues close. Same conventions as the task graph (graphs/task.mjs): each node declares its queue label and
|
|
6
6
|
* whether it holds `running`, and a node's write is the marker first, then the labels via `move()`.
|
|
7
7
|
*
|
|
8
8
|
* The triage worker runs in a read-only checkout (workers.mjs `readOnly`): detached at the base branch, no install,
|
|
@@ -11,9 +11,10 @@
|
|
|
11
11
|
import { z } from 'zod'
|
|
12
12
|
import { defineGraph, defineNode, defineWait, END } from '../graph/index.mjs'
|
|
13
13
|
import { iso, key, markerOf, MIN, setLabels, setMarker } from '../issue-state.mjs'
|
|
14
|
-
import { move, Q, WHY } from '../labels.mjs'
|
|
14
|
+
import { move, Q, WAIT, WHY } from '../labels.mjs'
|
|
15
15
|
import { newMarker, withHistory } from '../marker.mjs'
|
|
16
16
|
import { readTriage, TriageResult, triageComment, triagePrompt } from '../phases/dispatch.mjs'
|
|
17
|
+
import { humanReplies, quoted, replyContextOf } from '../human-reply.mjs'
|
|
17
18
|
import { traceWorker } from '../tracing.mjs'
|
|
18
19
|
import { stopOverdue } from '../workers.mjs'
|
|
19
20
|
import { task } from './task.mjs'
|
|
@@ -29,7 +30,12 @@ import { task } from './task.mjs'
|
|
|
29
30
|
*/
|
|
30
31
|
|
|
31
32
|
/** The nodes an issue in `q:intake` can rest at; a marker elsewhere starts triage over at attempt 1. */
|
|
32
|
-
const INTAKE_NODES = new Set(['start-triage', 'triaging', 'retry-triage', 'deferred'])
|
|
33
|
+
const INTAKE_NODES = new Set(['start-triage', 'triaging', 'retry-triage', 'deferred', 'blocked'])
|
|
34
|
+
/** The nodes before a verdict: the marker keeps its `reply` context through them; any other node drops it. */
|
|
35
|
+
const PRE_VERDICT = new Set(['start-triage', 'triaging', 'retry-triage'])
|
|
36
|
+
|
|
37
|
+
/** The open issues among `issue`'s GitHub `blockedBy` links. @param {Issue} issue */
|
|
38
|
+
export const openBlockers = (issue) => (issue.blockedBy ?? []).filter((b) => b.state === 'OPEN').map((b) => b.number)
|
|
33
39
|
|
|
34
40
|
/** The pseudo-branch that names an issue's triage checkout (`<root>/triage-<n>`); never created. @param {number} n */
|
|
35
41
|
export const triageBranch = (n) => `cambium/triage-${n}`
|
|
@@ -61,6 +67,7 @@ async function land(ctx, node, marker, { extra = [], status = 'waiting' } = {})
|
|
|
61
67
|
const decl = nodeOf(node)
|
|
62
68
|
await setMarker(ctx, slug, issue, {
|
|
63
69
|
...graphMarker(marker),
|
|
70
|
+
...(PRE_VERDICT.has(node) ? {} : { reply: null }),
|
|
64
71
|
graph: dispatch.name,
|
|
65
72
|
graphVersion: dispatch.version,
|
|
66
73
|
phase: 'dispatch',
|
|
@@ -110,6 +117,8 @@ const needsHuman = (/** @type {Triaged} */ o) => verdictOf(o) === 'needs-human'
|
|
|
110
117
|
const duplicate = (/** @type {Triaged} */ o) => verdictOf(o) === 'duplicate'
|
|
111
118
|
const obsolete = (/** @type {Triaged} */ o) => verdictOf(o) === 'obsolete'
|
|
112
119
|
const defer = (/** @type {Triaged} */ o) => verdictOf(o) === 'defer'
|
|
120
|
+
const blocked = (/** @type {Triaged} */ o) => verdictOf(o) === 'blocked'
|
|
121
|
+
const noneOpen = (/** @type {{ to: string }} */ o) => o.to === 'defer'
|
|
113
122
|
|
|
114
123
|
/** @param {DispatchCtx} ctx */
|
|
115
124
|
export const lostLeaseOf = (ctx) => ({
|
|
@@ -149,8 +158,12 @@ const startTriage = declare(
|
|
|
149
158
|
} catch (err) {
|
|
150
159
|
return { to: 'retry', reason: `could not start triage: ${errText(err)}`, outcome: 'spawn-failed' }
|
|
151
160
|
}
|
|
161
|
+
// A human reply since the issue last waited (on a needs-human, defer or blocked reason) is the answer to it.
|
|
162
|
+
const reply = m0.reply ?? replyContextOf(markerOf(issue))
|
|
163
|
+
const replies = reply ? quoted(humanReplies(issue, { since: reply.since, botLogin: config.graft.botLogin })) : []
|
|
152
164
|
await land(ctx, 'triaging', {
|
|
153
165
|
...m0,
|
|
166
|
+
reply,
|
|
154
167
|
deferUntil: null,
|
|
155
168
|
host: config.host,
|
|
156
169
|
start: iso(ctx.tick.now),
|
|
@@ -183,7 +196,13 @@ const startTriage = declare(
|
|
|
183
196
|
queued,
|
|
184
197
|
agentsMd,
|
|
185
198
|
deferHours: caps.deferHours,
|
|
186
|
-
deferred:
|
|
199
|
+
deferred:
|
|
200
|
+
!replies.length && m0.deferReason && !m0.blockedBy?.length
|
|
201
|
+
? { count: m0.defers ?? 0, reason: m0.deferReason }
|
|
202
|
+
: null,
|
|
203
|
+
blocked:
|
|
204
|
+
!replies.length && m0.blockedBy?.length ? { by: m0.blockedBy, reason: m0.deferReason ?? '' } : null,
|
|
205
|
+
replied: replies.length ? { question: reply?.question ?? null, replies } : null,
|
|
187
206
|
}),
|
|
188
207
|
})
|
|
189
208
|
} catch (err) {
|
|
@@ -455,21 +474,27 @@ const deferred = declare(
|
|
|
455
474
|
}
|
|
456
475
|
const hours = d.recheckHours ?? deferHours
|
|
457
476
|
const until = iso(ctx.tick.now + hours * 60 * MIN)
|
|
458
|
-
await land(
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
477
|
+
await land(
|
|
478
|
+
ctx,
|
|
479
|
+
'deferred',
|
|
480
|
+
{
|
|
481
|
+
...withHistory(m, {
|
|
482
|
+
at: iso(ctx.tick.now),
|
|
483
|
+
attempt: m.attempt,
|
|
484
|
+
outcome: 'defer',
|
|
485
|
+
reason: d.reason,
|
|
486
|
+
log: d.log,
|
|
487
|
+
}),
|
|
488
|
+
defers,
|
|
489
|
+
deferUntil: until,
|
|
490
|
+
deferReason: d.reason,
|
|
491
|
+
blockedBy: null,
|
|
492
|
+
host: null,
|
|
493
|
+
start: null,
|
|
494
|
+
input: null,
|
|
495
|
+
},
|
|
496
|
+
{ extra: [WAIT.deferred] },
|
|
497
|
+
)
|
|
473
498
|
ctx.log('info', `triage deferred until ${until} (${defers}/${maxDefers}): ${d.reason.split('\n')[0]}`, {
|
|
474
499
|
repo: ctx.subject.slug,
|
|
475
500
|
issue: issue.number,
|
|
@@ -480,6 +505,77 @@ const deferred = declare(
|
|
|
480
505
|
{ queue: Q.intake, running: false },
|
|
481
506
|
)
|
|
482
507
|
|
|
508
|
+
const BlockedIn = z.object({
|
|
509
|
+
blockedBy: z.array(z.number().int().positive()).min(1),
|
|
510
|
+
reason: z.string(),
|
|
511
|
+
log: z.string().optional(),
|
|
512
|
+
})
|
|
513
|
+
const blockedNode = declare(
|
|
514
|
+
defineNode({
|
|
515
|
+
name: 'blocked',
|
|
516
|
+
input: BlockedIn,
|
|
517
|
+
output: z.discriminatedUnion('to', [
|
|
518
|
+
z.object({ to: z.literal('wait'), blockedBy: z.array(z.number().int()) }),
|
|
519
|
+
z.object({ to: z.literal('defer'), reason: z.string(), log: z.string() }),
|
|
520
|
+
]),
|
|
521
|
+
/**
|
|
522
|
+
* Blocked: the issue waits on other issues. Each one triage named that GitHub does not link yet is added as a
|
|
523
|
+
* `blockedBy` link; then the issue rests here in `q:intake` with `wait:blocked` and no `deferUntil`. Schedule
|
|
524
|
+
* does not triage it while any `blockedBy` issue is open, and triages it the tick after the last one closes.
|
|
525
|
+
* Not a defer: `maxDefers` does not count it. Schedule also parks an untriaged issue here that GitHub already
|
|
526
|
+
* shows blocked. When none of the named issues is open (closed, or the link failed) it is a plain defer.
|
|
527
|
+
* @param {z.infer<typeof BlockedIn>} b @param {DispatchCtx} ctx
|
|
528
|
+
*/
|
|
529
|
+
run: async (b, ctx) => {
|
|
530
|
+
const { slug } = ctx.subject
|
|
531
|
+
const issue = issueOf(ctx)
|
|
532
|
+
const m = markerOf(issue)
|
|
533
|
+
const links = [...(issue.blockedBy ?? [])]
|
|
534
|
+
for (const n of b.blockedBy) {
|
|
535
|
+
if (n === issue.number || links.some((l) => l.number === n)) continue
|
|
536
|
+
try {
|
|
537
|
+
const { state } = await ctx.github.addBlockedBy(slug, issue.number, n)
|
|
538
|
+
links.push({ number: n, state, closedAt: null })
|
|
539
|
+
ctx.log('info', `linked blockedBy #${n}`, { repo: slug, issue: issue.number })
|
|
540
|
+
} catch (err) {
|
|
541
|
+
ctx.log('warn', `could not link blockedBy #${n}: ${errText(err)}`, { repo: slug, issue: issue.number })
|
|
542
|
+
}
|
|
543
|
+
}
|
|
544
|
+
issue.blockedBy = links
|
|
545
|
+
const open = openBlockers(issue)
|
|
546
|
+
const list = b.blockedBy.map((n) => `#${n}`).join(', ')
|
|
547
|
+
if (!open.length)
|
|
548
|
+
return { to: 'defer', reason: `blocked by ${list}, but none is open. ${b.reason}`, log: b.log ?? '' }
|
|
549
|
+
await land(
|
|
550
|
+
ctx,
|
|
551
|
+
'blocked',
|
|
552
|
+
{
|
|
553
|
+
...withHistory(m, {
|
|
554
|
+
at: iso(ctx.tick.now),
|
|
555
|
+
attempt: m.attempt,
|
|
556
|
+
outcome: 'blocked',
|
|
557
|
+
reason: `${open.map((n) => `#${n}`).join(', ')}: ${b.reason}`,
|
|
558
|
+
...(b.log ? { log: b.log } : {}),
|
|
559
|
+
}),
|
|
560
|
+
deferUntil: null,
|
|
561
|
+
deferReason: b.reason,
|
|
562
|
+
blockedBy: open,
|
|
563
|
+
host: null,
|
|
564
|
+
start: null,
|
|
565
|
+
input: null,
|
|
566
|
+
},
|
|
567
|
+
{ extra: [WAIT.blocked] },
|
|
568
|
+
)
|
|
569
|
+
ctx.log('info', `blocked by ${open.map((n) => `#${n}`).join(', ')}: ${b.reason.split('\n')[0]}`, {
|
|
570
|
+
repo: slug,
|
|
571
|
+
issue: issue.number,
|
|
572
|
+
})
|
|
573
|
+
return { to: 'wait', blockedBy: open }
|
|
574
|
+
},
|
|
575
|
+
}),
|
|
576
|
+
{ queue: Q.intake, running: false },
|
|
577
|
+
)
|
|
578
|
+
|
|
483
579
|
const ObsIn = z.object({ reason: z.string(), log: z.string() })
|
|
484
580
|
const closeObsolete = declare(
|
|
485
581
|
defineNode({
|
|
@@ -527,7 +623,7 @@ export const dispatch = defineGraph({
|
|
|
527
623
|
name: 'dispatch',
|
|
528
624
|
version: 1,
|
|
529
625
|
entry: { queue: Q.intake, node: 'start-triage', input: () => ({}) },
|
|
530
|
-
nodes: [startTriage, triaging, retryTriage, toTask, toHuman, closeDuplicate, deferred, closeObsolete],
|
|
626
|
+
nodes: [startTriage, triaging, retryTriage, toTask, toHuman, closeDuplicate, deferred, blockedNode, closeObsolete],
|
|
531
627
|
edges: [
|
|
532
628
|
['start-triage', 'triaging', started, (o) => ({ attempt: o.attempt })],
|
|
533
629
|
['start-triage', 'to-human', budgetSpent],
|
|
@@ -537,6 +633,7 @@ export const dispatch = defineGraph({
|
|
|
537
633
|
['triaging', 'to-task', actionable, (o) => ({ ...pick(o.result, ['reason', 'title', 'acceptance']), log: o.log })],
|
|
538
634
|
['triaging', 'close-duplicate', duplicate, (o) => ({ ...pick(o.result, ['duplicateOf', 'reason']), log: o.log })],
|
|
539
635
|
['triaging', 'deferred', defer, (o) => ({ ...pick(o.result, ['reason', 'recheckHours']), log: o.log })],
|
|
636
|
+
['triaging', 'blocked', blocked, (o) => ({ blockedBy: o.result.blockedBy, reason: o.result.reason, log: o.log })],
|
|
540
637
|
['triaging', 'close-obsolete', obsolete, (o) => ({ reason: o.result.reason, log: o.log })],
|
|
541
638
|
['triaging', 'to-human', needsHuman, (o) => ({ reason: o.result.reason, outcome: 'needs-human', log: o.log })],
|
|
542
639
|
['triaging', 'to-human'],
|
|
@@ -547,6 +644,8 @@ export const dispatch = defineGraph({
|
|
|
547
644
|
['close-duplicate', END],
|
|
548
645
|
['deferred', 'to-human', budgetSpent],
|
|
549
646
|
['deferred', END],
|
|
647
|
+
['blocked', 'deferred', noneOpen, (o) => ({ reason: o.reason, log: o.log })],
|
|
648
|
+
['blocked', END],
|
|
550
649
|
['close-obsolete', END],
|
|
551
650
|
],
|
|
552
651
|
})
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
// @ts-check
|
|
2
|
+
/**
|
|
3
|
+
* Human replies: a comment on an issue, written after the issue entered its current state, by someone who is
|
|
4
|
+
* neither cambium nor a bot. A human answers a `q:human` question (or says a parked issue is not really blocked) by
|
|
5
|
+
* commenting; cambium sends the issue back to triage at once and quotes the reply in the triage prompt
|
|
6
|
+
* (dispatch-engine.mjs `wake`, graphs/dispatch.mjs `start-triage`).
|
|
7
|
+
*/
|
|
8
|
+
import { parseMarker } from './marker.mjs'
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* @typedef {import('./github.mjs').Issue} Issue
|
|
12
|
+
* @typedef {import('./github.mjs').Comment} Comment
|
|
13
|
+
* @typedef {import('./marker.mjs').Marker} Marker
|
|
14
|
+
* @typedef {{ since: string, question: string | null }} ReplyContext
|
|
15
|
+
* What a reply answers: the state's start (replies after it count) and the reason the issue was waiting for.
|
|
16
|
+
*/
|
|
17
|
+
|
|
18
|
+
/** A reply quoted in the triage prompt is cut to this many characters. */
|
|
19
|
+
export const REPLY_CHARS = 2000
|
|
20
|
+
/** At most this many replies are quoted, the newest. */
|
|
21
|
+
export const REPLIES_KEPT = 5
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* When the marker's issue entered its current state: the later of `enteredAt` and the last history `at` (a
|
|
25
|
+
* stage-era write can leave an old `enteredAt` behind a newer history entry). Null without either.
|
|
26
|
+
* @param {Marker | null | undefined} m @returns {string | null}
|
|
27
|
+
*/
|
|
28
|
+
export function stateSince(m) {
|
|
29
|
+
if (!m) return null
|
|
30
|
+
const times = [m.enteredAt, m.history.at(-1)?.at].filter((t) => t && Number.isFinite(Date.parse(t)))
|
|
31
|
+
if (!times.length) return null
|
|
32
|
+
return /** @type {string} */ (
|
|
33
|
+
times.reduce((a, b) => (Date.parse(/** @type {string} */ (b)) > Date.parse(/** @type {string} */ (a)) ? b : a))
|
|
34
|
+
)
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* The human replies on `issue` written after `since`, oldest first. Never cambium's: not by `botLogin`, not by the
|
|
39
|
+
* login that wrote the state comment, not a `Bot`-type author, and not a comment carrying a state marker. No `since`:
|
|
40
|
+
* none (nothing to be a reply to).
|
|
41
|
+
* @param {Issue} issue @param {{ since: string | null, botLogin?: string | null }} o @returns {Comment[]}
|
|
42
|
+
*/
|
|
43
|
+
export function humanReplies(issue, { since, botLogin = null }) {
|
|
44
|
+
if (!since) return []
|
|
45
|
+
const after = Date.parse(since)
|
|
46
|
+
if (!Number.isFinite(after)) return []
|
|
47
|
+
const self = new Set([botLogin, issue.stateComment?.author].filter(Boolean))
|
|
48
|
+
return (issue.comments ?? []).filter(
|
|
49
|
+
(c) => !!c.author && !c.bot && !self.has(c.author) && !parseMarker(c.body) && Date.parse(c.createdAt) > after,
|
|
50
|
+
)
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/**
|
|
54
|
+
* The context a triage after `m` quotes replies against, or null when `m` is not waiting on anything: the
|
|
55
|
+
* dispatch graph's `deferred` / `blocked` (the defer or blocked reason), or any `to-human` (the needs-human reason).
|
|
56
|
+
* @param {Marker | null | undefined} m @returns {ReplyContext | null}
|
|
57
|
+
*/
|
|
58
|
+
export function replyContextOf(m) {
|
|
59
|
+
if (!m || m.status === 'done') return null
|
|
60
|
+
const since = stateSince(m)
|
|
61
|
+
if (!since) return null
|
|
62
|
+
if (m.graph === 'dispatch' && (m.node === 'deferred' || m.node === 'blocked'))
|
|
63
|
+
return { since, question: m.deferReason ?? m.history.at(-1)?.reason ?? null }
|
|
64
|
+
if (m.node === 'to-human') return { since, question: m.lastFailure ?? m.history.at(-1)?.reason ?? null }
|
|
65
|
+
return null
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* The replies as the triage prompt quotes them: the newest {@link REPLIES_KEPT}, each cut to {@link REPLY_CHARS}.
|
|
70
|
+
* @param {Comment[]} replies @returns {{ author: string, at: string, body: string }[]}
|
|
71
|
+
*/
|
|
72
|
+
export function quoted(replies) {
|
|
73
|
+
return replies.slice(-REPLIES_KEPT).map((c) => ({
|
|
74
|
+
author: c.author ?? 'unknown',
|
|
75
|
+
at: c.createdAt,
|
|
76
|
+
body: c.body.length > REPLY_CHARS ? `${c.body.slice(0, REPLY_CHARS)}… (cut)` : c.body,
|
|
77
|
+
}))
|
|
78
|
+
}
|
package/src/labels.mjs
CHANGED
|
@@ -7,6 +7,12 @@ export const Q = /** @type {const} */ ({
|
|
|
7
7
|
})
|
|
8
8
|
export const QUEUE_LABELS = Object.values(Q)
|
|
9
9
|
export const RUNNING = 'running'
|
|
10
|
+
/**
|
|
11
|
+
* A parked `q:intake` issue triage already looked at, so canopy can tell it from one awaiting triage:
|
|
12
|
+
* `wait:deferred` rests at the dispatch graph's `deferred` node until `deferUntil`; `wait:blocked` has open GitHub
|
|
13
|
+
* `blockedBy` issues. Any queue move drops them unless it names one again.
|
|
14
|
+
*/
|
|
15
|
+
export const WAIT = /** @type {const} */ ({ deferred: 'wait:deferred', blocked: 'wait:blocked' })
|
|
10
16
|
export const WHY = /** @type {const} */ ({
|
|
11
17
|
budget: 'why:budget',
|
|
12
18
|
reject: 'why:reject',
|
|
@@ -25,7 +31,10 @@ export function move(labels, target, { running = false, extra = [] } = {}) {
|
|
|
25
31
|
const want = new Set([...(target ? [target] : []), ...extra, ...(running ? [RUNNING] : [])])
|
|
26
32
|
const leaving = (/** @type {string} */ l) =>
|
|
27
33
|
!want.has(l) &&
|
|
28
|
-
((l.startsWith('q:') && l !== target) ||
|
|
34
|
+
((l.startsWith('q:') && l !== target) ||
|
|
35
|
+
l === RUNNING ||
|
|
36
|
+
(l.startsWith('why:') && target !== Q.human) ||
|
|
37
|
+
l.startsWith('wait:'))
|
|
29
38
|
return {
|
|
30
39
|
add: [...want].filter((l) => !labels.includes(l)),
|
|
31
40
|
remove: labels.filter(leaving),
|
package/src/marker.mjs
CHANGED
|
@@ -47,11 +47,16 @@
|
|
|
47
47
|
* defers?: number,
|
|
48
48
|
* deferUntil?: string | null,
|
|
49
49
|
* deferReason?: string | null,
|
|
50
|
+
* blockedBy?: number[] | null,
|
|
51
|
+
* reply?: { since: string, question: string | null } | null,
|
|
50
52
|
* }} Marker
|
|
51
53
|
* `mergeRefusal`: the last `graft pr merge` cambium was refused (PR graph `merge`), and on which head.
|
|
52
54
|
* `reworks`: how many times the PR graph sent this issue's PR back to a worker.
|
|
53
55
|
* `defers`, `deferUntil`, `deferReason`: the dispatch graph's `deferred` node: how many times triage deferred, until
|
|
54
|
-
* when, and what the next triage should check.
|
|
56
|
+
* when, and what the next triage should check. At the `blocked` node `deferReason` is why and `blockedBy` the open
|
|
57
|
+
* GitHub `blockedBy` issues it waits on (no `deferUntil`).
|
|
58
|
+
* `reply`: while triage is pending or running, what a human reply answers (human-reply.mjs): human comments after
|
|
59
|
+
* `since` are quoted in the triage prompt as the answer to `question`. Cleared when triage lands a verdict.
|
|
55
60
|
* `triage`: what the dispatch graph's triage added when it handed the issue to `q:task`; the task prompt shows it.
|
|
56
61
|
* @typedef {{ graph: string, entryNode: string, nodes?: Iterable<string> }} QueueOwner
|
|
57
62
|
*/
|
|
@@ -180,7 +185,10 @@ export function renderMarker(input, { maxAttempts } = {}) {
|
|
|
180
185
|
(marker.pr ? ` · PR #${marker.pr}` : '') +
|
|
181
186
|
(marker.host ? ` · host \`${marker.host}\`` : '') +
|
|
182
187
|
(marker.start ? ` · started ${marker.start}` : '') +
|
|
183
|
-
(marker.node === 'deferred' && marker.deferUntil ? ` · re-triage after ${marker.deferUntil}` : '')
|
|
188
|
+
(marker.node === 'deferred' && marker.deferUntil ? ` · re-triage after ${marker.deferUntil}` : '') +
|
|
189
|
+
(marker.node === 'blocked' && marker.blockedBy?.length
|
|
190
|
+
? ` · re-triage once ${marker.blockedBy.map((n) => `#${n}`).join(', ')} close`
|
|
191
|
+
: ''),
|
|
184
192
|
]
|
|
185
193
|
if (marker.lastFailure)
|
|
186
194
|
lines.push(
|
package/src/phases/dispatch.mjs
CHANGED
|
@@ -21,8 +21,9 @@ export const DISPATCH_NOT_BUILT = 'dispatch phase is not built yet; q:intake iss
|
|
|
21
21
|
/** The verdict a triage worker ends with, as the last JSON block of its final message. */
|
|
22
22
|
export const TriageResult = z
|
|
23
23
|
.object({
|
|
24
|
-
verdict: z.enum(['actionable', 'needs-human', 'duplicate', 'defer', 'obsolete']),
|
|
24
|
+
verdict: z.enum(['actionable', 'needs-human', 'duplicate', 'defer', 'blocked', 'obsolete']),
|
|
25
25
|
duplicateOf: z.number().int().positive().optional(),
|
|
26
|
+
blockedBy: z.array(z.number().int().positive()).min(1).optional(),
|
|
26
27
|
recheckHours: z.number().positive().max(168).optional(),
|
|
27
28
|
reason: z.string().trim().min(1),
|
|
28
29
|
title: z.string().trim().min(1).optional(),
|
|
@@ -32,6 +33,10 @@ export const TriageResult = z
|
|
|
32
33
|
message: 'a duplicate verdict needs duplicateOf',
|
|
33
34
|
path: ['duplicateOf'],
|
|
34
35
|
})
|
|
36
|
+
.refine((r) => r.verdict !== 'blocked' || r.blockedBy !== undefined, {
|
|
37
|
+
message: 'a blocked verdict needs blockedBy',
|
|
38
|
+
path: ['blockedBy'],
|
|
39
|
+
})
|
|
35
40
|
|
|
36
41
|
/** @typedef {z.infer<typeof TriageResult>} Triage */
|
|
37
42
|
|
|
@@ -100,6 +105,8 @@ export function readTriage(log, issue) {
|
|
|
100
105
|
return { ok: false, error: `invalid triage result: ${parsed.error.issues.map(formatIssue).join('; ')}` }
|
|
101
106
|
if (parsed.data.verdict === 'duplicate' && parsed.data.duplicateOf === issue)
|
|
102
107
|
return { ok: false, error: `invalid triage result: duplicateOf: #${issue} cannot duplicate itself` }
|
|
108
|
+
if (parsed.data.verdict === 'blocked' && parsed.data.blockedBy?.includes(issue))
|
|
109
|
+
return { ok: false, error: `invalid triage result: blockedBy: #${issue} cannot block itself` }
|
|
103
110
|
return { ok: true, result: parsed.data }
|
|
104
111
|
}
|
|
105
112
|
|
|
@@ -111,9 +118,23 @@ export function readTriage(log, issue) {
|
|
|
111
118
|
* repo: string, baseBranch: string, issue: import('../github.mjs').Issue,
|
|
112
119
|
* queued: { number: number, title: string, labels: string[] }[], agentsMd: string | null,
|
|
113
120
|
* deferred?: { count: number, reason: string } | null, deferHours?: number,
|
|
121
|
+
* blocked?: { by: number[], reason: string } | null,
|
|
122
|
+
* replied?: { question: string | null, replies: { author: string, at: string, body: string }[] } | null,
|
|
114
123
|
* }} input
|
|
124
|
+
* `blocked`: an earlier triage parked it on these issues, all closed now. `replied`: a human commented since the
|
|
125
|
+
* issue last waited; `question` is what it waited on (the needs-human, defer or blocked reason).
|
|
115
126
|
*/
|
|
116
|
-
export function triagePrompt({
|
|
127
|
+
export function triagePrompt({
|
|
128
|
+
repo,
|
|
129
|
+
baseBranch,
|
|
130
|
+
issue,
|
|
131
|
+
queued,
|
|
132
|
+
agentsMd,
|
|
133
|
+
deferred = null,
|
|
134
|
+
deferHours = 6,
|
|
135
|
+
blocked = null,
|
|
136
|
+
replied = null,
|
|
137
|
+
}) {
|
|
117
138
|
const others = queued
|
|
118
139
|
.filter((q) => q.number !== issue.number)
|
|
119
140
|
.map((q) => `- #${q.number} ${q.title} (${q.labels.filter((l) => l.startsWith('q:')).join(', ') || 'no queue'})`)
|
|
@@ -128,25 +149,43 @@ Verdicts:
|
|
|
128
149
|
- needs-human: too foggy to ticket; a decision only a human can make (direction, priority, money, access, policy); information no one but a human has; or work that is not a code change in this repository. \`reason\` says exactly what the human must decide or supply. Never for something a machine can check, now or later.
|
|
129
150
|
- 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.
|
|
130
151
|
- obsolete: the work no longer applies, and you verified it: the code path is gone, the bug is already fixed on ${baseBranch}, or its verification already passed. cambium closes it as not planned. \`reason\` gives the evidence (commit, file, run).
|
|
131
|
-
- defer: the verdict hangs on something a machine can check later but not yet: a CI or CD run that has not happened, a release, a PR still merging, a deploy, an upstream fix. cambium triages it again after \`recheckHours\` (default ${deferHours}). \`reason\` says exactly what to check next time and what each answer means (e.g. "next main cd run green → obsolete; red → actionable").
|
|
152
|
+
- defer: the verdict hangs on something a machine can check later but not yet: a CI or CD run that has not happened, a release, a PR still merging, a deploy, an upstream fix. cambium triages it again after \`recheckHours\` (default ${deferHours}). \`reason\` says exactly what to check next time and what each answer means (e.g. "next main cd run green → obsolete; red → actionable"). Not for waiting on another issue: that is blocked.
|
|
153
|
+
- blocked: it cannot start until other issues in ${repo} are done. \`blockedBy\` lists their numbers (never #${issue.number}); cambium records each as a GitHub "blocked by" link on this issue and triages it again as soon as the last of them closes, not on a timer. \`reason\` says what each blocker must deliver.
|
|
132
154
|
|
|
133
155
|
How to look:
|
|
134
156
|
- Read the code here (Read, Glob, Grep) to judge what the change touches and whether it already exists.
|
|
135
157
|
- First, has it already been done? Its comments (\`graft api GET /repos/${repo}/issues/${issue.number}/comments\`) and its timeline (\`graft api GET '/repos/${repo}/issues/${issue.number}/timeline?per_page=100'\`: cross-referenced PRs, and whether they merged) often say so. A merged PR whose change is on ${baseBranch}, and nothing left of the issue, is obsolete; a PR still open or in CI is defer.
|
|
158
|
+
- Does it already wait on other issues? Its GitHub "blocked by" links: \`graft api GET /repos/${repo}/issues/${issue.number}/dependencies/blocked_by\`. An open one, or prose naming an open issue it needs first, is blocked.
|
|
136
159
|
- Read an issue with \`graft issue read <n>\`; search with \`graft api GET '/search/issues?q=repo:${repo}+is:issue+<words>'\`. Never \`gh\`.
|
|
160
|
+
- A human reply (quoted below, when there is one) answering the open question usually makes the issue actionable: fold the answer into \`title\` and \`acceptance\` so the task worker gets it with the issue. If the reply leaves the question open, the verdict is needs-human again, and \`reason\` says what is still missing.
|
|
137
161
|
- Be quick: a verdict, not an investigation. When in doubt whether the work is clear enough to do, choose needs-human; when in doubt whether something is true, check it, or defer until it can be checked.
|
|
138
162
|
|
|
139
163
|
End your final message with exactly one fenced JSON block, and nothing after it:
|
|
140
164
|
\`\`\`json
|
|
141
|
-
{ "verdict": "actionable" | "needs-human" | "duplicate" | "obsolete" | "defer", "duplicateOf": 123, "recheckHours": 6, "reason": "…", "title": "…", "acceptance": ["…"] }
|
|
165
|
+
{ "verdict": "actionable" | "needs-human" | "duplicate" | "obsolete" | "defer" | "blocked", "duplicateOf": 123, "blockedBy": [124], "recheckHours": 6, "reason": "…", "title": "…", "acceptance": ["…"] }
|
|
142
166
|
\`\`\`
|
|
143
|
-
\`duplicateOf\` only for duplicate; \`recheckHours\` only for defer, and optional; \`title\` and \`acceptance\` only for actionable, and optional. A missing or malformed block sends the issue to a human with the error.
|
|
144
|
-
${deferred ? `\nThis is re-triage ${deferred.count + 1}: an earlier triage deferred it to check this:\n${deferred.reason}\nCheck it now. If it still cannot be checked, defer again.\n` : ''}${others ? `\nOther issues in cambium's queues right now:\n${others}\n` : ''}
|
|
167
|
+
\`duplicateOf\` only for duplicate; \`blockedBy\` only for blocked; \`recheckHours\` only for defer, and optional; \`title\` and \`acceptance\` only for actionable, and optional. A missing or malformed block sends the issue to a human with the error.
|
|
168
|
+
${deferred ? `\nThis is re-triage ${deferred.count + 1}: an earlier triage deferred it to check this:\n${deferred.reason}\nCheck it now. If it still cannot be checked, defer again.\n` : ''}${blocked ? `\nAn earlier triage found it blocked by ${blocked.by.map((n) => `#${n}`).join(', ')}, now closed:\n${blocked.reason}\nJudge it again now that they are done.\n` : ''}${replied ? repliedNote(replied) : ''}${others ? `\nOther issues in cambium's queues right now:\n${others}\n` : ''}
|
|
145
169
|
--- Issue #${issue.number}: ${issue.title} (${issue.url})
|
|
146
170
|
${issue.body}
|
|
147
171
|
${agentsMd ? `\n--- AGENTS.md (the contract a task worker will follow)\n${agentsMd}` : ''}`
|
|
148
172
|
}
|
|
149
173
|
|
|
174
|
+
/**
|
|
175
|
+
* The prompt's section quoting the human replies as the answer to what the issue waited on.
|
|
176
|
+
* @param {NonNullable<Parameters<typeof triagePrompt>[0]['replied']>} r
|
|
177
|
+
*/
|
|
178
|
+
function repliedNote({ question, replies }) {
|
|
179
|
+
const quote = (/** @type {string} */ s) =>
|
|
180
|
+
s
|
|
181
|
+
.split('\n')
|
|
182
|
+
.map((l) => `> ${l}`)
|
|
183
|
+
.join('\n')
|
|
184
|
+
return `\nAn earlier triage or step left it waiting on this:\n${quote(question ?? '(no reason recorded)')}\nA human has since replied on the issue. Read the reply as the answer to that:\n${replies
|
|
185
|
+
.map((r) => `\n@${r.author} at ${r.at}:\n${quote(r.body)}\n`)
|
|
186
|
+
.join('')}`
|
|
187
|
+
}
|
|
188
|
+
|
|
150
189
|
/**
|
|
151
190
|
* The comment triage leaves on an actionable issue.
|
|
152
191
|
* @param {{ reason: string, title?: string, acceptance?: string[] }} t
|