oda-engine 0.0.0-stage → 0.1.1

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 +131 -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-CptQkDVX.js +1 -0
  197. package/web-dist/assets/KTX2Loader-C53LJqss.js +2 -0
  198. package/web-dist/assets/SPZLoader-BQ3tjaTv.js +1 -0
  199. package/web-dist/assets/gaussianSplat-_9tcWegB.js +1 -0
  200. package/web-dist/assets/index-Baka-ZO7.js +693 -0
  201. package/web-dist/assets/index-CcjyyQco.css +1 -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,488 @@
1
+ // A whole environment from a world generator, only after the creator
2
+ // approved what it costs:
3
+ // environment_generate estimate -> (nw_ask kind cost, the creator approves) -> submit
4
+ // environment_job polls the world, downloads its splat, collider,
5
+ // panorama and thumbnail into quarantine
6
+ // (.nowhere/quarantine/env-<job>/), where asset_import
7
+ // takes them as a splat environment
8
+ //
9
+ // The same gates as asset_generate (generate.mjs): nothing is spent without
10
+ // the creator's key (read through ctx.secret, never printed), an approval
11
+ // that covers the estimate, and here also an account balance that covers it,
12
+ // asked of the vendor first for free. A space's environment comes from scans
13
+ // first (asset_search); a generated world is for when the creator asks for
14
+ // one. World Labs' Marble is the one provider (assets/environments/); every
15
+ // check drives it with a fake fetch.
16
+
17
+ import { z } from 'zod'
18
+ import { createHash } from 'node:crypto'
19
+ import fs from 'node:fs'
20
+ import fsp from 'node:fs/promises'
21
+ import { createRequire } from 'node:module'
22
+ import path from 'node:path'
23
+ import { ENVIRONMENT_PROVIDERS } from '../assets/environments/index.mjs'
24
+ import { addToManifest } from '../assets/fetch.mjs'
25
+ import { isJobId, listJobs, newJobId, readJob, writeJob } from '../assets/jobs.mjs'
26
+ import { inputRecordOf, today } from '../assets/ledger.mjs'
27
+ import { download, fetchOf, imageMime, mbOf, NetError, userAgentFor } from '../assets/net.mjs'
28
+ import { PRICES } from '../assets/providers/index.mjs'
29
+ import { spzHeader } from '../assets/splat.mjs'
30
+ import { pictureInput } from './generate.mjs'
31
+
32
+ const require = createRequire(import.meta.url)
33
+ const { QUARANTINE, QUARANTINE_LIMITS } = require('../downloads.cjs')
34
+
35
+ export const RPC_METHODS = []
36
+
37
+ const fail = (text) => ({ text, isError: true })
38
+ const usd = (n) => `$${n.toFixed(2)}`
39
+ const MB = 1024 * 1024
40
+
41
+ const keyOf = (ctx, envVar) => {
42
+ try {
43
+ const v = ctx?.secret?.(envVar)
44
+ return typeof v === 'string' && v.trim() ? v.trim() : null
45
+ } catch {
46
+ return null
47
+ }
48
+ }
49
+
50
+ /** Where a key comes from, in words for whoever has none: the studio's
51
+ * connector card, or the environment the CLI's server runs in. */
52
+ function noKey(provider, ctx) {
53
+ const where =
54
+ ctx?.host === 'cli'
55
+ ? `Set ${provider.envVar} in the environment the Oda server runs in (or save it with oda keys where this Oda has that command), then try again.`
56
+ : `Ask the creator for it with nw_ask kind key, connector ${provider.connector}: they paste it into the ${provider.label} card under Settings, Connectors.`
57
+ return fail(
58
+ `${provider.label} has no key here, so nothing was sent and nothing was spent. ${where} The key is made at ${provider.keyUrl}; World API credits are bought at ${provider.billingUrl} (at least $5) and are not the Marble app's credits.`,
59
+ )
60
+ }
61
+
62
+ /** A vendor's refusal, in words that say what to do. */
63
+ function vendorWords(provider, err) {
64
+ const m = String(err?.message ?? err)
65
+ if (/answered 401|answered 403/.test(m)) return `${provider.label} refused the key (${m}). Check it at ${provider.keyUrl}.`
66
+ if (/answered 402/.test(m)) return `${provider.label} says the account has too few API credits (${m}). They are bought at ${provider.billingUrl}.`
67
+ if (/answered 429/.test(m)) return `${provider.label} is taking no more worlds from this account just now (rate limit, about three a minute): wait a minute and submit again. Nothing was started.`
68
+ if (/answered 400|answered 422/.test(m)) return `${provider.label} refused the request (${m}): a prompt it will not take, or a picture it cannot read.`
69
+ return `${provider.label} could not be asked: ${m}`
70
+ }
71
+
72
+ /** Whether a submit that failed may still have started a world (and its
73
+ * bill): the request went out and no clear refusal came back, as with a
74
+ * 5xx, a dropped connection, or an answer that was not JSON or had no
75
+ * operation id. A refusal before sending (the URL, the host) or a 4xx
76
+ * answer started nothing. */
77
+ export function mayHaveStarted(err) {
78
+ const code = err?.code
79
+ if (code === 'bad-url' || code === 'host' || code === 'blocked' || code === 'no-fetch') return false
80
+ const status = /answered (\d{3})/.exec(String(err?.message ?? ''))
81
+ if (status) return Number(status[1]) >= 500
82
+ // node's fetch: no such host, or nobody listening, before a byte was sent.
83
+ const cause = err?.cause?.code
84
+ if (cause === 'ENOTFOUND' || cause === 'EAI_AGAIN' || cause === 'ECONNREFUSED') return false
85
+ return true
86
+ }
87
+
88
+ // ---------------------------------------------------------------- the plan
89
+
90
+ function planFor(args) {
91
+ const provider = ENVIRONMENT_PROVIDERS[args.provider ?? 'worldlabs']
92
+ if (!provider) return { error: `${args.provider} is not a world generator (${Object.keys(ENVIRONMENT_PROVIDERS).join(', ')}).` }
93
+ const model = args.model ?? provider.defaultModel()
94
+ if (!provider.models.includes(model)) return { error: `${provider.label} has no model ${model} (${provider.models.join(', ')}).` }
95
+ if (!provider.inputs.includes(args.input)) return { error: `${provider.label} makes worlds from ${provider.inputs.join(', ')}, not ${args.input}.` }
96
+ if (args.input === 'text' && !args.prompt?.trim()) return { error: 'A world from text needs a prompt: the place, its light, its materials, in English. Never a living artist\'s name or a copyrighted place\'s.' }
97
+ if (args.input !== 'text' && !args.image) return { error: `A world from ${args.input === 'pano' ? 'a panorama' : 'a picture'} needs image: a project path to a PNG or JPEG${args.input === 'pano' ? ' twice as wide as it is tall (image_generate kind panorama makes one)' : ''}.` }
98
+ if (args.input === 'text' && args.image) return { error: 'image is for input image or pano; a world from text takes the prompt alone.' }
99
+ const price = provider.price(args.input, model, PRICES)
100
+ if (!price) return { error: `There is no price for ${provider.label} ${model} from ${args.input} in prices.json, so it cannot be estimated or run.` }
101
+ const lines = [{ label: `${provider.label} world from ${args.input} (${model}, ${price.unit})`, usd: Math.round(price.high * 100) / 100 }]
102
+ const totalUsd = lines[0].usd
103
+ const estimateId = createHash('sha256').update(JSON.stringify([provider.id, args.input, model, args.prompt ?? '', args.image ?? '', args.seed ?? null])).digest('hex').slice(0, 12)
104
+ return { provider, model, price, lines, totalUsd, estimateId }
105
+ }
106
+
107
+ // ---------------------------------------------------------------- environment_generate
108
+
109
+ const GENERATE_SHAPE = {
110
+ action: z.enum(['estimate', 'submit']).describe('estimate first; submit only after the creator approved a cost card that covers it.'),
111
+ provider: z.enum(['worldlabs']).default('worldlabs'),
112
+ input: z.enum(['text', 'image', 'pano']).describe('text: from the prompt alone; image: from a picture of the place (its panorama is made first); pano: from an equirectangular panorama (2:1) of it, the cheapest and the most faithful.'),
113
+ model: z.enum(['marble-1.1', 'marble-1.1-plus', 'marble-1.0', 'marble-1.0-draft']).optional().describe('Default marble-1.1. marble-1.1-plus: a bigger world outdoors or in a large hall, up to twice the cost. marble-1.0-draft: a tenth of the cost, for trying a prompt.'),
114
+ prompt: z.string().max(2000).optional().describe('text: the place, its light and its materials, from the brief, in English; image and pano: optional guidance. Never a living artist\'s name or a copyrighted place.'),
115
+ image: z.string().optional().describe('image and pano: a project path to a PNG or JPEG under 10 MB: the reference the brief names, or one image_generate made.'),
116
+ name: z.string().max(64).optional().describe("The world's name at World Labs; by default the job's id, so the world can always be found by it."),
117
+ seed: z.number().int().min(0).max(4294967295).optional(),
118
+ resolution: z.enum(['100k', '500k']).default('500k').describe("Which splat environment_job downloads: 500k (the default; 33 fps on WebGPU and 19 on WebGL 2 on an M5 Pro desktop, measured) or 100k for slower devices. World Labs' full_res (about 2 million splats, 9.5 fps there) is past the 1 million a planet may draw, so it is not offered. The price is the same."),
119
+ confirm: z.string().max(40).optional().describe('Only where the host asks for it: the estimate id the estimate answered, once the creator agreed.'),
120
+ }
121
+
122
+ const GENERATE_DESCRIPTION =
123
+ "Generates a whole explorable environment with a paid world model (World Labs Marble): Gaussian splats of the place, a collider to walk on and the panorama it was made from, from a sentence, a picture or a panorama. Only when the creator asked for a generated world or a splat environment: a space's ground, walls and props come from scans first (asset_search). action estimate answers the cost lines for a cost card (about $1.26 for a world from text with marble-1.1, up to $2.46 with 1.1 Plus); ask the creator with nw_ask kind cost, in the screen language, and only after they approve call action submit with the same request. submit refuses without the key (ask with nw_ask kind key, connector worldlabs), without an approval that covers the estimate, and when the account's API credits do not cover it. It starts the world (about five minutes) and answers its job id; follow it with environment_job, then asset_import what it made as a splat."
124
+
125
+ async function generate(args, ctx) {
126
+ const plan = planFor(args)
127
+ if (plan.error) return fail(plan.error)
128
+ const { provider, model, price, lines, totalUsd, estimateId } = plan
129
+
130
+ if (args.action === 'estimate') {
131
+ return {
132
+ text: [
133
+ `Estimate ${estimateId}: ${lines.map((l) => `${l.label} up to ${usd(l.usd)}`).join('; ')} (prices checked ${PRICES.worldlabs?.checked ?? PRICES.checked}). It takes about five minutes; the splat, its collider and its panorama come with it.`,
134
+ `For the cost card: ${JSON.stringify({ items: lines, note: `${provider.label}, ${PRICES.worldlabs?.checked ?? PRICES.checked} prices; World API credits, not the Marble app's` })}`,
135
+ "Ask with nw_ask kind cost, in the screen language, then submit.",
136
+ ].join('\n'),
137
+ }
138
+ }
139
+
140
+ // submit: the key, the approval, the balance and the input. Nothing is sent before all four.
141
+ // In a space's reference loop Marble is the creator's choice on the
142
+ // kickoff card, never a default or an unanswered card's, and it goes on a
143
+ // cost card of its own answered after the kickoff, not on the level's
144
+ // pooled approval (REFERENCE_LOOP.md 2.1).
145
+ const loop = ctx?.loop
146
+ if (loop?.kickoff && loop.active !== false) {
147
+ if (loop.kickoff.environment !== 'marble') {
148
+ return fail(`The kickoff card did not choose Marble for this space (${loop.kickoff.environment ? `it chose ${loop.kickoff.environment}` : 'it was not answered'}), so nothing was sent. Build the environment in code, or ask the creator in your reply whether they want a generated world.`)
149
+ }
150
+ if (typeof loop.costCardCovers !== 'function' || !loop.costCardCovers(totalUsd)) {
151
+ return fail(`Marble asks its own cost card, after the kickoff: run action estimate, ask with nw_ask kind cost (its lines: the Marble world at ${usd(totalUsd)}, and the rest of the level's work, since an approval covers what is left of the request), and submit after the creator approves. Nothing was sent.`)
152
+ }
153
+ }
154
+ const key = keyOf(ctx, provider.envVar)
155
+ if (!key) return noKey(provider, ctx)
156
+ if (args.confirm && typeof ctx?.ledger?.confirmEstimate === 'function') {
157
+ try {
158
+ ctx.ledger.confirmEstimate({ id: args.confirm, usd: totalUsd, matches: args.confirm === estimateId })
159
+ } catch {
160
+ // the host's stand-in decides; the approval below is the gate
161
+ }
162
+ }
163
+ const approved = ctx?.ledger?.approvedUsd?.()
164
+ const spent = Number(ctx?.ledger?.spentUsd?.() ?? 0) || 0
165
+ if (approved === null || approved === undefined || !Number.isFinite(approved)) {
166
+ return fail(`No cost card has been approved for this, so nothing was sent. Run action estimate, ask the creator with nw_ask kind cost (${usd(totalUsd)}), and submit after they approve.`)
167
+ }
168
+ if (approved - spent < totalUsd - 1e-9) {
169
+ return fail(`The approval left is ${usd(Math.max(0, approved - spent))} (approved ${usd(approved)}, spent ${usd(spent)}), less than this estimate of ${usd(totalUsd)}, so nothing was sent. Ask again with nw_ask kind cost for the new total.`)
170
+ }
171
+ let picture = null
172
+ if (args.input !== 'text') {
173
+ picture = await pictureInput(ctx, args.image)
174
+ if (picture.error) return fail(picture.error)
175
+ }
176
+ const fetch = fetchOf(ctx)
177
+ const ua = userAgentFor(ctx)
178
+ // The account's own balance first: World Labs admits a request on a low
179
+ // balance and bills what it overran weeks later.
180
+ if (typeof provider.credits === 'function') {
181
+ let left
182
+ try {
183
+ left = await provider.credits({ key, fetch, ua })
184
+ } catch (err) {
185
+ return fail(`${vendorWords(provider, err)} Nothing was started.`)
186
+ }
187
+ if (left < price.credits[1]) {
188
+ return fail(`The ${provider.label} account has ${Math.floor(left).toLocaleString('en-US')} API credits, fewer than this world may take (${price.credits[1].toLocaleString('en-US')}), so nothing was started: World Labs would run the account below zero and bill the rest later. Credits are bought at ${provider.billingUrl}.`)
189
+ }
190
+ }
191
+ // The job's id names the world at the vendor when the request names none,
192
+ // so a world whose start was never confirmed can still be found by it.
193
+ const jobId = newJobId(provider.id)
194
+ const name = args.name ?? `nowhere ${jobId}`
195
+ const submittedAt = new Date().toISOString()
196
+ let started
197
+ try {
198
+ started = await provider.submit({
199
+ input: args.input,
200
+ model,
201
+ prompt: args.prompt?.trim() || undefined,
202
+ image: picture ? { data: picture.data, extension: picture.mime === 'image/png' ? 'png' : 'jpg' } : null,
203
+ name,
204
+ seed: args.seed,
205
+ key,
206
+ fetch,
207
+ ua,
208
+ })
209
+ } catch (err) {
210
+ if (!mayHaveStarted(err)) return fail(`${vendorWords(provider, err)} Nothing was spent.`)
211
+ // The request went out and the answer was lost or broken: the world may
212
+ // be running, and billed. Its cost goes into the spend now, so the same
213
+ // approval cannot pay for a second one, and the job is kept unconfirmed.
214
+ await writeJob(ctx.projectRoot, {
215
+ id: jobId,
216
+ provider: provider.id,
217
+ kind: 'environment',
218
+ task: `${args.input}-to-world`,
219
+ model,
220
+ prompt: args.prompt ?? '',
221
+ name,
222
+ resolution: args.resolution ?? '500k',
223
+ vendorIds: [],
224
+ estimateUsd: totalUsd,
225
+ estimateCredits: price.credits,
226
+ createdAt: submittedAt,
227
+ status: 'unconfirmed',
228
+ error: String(err?.message ?? err).slice(0, 300),
229
+ candidates: [{ n: 1, status: 'unconfirmed', progress: 0 }],
230
+ })
231
+ try {
232
+ ctx?.ledger?.addGeneration?.(totalUsd, `${provider.id} ${args.input}-to-world (unconfirmed)`)
233
+ } catch (e) {
234
+ ctx?.log?.(`[environment] ledger.addGeneration failed: ${e?.message ?? e}`)
235
+ }
236
+ return fail(
237
+ `${provider.label} may have started the world: the request went out, but ${String(err?.message ?? err).slice(0, 200)}. Up to ${usd(totalUsd)} is recorded in the spend, so this approval does not pay for a second one. Do not submit again: ask the creator to look at their worlds at https://platform.worldlabs.ai for one named "${name}", started at ${submittedAt}. It is kept as job ${jobId}, unconfirmed.`,
238
+ )
239
+ }
240
+ const job = {
241
+ id: jobId,
242
+ provider: provider.id,
243
+ kind: 'environment',
244
+ task: `${args.input}-to-world`,
245
+ model,
246
+ prompt: args.prompt ?? '',
247
+ promptSha256: createHash('sha256').update(args.prompt ?? '').digest('hex'),
248
+ ...(picture ? { image: picture.rel, inputs: [inputRecordOf(picture.rel, picture.sha256, picture.entry)] } : {}),
249
+ name,
250
+ resolution: args.resolution ?? '500k',
251
+ vendorIds: [started.vendorId],
252
+ estimateUsd: totalUsd,
253
+ estimateCredits: price.credits,
254
+ createdAt: submittedAt,
255
+ status: 'pending',
256
+ candidates: [{ n: 1, vendorId: started.vendorId, ...(started.worldId ? { worldId: started.worldId } : {}), status: 'pending', progress: 0 }],
257
+ }
258
+ await writeJob(ctx.projectRoot, job)
259
+ // Recorded once, at the estimate's upper price: what the vendor bills is
260
+ // its own answer, which environment_job reports beside it.
261
+ try {
262
+ ctx?.ledger?.addGeneration?.(totalUsd, `${provider.id} ${job.task}`)
263
+ } catch (err) {
264
+ ctx?.log?.(`[environment] ledger.addGeneration failed: ${err?.message ?? err}`)
265
+ }
266
+ return {
267
+ text: [
268
+ `Started ${provider.label} ${job.task} (${model}) as job ${jobId}, up to ${usd(totalUsd)}, recorded in the spend.`,
269
+ `Follow it with environment_job (id "${jobId}"); a world takes about five minutes.`,
270
+ ].join('\n'),
271
+ }
272
+ }
273
+
274
+ // ---------------------------------------------------------------- environment_job
275
+
276
+ const JOB_SHAPE = {
277
+ id: z.string().describe('The job id environment_generate answered.'),
278
+ wait: z.number().int().min(0).max(120).default(60).describe('Seconds to keep polling (every 10 s) before answering; a world takes about five minutes, so ask again.'),
279
+ }
280
+
281
+ const JOB_DESCRIPTION =
282
+ "Checks a world from environment_generate: polls the vendor every 10 seconds for up to wait seconds and answers where it is. When it is done it downloads the splat (at the resolution the job asked for), its collider, its panorama and its thumbnail into quarantine as env-<job>, with source.json (the licence, the credit line World Labs is owed, the cost and the frame: up, metres, ground) and shows the thumbnail; bring it into the space with asset_import from that id as \"assets/<name>.spz\". Jobs survive a restart."
283
+
284
+ const EXT_OF = { 'image/png': '.png', 'image/jpeg': '.jpg' }
285
+
286
+ /** Downloads a finished world into quarantine; { qid, files, thumbnail } or { error }. */
287
+ async function downloadWorld(root, job, provider, world, { fetch, ua }) {
288
+ const plan = provider.files(world, { resolution: job.resolution })
289
+ if (plan.error) return { error: plan.error }
290
+ const qid = `env-${job.id}`
291
+ const dir = path.join(root, QUARANTINE, qid)
292
+ await fsp.rm(dir, { recursive: true, force: true })
293
+ await fsp.mkdir(dir, { recursive: true })
294
+ const got = []
295
+ let total = 0
296
+ let thumbnail = null
297
+ try {
298
+ for (const f of plan.files) {
299
+ // The splat is the heaviest by far; every file within what a generated
300
+ // download may weigh, all of them together too.
301
+ const left = QUARANTINE_LIMITS.generated - total
302
+ const temp = path.join(dir, `${f.name}.download`)
303
+ const r = await download(f.url, temp, { fetch, hosts: provider.fileHosts, ua, maxBytes: left })
304
+ const head = Buffer.alloc(16)
305
+ const fd = await fsp.open(temp, 'r')
306
+ await fd.read(head, 0, 16, 0)
307
+ await fd.close()
308
+ let name = f.name
309
+ if (f.role === 'pano' || f.role === 'thumbnail') {
310
+ const mime = imageMime(head)
311
+ if (!mime) {
312
+ await fsp.rm(temp, { force: true })
313
+ if (f.role === 'thumbnail') continue
314
+ throw new Error('its panorama is not a PNG or a JPEG')
315
+ }
316
+ name = `${f.name}${EXT_OF[mime]}`
317
+ }
318
+ if (f.role === 'collider' && head.subarray(0, 4).toString('latin1') !== 'glTF') throw new Error('its collider is not a GLB')
319
+ if (f.role === 'splat' && !spzHeader(await fsp.readFile(temp))) throw new Error('its splat is not an SPZ')
320
+ await fsp.rename(temp, path.join(dir, name))
321
+ total += r.bytes
322
+ got.push({ path: name, bytes: r.bytes, sha256: r.sha256, role: f.role, host: r.host })
323
+ if (f.role === 'thumbnail') thumbnail = name
324
+ }
325
+ } catch (err) {
326
+ await fsp.rm(dir, { recursive: true, force: true })
327
+ return { error: err instanceof NetError ? err.message : String(err?.message ?? err) }
328
+ }
329
+ const credits = Number.isFinite(job.credits) ? job.credits : null
330
+ const usdSpent = credits !== null ? Math.round(credits * (PRICES.worldlabs?.creditUsd ?? 0) * 100) / 100 : job.estimateUsd
331
+ const license = provider.licenseOf(job.model)
332
+ const source = {
333
+ provider: provider.id,
334
+ id: plan.meta.world_id ?? job.id,
335
+ kind: 'splat',
336
+ title: String(job.name || job.prompt || `${provider.label} world`).slice(0, 200),
337
+ author: `${provider.label} (generated)`,
338
+ ...(plan.meta.marble_url ? { url: plan.meta.marble_url } : {}),
339
+ host: got[0]?.host,
340
+ license,
341
+ fetchedAt: today(),
342
+ job: job.id,
343
+ generation: { vendor: provider.id, model: job.model, prompt: String(job.prompt ?? '').slice(0, 2000), job: job.id, usd: usdSpent },
344
+ provenance: { promptSha256: job.promptSha256 ?? null, inputs: job.inputs ?? [] },
345
+ frame: plan.frame,
346
+ meta: { ...plan.meta, ...(credits !== null ? { credits } : {}) },
347
+ files: got.map(({ path: p, bytes, sha256 }) => ({ path: p, bytes, sha256 })),
348
+ }
349
+ await fsp.writeFile(path.join(dir, 'source.json'), `${JSON.stringify(source, null, 2)}\n`)
350
+ await addToManifest(root, {
351
+ id: qid,
352
+ file: qid,
353
+ name: `${provider.label} ${job.task}`,
354
+ url: '',
355
+ referrer: '',
356
+ host: got[0]?.host ?? '',
357
+ bytes: total,
358
+ sha256: got[0]?.sha256 ?? '',
359
+ kind: 'splat',
360
+ ok: true,
361
+ problem: null,
362
+ at: new Date().toISOString(),
363
+ source: { provider: provider.id, job: job.id, license },
364
+ })
365
+ return { qid, files: got, thumbnail, plan, usdSpent, credits }
366
+ }
367
+
368
+ async function job(args, ctx, deps) {
369
+ if (!ctx?.projectRoot) return fail('No project is open.')
370
+ if (!isJobId(args.id) || !String(args.id).startsWith('worldlabs-')) {
371
+ const recent = (await listJobs(ctx.projectRoot)).filter((j) => j.startsWith('worldlabs-')).slice(-6)
372
+ return fail(`"${args.id}" is not a world's job id.${recent.length ? ` Worlds in this project: ${recent.join(', ')}.` : ''}`)
373
+ }
374
+ const current = await readJob(ctx.projectRoot, args.id)
375
+ if (!current) return fail(`There is no job ${args.id} in this project (.nowhere/jobs/).`)
376
+ const provider = ENVIRONMENT_PROVIDERS[current.provider]
377
+ if (!provider) return fail(`Job ${args.id} is for ${current.provider}, which this studio does not run.`)
378
+ if (current.status === 'unconfirmed' || !current.vendorIds?.[0]) {
379
+ return fail(
380
+ `Job ${current.id} was never confirmed: its request went out at ${current.createdAt} and ${current.error ?? 'no answer came back'}, so there is no operation to follow. ${provider.label} may have made it: ask the creator to look at their worlds at https://platform.worldlabs.ai for one named "${current.name}". Its cost (${usd(current.estimateUsd)}) is in the spend.`,
381
+ )
382
+ }
383
+ const key = keyOf(ctx, provider.envVar)
384
+ if (!key) return noKey(provider, ctx)
385
+ const fetch = fetchOf(ctx)
386
+ const ua = userAgentFor(ctx)
387
+ const c = current.candidates[0]
388
+ const started = deps.now()
389
+ const waitMs = (args.wait ?? 60) * 1000
390
+ let world = null
391
+ while (c.status !== 'succeeded' && c.status !== 'failed') {
392
+ try {
393
+ const r = await provider.poll(c, { key, fetch, ua })
394
+ c.status = r.status
395
+ if (Number.isFinite(r.progress)) c.progress = r.progress
396
+ c.note = r.note
397
+ if (r.worldId) c.worldId = r.worldId
398
+ if (r.error) c.error = r.error
399
+ if (r.world) world = r.world
400
+ if (Number.isFinite(r.credits)) current.credits = r.credits
401
+ } catch (err) {
402
+ // A poll that failed (the network, a 5xx) is not the world failing.
403
+ c.note = `the last poll failed: ${String(err?.message ?? err).slice(0, 160)}`
404
+ }
405
+ current.status = c.status
406
+ current.updatedAt = new Date().toISOString()
407
+ await writeJob(ctx.projectRoot, current)
408
+ if (c.status === 'succeeded' || c.status === 'failed') break
409
+ if (deps.now() - started + 10_000 > waitMs) break
410
+ await deps.sleep(10_000)
411
+ }
412
+ const lines = [`Job ${current.id} (${provider.label} ${current.task}, ${current.model}): ${current.status}${Number.isFinite(c.progress) && current.status !== 'succeeded' ? `, ${c.progress}%` : ''}${c.note ? ` (${c.note})` : ''}${c.error ? `: ${c.error}` : ''}.`]
413
+ if (current.status === 'failed') {
414
+ lines.push(`${provider.label} could not make it. Change the prompt or the picture and estimate again; the spend already recorded stays.`)
415
+ return { text: lines.join('\n') }
416
+ }
417
+ if (current.status !== 'succeeded') {
418
+ lines.push('Still going: call environment_job again in a minute.')
419
+ return { text: lines.join('\n') }
420
+ }
421
+ const qid = `env-${current.id}`
422
+ const dir = path.join(ctx.projectRoot, QUARANTINE, qid)
423
+ let got
424
+ if (current.downloaded && fs.existsSync(path.join(dir, 'world.spz'))) {
425
+ got = { qid, files: JSON.parse(await fsp.readFile(path.join(dir, 'source.json'), 'utf8')).files ?? [], thumbnail: (await fsp.readdir(dir)).find((n) => n.startsWith('thumbnail')) ?? null }
426
+ } else {
427
+ // A world found done in an earlier answer, before its files came down,
428
+ // is asked for once more, for its links.
429
+ if (!world) {
430
+ try {
431
+ world = (await provider.poll(c, { key, fetch, ua })).world ?? null
432
+ } catch (err) {
433
+ return fail(`${lines[0]} Its files could not be asked for: ${err?.message ?? err}`)
434
+ }
435
+ }
436
+ got = await downloadWorld(ctx.projectRoot, current, provider, world, { fetch, ua })
437
+ if (got.error) {
438
+ current.downloadError = got.error
439
+ await writeJob(ctx.projectRoot, current)
440
+ return fail(`${lines[0]} It could not be downloaded: ${got.error}`)
441
+ }
442
+ current.downloaded = qid
443
+ delete current.downloadError
444
+ await writeJob(ctx.projectRoot, current)
445
+ }
446
+ const images = []
447
+ if (got.thumbnail) {
448
+ try {
449
+ const buf = await fsp.readFile(path.join(dir, got.thumbnail))
450
+ const mime = imageMime(buf)
451
+ if (mime) images.push({ data: buf.toString('base64'), mime })
452
+ } catch {
453
+ // the text says what came
454
+ }
455
+ }
456
+ const splat = got.files.find((f) => f.path === 'world.spz')
457
+ const header = splat ? spzHeader(await fsp.readFile(path.join(dir, 'world.spz'))) : null
458
+ const source = JSON.parse(await fsp.readFile(path.join(dir, 'source.json'), 'utf8'))
459
+ lines.push(
460
+ `Downloaded into quarantine as ${qid}: ${got.files.map((f) => `${f.path} (${mbOf(f.bytes)} MB)`).join(', ')}.`,
461
+ header ? `The splat holds ${header.count.toLocaleString('en-US')} splats (${source.meta?.resolution ?? current.resolution}), colour detail degree ${header.shDegree}.` : null,
462
+ Number.isFinite(source.meta?.credits) ? `World Labs charged ${source.meta.credits.toLocaleString('en-US')} credits (${usd(source.generation.usd)}), against the estimate of ${usd(current.estimateUsd)}.` : `World Labs did not say what it charged; the estimate of ${usd(current.estimateUsd)} stands in the spend.`,
463
+ `Frame: y down, ${source.frame?.scale ? `${source.frame.scale} m per unit` : 'its own units (World Labs could not tell the scale)'}${Number.isFinite(source.frame?.ground) ? `, ground ${source.frame.ground} m below the start` : ''}: asset_import turns it upright, into metres and onto y = 0, the collider with it.`,
464
+ `Licence: the creator's (a paid World API account owns what it makes); the credit "${source.license.credit}" goes into CREDITS.md.`,
465
+ `Next: asset_import from "${qid}" as "assets/<name>.spz" (the collider comes in beside it as assets/<name>_collider.glb), then look at it with nw_view.`,
466
+ )
467
+ return { text: lines.filter(Boolean).join('\n'), ...(images.length ? { images } : {}) }
468
+ }
469
+
470
+ // ---------------------------------------------------------------- the defs
471
+
472
+ /** The ToolDefs, with the clock replaceable for checks. */
473
+ export function makeEnvironmentTools(overrides = {}) {
474
+ const deps = { now: () => Date.now(), sleep: (ms) => new Promise((r) => setTimeout(r, ms)), ...overrides }
475
+ const guarded = (name, fn) => async (args, ctx) => {
476
+ try {
477
+ return await fn(args, ctx)
478
+ } catch (err) {
479
+ return fail(`${name} failed: ${err?.message ?? err}`)
480
+ }
481
+ }
482
+ return [
483
+ { name: 'environment_generate', description: GENERATE_DESCRIPTION, shape: GENERATE_SHAPE, readOnly: false, handler: guarded('environment_generate', (a, c) => generate(a, c)) },
484
+ { name: 'environment_job', description: JOB_DESCRIPTION, shape: JOB_SHAPE, readOnly: true, handler: guarded('environment_job', (a, c) => job(a, c, deps)) },
485
+ ]
486
+ }
487
+
488
+ export const TOOLS = makeEnvironmentTools()