@oakgreencc/cambium 0.0.3 → 0.0.5
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/package.json +1 -1
- package/src/marker.mjs +178 -21
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@oakgreencc/cambium",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.5",
|
|
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/marker.mjs
CHANGED
|
@@ -3,16 +3,36 @@
|
|
|
3
3
|
* The cambium-owned state comment: a hidden JSON marker that is the truth,
|
|
4
4
|
* plus a human-readable rendering of it. One per issue; cambium edits it in
|
|
5
5
|
* place on every transition.
|
|
6
|
+
*
|
|
7
|
+
* Marker v2 names a position in a graph: `{ graph, graphVersion, node, status }`.
|
|
8
|
+
* v1 markers (a `stage` in the fixed task pipeline) are still read and are
|
|
9
|
+
* normalised to v2 in memory; the writer only emits v2.
|
|
10
|
+
*
|
|
11
|
+
* Until the graph runtime replaces the stage tick, v2 also carries the v1
|
|
12
|
+
* fields the tick drives (`phase`, `stage`, `pr`, `host`, …). While `stage` is
|
|
13
|
+
* present it is the tick's view and decides `node` (and `status`) on write.
|
|
6
14
|
*/
|
|
7
15
|
|
|
8
16
|
/**
|
|
9
17
|
* @typedef {'queued' | 'running' | 'submitted' | 'human' | 'done'} Stage
|
|
10
|
-
* @typedef {
|
|
18
|
+
* @typedef {'waiting' | 'entering' | 'done'} Status
|
|
11
19
|
* @typedef {{
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
20
|
+
* at: string, attempt: number, outcome: string, reason?: string, pr?: number, log?: string,
|
|
21
|
+
* node?: string | null, spanId?: string,
|
|
22
|
+
* }} HistoryEntry
|
|
23
|
+
* @typedef {{
|
|
24
|
+
* v: 2,
|
|
25
|
+
* graph: string,
|
|
26
|
+
* graphVersion: number,
|
|
27
|
+
* node: string,
|
|
28
|
+
* status: Status,
|
|
29
|
+
* input: Record<string, unknown> | null,
|
|
15
30
|
* attempt: number,
|
|
31
|
+
* traceparent: string | null,
|
|
32
|
+
* enteredAt: string | null,
|
|
33
|
+
* history: HistoryEntry[],
|
|
34
|
+
* phase: 'task' | 'dispatch',
|
|
35
|
+
* stage?: Stage,
|
|
16
36
|
* pr: number | null,
|
|
17
37
|
* branch: string | null,
|
|
18
38
|
* host: string | null,
|
|
@@ -21,28 +41,88 @@
|
|
|
21
41
|
* queued?: boolean,
|
|
22
42
|
* failedSha?: string | null,
|
|
23
43
|
* lastFailure?: string | null,
|
|
24
|
-
* history: HistoryEntry[],
|
|
25
44
|
* }} Marker
|
|
45
|
+
* @typedef {{ graph: string, entryNode: string, nodes?: Iterable<string> }} QueueOwner
|
|
26
46
|
*/
|
|
27
47
|
|
|
28
48
|
const PREFIX = '<!-- cambium:state '
|
|
29
49
|
const RE = /<!-- cambium:state (.*?) -->/s
|
|
30
50
|
const HISTORY_KEPT = 20
|
|
31
51
|
|
|
32
|
-
/**
|
|
33
|
-
export
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
52
|
+
/** The task graph's entry node: where a fresh or reset task issue starts. */
|
|
53
|
+
export const TASK_ENTRY = 'start-worker'
|
|
54
|
+
|
|
55
|
+
/** v1 `stage` → the task-graph node it corresponds to. */
|
|
56
|
+
export const STAGE_NODE = Object.freeze({
|
|
57
|
+
queued: TASK_ENTRY,
|
|
58
|
+
running: 'worker-running',
|
|
59
|
+
submitted: 'ci-running',
|
|
60
|
+
human: 'to-human',
|
|
61
|
+
done: 'close-out',
|
|
62
|
+
})
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Markers written by the stage tick (and v1 markers) predate graph versions.
|
|
66
|
+
* A real graph version is ≥ 1, so a stage-era marker always goes through the
|
|
67
|
+
* node-still-exists check the first time the graph runtime sees it.
|
|
68
|
+
*/
|
|
69
|
+
const STAGE_ERA_VERSION = 0
|
|
70
|
+
|
|
71
|
+
/** v2 defaults, without the stage tick's `stage`. @param {Partial<Marker>} from @returns {Marker} */
|
|
72
|
+
const withDefaults = (from) =>
|
|
73
|
+
syncStage({
|
|
74
|
+
graph: 'task',
|
|
75
|
+
graphVersion: STAGE_ERA_VERSION,
|
|
76
|
+
node: TASK_ENTRY,
|
|
77
|
+
status: 'waiting',
|
|
78
|
+
input: null,
|
|
38
79
|
attempt: 1,
|
|
80
|
+
traceparent: null,
|
|
81
|
+
enteredAt: null,
|
|
82
|
+
phase: 'task',
|
|
39
83
|
pr: null,
|
|
40
84
|
branch: null,
|
|
41
85
|
host: null,
|
|
42
86
|
start: null,
|
|
43
87
|
history: [],
|
|
44
88
|
...from,
|
|
45
|
-
|
|
89
|
+
v: 2,
|
|
90
|
+
})
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* A fresh marker. Unless a `node` is given it is the stage tick's: `queued`
|
|
94
|
+
* at the task graph's entry.
|
|
95
|
+
*
|
|
96
|
+
* @param {Partial<Marker>} [from] @returns {Marker}
|
|
97
|
+
*/
|
|
98
|
+
export const newMarker = (from = {}) => withDefaults(from.node ? from : { stage: 'queued', ...from })
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* While the stage tick drives the marker, `stage` decides the node: the tick
|
|
102
|
+
* only ever spreads a new `stage` into the marker.
|
|
103
|
+
*
|
|
104
|
+
* @param {Marker} m @returns {Marker}
|
|
105
|
+
*/
|
|
106
|
+
function syncStage(m) {
|
|
107
|
+
if (!m.stage || !(m.stage in STAGE_NODE)) return m
|
|
108
|
+
return { ...m, node: STAGE_NODE[m.stage], status: m.stage === 'done' ? 'done' : 'waiting' }
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* A v1 marker as v2: stage → node, phase → graph, `start` → `enteredAt`. The
|
|
113
|
+
* v1 fields stay, so the stage tick keeps working on the result.
|
|
114
|
+
*
|
|
115
|
+
* @param {Record<string, any>} v1 @returns {Marker}
|
|
116
|
+
*/
|
|
117
|
+
export function migrateV1(v1) {
|
|
118
|
+
return withDefaults({
|
|
119
|
+
stage: 'queued',
|
|
120
|
+
...v1,
|
|
121
|
+
graph: v1.phase ?? 'task',
|
|
122
|
+
graphVersion: STAGE_ERA_VERSION,
|
|
123
|
+
enteredAt: v1.start ?? null,
|
|
124
|
+
history: Array.isArray(v1.history) ? v1.history : [],
|
|
125
|
+
})
|
|
46
126
|
}
|
|
47
127
|
|
|
48
128
|
/** @param {string | null | undefined} body @returns {Marker | null} */
|
|
@@ -51,28 +131,41 @@ export function parseMarker(body) {
|
|
|
51
131
|
if (!m) return null
|
|
52
132
|
try {
|
|
53
133
|
const parsed = JSON.parse(m[1])
|
|
54
|
-
|
|
134
|
+
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null
|
|
135
|
+
if (parsed.v === 2) return withDefaults(parsed)
|
|
136
|
+
if (parsed.v === 1 || parsed.v === undefined) return migrateV1(parsed)
|
|
137
|
+
return null
|
|
55
138
|
} catch {
|
|
56
139
|
return null
|
|
57
140
|
}
|
|
58
141
|
}
|
|
59
142
|
|
|
60
|
-
/**
|
|
61
|
-
|
|
143
|
+
/**
|
|
144
|
+
* Appends to the history (newest 20 kept). An entry without a `node` records
|
|
145
|
+
* the node the marker is at, i.e. where the outcome happened.
|
|
146
|
+
*
|
|
147
|
+
* @param {Marker} marker @param {HistoryEntry} entry @returns {Marker}
|
|
148
|
+
*/
|
|
149
|
+
export const withHistory = (marker, entry) => ({
|
|
150
|
+
...marker,
|
|
151
|
+
history: [...marker.history, { node: marker.node, ...entry }].slice(-HISTORY_KEPT),
|
|
152
|
+
})
|
|
62
153
|
|
|
63
154
|
/**
|
|
64
155
|
* The comment body. `--` inside the JSON would end the HTML comment early, so
|
|
65
|
-
* it is written as a JSON escape.
|
|
156
|
+
* it is written as a JSON escape. Always emits v2.
|
|
66
157
|
*
|
|
67
|
-
* @param {Marker}
|
|
158
|
+
* @param {Marker} input
|
|
68
159
|
* @param {{ maxAttempts?: number }} [opts]
|
|
69
160
|
*/
|
|
70
|
-
export function renderMarker(
|
|
161
|
+
export function renderMarker(input, { maxAttempts } = {}) {
|
|
162
|
+
const marker = withDefaults(input)
|
|
71
163
|
const json = JSON.stringify(marker).replace(/--/g, '-\\u002d')
|
|
72
164
|
const of = maxAttempts ? `/${maxAttempts}` : ''
|
|
73
165
|
const lines = [
|
|
74
166
|
`${PREFIX}${json} -->`,
|
|
75
|
-
`**cambium** · ${marker.
|
|
167
|
+
`**cambium** · ${marker.graph} · ${marker.node}${marker.status === 'waiting' ? '' : ` (${marker.status})`}` +
|
|
168
|
+
` · attempt ${marker.attempt}${of}` +
|
|
76
169
|
(marker.pr ? ` · PR #${marker.pr}` : '') +
|
|
77
170
|
(marker.host ? ` · host \`${marker.host}\`` : '') +
|
|
78
171
|
(marker.start ? ` · started ${marker.start}` : ''),
|
|
@@ -88,10 +181,10 @@ export function renderMarker(marker, { maxAttempts } = {}) {
|
|
|
88
181
|
'</details>',
|
|
89
182
|
)
|
|
90
183
|
if (marker.history.length) {
|
|
91
|
-
lines.push('', '| at | attempt | outcome | detail |', '
|
|
184
|
+
lines.push('', '| at | node | attempt | outcome | detail |', '|---|---|---|---|---|')
|
|
92
185
|
for (const h of marker.history)
|
|
93
186
|
lines.push(
|
|
94
|
-
`| ${h.at} | ${h.attempt} | ${h.outcome} | ${[
|
|
187
|
+
`| ${h.at} | ${h.node ?? ''} | ${h.attempt} | ${h.outcome} | ${[
|
|
95
188
|
h.pr ? `#${h.pr}` : '',
|
|
96
189
|
h.reason ?? '',
|
|
97
190
|
h.log ? `log \`${h.log}\`` : '',
|
|
@@ -105,3 +198,67 @@ export function renderMarker(marker, { maxAttempts } = {}) {
|
|
|
105
198
|
lines.push('', '_Written by cambium. Only cambium moves this issue’s labels._')
|
|
106
199
|
return lines.join('\n')
|
|
107
200
|
}
|
|
201
|
+
|
|
202
|
+
// ---- Rules for the graph runtime (pure; the runtime applies them)
|
|
203
|
+
|
|
204
|
+
/**
|
|
205
|
+
* Label vs node: the queue label wins. If the issue's queue label is owned by
|
|
206
|
+
* a different graph than the marker's, or (when the owner lists its `nodes`)
|
|
207
|
+
* the marker's node does not sit in that queue, or the marker's graph is done,
|
|
208
|
+
* the issue restarts at the owning graph's entry node.
|
|
209
|
+
*
|
|
210
|
+
* No queue label known to `queues`: the marker stands (nothing to compare).
|
|
211
|
+
* No marker: a fresh start at the entry node, which is not a reset.
|
|
212
|
+
*
|
|
213
|
+
* @param {string[]} labels
|
|
214
|
+
* @param {Marker | null} marker
|
|
215
|
+
* @param {Record<string, QueueOwner>} queues queue label → owning graph
|
|
216
|
+
* @returns {{ graph: string, node: string, reset: boolean } | null} null: no queue label and no marker
|
|
217
|
+
*/
|
|
218
|
+
export function effectivePosition(labels, marker, queues) {
|
|
219
|
+
const label = labels.find((l) => Object.hasOwn(queues, l))
|
|
220
|
+
if (!label) return marker ? { graph: marker.graph, node: marker.node, reset: false } : null
|
|
221
|
+
const owner = queues[label]
|
|
222
|
+
if (!marker) return { graph: owner.graph, node: owner.entryNode, reset: false }
|
|
223
|
+
const agrees =
|
|
224
|
+
marker.graph === owner.graph && marker.status !== 'done' && (!owner.nodes || new Set(owner.nodes).has(marker.node))
|
|
225
|
+
return agrees
|
|
226
|
+
? { graph: marker.graph, node: marker.node, reset: false }
|
|
227
|
+
: { graph: owner.graph, node: owner.entryNode, reset: true }
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
/**
|
|
231
|
+
* Graph versioning: a marker written under an older version keeps running if
|
|
232
|
+
* its node still exists in the current version; otherwise it restarts at the
|
|
233
|
+
* entry node, with a history note saying why.
|
|
234
|
+
*
|
|
235
|
+
* @param {Marker} marker
|
|
236
|
+
* @param {{ version: number, nodes: Iterable<string>, entryNode: string, at: string }} current
|
|
237
|
+
* @returns {{ action: 'keep' } | { action: 'restart', node: string, note: HistoryEntry }}
|
|
238
|
+
*/
|
|
239
|
+
export function graphVersionDecision(marker, { version, nodes, entryNode, at }) {
|
|
240
|
+
if (marker.graphVersion === version || new Set(nodes).has(marker.node)) return { action: 'keep' }
|
|
241
|
+
return {
|
|
242
|
+
action: 'restart',
|
|
243
|
+
node: entryNode,
|
|
244
|
+
note: {
|
|
245
|
+
at,
|
|
246
|
+
attempt: marker.attempt,
|
|
247
|
+
node: marker.node,
|
|
248
|
+
outcome: 'graph-changed',
|
|
249
|
+
reason: `${marker.graph} v${marker.graphVersion} → v${version}: node ${marker.node} no longer exists; restarting at ${entryNode}`,
|
|
250
|
+
},
|
|
251
|
+
}
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
/**
|
|
255
|
+
* `status: 'entering'` is written before a step node runs. On a later tick,
|
|
256
|
+
* a marker still `entering` with no tracked process means the step died
|
|
257
|
+
* mid-flight: the node's `recover` runs (default: requeue). Anything else
|
|
258
|
+
* resumes normally.
|
|
259
|
+
*
|
|
260
|
+
* @param {Marker} marker @param {boolean} hasTrackedProcess
|
|
261
|
+
* @returns {'resume' | 'recover'}
|
|
262
|
+
*/
|
|
263
|
+
export const enteringDecision = (marker, hasTrackedProcess) =>
|
|
264
|
+
marker.status === 'entering' && !hasTrackedProcess ? 'recover' : 'resume'
|