antcolony

13.6 KB

1. // lease.hl — leases that expire (mission 020, ticket antcolony#1/#2; concept docs/scheduler-agent.md §2
2. // "a ticket handed to an agent gets a lease; the agent's heartbeat renews it").
3. //
4. // tickets is the only state, so a lease is TEXT in the ticket: one plain line for the creator + ONE short machine
5. // line (mission 023: markers must not clutter what the creator reads):
6. // the lease itself = the `→ in progress` state event of `work`:
7. // A worker started on this ticket.
8. //
9. // colony-lease: <S> · host <H> · started · ms <expiry epoch ms>
10. // a heartbeat (only when a session outlives half the ttl) = a comment `Still working.` + `colony-lease: <S> · host <H> · renewed · ms …`
11. // a resumed session = a comment `Work continues after a pause.` + `colony-lease: <S> · host <H> · resumed (park k) · ms …`
12. // a parked session = a comment `Paused: … — continues after …` +
13. // colony-parked: <S> · host <H> · phase worker|controller · resume-ms <ms> · ms <expiry>
14. // (markers written before mission 023 also carry `lease until <ISO>` / `claude <uuid>` / `resume after <ISO>`
15. // parts — still parsed; unknown parts are ignored.)
16. // The LAST marker of the lease's session (from the `→ in progress` event on) decides. Past its `ms` the lease is
17. // dead: `expireLease` sets the ticket back to `open` with a short state text and the marker
18. // `colony-lease-expired: <S> · host <H>`. An `in progress` without a colony-lease marker (the architect's missions,
19. // v0 leases) is never expired — nobody can know how long it may take.
20. //
21. // Mission 031 (ticket antcolony#1 — live 2026-09-24 21:05Z: ident#19 was deployed and handed to the creator while the
22. // daemon's iteration was running; the iteration still acted on what it had read before and expired the finished ticket →
23. // back to open, a second worker ran on it):
24. // * a lease ENDS (kind `ended`, never expired) as soon as, after its `→ in progress` event, the ticket left `in progress`
25. // (any state change, by anyone) or its session's work was finished: a `colony-deployed:` line (any session — the
26. // deploy of the built work; also the gap between `deployed`'s comment and its state change, 146 ms live) or a
27. // `colony-report:` (not a `· ready to deploy` one — readyOf) / `colony-verdict:` / `colony-run:` / `colony-lease-expired:`
28. // line of THE LEASE'S session;
29. // * the daemon never acts on its survey alone: `expireLease` / `stillLeased` RE-READ the ticket right before the write
30. // and act only if it is STILL `in progress` with the SAME lease (same session, same expiry, same parked state);
31. // otherwise nothing is written and the reason is returned (`skipped`), which the caller prints.
32. // Remaining gap: the re-read and the write are two requests (a few ms apart); tickets has no conditional state change.
33. // COLONY_TEST_HOOK_URL (tests only): GET <url>?action=…&project=…&number=…&session=… right BEFORE that re-read, waiting
34. // for the answer — the e2e changes the ticket there to reproduce the race deterministically.
35. import { every, now, timestamp } from 'hl:time'
36. import { env } from 'hl:proc'
37. import { fetch } from 'hl:fetch'
38. import { postJson, getJson, readToken, ticketPath, userAgent } from './tickets.hl'
39. import { NL } from './util.hl'
41. static LEASE = 'colony-lease: '
42. static PARKED = 'colony-parked: '
44. // lease settings: --lease-ttl / COLONY_LEASE_TTL (s, default 7200), --heartbeat / COLONY_HEARTBEAT (s, default ttl/2).
45. // Mission 023 ("heartbeats: as few and as short as possible"): was 3600 / ttl/3 = 3 comments per session hour; now a
46. // session shorter than 1 h writes none, the default worker (1 h) + controller (15 min) at most one.
47. static optionOf = (argv, flag, name, fallback) => {
48. let i = 0
49. while (i < argv.length) {
50. if (argv[i] == flag && i + 1 < argv.length) { return argv[i + 1] }
51. i = i + 1
52. }
53. let v = env(name)
54. if (v == null || v == '') { return fallback }
55. return v
56. }
57. static wholeOrNull = (s) => {
58. if (s == null || s == '') { return null }
59. let i = 0
60. while (i < s.length) {
61. let c = s.charCodeAt(i)
62. if (c < 48 || c > 57) { return null }
63. i = i + 1
64. }
65. let n = toNumber(s)
66. if (n < 1) { return null }
67. return n
68. }
69. // → { ttl, heartbeat } (seconds) or { error }
70. static leaseSettings = (argv) => {
71. let t = optionOf(argv, '--lease-ttl', 'COLONY_LEASE_TTL', '7200')
72. let ttl = wholeOrNull(t)
73. if (ttl == null) { return { error = '--lease-ttl must be whole seconds ≥ 1, got ' + t } }
74. let half = (ttl - ttl % 2) / 2
75. if (half < 1) { half = 1 }
76. let h = optionOf(argv, '--heartbeat', 'COLONY_HEARTBEAT', '' + half)
77. let hb = wholeOrNull(h)
78. if (hb == null) { return { error = '--heartbeat must be whole seconds ≥ 1, got ' + h } }
79. if (hb >= ttl) { return { error = '--heartbeat (' + hb + ' s) must be shorter than --lease-ttl (' + ttl + ' s)' } }
80. return { ttl = ttl heartbeat = hb }
81. }
83. static leaseLine = (session, host, what, expiryMs) => {
84. return LEASE + session + ' · host ' + host + ' · ' + what + ' · ms ' + expiryMs
85. }
86. static parkLine = (session, host, phase, resumeMs, expiryMs) => {
87. return PARKED + session + ' · host ' + host + ' · phase ' + phase + ' · resume-ms ' + resumeMs + ' · ms ' + expiryMs
88. }
89. // a time for the creator: `2026-09-24 18:19 UTC`
90. static clock = (ms) => {
91. let t = timestamp(ms)
92. return t.slice(0, 10) + ' ' + t.slice(11, 16) + ' UTC'
93. }
95. // one marker line → { kind: lease | parked, session, host, phase, claude, resumeMs, expiryMs } or null
96. static parseLine = (line) => {
97. let kind = null
98. let rest = null
99. if (line.startsWith(LEASE)) {
100. kind = 'lease'
101. rest = line.slice(LEASE.length)
102. } else if (line.startsWith(PARKED)) {
103. kind = 'parked'
104. rest = line.slice(PARKED.length)
105. } else { return null }
106. let parts = rest.split(' · ')
107. let m = { kind = kind session = parts[0].trim() host = null phase = null claude = null resumeMs = null expiryMs = null }
108. for (p of parts) {
109. if (p.startsWith('host ')) { m.host = p.slice(5) }
110. else if (p.startsWith('phase ')) { m.phase = p.slice(6) }
111. else if (p.startsWith('claude ')) { m.claude = p.slice(7) }
112. else if (p.startsWith('resume-ms ')) { m.resumeMs = toNumber(p.slice(10)) }
113. else if (p.startsWith('ms ')) { m.expiryMs = toNumber(p.slice(3)) }
114. }
115. if (m.expiryMs == null) { return null }
116. return m
117. }
119. // the markers in one event text (a comment or a state text), in order
120. static markersIn = (text) => {
121. let out = []
122. if (text == null) { return out }
123. for (l of text.split(NL)) {
124. let m = parseLine(l.trim())
125. if (m != null) { out.push(m) }
126. }
127. return out
128. }
130. // mission 027 (deploy gate): the session whose report on a project with a live site waits for the deploy — the last
131. // `colony-report: S · … · ready to deploy` line, unless a later `colony-deployed: S`, a lease of ANOTHER session or a state
132. // change away from `in progress` came after it → S or null
133. static READY_END = ' · ready to deploy'
134. static readyOf = (events) => {
135. let s = null
136. for (e of events) {
137. if (e.text != null) {
138. for (l of e.text.split(NL)) {
139. let t = l.trim()
140. if (t.startsWith('colony-report: ') && t.endsWith(READY_END)) { s = t.slice(15).split(' · ')[0].trim() }
141. else if (s != null && t.startsWith('colony-deployed: ' + s + ' ')) { s = null }
142. else if (s != null && t.startsWith(LEASE) && !t.startsWith(LEASE + s + ' ')) { s = null }
143. }
144. }
145. if (s != null && e.kind == 'state' && e.to != 'in progress') { s = null }
146. }
147. return s
148. }
150. // mission 031: the lease of `session` taken at events[at] has ENDED (see the header) → a short reason, or null
151. static END_OWN = ['colony-report: ' 'colony-verdict: ' 'colony-run: ' 'colony-lease-expired: ']
152. static endOf = (events, at, session) => {
153. let j = at + 1
154. while (j < events.length) {
155. let e = events[j]
156. if (e.kind == 'state' && e.to != 'in progress') {
157. return 'the ticket was moved to "' + e.to + '"' + (e.author != null ? ' by ' + e.author : '')
158. }
159. if (e.text != null) {
160. for (l of e.text.split(NL)) {
161. let t = l.trim()
162. if (t.startsWith('colony-deployed: ')) { return 'deployed (' + t.split(' · ')[0] + ')' }
163. // a `… · ready to deploy` report keeps the ticket in progress on purpose (readyOf: kind ready) — not an end here
164. let own = !t.endsWith(READY_END)
165. for (p of END_OWN) {
166. if (own && (t.startsWith(p + session + ' ') || t == (p + session))) { return 'its session finished (' + p + session + ')' }
167. }
168. }
169. }
170. j = j + 1
171. }
172. return null
173. }
175. // the lease of a ticket from its events (oldest first) →
176. // { kind: none | foreign | colony | ready (mission 027: built, waiting for the deploy — never expires) | ended (mission 031:
177. // finished or moved on — never expires), session, host, expiryMs, parked, phase, claude, resumeMs, text }
178. static leaseOf = (events) => {
179. let rs = readyOf(events)
180. if (rs != null) { return { kind = 'ready' session = rs text = 'built, waiting for the deploy' } }
181. let at = -1
182. let i = 0
183. while (i < events.length) {
184. let e = events[i]
185. if (e.kind == 'state' && e.to == 'in progress') { at = i }
186. i = i + 1
187. }
188. if (at < 0) { return { kind = 'none' } }
189. let first = markersIn(events[at].text)
190. if (first.length == 0 || first[0].kind != 'lease') {
191. let t = events[at].text == null ? '' : events[at].text
192. return { kind = 'foreign' text = t.split(NL)[0] }
193. }
194. let session = first[0].session
195. let ended = endOf(events, at, session)
196. if (ended != null) { return { kind = 'ended' session = session host = first[0].host text = ended } }
197. let last = first[0]
198. let j = at + 1
199. while (j < events.length) {
200. for (m of markersIn(events[j].text)) { if (m.session == session) { last = m } }
201. j = j + 1
202. }
203. return { kind = 'colony' session = session host = last.host expiryMs = last.expiryMs parked = last.kind == 'parked' phase = last.phase claude = last.claude resumeMs = last.resumeMs }
204. }
206. // mission 031: tests only — COLONY_TEST_HOOK_URL gets a GET right before the re-read (the answer is awaited, ignored)
207. static testHook = (action, project, number, session) => {
208. let u = env('COLONY_TEST_HOOK_URL')
209. if (u == null || u == '') { return null }
210. fetch(u + '?action=' + action + '&project=' + project + '&number=' + number + '&session=' + session, { headers = { 'user-agent' = userAgent() } timeoutMs = 20000 })
211. return null
212. }
214. // mission 031: RE-READ the ticket right before acting on a lease the survey saw (`seen`, from leaseOf) →
215. // { ok: true, lease } when it is STILL `in progress` with the same lease (same session, expiry and parked state),
216. // else { ok: false, why } — the caller writes nothing and prints why.
217. static stillLeased = (action, project, number, seen) => {
218. testHook(action, project, number, seen.session)
219. let d = getJson(ticketPath(project, number))
220. if (d.status != 200) { return { ok = false why = 'could not re-read it (' + d.status + ')' } }
221. let st = d.json.ticket.state
222. if (st != 'in progress') { return { ok = false why = 'it is "' + st + '" now' } }
223. let l = leaseOf(d.json.events)
224. if (l.kind == 'ready') { return { ok = false why = 'it is built now, waiting for the deploy (session ' + l.session + ')' } }
225. if (l.kind == 'ended') { return { ok = false why = 'the lease of ' + l.session + ' has ended: ' + l.text } }
226. if (l.kind != 'colony') { return { ok = false why = 'it has no colony lease any more' } }
227. if (l.session != seen.session) { return { ok = false why = 'another session holds it now (' + l.session + ')' } }
228. if (l.expiryMs != seen.expiryMs || l.parked != seen.parked) { return { ok = false why = 'the lease of ' + l.session + ' changed (now ' + (l.parked ? 'parked, ' : '') + 'until ' + timestamp(l.expiryMs).slice(0, 19) + 'Z)' } }
229. return { ok = true lease = l }
230. }
232. // the lease is dead → the ticket back to `open`, the reason in the state text → { ok, text } or { ok: false, skipped: true,
233. // text: why } (mission 031: only if the ticket is STILL in progress with the same dead lease — re-read first)
234. static expireLease = (project, number, seen, token) => {
235. let chk = stillLeased('expire', project, number, seen)
236. if (!chk.ok) { return { ok = false skipped = true text = chk.why } }
237. let lease = chk.lease
238. if (now() < lease.expiryMs) { return { ok = false skipped = true text = 'the lease is alive until ' + timestamp(lease.expiryMs).slice(0, 19) + 'Z' } }
239. let what = lease.parked ? 'Back to open: the paused work was never continued — a new worker will pick it up.' : 'Back to open: the worker stopped answering (its computer crashed or went offline) — a new worker will pick it up.'
240. let text = what + NL + NL + 'colony-lease-expired: ' + lease.session + ' · host ' + lease.host
241. let s = postJson(ticketPath(project, number) + '/state', { state = 'open' text = text }, token)
242. if (s.status != 201) { return { ok = false text = s.status + ' ' + s.text } }
243. return { ok = true text = 'open' }
244. }
246. // a comment on the ticket with a lease marker → { ok, text }
247. static postLease = (project, number, text, token) => {
248. let c = postJson(ticketPath(project, number) + '/comments', { text = text }, token)
249. if (c.status != 201) { return { ok = false text = c.status + ' ' + c.text } }
250. return { ok = true text = 'ok' }
251. }
253. // the heartbeat of a running session: every `hb` s a renewal comment (expiry = now + ttl). → the timer (stop() it)
254. // l = { project, number, ref, session, host, ttl, heartbeat }
255. static startHeartbeat = (l) => {
256. let t = every(l.heartbeat)
257. on t.tick(x) {
258. let tk = readToken()
259. if (tk.error != null) {
260. console.log('lease: HEARTBEAT FAILED for ' + l.ref + ' (session ' + l.session + '): ' + tk.error)
261. return null
262. }
263. let exp = now() + l.ttl * 1000
264. let r = postLease(l.project, l.number, 'Still working.' + NL + NL + leaseLine(l.session, l.host, 'renewed', exp), tk.token)
265. if (r.ok) { console.log('lease: renewed ' + l.ref + ' (session ' + l.session + ') until ' + timestamp(exp)) }
266. else { console.log('lease: HEARTBEAT FAILED for ' + l.ref + ' (session ' + l.session + '): ' + r.text) }
267. return null
268. }
269. return t
270. }