oda-engine 0.0.0-stage → 0.1.0

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.
Files changed (204) hide show
  1. package/README.md +151 -2
  2. package/bin/nowhere.mjs +352 -0
  3. package/lib/account.mjs +57 -0
  4. package/lib/agentModules.mjs +57 -0
  5. package/lib/devServer.mjs +351 -0
  6. package/lib/headless.mjs +231 -0
  7. package/lib/headlessPreview.mjs +212 -0
  8. package/lib/keys.mjs +517 -0
  9. package/lib/make.mjs +855 -0
  10. package/lib/mcp.mjs +537 -0
  11. package/lib/open.mjs +22 -0
  12. package/lib/preview.mjs +87 -0
  13. package/lib/previewRpc.mjs +134 -0
  14. package/lib/project.mjs +359 -0
  15. package/lib/publishFlow.mjs +90 -0
  16. package/lib/resources.mjs +50 -0
  17. package/lib/rules.mjs +60 -0
  18. package/lib/scaffold.mjs +42 -0
  19. package/lib/setup.mjs +59 -0
  20. package/lib/tools.mjs +668 -0
  21. package/package.json +51 -4
  22. package/template/game.config.json +9 -0
  23. package/template/scene.json +4 -0
  24. package/template/src/main.ts +11 -0
  25. package/vendor/DOCS.md +447 -0
  26. package/vendor/agent/appRun.mjs +520 -0
  27. package/vendor/agent/assets/brief.mjs +242 -0
  28. package/vendor/agent/assets/collider.mjs +531 -0
  29. package/vendor/agent/assets/environments/index.mjs +12 -0
  30. package/vendor/agent/assets/environments/worldlabs.mjs +161 -0
  31. package/vendor/agent/assets/fetch.mjs +168 -0
  32. package/vendor/agent/assets/footprint.mjs +13 -0
  33. package/vendor/agent/assets/gltf.mjs +547 -0
  34. package/vendor/agent/assets/hdr.mjs +269 -0
  35. package/vendor/agent/assets/imageOps.mjs +171 -0
  36. package/vendor/agent/assets/images/codex.mjs +307 -0
  37. package/vendor/agent/assets/images/fal.mjs +75 -0
  38. package/vendor/agent/assets/images/gemini.mjs +84 -0
  39. package/vendor/agent/assets/images/index.mjs +25 -0
  40. package/vendor/agent/assets/images/openai.mjs +75 -0
  41. package/vendor/agent/assets/images/stability.mjs +71 -0
  42. package/vendor/agent/assets/images/views.mjs +31 -0
  43. package/vendor/agent/assets/import.mjs +1352 -0
  44. package/vendor/agent/assets/inspect.mjs +465 -0
  45. package/vendor/agent/assets/jobs.mjs +196 -0
  46. package/vendor/agent/assets/ktx2.mjs +290 -0
  47. package/vendor/agent/assets/ledger.mjs +466 -0
  48. package/vendor/agent/assets/net.mjs +254 -0
  49. package/vendor/agent/assets/prices.json +39 -0
  50. package/vendor/agent/assets/providers/fal.mjs +115 -0
  51. package/vendor/agent/assets/providers/index.mjs +22 -0
  52. package/vendor/agent/assets/providers/meshy.mjs +119 -0
  53. package/vendor/agent/assets/providers/tripo.mjs +188 -0
  54. package/vendor/agent/assets/sources/ambientcg.mjs +129 -0
  55. package/vendor/agent/assets/sources/index.mjs +23 -0
  56. package/vendor/agent/assets/sources/polyhaven.mjs +237 -0
  57. package/vendor/agent/assets/sources/polypizza.mjs +121 -0
  58. package/vendor/agent/assets/splat.mjs +631 -0
  59. package/vendor/agent/assets/targets.mjs +122 -0
  60. package/vendor/agent/assets/tile.mjs +261 -0
  61. package/vendor/agent/assets/unzip.mjs +180 -0
  62. package/vendor/agent/blender/cleanup.py +360 -0
  63. package/vendor/agent/blender/convert.py +167 -0
  64. package/vendor/agent/blender/find.mjs +192 -0
  65. package/vendor/agent/blender/nw_export.py +104 -0
  66. package/vendor/agent/blender/nw_rubric.py +426 -0
  67. package/vendor/agent/blender/run.mjs +193 -0
  68. package/vendor/agent/blender/runner.py +252 -0
  69. package/vendor/agent/blender/sheet.py +743 -0
  70. package/vendor/agent/depth.mjs +134 -0
  71. package/vendor/agent/director/board.mjs +451 -0
  72. package/vendor/agent/director/contracts.mjs +663 -0
  73. package/vendor/agent/director/director.mjs +2365 -0
  74. package/vendor/agent/director/estimate.mjs +200 -0
  75. package/vendor/agent/director/gate.mjs +802 -0
  76. package/vendor/agent/director/limits.json +16 -0
  77. package/vendor/agent/director/methods.mjs +457 -0
  78. package/vendor/agent/director/policy.json +33 -0
  79. package/vendor/agent/director/prompts.mjs +244 -0
  80. package/vendor/agent/director/reading.mjs +341 -0
  81. package/vendor/agent/director/router.mjs +184 -0
  82. package/vendor/agent/director/seams.mjs +243 -0
  83. package/vendor/agent/director/session.mjs +643 -0
  84. package/vendor/agent/director/store.mjs +119 -0
  85. package/vendor/agent/director/taskGate.mjs +110 -0
  86. package/vendor/agent/director/teamLedger.mjs +118 -0
  87. package/vendor/agent/director/triage.mjs +63 -0
  88. package/vendor/agent/downloads.cjs +363 -0
  89. package/vendor/agent/flow.mjs +78 -0
  90. package/vendor/agent/guard.mjs +613 -0
  91. package/vendor/agent/host.mjs +1736 -0
  92. package/vendor/agent/language.mjs +58 -0
  93. package/vendor/agent/ledger.mjs +360 -0
  94. package/vendor/agent/locale.cjs +186 -0
  95. package/vendor/agent/loop/capacity.mjs +74 -0
  96. package/vendor/agent/loop/compose.mjs +127 -0
  97. package/vendor/agent/loop/gate.mjs +205 -0
  98. package/vendor/agent/loop/judge.mjs +189 -0
  99. package/vendor/agent/loop/levels.mjs +273 -0
  100. package/vendor/agent/loop/state.mjs +358 -0
  101. package/vendor/agent/notes.cjs +278 -0
  102. package/vendor/agent/pace.mjs +258 -0
  103. package/vendor/agent/panels.mjs +431 -0
  104. package/vendor/agent/prompt.mjs +342 -0
  105. package/vendor/agent/reference/board.mjs +410 -0
  106. package/vendor/agent/reference/compose.mjs +364 -0
  107. package/vendor/agent/reference/decode.mjs +56 -0
  108. package/vendor/agent/reference/facts.mjs +1874 -0
  109. package/vendor/agent/reference/png.mjs +107 -0
  110. package/vendor/agent/reference/records.mjs +63 -0
  111. package/vendor/agent/reference/web.mjs +252 -0
  112. package/vendor/agent/roles/artist.mjs +69 -0
  113. package/vendor/agent/roles/builder.mjs +79 -0
  114. package/vendor/agent/roles/checks.mjs +223 -0
  115. package/vendor/agent/roles/common.mjs +188 -0
  116. package/vendor/agent/roles/critic.mjs +171 -0
  117. package/vendor/agent/roles/index.mjs +39 -0
  118. package/vendor/agent/roles/modeller.mjs +142 -0
  119. package/vendor/agent/roles/qa.mjs +58 -0
  120. package/vendor/agent/roles/rubrics.mjs +79 -0
  121. package/vendor/agent/roles/sound.mjs +69 -0
  122. package/vendor/agent/rounds.cjs +333 -0
  123. package/vendor/agent/shared.mjs +284 -0
  124. package/vendor/agent/stopGate.mjs +574 -0
  125. package/vendor/agent/subagents.mjs +129 -0
  126. package/vendor/agent/tools/assets.mjs +499 -0
  127. package/vendor/agent/tools/blender.mjs +754 -0
  128. package/vendor/agent/tools/cards.mjs +479 -0
  129. package/vendor/agent/tools/choices.mjs +479 -0
  130. package/vendor/agent/tools/compose.mjs +74 -0
  131. package/vendor/agent/tools/environment.mjs +488 -0
  132. package/vendor/agent/tools/eyes.mjs +733 -0
  133. package/vendor/agent/tools/generate.mjs +338 -0
  134. package/vendor/agent/tools/guide.mjs +46 -0
  135. package/vendor/agent/tools/harness.mjs +193 -0
  136. package/vendor/agent/tools/image.mjs +643 -0
  137. package/vendor/agent/tools/index.mjs +162 -0
  138. package/vendor/agent/tools/look.mjs +578 -0
  139. package/vendor/agent/tools/loop.mjs +858 -0
  140. package/vendor/agent/tools/others.mjs +123 -0
  141. package/vendor/agent/tools/pictures.mjs +535 -0
  142. package/vendor/agent/tools/reference.mjs +366 -0
  143. package/vendor/agent/transcripts.mjs +118 -0
  144. package/vendor/agent-loop.mjs +602 -0
  145. package/vendor/agent-plugin/.claude-plugin/plugin.json +5 -0
  146. package/vendor/agent-plugin/skills/art-direction/SKILL.md +82 -0
  147. package/vendor/agent-plugin/skills/asset-legality/SKILL.md +101 -0
  148. package/vendor/agent-plugin/skills/asset-sources/SKILL.md +111 -0
  149. package/vendor/agent-plugin/skills/blender-modeling/SKILL.md +97 -0
  150. package/vendor/agent-plugin/skills/look-dev/SKILL.md +104 -0
  151. package/vendor/agent-plugin/skills/playtesting/SKILL.md +74 -0
  152. package/vendor/agent-plugin/skills/reference-loop/SKILL.md +102 -0
  153. package/vendor/agent-plugin/skills/sound-design/SKILL.md +60 -0
  154. package/vendor/agent-plugin/skills/style/SKILL.md +35 -0
  155. package/vendor/agent-plugin/skills/tsl-r185/SKILL.md +107 -0
  156. package/vendor/auth.cjs +570 -0
  157. package/vendor/build.cjs +953 -0
  158. package/vendor/catalog.json +455 -0
  159. package/vendor/connectors.cjs +688 -0
  160. package/vendor/eyes.mjs +733 -0
  161. package/vendor/gameExports.json +1390 -0
  162. package/vendor/git.cjs +222 -0
  163. package/vendor/models.json +57 -0
  164. package/vendor/publish.cjs +1018 -0
  165. package/vendor/refBoard.cjs +301 -0
  166. package/vendor/schema/dist/assets.d.ts +335 -0
  167. package/vendor/schema/dist/assets.js +439 -0
  168. package/vendor/schema/dist/brief.d.ts +357 -0
  169. package/vendor/schema/dist/brief.js +302 -0
  170. package/vendor/schema/dist/common.d.ts +9 -0
  171. package/vendor/schema/dist/common.js +13 -0
  172. package/vendor/schema/dist/config.d.ts +406 -0
  173. package/vendor/schema/dist/config.js +355 -0
  174. package/vendor/schema/dist/contract.d.ts +599 -0
  175. package/vendor/schema/dist/contract.js +1146 -0
  176. package/vendor/schema/dist/index.d.ts +14 -0
  177. package/vendor/schema/dist/index.js +21 -0
  178. package/vendor/schema/dist/look.d.ts +463 -0
  179. package/vendor/schema/dist/look.js +681 -0
  180. package/vendor/schema/dist/lookStats.d.ts +230 -0
  181. package/vendor/schema/dist/lookStats.js +768 -0
  182. package/vendor/schema/dist/pilot.d.ts +32 -0
  183. package/vendor/schema/dist/pilot.js +44 -0
  184. package/vendor/schema/dist/publish.d.ts +214 -0
  185. package/vendor/schema/dist/publish.js +291 -0
  186. package/vendor/schema/dist/scene.d.ts +75 -0
  187. package/vendor/schema/dist/scene.js +120 -0
  188. package/vendor/schema/dist/skyLight.d.ts +141 -0
  189. package/vendor/schema/dist/skyLight.js +436 -0
  190. package/vendor/schema/dist/style.d.ts +131 -0
  191. package/vendor/schema/dist/style.js +155 -0
  192. package/vendor/schema/package.json +1 -0
  193. package/vendor/selectionPrompt.mjs +51 -0
  194. package/vendor/useTools.mjs +195 -0
  195. package/vendor/userMessage.mjs +26 -0
  196. package/web-dist/assets/GaussianSplatUtils-CB77cP9U.js +1 -0
  197. package/web-dist/assets/KTX2Loader-6OIWUF7s.js +2 -0
  198. package/web-dist/assets/SPZLoader-zYj0Alfv.js +1 -0
  199. package/web-dist/assets/gaussianSplat-CJTI1sEh.js +1 -0
  200. package/web-dist/assets/index-CcjyyQco.css +1 -0
  201. package/web-dist/assets/index-DMyJcoZJ.js +693 -0
  202. package/web-dist/assets/meshopt_decoder.module-BvwdjiD3.js +1 -0
  203. package/web-dist/assets/zstddec.module-CfFeQW7d.js +1 -0
  204. package/web-dist/index.html +34 -0
