antcolony

16.8 KB

1. // brief.hl — `brief <project> <n>`: assemble a worker brief MECHANICALLY, modelled on the
2. // architect's hand-written `missions/*.md` (reading order, standard Hybriel block, rules, report).
3. //
4. // Mission 027: + "Conventions for all apps" (templates/conventions.md, as text) after Read first; "Tickets of <project>"
5. // (every other ticket, newest first, ≤ 40) before the Budget; the report part says WHERE the creator tests (live URL).
6. // Parts: [mission 022: "REJECTED by the creator: …" first while a rejection is unanswered] · header (ticket, session, ports) ·
7. // [mission 026: "Previous attempt" when the ticket had an earlier colony session — previous.hl] · Read first (the ticket, the concept, the project's
8. // README/STATUS, the antcolony README) · Where (code folder, live/deploy note) · Hybriel block
9. // (only when the project depends on hybriel) · Known open tickets of every project it depends on ·
10. // Relations (mission 022: parent / children / blocked by / blocks) · Rules · Report (the JSON schema of docs/scheduler-agent.md §4) · the ticket itself with its
11. // history (Markdown read view when tickets serves `Accept: text/markdown`, else rendered here
12. // from the JSON).
13. import { readFile, writeFile, mkDir } from 'hl:fs'
14. import { env } from 'hl:proc'
15. import { now, timestamp } from 'hl:time'
16. import { randomBytes } from 'hl:crypto'
17. import { loadRegistry } from './registry.hl'
18. import { getJson, getRaw, ticketPath, pageUrl, baseUrl, isCreatorEvent } from './tickets.hl'
19. import { NL, fromCwd, option, positionals, sortByNumber } from './util.hl'
20. import { relationsOf, rejectionOf, rejectedLines, relationLines, questionWhy, isCreatorQuestion } from './relations.hl'
21. import { setting, isWholeNumber } from './claude.hl'
22. import { previousLines } from './previous.hl'
23. import { decisionLines, layoutsConventions, creatorNames } from './librarian.hl'
25. static CLOSED = ['confirmed', 'rejected']
27. // `A-B` with 1 <= A <= B <= 65535 → { from, to } or null
28. static portRange = (s) => {
29. let d = s.indexOf('-')
30. if (d <= 0) { return null }
31. let a = toNumber(s.slice(0, d))
32. let b = toNumber(s.slice(d + 1))
33. if (a == null || b == null || a < 1 || b > 65535 || a > b) { return null }
34. return { from = a to = b }
35. }
37. // the ticket + history as Markdown, rendered from the JSON (fallback while tickets has no read view)
38. static renderTicket = (data) => {
39. let t = data.ticket
40. let out = []
41. out.push('# ' + t.project + ' ' + t.ref + ': ' + t.subject)
42. out.push('')
43. out.push('state: **' + t.state + '** · opened ' + t.created + ' · updated ' + t.updated + ' · ' + pageUrl(t))
44. out.push('')
45. out.push(t.summary == '' ? '_(no summary)_' : t.summary)
46. out.push('')
47. out.push('## History')
48. for (e of data.events) {
49. let what = e.label
50. if (e.kind == 'state') { what = what + ' ' + e.from + ' → ' + e.to }
51. out.push('')
52. out.push('### ' + e.seq + ' · ' + e.when + ' · ' + e.author + ' ' + what)
53. if (e.text != null && e.text != '') {
54. out.push('')
55. out.push(e.text)
56. }
57. }
58. return out.join(NL)
59. }
61. // → { text, how } : the Markdown read view if tickets serves it, else the rendering above
62. static ticketMarkdown = (project, number, data) => {
63. let r = getRaw(ticketPath(project, number), 'text/markdown')
64. let ct = r == null ? null : r.headers['content-type']
65. if (r != null && r.status == 200 && ct != null && ct.startsWith('text/markdown')) { return { text = r.text().trim() how = 'Markdown read view' } }
66. return { text = renderTicket(data) how = 'rendered from JSON: tickets served no Markdown read view' }
67. }
69. // → lines: the not-closed tickets of one project
70. static depTickets = (project) => {
71. let r = getJson('/api/projects/' + project + '/tickets')
72. if (r.status == 404) { return ['- _(no tickets in project ' + project + ')_'] }
73. if (r.status != 200) { return ['- _(could not read: ' + r.status + ')_'] }
74. let out = []
75. for (t of r.json.tickets) {
76. if (!CLOSED.includes(t.state)) { out.push('- ' + t.project + ' ' + t.ref + ' [' + t.state + '] ' + t.subject + ' — ' + pageUrl(t)) }
77. }
78. if (out.length == 0) { out.push('- _(none open)_') }
79. return out
80. }
82. // mission 027 ("before asking, check … the project's open / confirmed tickets"): every other ticket of the project
83. // (all states: answered questions and confirmed work hold decisions), newest first, at most 40 → lines
84. static PROJECT_TICKETS_MAX = 40
86. // antcolony#22: an answered question shows the creator's answer — the creator's comments (and state notes) on it, quoted,
87. // each cut at 600 characters, the last 3 → lines (empty when the creator wrote nothing / the ticket cannot be read)
88. static ANSWER_MAX = 600
89. static answerLines = (t) => {
90. let d = getJson(ticketPath(t.project, t.number))
91. if (d.status != 200 || d.json == null || d.json.events == null) { return [] }
92. let names = creatorNames()
93. let texts = []
94. for (e of d.json.events) {
95. if ((e.kind == 'comment' || e.kind == 'state') && e.text != null && e.text.trim() != '' && isCreatorEvent(t.project, e, names)) { texts.push(e.text.trim()) }
96. }
97. let out = []
98. let i = texts.length > 3 ? texts.length - 3 : 0
99. while (i < texts.length) {
100. let x = texts[i]
101. if (x.length > ANSWER_MAX) { x = x.slice(0, ANSWER_MAX) + ' …' }
102. let first = true
103. for (l of x.split(NL)) {
104. out.push(' ' + (first ? '- Answer of the creator: ' : ' ') + l)
105. first = false
106. }
107. i = i + 1
108. }
109. return out
110. }
111. static projectTickets = (project, number) => {
112. let r = getJson('/api/projects/' + project + '/tickets')
113. if (r.status != 200) { return ['- _(could not read: ' + r.status + ')_'] }
114. let rows = []
115. for (t of r.json.tickets) { if (('' + t.number) != ('' + number)) { rows.push(t) } }
116. // newest first (the API's order is not relied on)
117. sortByNumber(rows, (t) => { return 0 - toNumber('' + t.number) })
118. let out = []
119. let i = 0
120. while (i < rows.length && out.length < PROJECT_TICKETS_MAX) {
121. let t = rows[i]
122. out.push('- ' + t.project + ' ' + t.ref + ' [' + t.state + '] ' + t.subject + ' — ' + pageUrl(t))
123. // antcolony#22: an answered / confirmed question carries the creator's answer
124. if ((t.state == 'answered' || t.state == 'confirmed') && isCreatorQuestion(t)) {
125. for (l of answerLines(t)) { out.push(l) }
126. }
127. i = i + 1
128. }
129. if (rows.length > PROJECT_TICKETS_MAX) { out.push('- _(and ' + (rows.length - PROJECT_TICKETS_MAX) + ' older ones: GET ' + baseUrl() + '/api/projects/' + project + '/tickets)_') }
130. if (out.length == 0) { out.push('- _(no other tickets)_') }
131. return out
132. }
134. static fill = (text, vars) => {
135. let s = text
136. for (k of vars.keys()) { s = s.replaceAll('{{' + k + '}}', vars[k]) }
137. return s
138. }
140. // the default session id: s-<UTC yyyymmddThhmm>-<6 hex>
141. static newSession = () => { return 's-' + timestamp(now()).slice(0, 16).replaceAll(':', '').replaceAll('-', '') + '-' + randomBytes(3, 'hex') }
143. static PORTS_MARKER = '@AGENT@'
144. static PORT_FROM_MARKER = '@PORT_FROM@'
145. static PORT_TO_MARKER = '@PORT_TO@'
147. // the port range from --ports / COLONY_PORTS / 8700-8749 → { from, to, text } or { error }
148. static portsOf = (argv) => {
149. let portsText = option(argv, '--ports')
150. if (portsText == null) { portsText = env('COLONY_PORTS') }
151. if (portsText == null || portsText == '') { portsText = '8700-8749' }
152. // mission 035 (antcolony#14): a brief built by the scheduler for an AGENT on another host — the agent owns the port pool,
153. // so the range is a marker the agent fills in (work --brief-file)
154. if (portsText == PORTS_MARKER) { return { from = PORT_FROM_MARKER to = PORT_TO_MARKER text = PORTS_MARKER } }
155. let ports = portRange(portsText)
156. if (ports == null) { return { error = '--ports must be A-B (1 ≤ A ≤ B ≤ 65535), got ' + portsText } }
157. return ports
158. }
160. // mission 025: the step budget → the step by which the report must be written: N − min(10, N/3 rounded down), at least 1
161. static reportStep = (n) => {
162. let r = (n - (n % 3)) / 3
163. if (r > 10) { r = 10 }
164. let s = n - r
165. return s < 1 ? 1 : s
166. }
168. // mission 025 (ticket antcolony#1 — the first live worker ran out of steps before its report): the brief tells the
169. // worker its budget (the same --max-turns / --timeout `work` passes to Claude) and to leave room for the report
170. static budgetLines = (argv) => {
171. let turnsText = setting(argv, '--max-turns', 'COLONY_MAX_TURNS', '40')
172. let timeText = setting(argv, '--timeout', 'COLONY_WORK_TIMEOUT', '3600')
173. let n = isWholeNumber(turnsText) ? toNumber(turnsText) : 40
174. let secs = isWholeNumber(timeText) ? toNumber(timeText) : 3600
175. let mins = (secs - (secs % 60)) / 60
176. let o = []
177. o.push('## Budget — leave room for the report')
178. o.push('- **Steps: at most ' + n + '** (every tool call is a step; Claude stops the session at step ' + n + '). **Write your report before step ' + reportStep(n) + '.** A session cut off before its report is lost work: nobody sees what you did.')
179. o.push('- Time: at most ' + (mins < 1 ? secs + ' seconds' : mins + ' minutes') + ', then the session is killed.')
180. o.push('- Running short: stop, start nothing new, and report what is done, what is verified and what is still open (e.g. "not copied back yet") — an honest partial report is worth more than one more step.')
181. return o
182. }
184. // assemble the brief (no file written) → { text, ref, session, ports, how, meta, ticket, reg }
185. // or { error, refused } (refused = a rule said no, not a failure)
186. static buildBrief = (project, number, argv) => {
187. let reg = loadRegistry()
188. for (e of reg.errors) { console.log('registry: ' + e) }
189. let m = reg.projects[project]
190. if (m == null) { return { refused = true error = 'REFUSED — project ' + project + ' has no metadata (' + reg.dir + '/' + project + '.json) → question for the creator (`next --post` files it)' } }
191. if (!m.hasConcept) { return { refused = true error = 'REFUSED — project ' + project + ' has no concept → question for the creator (`next --post` files it). No brief without a written concept.' } }
192. let ports = portsOf(argv)
193. if (ports.error != null) { return { error = ports.error } }
194. let got = getJson(ticketPath(project, number))
195. if (got.status != 200) { return { error = 'ticket ' + project + '#' + number + ' → ' + got.status + ' ' + (got.text == null ? '' : got.text) } }
196. let data = got.json
197. let t = data.ticket
198. // mission 030: a question ticket is never work (no brief, so `work` / `cycle` / `run` cannot start on it either)
199. let qwhy = questionWhy(t)
200. if (qwhy != null) { return { refused = true error = 'REFUSED — ' + project + t.ref + ' "' + t.subject + '" is ' + qwhy + ' (state ' + t.state + '); never work — no brief, no worker' } }
201. let session = option(argv, '--session')
202. if (session == null || session == '') { session = newSession() }
203. let ref = project + t.ref
204. let md = ticketMarkdown(project, number, data)
205. // mission 022: relations (children looked up for their `source`: creator questions vs. work) + the rejection
206. let lookup = (id) => {
207. let r = getJson('/api/tickets/' + id)
208. return r.status == 200 ? r.json.ticket : null
209. }
210. let rel = relationsOf(t, lookup)
211. let rj = rejectionOf(data.events)
213. let o = []
214. // "Rejections are work": a rejection no colony report answered yet is the FIRST thing of the brief
215. if (rj.pending) { for (l of rejectedLines(rj, ref)) { o.push(l) } }
216. o.push('# Brief — ' + ref + ': ' + t.subject)
217. o.push('')
218. o.push('Generated by antcolony-scheduler v0 at ' + timestamp(now()) + ' (UTC). Ticket: ' + pageUrl(t) + ' · session `' + session + '`.')
219. o.push('')
220. o.push("One-shot worker on ONE ticket. You do NOT deploy and do NOT touch Byrodin's services; only the creator confirms — you can at most set `awaiting creator` (the scheduler does it from your report).")
221. o.push('')
222. // mission 026: a ticket that had an earlier colony session → what it did, what is open, its work copy, its report
223. let prev = previousLines(data.events, m.dev == null ? '' : m.dev.folder)
224. if (prev.length > 0) {
225. for (l of prev) { o.push(l) }
226. o.push('')
227. }
228. o.push('## Read first — in this order')
229. o.push('1. The ticket with its history — section "Ticket" at the end of this brief (live: `GET ' + baseUrl() + ticketPath(project, number) + '`, send a `user-agent` header, `Accept: text/markdown` for the read view).')
230. o.push('2. **Concept: `' + m.concept + "`** — source of truth; don't add what it doesn't describe; where it is silent, make the smallest choice and list it under `decided`.")
231. if (m.dev != null && m.dev.folder != null) {
232. o.push('3. `' + m.dev.host + ':' + m.dev.folder + '/README.md` and `STATUS.md` (and any `docs/` they link).')
233. } else {
234. o.push("3. The project's README.md / STATUS.md.")
235. }
236. // mission 027: the conventions reach the worker AS TEXT (workers on Loreana cannot read Byrodin — the first gitoria
237. // worker tried ssh and was refused); the antcolony README stays named as the source
238. o.push('4. "Conventions for all apps" below (from `byrodin:/CONTAINERS/projects/antcolony/README.md`, as text — you may not be able to reach Byrodin).')
239. // mission 029 (antcolony#21): the creator's decisions (librarian) — global + this project's, after the conventions
240. o.push('5. "Decisions of the creator" below — collected from the creator\'s own words; they override anything else.')
241. // mission 029: every brief for an app with a UI (registry `"ui": true`) names the creator's markup/CSS rules
242. if (m.hasUi) { o.push('6. **UI rules: `' + layoutsConventions() + '`** — the creator\'s markup/CSS rules (WorldAPI layout conventions); every page and style you write follows them.') }
243. o.push('')
244. o.push(readFile('./templates/conventions.md').trim())
245. o.push('')
246. for (l of decisionLines(project, reg, t.subject + NL + (t.summary == null ? '' : t.summary))) { o.push(l) }
247. o.push('')
248. o.push('## Where')
249. if (m.dev != null) { o.push('- Development: `' + m.dev.host + ':' + m.dev.folder + '`') }
250. if (m.code != null) { o.push('- Code: `' + m.code.host + ':' + m.code.folder + '`') }
251. if (m.live != null) { o.push('- Live (never touch): `' + m.live.host + ':' + m.live.folder + '`' + (m.live.url != null ? ' — ' + m.live.url : '') + ' — the creator tests THERE after the deploy: write your `test` steps for it') }
252. if (m.deploy != null) { o.push('- Deploy: ' + m.deploy + ' — not your job') }
253. o.push('- **Ports for everything you start: ' + ports.from + '–' + ports.to + ' only** (other workers run tests on the same machine; `work` / `run` also put the range into your environment: `COLONY_PORTS`, `COLONY_PORT_FROM`, `COLONY_PORT_TO`).')
254. o.push('')
255. for (l of relationLines(rel)) { o.push(l) }
256. o.push('')
257. if (m.deps.includes('hybriel')) {
258. o.push(readFile('./templates/hybriel-block.md').trim())
259. o.push('In the JSON report below, a Hybriel finding is an `issues` entry with `"project": "hybriel"`.')
260. o.push('')
261. }
262. if (m.deps.length > 0) {
263. o.push('## Known open tickets of the projects ' + project + " depends on (check them before reporting an issue; don't re-report)")
264. for (d of m.deps) {
265. o.push('')
266. o.push('### ' + d)
267. for (l of depTickets(d)) { o.push(l) }
268. }
269. o.push('')
270. }
271. o.push('## Tickets of ' + project + ' — decisions may already be there (check before you ask a question)')
272. for (l of projectTickets(project, number)) { o.push(l) }
273. o.push('')
274. for (l of budgetLines(argv)) { o.push(l) }
275. o.push('')
276. o.push(readFile('./templates/rules.md').trim())
277. o.push('')
278. // mission 027: the test steps are for the creator on the live site (registry `live.url`) — or, without one, the real result
279. let where = m.live != null && m.live.url != null ? 'on the live site ' + m.live.url + ' (after the deploy — you do not deploy; describe what the creator clicks there)' : 'on the real result (this project has no live site: name what the creator opens, e.g. the document in the project folder — never a work copy)'
280. o.push(fill(readFile('./templates/report.md').trim(), { TICKET = ref SESSION = session PROJECTS = reg.names.join(', ') WHERE = where }))
281. o.push('')
282. o.push('## Ticket (' + md.how + ')')
283. o.push('')
284. o.push(md.text)
285. o.push('')
286. return { text = o.join(NL) ref = ref session = session ports = ports how = md.how meta = m ticket = t reg = reg rel = rel rejection = rj events = data.events }
287. }
289. static runBrief = (argv) => {
290. let pos = positionals(argv)
291. if (pos.length != 3) {
292. console.log('usage: brief <project> <number> [--out FILE] [--ports A-B] [--session ID]')
293. return false
294. }
295. let b = buildBrief(pos[1], pos[2], argv)
296. if (b.error != null) {
297. console.log('brief: ' + b.error)
298. return false
299. }
300. if (b.ticket.state != 'open') { console.log('brief: note — ' + b.ref + ' is "' + b.ticket.state + '", not open (the brief is written anyway)') }
301. if (!b.meta.takesWorkers) { console.log('brief: note — project ' + b.meta.name + ' takes no workers ("workers": false; `work` refuses it — the brief is written anyway)') }
302. let out = option(argv, '--out')
303. if (out == null || out == '') {
304. mkDir('./briefs', 448)
305. out = './briefs/' + pos[1] + '-' + pos[2] + '.md'
306. } else {
307. out = fromCwd(out)
308. }
309. writeFile(out, b.text, 420)
310. console.log('brief: ' + b.ref + ' → ' + (out.startsWith('./briefs/') ? out.slice(2) + ' (beside scheduler.hl)' : out) + ' (session ' + b.session + ', ports ' + b.ports.from + '-' + b.ports.to + ', ticket via ' + b.how + ')')
311. return true
312. }