@@ -0,0 +1,278 @@
1
+ // What the creator says while a run works (REFERENCE_LOOP.md 2.7): a message
2
+ // written in the chat, or a picture marked up in it (a round's composite, a
3
+ // still, any screenshot), goes into the running agent without stopping it.
4
+ // The renderer sends it (agent:note), main checks it (noteFor) and posts it
5
+ // to the agent host, and the host keeps it in this run's queue until the
6
+ // main agent's next tool result, where it arrives as a PostToolUse note; a
7
+ // note still waiting when the agent tries to finish is given at the Stop
8
+ // instead, so the run goes on to answer it. What the run never got to (it
9
+ // ended, it was stopped, it was a team's) goes back to the chat, which sends
10
+ // it as the next message.
11
+ //
12
+ // A marked picture carries its marks as the contract has them:
13
+ // { hero?: 'H1'..'H6', width, height, marks: [{ kind: 'pen'|'circle'|
14
+ // 'arrow'|'text', points?: [[x, y], ...], rect?: [x, y, w, h], text? }],
15
+ // source?: { path?, width, height } }
16
+ // in the pixels of the picture sent with them (width and height: the PNG
17
+ // with the marks drawn on it, which is at most 1568 px on its long side),
18
+ // and source the picture that was marked (a round's composite or still by
19
+ // its project path, at its own size). The host writes the picture sent into
20
+ // the project (.nowhere/notes/) so the agent can open it, and says where
21
+ // each mark is in words and numbers: in the pixels of that file, and, for a
22
+ // round's still or a composite whose layout is known, on which half and in
23
+ // the hero still's own pixels, the view as the screen shows it
24
+ // (rounds.cjs compositeLayout).
25
+ //
26
+ // Electron-free, so the checks drive it in plain Node.
27
+
28
+ const fs = require('node:fs')
29
+ const path = require('node:path')
30
+ const rounds = require('./rounds.cjs')
31
+
32
+ const NOTES_DIR = path.join('.nowhere', 'notes')
33
+ const MAX_TEXT = 4000
34
+ const MAX_MARKS = 40
35
+ const MAX_POINTS = 600
36
+ const MAX_MARK_TEXT = 300
37
+ /** How many notes one run keeps waiting at once: past it, the oldest wait for the next message. */
38
+ const MAX_WAITING = 12
39
+ const MARK_KINDS = new Set(['pen', 'circle', 'arrow', 'text'])
40
+ const HERO = /^H[1-6]$/
41
+ const NOTE_ID = /^[A-Za-z0-9_-]{1,64}$/
42
+ const EXT = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif' }
43
+
44
+ const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v)
45
+ const isNum = (v, min = -Infinity, max = Infinity) => typeof v === 'number' && Number.isFinite(v) && v >= min && v <= max
46
+ const round1 = (v) => Math.round(v * 10) / 10
47
+ const oneLine = (s) => String(s).replace(/\s+/g, ' ').trim()
48
+
49
+ /** The marks on a picture as the contract has them, or why not. A picture's
50
+ * size bounds every point: a mark outside it is not on the picture. */
51
+ function marksFor(input) {
52
+ if (input === undefined || input === null) return { marks: null }
53
+ const bad = (what) => ({ error: `Marks need ${what}.` })
54
+ if (!isRecord(input)) return bad('an object: { hero?, width, height, marks }')
55
+ if (input.hero !== undefined && input.hero !== null && !HERO.test(String(input.hero))) return bad('a hero of H1 to H6, or none')
56
+ const width = input.width
57
+ const height = input.height
58
+ if (!isNum(width, 1, 20_000) || !isNum(height, 1, 20_000)) return bad("the picture's width and height in pixels")
59
+ const list = input.marks
60
+ if (!Array.isArray(list) || list.length < 1 || list.length > MAX_MARKS) return bad(`1 to ${MAX_MARKS} marks`)
61
+ const inX = (x) => isNum(x, -1, width + 1)
62
+ const inY = (y) => isNum(y, -1, height + 1)
63
+ const point = (p) => Array.isArray(p) && p.length === 2 && inX(p[0]) && inY(p[1])
64
+ const out = []
65
+ for (const m of list) {
66
+ if (!isRecord(m) || !MARK_KINDS.has(m.kind)) return bad('each a kind: pen, circle, arrow or text')
67
+ const text = typeof m.text === 'string' && m.text.trim() ? oneLine(m.text).slice(0, MAX_MARK_TEXT) : undefined
68
+ if (m.kind === 'circle') {
69
+ const r = m.rect
70
+ if (!Array.isArray(r) || r.length !== 4 || !inX(r[0]) || !inY(r[1]) || !isNum(r[2], 1, width + 2) || !isNum(r[3], 1, height + 2)) return bad('a circle as rect [x, y, width, height] inside the picture')
71
+ out.push({ kind: 'circle', rect: r.map(round1), ...(text ? { text } : {}) })
72
+ continue
73
+ }
74
+ const pts = m.points
75
+ const want = m.kind === 'arrow' ? 2 : m.kind === 'text' ? 1 : null
76
+ if (!Array.isArray(pts) || pts.length < 1 || pts.length > MAX_POINTS || !pts.every(point)) return bad(`points inside the picture (at most ${MAX_POINTS})`)
77
+ if (want !== null && pts.length !== want) return bad(m.kind === 'arrow' ? 'an arrow as two points, from and to' : 'a text as one point')
78
+ if (m.kind === 'pen' && pts.length < 2) return bad('a pen line of two points or more')
79
+ if (m.kind === 'text' && !text) return bad('the words of a text mark')
80
+ out.push({ kind: m.kind, points: pts.map(([x, y]) => [round1(x), round1(y)]), ...(text ? { text } : {}) })
81
+ }
82
+ // The picture that was marked, when the one sent is a smaller copy of it.
83
+ let source = null
84
+ if (input.source !== undefined && input.source !== null) {
85
+ const src = input.source
86
+ const rel = src?.path === undefined || src?.path === null ? null : rounds.relImage(src.path)
87
+ if (!isRecord(src) || !isNum(src.width, 1, 40_000) || !isNum(src.height, 1, 40_000) || (src.path !== undefined && src.path !== null && !rel)) return bad('a source of { path?, width, height }: the picture that was marked, a project path to it, at its own size')
88
+ source = { ...(rel ? { path: rel } : {}), width: Math.round(src.width), height: Math.round(src.height) }
89
+ }
90
+ return { marks: { ...(input.hero ? { hero: input.hero } : {}), width: Math.round(width), height: Math.round(height), marks: out, ...(source ? { source } : {}) } }
91
+ }
92
+
93
+ /** A note as main takes it from the renderer, or why not. Images are
94
+ * checked by main's own checkImages (the same rule as a message's). */
95
+ function noteFor(input) {
96
+ if (!isRecord(input)) return { error: 'A note needs runId, noteId and text or a picture.' }
97
+ if (typeof input.runId !== 'string' || !input.runId || input.runId.length > 120) return { error: 'A note needs the id of the run it is for.' }
98
+ if (!NOTE_ID.test(String(input.noteId ?? ''))) return { error: 'A note needs an id.' }
99
+ const text = typeof input.text === 'string' ? input.text.trim() : ''
100
+ if (text.length > MAX_TEXT) return { error: `A note is at most ${MAX_TEXT} characters.` }
101
+ const marks = marksFor(input.marks)
102
+ if (marks.error) return { error: marks.error }
103
+ const images = Array.isArray(input.images) ? input.images : []
104
+ if (marks.marks && images.length !== 1) return { error: 'Marks come with the one picture they are drawn on.' }
105
+ if (!text && images.length === 0) return { error: 'A note needs words or a picture.' }
106
+ return { note: { runId: input.runId, noteId: input.noteId, text, images, marks: marks.marks } }
107
+ }
108
+
109
+ /** Where a mark is, in words and the picture's pixels. */
110
+ function markLine(m) {
111
+ const said = m.text ? ` "${m.text}"` : ''
112
+ const p = (pt) => `(${Math.round(pt[0])}, ${Math.round(pt[1])})`
113
+ if (m.kind === 'circle') {
114
+ const [x, y, w, h] = m.rect
115
+ return `circle around x ${Math.round(x)}..${Math.round(x + w)}, y ${Math.round(y)}..${Math.round(y + h)}${said}`
116
+ }
117
+ if (m.kind === 'arrow') return `arrow from ${p(m.points[0])} pointing at ${p(m.points[1])}${said}`
118
+ if (m.kind === 'text') return `words at ${p(m.points[0])}${said}`
119
+ const xs = m.points.map((q) => q[0])
120
+ const ys = m.points.map((q) => q[1])
121
+ return `pen line over x ${Math.round(Math.min(...xs))}..${Math.round(Math.max(...xs))}, y ${Math.round(Math.min(...ys))}..${Math.round(Math.max(...ys))}${said}`
122
+ }
123
+
124
+ /** The box a mark covers, in the pixels it is given in. A text mark and an
125
+ * arrow's tip are a point: what they point at. */
126
+ function boxOfMark(m) {
127
+ if (m.kind === 'circle') return [m.rect[0], m.rect[1], m.rect[0] + m.rect[2], m.rect[1] + m.rect[3]]
128
+ if (m.kind === 'arrow') return [m.points[1][0], m.points[1][1], m.points[1][0], m.points[1][1]]
129
+ const xs = m.points.map((q) => q[0])
130
+ const ys = m.points.map((q) => q[1])
131
+ return [Math.min(...xs), Math.min(...ys), Math.max(...xs), Math.max(...ys)]
132
+ }
133
+
134
+ const pct = (v) => `${Math.round(Math.max(0, Math.min(1, v)) * 100)}%`
135
+ /** From one share to another, or the one where they are the same (a point). */
136
+ const pcts = (a, b) => (pct(a) === pct(b) ? pct(a) : `${pct(a)}..${pct(b)}`)
137
+ const span = (a, b) => (Math.round(a) === Math.round(b) ? `${Math.round(a)}` : `${Math.round(a)}..${Math.round(b)}`)
138
+
139
+ /** Where a mark is in the view, from a box in the marked picture's own
140
+ * pixels: on which half of a composite, and in the hero still's pixels
141
+ * (the screen as the hero camera framed it); '' when the layout is not known. */
142
+ function placeOf(box, layout) {
143
+ if (!layout) return ''
144
+ const [x0, y0, x1, y1] = box
145
+ if (layout.kind === 'still') {
146
+ const { width, height } = layout.still
147
+ return `in the ${layout.hero} still x ${span(x0, x1)}, y ${span(y0, y1)} (${pcts(x0 / width, x1 / width)} across, ${pcts(y0 / height, y1 / height)} down)`
148
+ }
149
+ if (!layout.panels) return ''
150
+ const cx = (x0 + x1) / 2
151
+ const { target, now } = layout.panels
152
+ const onNow = cx >= now.x - 1 && cx <= now.x + now.w + 1
153
+ const onTarget = cx >= target.x - 1 && cx <= target.x + target.w + 1
154
+ if (!onNow && !onTarget) return 'between the halves'
155
+ const panel = onNow ? now : target
156
+ const u = (x) => Math.max(0, Math.min(1, (x - panel.x) / panel.w))
157
+ const v = (y) => Math.max(0, Math.min(1, (y - panel.y) / panel.h))
158
+ const fractions = `${pcts(u(x0), u(x1))} across, ${pcts(v(y0), v(y1))} down`
159
+ if (!onNow) return `on the target half (${fractions})`
160
+ // The now half is the still, cut to the target's shape when they differ.
161
+ const cut = layout.cut ?? (layout.still ? { x: 0, y: 0, w: layout.still.width, h: layout.still.height } : null)
162
+ if (!cut) return `on the now half (${fractions})`
163
+ const sx = (x) => cut.x + u(x) * cut.w
164
+ const sy = (y) => cut.y + v(y) * cut.h
165
+ return `on the now half, in the ${layout.hero} still x ${span(sx(x0), sx(x1))}, y ${span(sy(y0), sy(y1))} (${fractions})`
166
+ }
167
+
168
+ /** How the marked picture is laid out, for the agent: '' for one with no layout. */
169
+ function layoutWords(layout) {
170
+ if (!layout) return ''
171
+ if (layout.kind === 'still') return ` It is the ${layout.hero} still, ${layout.still.width} x ${layout.still.height} px: its pixels are the screen's as the ${layout.hero} hero camera frames it.`
172
+ if (!layout.panels) return ` It is the ${layout.hero} target | now composite: the left half is the target, the right half the space now.`
173
+ const still = layout.still ? `, ${layout.still.width} x ${layout.still.height} px` : ''
174
+ return ` It is the ${layout.hero} target | now composite: the left half is the target, the right half the space now; a mark on the now half is also told in the ${layout.hero} still's own pixels${still}, the screen as the ${layout.hero} hero camera frames it.`
175
+ }
176
+
177
+ /** The marks for the agent: which picture, its size, then each mark, in
178
+ * the pixels of the file it reads and, where the layout is known, in the
179
+ * hero still's. layout: rounds.cjs compositeLayout of marks.source.path. */
180
+ function marksText(marks, file, layout = null) {
181
+ if (!marks) return ''
182
+ const of = marks.hero ? ` (hero view ${marks.hero})` : ''
183
+ const where = file ? `${file}${of}, ` : `the picture${of}, `
184
+ const src = marks.source
185
+ // The file sent may be a smaller copy of the picture marked: its marks
186
+ // are in the file's pixels, and back in the picture's to place them.
187
+ const k = src ? src.width / marks.width : 1
188
+ const copy = src && (src.path || Math.abs(k - 1) > 0.01) ? `, a copy of ${src.path ?? 'the picture marked'} (${src.width} x ${src.height} px)` : ''
189
+ const lines = marks.marks.map((m, i) => {
190
+ const place = placeOf(boxOfMark(m).map((v) => v * k), layout)
191
+ return ` ${i + 1}. ${markLine(m)}${place ? `; ${place}` : ''}`
192
+ })
193
+ return `The creator marked ${where}${marks.width} x ${marks.height} px${copy} (Read it to see the marks drawn on it).${layoutWords(layout)} The marks, in the pixels of ${file ?? 'the picture sent'}:\n${lines.join('\n')}\nMarks as data: ${JSON.stringify(marks)}`
194
+ }
195
+
196
+ /** The layout of the picture a note's marks were drawn on, in the open
197
+ * project, or null (rounds.cjs compositeLayout). */
198
+ function layoutFor(root, marks) {
199
+ const src = marks?.source
200
+ if (!root || !src?.path) return null
201
+ try {
202
+ return rounds.compositeLayout(root, src.path, { width: src.width, height: src.height })
203
+ } catch {
204
+ return null
205
+ }
206
+ }
207
+
208
+ /** A picture of a note, kept in the project for the agent to open: its
209
+ * project-relative path, or null when it could not be written. */
210
+ function keepPicture(root, image, stamp, i) {
211
+ const ext = EXT[image?.mime]
212
+ if (!root || !ext || typeof image.data !== 'string') return null
213
+ const rel = path.posix.join('.nowhere', 'notes', `${stamp}-${i}.${ext}`)
214
+ try {
215
+ fs.mkdirSync(path.join(root, NOTES_DIR), { recursive: true })
216
+ fs.writeFileSync(path.join(root, ...rel.split('/')), Buffer.from(image.data, 'base64'))
217
+ return rel
218
+ } catch {
219
+ return null
220
+ }
221
+ }
222
+
223
+ const stampOf = (ms) => new Date(ms).toISOString().replace(/[-:]/g, '').replace('T', '-').slice(0, 15)
224
+
225
+ /** The words a note arrives in, for the agent. */
226
+ function noteText(note) {
227
+ const parts = []
228
+ if (note.text) parts.push(note.text.split('\n').map((l) => `> ${l}`).join('\n'))
229
+ if (note.marks) parts.push(marksText(note.marks, note.files[0] ?? null, note.layout ?? null))
230
+ else if (note.files.length) parts.push(`With ${note.files.length === 1 ? 'a picture' : `${note.files.length} pictures`}: ${note.files.join(', ')} (Read to see).`)
231
+ else if (note.images.length) parts.push('With a picture that could not be kept in the project.')
232
+ return parts.join('\n')
233
+ }
234
+
235
+ /** One run's notes waiting for the main agent.
236
+ * onDelivered(ids): told when notes went into a tool result or the Stop. */
237
+ function createNoteQueue({ projectRoot, onDelivered = () => {}, now = Date.now } = {}) {
238
+ const waiting = []
239
+ let seq = 0
240
+ return {
241
+ /** Keeps a checked note (noteFor's), its pictures written into the project now. */
242
+ add(note) {
243
+ if (!note || typeof note.noteId !== 'string') return { ok: false, error: 'Not a note.' }
244
+ if (waiting.length >= MAX_WAITING) return { ok: false, error: 'Too many notes are waiting already.' }
245
+ const at = now()
246
+ const stamp = `${stampOf(at)}-${++seq}`
247
+ const images = Array.isArray(note.images) ? note.images : []
248
+ const files = images.map((img, i) => keepPicture(projectRoot, img, stamp, i + 1)).filter(Boolean)
249
+ const layout = layoutFor(projectRoot, note.marks)
250
+ waiting.push({ noteId: note.noteId, text: String(note.text ?? ''), images, files, marks: note.marks ?? null, layout, at })
251
+ return { ok: true, files, layout }
252
+ },
253
+ pending: () => waiting.length,
254
+ /** Every waiting note as one block of words for the agent, and they are
255
+ * delivered; null when none waits. */
256
+ take() {
257
+ if (waiting.length === 0) return null
258
+ const notes = waiting.splice(0)
259
+ const head =
260
+ notes.length === 1
261
+ ? 'The creator sent this while you work. It is not a new request and does not stop the run: take it into the work now, at the next step it fits, and say in your next words to them what you changed for it.'
262
+ : `The creator sent these ${notes.length} messages while you work. They are not a new request and do not stop the run: take them into the work now, at the next step each fits, and say in your next words to them what you changed for each.`
263
+ const body = notes.map((n, i) => `${notes.length > 1 ? `${i + 1}. ` : ''}${noteText(n)}`).join('\n\n')
264
+ try {
265
+ onDelivered(notes.map((n) => n.noteId))
266
+ } catch {
267
+ // the chat not hearing it does not take it back
268
+ }
269
+ return `${head}\n\n${body}`
270
+ },
271
+ /** The ids still waiting, which go back to the chat. */
272
+ drain() {
273
+ return waiting.splice(0).map((n) => n.noteId)
274
+ },
275
+ }
276
+ }
277
+
278
+ module.exports = { noteFor, marksFor, marksText, markLine, layoutFor, createNoteQueue, NOTES_DIR, MAX_TEXT }
@@ -0,0 +1,258 @@
1
+ // How a request keeps moving, on any model. A QA run (2026-10-20) gave
2
+ // Claude Haiku 5.5 a detailed island build at max effort: it thought about
3
+ // 21k tokens a call, took 40 minutes for 17 calls and never got the island
4
+ // built, so the run ended with nothing that ran. Depth now fits the model
5
+ // (depth.mjs fitDepth), and this keeps the run honest while it goes:
6
+ //
7
+ // - a model with a thinking limit per step (models.json thinkingPerCall)
8
+ // that thinks past it gets its effort lowered a level for the steps after,
9
+ // down to medium, and is told why;
10
+ // - the agent hears the time and the steps: when half the usual time for
11
+ // this kind of request has gone and nothing it built or changed has passed
12
+ // nw_check yet, when the usual time has gone, and when it is time to wrap
13
+ // up (twice the usual time, or three quarters of the steps), so a big
14
+ // build ends with a game that runs and a reply rather than at the step
15
+ // limit. A request at a quality step (loop/levels.mjs QUALITY) has its
16
+ // time from the step: its wrap-up comes only from the steps used, and its
17
+ // notes never ask for short steps.
18
+ //
19
+ // The notes go into the next tool result of the main agent (host.mjs
20
+ // PostToolUse, the other vendors' afterTool), never to a helper.
21
+ //
22
+ // A space in the reference loop (REFERENCE_LOOP.md 2.6, 3) keeps the time
23
+ // of its speed level instead: no "usual time" or "wrap up" before the
24
+ // level's floor (finishing early there means something is missing), and the
25
+ // wrap-up when its cap draws near, counted over every request the loop has
26
+ // run (loop/state.mjs elapsedMin). The steps' safety net stays as it is.
27
+ //
28
+ // On a Claude subscription the run also keeps to its plan's five-hour
29
+ // window (the SDK's rate_limit_event): when the window would run out before
30
+ // it resets at the pace the run uses it, each tool call is held a little
31
+ // (holdMs, up to HOLD_MAX_MS) so the run ends near WINDOW_SHARE of the
32
+ // window instead of stopping at the limit, and the agent hears why once.
33
+
34
+ import { EFFORTS, lowerEffort } from './depth.mjs'
35
+ import { WINDOW_SHARE } from './loop/levels.mjs'
36
+
37
+ /** The longest one tool call is held for the window. */
38
+ export const HOLD_MAX_MS = 50_000
39
+ /** The plan's window the SDK reports on. */
40
+ const WINDOW_MS = 5 * 60 * 60_000
41
+ /** How long a run must have watched the window before it judges its pace. */
42
+ const WATCH_MS = 60_000
43
+ /** A step's time when the run has not shown its own yet. */
44
+ const STEP_MS = 20_000
45
+
46
+ /** A rate-limit event's numbers as a share (0 to 1) and a time in ms, or null. */
47
+ export function windowOf(info) {
48
+ if (!info || typeof info !== 'object') return null
49
+ if (info.rateLimitType && info.rateLimitType !== 'five_hour') return null
50
+ let share = Number(info.utilization)
51
+ if (!Number.isFinite(share)) return null
52
+ if (share > 1.0001) share /= 100
53
+ let resetsAt = Number(info.resetsAt)
54
+ if (Number.isFinite(resetsAt) && resetsAt < 1e12) resetsAt *= 1000
55
+ return { share: Math.min(1, Math.max(0, share)), resetsAt: Number.isFinite(resetsAt) ? resetsAt : null, status: info.status ?? null }
56
+ }
57
+
58
+ /** Minutes a request usually takes, by the depth the request itself asked
59
+ * for (before the model's ceiling): a question, a tweak, a feature, a new
60
+ * game, a detailed build. */
61
+ export const USUAL_MINUTES = { low: 3, medium: 8, high: 15, xhigh: 30, max: 40 }
62
+
63
+ /**
64
+ * @param {{ depth: { effort: string, asked?: string }, model?: { name?: string, id?: string, effortCeiling?: string, thinkingPerCall?: number },
65
+ * maxTurns?: number, now?: () => number, quality?: number | null }} options
66
+ * quality: the request's quality step, null without one.
67
+ */
68
+ export function createPace({ depth, model, maxTurns = 400, now = () => Date.now(), quality = null }) {
69
+ const stepped = Number.isInteger(quality) && quality >= 1
70
+ const startedAt = now()
71
+ const kind = EFFORTS.includes(depth?.asked) ? depth.asked : depth?.effort
72
+ const usual = USUAL_MINUTES[kind] ?? USUAL_MINUTES.high
73
+ const ceiling = EFFORTS.includes(model?.effortCeiling) ? model.effortCeiling : 'max'
74
+ const perCall = Number(model?.thinkingPerCall) > 0 ? Number(model.thinkingPerCall) : null
75
+ const modelName = model?.name ?? model?.id ?? 'this model'
76
+ let effort = depth?.effort ?? 'medium'
77
+ let lowered = false
78
+ let calls = 0
79
+ let checked = false
80
+ let edited = false
81
+ const building = !!depth?.big || kind === 'xhigh' || kind === 'max'
82
+ /** The main agent's call in flight: the API's thinking count and the CLI's estimate. */
83
+ let call = null
84
+ const pending = []
85
+ const said = new Set()
86
+ /** The loop's time, once a kickoff set it: { floorMin, capMin, elapsed() }. */
87
+ let loop = null
88
+ /** The plan's window: the first reading this run saw in it, and the latest. */
89
+ let windowFirst = null
90
+ let windowNow = null
91
+ let holding = false
92
+ /** When the last few tool calls began, for a step's usual length. */
93
+ const toolTimes = []
94
+
95
+ return {
96
+ get effort() {
97
+ return effort
98
+ },
99
+ get calls() {
100
+ return calls
101
+ },
102
+ usualMinutes: usual,
103
+ maxTurns,
104
+ /** A main-agent call began (its message_start). */
105
+ callStarted() {
106
+ calls++
107
+ call = { thinking: 0, estimate: 0 }
108
+ },
109
+ /** Thinking for the call in flight: `tokens` the API's count so far
110
+ * (usage.output_tokens_details.thinking_tokens), `estimateDelta` the
111
+ * CLI's thinking_tokens progress. Ignored between calls. */
112
+ thinking({ tokens, estimateDelta } = {}) {
113
+ if (!call) return
114
+ if (Number.isFinite(tokens)) call.thinking = Math.max(call.thinking, tokens)
115
+ if (Number.isFinite(estimateDelta) && estimateDelta > 0) call.estimate += estimateDelta
116
+ },
117
+ /** The call in flight ended. Returns the effort to switch to when it
118
+ * thought past the model's limit for one step, else null. */
119
+ callEnded() {
120
+ if (!call) return null
121
+ const thought = call.thinking > 0 ? call.thinking : call.estimate
122
+ call = null
123
+ if (!perCall || thought <= perCall) return null
124
+ const next = lowerEffort(effort, 'medium')
125
+ if (!next) return null
126
+ effort = next
127
+ lowered = true
128
+ pending.push(
129
+ `That step thought for about ${Math.round(thought / 1000)}k tokens, more than one step should on ${modelName}. The studio lowered your effort to ${next} for the steps after it: think briefly, act, then look, one short step at a time.`,
130
+ )
131
+ return next
132
+ },
133
+ /** The creator approved a cost on a lighter request: deeper, up to `to`
134
+ * and never past the model's ceiling, unless the thinking limit has
135
+ * lowered it. Returns the new effort, or null for no change. */
136
+ raise(to = 'xhigh') {
137
+ if (lowered) return null
138
+ const target = EFFORTS[Math.min(EFFORTS.indexOf(to), EFFORTS.indexOf(ceiling))]
139
+ if (!target || EFFORTS.indexOf(target) <= EFFORTS.indexOf(effort)) return null
140
+ effort = target
141
+ return target
142
+ },
143
+ /** One step of the other vendors' loop (it reports no thinking). */
144
+ step() {
145
+ calls++
146
+ },
147
+ /** The loop's speed level took over the time (a kickoff, or a continued loop). */
148
+ setLoop({ floorMin = 0, capMin, elapsed } = {}) {
149
+ if (!Number.isFinite(capMin) || capMin <= 0) return
150
+ loop = { floorMin: Math.max(0, Number(floorMin) || 0), capMin, elapsed: typeof elapsed === 'function' ? elapsed : () => (now() - startedAt) / 60_000 }
151
+ },
152
+ get loop() {
153
+ return loop ? { floorMin: loop.floorMin, capMin: loop.capMin } : null
154
+ },
155
+ /** A rate_limit_event from the SDK (its rate_limit_info). */
156
+ rateLimit(info) {
157
+ const w = windowOf(info)
158
+ if (!w) return
159
+ const at = now()
160
+ // A new window (it reset) starts the watch again.
161
+ if (!windowFirst || (w.resetsAt && windowNow?.resetsAt && w.resetsAt !== windowNow.resetsAt) || w.share < (windowNow?.share ?? 0) - 0.05) windowFirst = { share: w.share, at }
162
+ windowNow = { ...w, at }
163
+ },
164
+ /** A tool call began (the PreToolUse hook): a step's length is read from these. */
165
+ toolStarted() {
166
+ toolTimes.push(now())
167
+ if (toolTimes.length > 12) toolTimes.shift()
168
+ },
169
+ /** How long to hold the next tool call so the plan's window lasts, in ms (0: none). */
170
+ holdMs() {
171
+ const w = windowNow
172
+ if (!w?.resetsAt) return 0
173
+ const at = now()
174
+ const left = Math.min(WINDOW_MS, w.resetsAt - at)
175
+ if (left <= 0) return 0
176
+ let hold = 0
177
+ if (w.share >= WINDOW_SHARE) hold = HOLD_MAX_MS
178
+ else if (windowFirst && at - windowFirst.at >= WATCH_MS && w.share > windowFirst.share) {
179
+ const rate = (w.share - windowFirst.share) / (at - windowFirst.at)
180
+ const allowed = (WINDOW_SHARE - w.share) / left
181
+ if (w.share + rate * left > WINDOW_SHARE) {
182
+ const steps = toolTimes.length >= 2 ? (toolTimes.at(-1) - toolTimes[0]) / (toolTimes.length - 1) : STEP_MS
183
+ hold = Math.min(HOLD_MAX_MS, Math.round(Math.max(steps, 1000) * (rate / Math.max(allowed, 1e-12) - 1)))
184
+ }
185
+ }
186
+ if (hold > 0 && !holding) {
187
+ const resets = new Date(w.resetsAt).toISOString().slice(11, 16)
188
+ pending.push(
189
+ `The creator's plan has used ${Math.round(w.share * 100)}% of its five-hour window, which resets at ${resets} UTC. At this pace it would run out before then and stop the work, so the studio is spacing your steps to end near ${Math.round(WINDOW_SHARE * 100)}% of it. Keep going: fewer, larger steps and fewer helpers use less of it.`,
190
+ )
191
+ }
192
+ holding = hold > 0
193
+ return hold
194
+ },
195
+ /** A passing nw_check in this request. It counts once the game has
196
+ * changed: `changed` is the stop gate's word that the game's files
197
+ * differ from the start (a Bash edit included), else a Write or Edit
198
+ * noted here. A check of the untouched starter, before anything was
199
+ * built, is not the build, and must not quiet the "unbuilt" note. */
200
+ noteCheck({ changed = false } = {}) {
201
+ if (changed || edited) checked = true
202
+ },
203
+ /** The main agent changed a file (Write, Edit and the like). */
204
+ noteEdit() {
205
+ edited = true
206
+ },
207
+ /** The notes due now, for the main agent's next tool result; null for none. */
208
+ notes() {
209
+ const minutes = (now() - startedAt) / 60_000
210
+ const m = Math.max(1, Math.round(minutes))
211
+ const out = pending.splice(0)
212
+ // A loop keeps its level's time: nothing hurries it before the floor,
213
+ // and the wrap-up comes near the cap. The steps' safety net stays.
214
+ if (loop) {
215
+ const spent = loop.elapsed()
216
+ const s = Math.max(1, Math.round(spent))
217
+ const due = [
218
+ ['last', ['wrap', 'cap'], calls >= Math.floor(maxTurns * 0.9), () => `Only ${Math.max(0, maxTurns - calls)} of ${maxTurns} steps are left. Start nothing new: run nw_check and a last nw_round, show the approval card (nw_ask_approval), and reply with the score against the bar.`],
219
+ ['cap', [], spent >= Math.max(loop.floorMin, loop.capMin * 0.9), () => `${s} of the level's ${loop.capMin} minutes have gone: the time cap is near. Finish the round you are on with nw_round, show the approval card (nw_ask_approval), and reply with the score against the bar, saying plainly if it is below it.`],
220
+ ['wrap', [], calls >= Math.floor(maxTurns * 0.75) && spent >= loop.floorMin, () => `${calls} of ${maxTurns} steps are in: finish the round you are on with nw_round, then show the approval card (nw_ask_approval).`],
221
+ [
222
+ 'unbuilt',
223
+ [],
224
+ (building || edited) && !checked && minutes >= Math.min(usual / 2, Math.max(10, loop.floorMin / 4)),
225
+ () => `${m} minutes and ${calls} steps in, and the space has not passed nw_check in this request yet. Get the smallest version that runs through nw_check now, then take it to the targets round by round.`,
226
+ ],
227
+ ]
228
+ const next = due.find(([key, , when]) => when && !said.has(key))
229
+ if (next) {
230
+ out.push(next[3]())
231
+ for (const key of [next[0], ...next[1]]) said.add(key)
232
+ }
233
+ return out.length ? out.join('\n\n') : null
234
+ }
235
+ // One at a time, the most urgent first; each makes the ones it covers moot.
236
+ const due = [
237
+ ['last', ['wrap', 'unbuilt', 'usual'], calls >= Math.floor(maxTurns * 0.9), () => `Only ${Math.max(0, maxTurns - calls)} of ${maxTurns} steps are left. Start nothing new: run nw_check, put back anything half done, and reply with what is done and what is left.`],
238
+ ['wrap', ['unbuilt', 'usual'], (!stepped && minutes >= usual * 2) || calls >= Math.floor(maxTurns * 0.75), () => `${m} minutes and ${calls} of ${maxTurns} steps in: wrap up. Finish the step you are on, run nw_check and nw_view, and reply with what is done and what is left; the creator can ask you to continue.`],
239
+ [
240
+ 'unbuilt',
241
+ [],
242
+ kind !== 'low' && (building || edited) && !checked && minutes >= usual / 2,
243
+ () =>
244
+ building
245
+ ? `${m} minutes and ${calls} steps in, and the space has not passed nw_check in this request yet. Get the smallest version that runs (every element the creator asked for, in rough form) through nw_check now, then improve it${stepped ? '' : ' in short steps'}.`
246
+ : `${m} minutes and ${calls} steps in, and your changes have not passed nw_check yet. Run nw_check on what you have now, then go on${stepped ? '' : ' in short steps'}.`,
247
+ ],
248
+ ['usual', [], minutes >= usual, () => `${m} minutes in; a request like this usually takes about ${usual}. Finish the step you are on and keep the space working (nw_check, then nw_view); do the rest ${stepped ? 'so that each step ends' : 'in short steps that each end'} in a space that runs.`],
249
+ ]
250
+ const next = due.find(([key, , when]) => when && !said.has(key))
251
+ if (next) {
252
+ out.push(next[3]())
253
+ for (const key of [next[0], ...next[1]]) said.add(key)
254
+ }
255
+ return out.length ? out.join('\n\n') : null
256
+ },
257
+ }
258
+ }