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
package/README.md CHANGED
@@ -1,3 +1,152 @@
1
- # Temporary Holding Version
1
+ # oda-engine
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Make [Oda](https://nowhere-psi.vercel.app) games from your own tools, and publish them as planets in the Oda universe. A command line for you, an MCP server for your agent (Claude Code, Codex, Cursor or any other), and a live preview in the browser. The same build, checks and publishing as the Oda Studio app.
4
+
5
+ ## Start
6
+
7
+ ```sh
8
+ npx oda-engine new my-game
9
+ cd my-game
10
+ npx oda-engine dev
11
+ ```
12
+
13
+ `dev` opens the preview in your browser. It draws with WebGPU in Chrome, Edge, or Safari 26 and later, and with WebGL 2 in a browser that has no WebGPU. Every save updates it. Edit `src/main.ts` by hand, or let an agent do it.
14
+
15
+ Installed globally (`npm i -g oda-engine`), the command is `oda`.
16
+
17
+ ## With an agent
18
+
19
+ Add the MCP server once, for every project:
20
+
21
+ ```sh
22
+ npx oda-engine setup claude # Claude Code
23
+ npx oda-engine setup codex # Codex
24
+ ```
25
+
26
+ Any other MCP client: run `npx -y oda-engine mcp` over stdio, in the project's folder (or pass `--project <folder>`).
27
+
28
+ Then open the agent in a game folder, or an empty one, and ask for a game. Its tools:
29
+
30
+ | tool | what it does |
31
+ | --- | --- |
32
+ | `nw_new` | makes a project here |
33
+ | `nw_docs` | the SDK guide |
34
+ | `nw_schema` | the JSON Schema of `game.config.json` or `scene.json` |
35
+ | `nw_check` | build, schema, the planet's contract and size limits, then runs it in the preview and reports what it threw and every material that failed to build |
36
+ | `nw_view` | pictures of the game through the cameras the agent picks: the player's view, an orbit or a close-up of anything placed, the whole map |
37
+ | `nw_play` | plays it hands-free (a timeline of held keys and mouse look) and reports where the player went, the HP, the frame rate, with pictures from the player's eyes |
38
+ | `nw_eval` | reads a value from the running game |
39
+ | `nw_logs` | the running game's console, load errors, auto-size notices and materials |
40
+ | `nw_status` | what the running game reports: its state, materials, frame counters, size and draw cost, and every placed model |
41
+ | `look_apply`, `look_compare` | the planet's look (sky, fog, light, tone curve, grade, glow, AO): validated edits of `game.config.json` with values taken from the brief, and a comparison with a reference picture in numbers |
42
+ | `nw_reference`, `nw_compare` | what a reference picture holds in numbers (palette, value key, contrast, haze, horizon, composition), or with `board: true` every picture under `refs/` and `.nowhere/refs/` at once, and a view of the space set beside it with the differences |
43
+ | `asset_search`, `asset_fetch`, `asset_import`, `asset_ledger` | CC0 models, materials and skies from Poly Haven, ambientCG and Poly Pizza (Kenney), brought in at real size, optimised, and recorded with their licence in `assets.lock.json` |
44
+ | `asset_generate`, `asset_job` | a model from Meshy, Tripo or fal (TRELLIS.2): an estimate first, then the job once you agree to its cost |
45
+ | `environment_generate`, `environment_job` | a whole place as Gaussian splats with its collider, from World Labs Marble: an estimate first, then the world once you agree to its cost; `asset_import` brings it (or your own scan, `.ply` or `.spz`) in as `assets/<name>.spz` |
46
+ | `image_generate` | a picture of one asset for image-to-3D, from Codex on your ChatGPT plan (with your consent) or a paid image model: an estimate first |
47
+ | `nw_blender` | runs a bpy script written for one asset in Blender without a window, and scores each export (silhouette, bevel, materials, triangles) |
48
+ | `nw_guide` | the guides: the TSL facts, the look, where assets come from, Blender, licences, art direction, sound, playtests |
49
+ | `nw_screenshot` | the map from the standard view (`nw_view` does this and more) |
50
+ | `nw_login` | opens the browser for you to sign in to Oda |
51
+ | `nw_publish` | publishes the planet, when you ask for it |
52
+
53
+ The tools that run the game open the preview in your browser the first time they need it, or use the one `oda dev` already has open. Every new project carries `AGENTS.md` and `CLAUDE.md` with the platform's rules and how to make it look good: the SDK's TSL materials, a look set from what was asked and the reference, assets from a library or Blender rather than boxes.
54
+
55
+ The asset tools reach the libraries' public APIs; your MCP client asks you before each call. Poly Pizza needs a free key in `POLYPIZZA_API_KEY`, Meshy in `MESHY_API_KEY`, fal in `FAL_KEY`, Tripo in `TRIPO_API_KEY` and World Labs in `WORLDLABS_API_KEY` (its World API credits, not the Marble app's), in the environment the server runs in or stored once with `oda keys set` (the Keys section below); `image_generate`'s Codex needs `NOWHERE_ALLOW_CODEX=1` there. `nw_blender` needs Blender 4.2 or later. `oda mcp --headless` gives the server's tools headless Chrome as the preview's page instead of your browser.
56
+
57
+ ## From a terminal: every tool
58
+
59
+ The same tools run straight from a terminal, with no MCP client and no window: a shell, a script, or an agent with only a shell.
60
+
61
+ ```sh
62
+ oda tools # every tool, one line each (--json: the full schemas)
63
+ oda tool nw_check # any tool by name
64
+ oda tool nw_view --view closeup --target player --yaw 30
65
+ oda tool nw_schema --kind scene
66
+ oda tool nw_view --json '{"views":[{"view":"player"},{"view":"overview"}]}'
67
+ oda tool nw_blender --help # a tool's description and fields
68
+ ```
69
+
70
+ The short forms:
71
+
72
+ ```sh
73
+ oda view [player|orbit|closeup|overview|free ...] [--target x] [--yaw 30] [--distance 12]
74
+ oda play --keys KeyW,ShiftLeft --seconds 3 # or --steps '[{"keys":["KeyW"],"seconds":2}]'
75
+ oda eval 'world.state'
76
+ oda logs [--level warn] oda status oda screenshot
77
+ oda look apply --set '{"look":{"exposure":1.1}}' oda look compare ref.png
78
+ oda reference ref.png oda compare ref.png
79
+ oda asset search mossy rock --kind model oda asset fetch <id> oda asset import <id> --as assets/rock.glb
80
+ oda asset job <id> oda asset ledger
81
+ oda blender blender/lantern.py --out assets/lantern.glb
82
+ oda guide tsl-r185 # oda guide alone lists the guides
83
+ ```
84
+
85
+ Arguments: `--json '{...}'` is the whole input; `--<field> <value>` sets one field (a value that parses as JSON is used parsed, so `--distance 12` is a number and `--target '[0,1,0]'` a point, else it is text; `--<field>` twice makes a list, and so does `a,b` for a list field; `--<field>` alone is true). `--project <folder>` names the project (the default is the folder you are in, or the project above it). A tool's text goes to stdout; every picture it answers is saved as a file of its own type (`.jpg` or `.png`) under `<project>/.nowhere/shots/<tool>-<stamp>-<n>.<ext>`, or under `--save <dir>`, and each path is printed. `--raw` prints the whole result as JSON, with the pictures' paths in place of their bytes. Exit 0, 1 when the tool answered an error, 2 for a wrong command line.
86
+
87
+ The preview: a command that runs the game starts the dev server and headless Chrome on your GPU (WebGPU; `NOWHERE_CHROME` points at another Chrome), uses them, and stops both before it exits. `oda dev --headless` keeps one open until Ctrl+C, so a series of `oda view`, `oda play`, `oda status` reuses its page and runs in a second each. A `oda dev` with a page open in your browser is used as it is.
88
+
89
+ Paid generation: `oda asset generate --provider meshy --task text-to-3d --prompt "a brass ship lantern"` (the action defaults to estimate) prints the cost lines and the estimate id, and sends nothing. The same command again with `--confirm <id>` runs the estimate once more, checks the id still matches (the request did not change), then submits: the cost lines are printed and you are asked `Start it? [y/N]` at the terminal (Ctrl+C there is a no, and stops the command). `--yes` answers yes in the command at a terminal. Without a terminal, `--yes` could be any program's word rather than yours, so it counts only where you set `NOWHERE_ALLOW_PAID=1` in the environment (the same opt-in an MCP client that cannot ask needs); otherwise nothing is sent. A command run by an agent inside the studio or `oda make` never starts a paid generation and never takes `--yes`: the run's own tools ask you. The vendor's key comes from the environment or from `oda keys` (`MESHY_API_KEY`, `FAL_KEY`, `TRIPO_API_KEY`, `WORLDLABS_API_KEY`). `oda image ...` (image_generate) works the same way; its Codex provider needs `NOWHERE_ALLOW_CODEX=1`.
90
+
91
+ ## Keys
92
+
93
+ The services' keys for the terminal commands (`oda tool` and the short forms, `oda make`, `oda mcp`), kept where only you can read them, so nothing has to be exported before every command:
94
+
95
+ ```sh
96
+ oda keys set meshy # pasted at a prompt, not shown (or: pbpaste | oda keys set meshy)
97
+ oda keys list # each key: stored (ending in its last four characters), from the environment, or not set
98
+ oda keys test meshy # tries the key that would be used against the service
99
+ oda keys remove meshy
100
+ oda keys path # where they are kept
101
+ ```
102
+
103
+ A key is named by its service (`anthropic`, `meshy`, `fal`, `tripo`, `polypizza`, ... `oda keys list` has them all) or by its variable (`MESHY_API_KEY`); any other `UPPER_CASE` variable can be stored too. On a Mac the keys live in the login Keychain, one item per variable (service `nowhere`); elsewhere, and for a key the Keychain refused, in `~/.config/nowhere/keys.json`, readable only by you (`NOWHERE_CONFIG_DIR` moves it, `NOWHERE_KEYCHAIN=0` keeps everything in the file). The environment wins: a variable that is already set is used as it is, and the stored one is left alone. `NOWHERE_STORED_KEYS=0` keeps the stored keys out of a command. `oda make` loads only the services' keys (the ones with an id in `oda keys list`), never another variable you stored, and a command an agent runs inside the studio or `oda make` loads none and cannot set or remove one. A key in the Keychain or the file can be read by any program running as you (the Keychain item trusts `/usr/bin/security`, which wrote it), so an agent with a shell of its own, outside the studio's guard, can read it too. A value given on the command line (`oda keys set meshy msy_...`) is taken with a warning, since the shell's history keeps it. The studio app keeps its own keys, so a key set here is for the terminal, `oda make` and `oda mcp`.
104
+
105
+ ## Without a window: `oda make`
106
+
107
+ ```sh
108
+ ANTHROPIC_API_KEY=... oda make my-game --request "a misty cliff walk to a lighthouse" --image ref.png --quality 3 --approve-cost 65 --allow-web --allow-codex
109
+ ```
110
+
111
+ Makes a whole space from one request, as the Oda Studio does, with nothing on the screen: the studio's own agent (or, with team production turned on, its director and roles), run on Claude through the Claude Agent SDK (an optional part of this package: `npm install -g @anthropic-ai/claude-agent-sdk@0.3.290` where it is missing). Its eyes are the preview page in headless Chrome on your GPU (WebGPU), so it needs Chrome or Chromium (`NOWHERE_CHROME` points at another). A new or empty folder becomes a project. Each `--image` (up to 24) goes on the space's reference board, as a picture attached in the studio does: the agent measures the board, writes the brief from it, builds to the brief and compares the brief's hero views with the pictures. The Anthropic key comes from `ANTHROPIC_API_KEY` or from `oda keys set anthropic`, and the services' keys the same way.
112
+
113
+ The cards the studio would show you are answered by the flags: `--approve-cost <usd>` approves cost cards up to this in all: a card that does not fit what is left is approved for what is left, and cancelled once nothing is (the default, 0, approves none, and the production stops before any model is asked; what is left is this amount less what was approved or, when that is more, what the run has spent, and the run is stopped by 1.5 times this amount plus $1), `--allow-web` allows the web (otherwise denied), `--allow-codex` lets Codex make a picture a model is built from on this computer's ChatGPT plan (otherwise denied), `--decline-paid` keeps paid generation off and its keys out of the agent's environment, `--vision approve|skip` answers the vision card, `--quality <1-5>` sets the model, the effort a build runs at, the rounds and the bar as the studio's quality gauge does (1 Quick to 5 Max; it approves no cost, so without `--approve-cost` it prints the step's upper estimate and stops before anything starts; step 3, Careful, is estimated at up to about $65 for a new space), `--best` asks for the most the model can do: the top quality step under `--ceiling`, the web and Codex allowed, choices left to the agent, and that step's upper estimate approved (printed at the start) unless `--approve-cost` gives another amount, `--ceiling <model id>` keeps every step at or below that model's price (the quality step's model included), `--route auto|production|fast` lets the director choose, runs a production, or keeps to one agent (one agent is the default: team production is experimental and off, and `NOWHERE_TEAM_PRODUCTION=1` turns it on, making auto the default), and `--max-sessions <n>` sets how many work at once. A key it lacks is skipped; a choice card is left to the agent, which picks and says which. At the start it says when the web is not allowed and when there is no picture generator (neither `--allow-codex` nor an OpenAI key), since the space then has no target pictures to be judged against.
114
+
115
+ Each run is recorded in `.nowhere/make/<stamp>/` (`run.json` with the versions, the flags, the GPU, the times, the outcome and the cost by model; `events.jsonl`, `cards.jsonl`, `host.log`, `page-console.log`), beside the director's `.nowhere/production/<id>/`, and the project is committed at the end (`make: <request>`, `make (kept below the bar): <request>` when the game runs with all of its parts in but some of them below the critic's bar, or `make (unfinished): <request>`). Exit 0 when the game was made and passed its final check, 1 when it was not finished or is kept below the bar, 2 when it could not start. Ctrl+C stops it, and so does closing the terminal; a second Ctrl+C quits at once. The headless browser never outlives the run.
116
+
117
+ ## Commands
118
+
119
+ ```
120
+ oda new <folder> [--title "My game"] make a project
121
+ oda dev [folder] [--port N] [--no-open] live preview
122
+ oda dev --headless the preview in headless Chrome, kept open for the tool commands
123
+ oda check [folder] [--offline] build, schema, contract, budgets (and a run, with a preview open),
124
+ then whether the live Oda would take it (a dry run)
125
+ oda login | logout | whoami your Oda account
126
+ oda publish [folder] publish or update the planet
127
+ oda make <folder> --request "..." make a game from one request, with no window
128
+ oda tools [--json] every tool, one line each
129
+ oda tool <name> [--<field> value]... run any tool from a terminal, with no window
130
+ oda view | play | eval | logs | status | screenshot the eyes, as commands
131
+ oda look | reference | compare | asset | blender | guide | image the quality tools, as commands
132
+ oda keys set|list|test|remove|path the services' API keys for tool, make and mcp
133
+ oda mcp [--project folder] [--headless] the MCP server (--headless: the preview in headless Chrome)
134
+ oda setup claude | codex add the MCP server to an agent
135
+ oda docs the SDK guide
136
+ oda schema [config|scene] a document's JSON Schema
137
+ ```
138
+
139
+ ## Publishing
140
+
141
+ `oda check` asks the live Oda too, unless you pass `--offline`: what its server takes, what its player plays and which `@nowhere/sdk` names that player has, and a dry run of the planet (its files described, never sent). An answer that does not come is said as not checked. It exits 0 when everything passed (or with `--offline`), 1 for a problem with the project or a "no" from the live Oda, and 2 when the project passed but the live Oda could not be asked: not a problem with the game, and not a pass either. `oda login` signs you in with Google in your browser; the session is kept in `~/.config/nowhere/session.json`, readable only by you. `oda publish` checks the project, takes the planet's picture and splat from the preview, commits the project (publishing needs a commit: a project's first commit is what keeps it the same planet everywhere) and uploads it. Publishing again updates the planet.
142
+
143
+ ## A project
144
+
145
+ - `src/main.ts` exports `createGame(ctx)` returning `{ root, update(dt), dispose() }`.
146
+ - `three` and `@nowhere/sdk` are provided by the host; do not install them.
147
+ - Materials are TSL node materials (three r186, WebGPU), each written for the space's brief: the SDK has no ready-made ones.
148
+ - `game.config.json`: size, sky, fog, light, ground, bloom, and the look (tone mapping, grade, AO, vignette), drawn the same in the preview and on the planet.
149
+ - `scene.json` and `assets/`: models placed by hand, which the game can use, and the files the game loads with `ctx.assets`, each recorded in `assets.lock.json`. One unit is one metre; a model over 12 m or under 0.375 m is shown at 3 m unless its placement sets `"normalize": false`.
150
+ - The visitor walks at 7 m/s and runs at twice that; `config.player` sets `speed`, `run`, `eyeHeight` and `fov` for a space's own scale.
151
+ - Game features (the visitor's health with damage and healing, hazards) are switched off for now: Oda makes spaces first. The SDK keeps them, described in an appendix of its guide.
152
+ - Items are on. A planet lists what a visitor can take away under `items` in game.config.json and gives only those (`world.give`, `world.pickUpOnTouch`); a signed-in visitor's bag is held to that list by the server.
@@ -0,0 +1,352 @@
1
+ #!/usr/bin/env node
2
+ // nowhere: make nowhere spaces from a terminal, and from the agents people
3
+ // already use (README.md).
4
+
5
+ import path from 'node:path'
6
+ import fs from 'node:fs'
7
+
8
+ const HELP = `oda: make Oda spaces, and publish them as planets in the Oda universe.
9
+
10
+ oda new <folder> [--title "My space"] make a project (an empty starter, AGENTS.md, CLAUDE.md, git)
11
+ oda dev [folder] [--port N] [--no-open] live preview in the browser; reloads on every save
12
+ oda dev --headless the preview in headless Chrome, kept open for the tool commands
13
+ oda check [folder] [--offline] build, schema, the planet's gates and budgets, and
14
+ whether the live Oda would take it (a dry run)
15
+ oda publish [folder] publish (or update) the planet
16
+ oda make <folder> --request "..." make a space from one request, with no window (oda make --help)
17
+ oda tools [--json] every tool the agent has, one line each
18
+ oda tool <name> [--<field> value]... run any of them from here, with no window (oda tool --help)
19
+ oda view | play | eval | logs | status | screenshot the eyes on the running space, as tool commands
20
+ oda look | reference | compare | asset | blender | guide | image the quality tools, the same way
21
+ oda keys set|list|test|remove|path the services' API keys for tool, make and mcp (oda keys --help)
22
+ oda login | logout | whoami the Oda account publishing uses
23
+ oda mcp [--project folder] [--headless] the MCP server, for Claude Code, Codex and other agents
24
+ oda setup claude | codex add the MCP server to Claude Code or Codex
25
+ oda docs the SDK guide
26
+ oda schema [config|scene] the JSON Schema of a project document
27
+ `
28
+
29
+ /**
30
+ * The stored keys (`nowhere keys`, lib/keys.mjs) go into process.env before
31
+ * the commands that use them run: tool and its short forms, make and mcp.
32
+ * The environment always wins over a stored key, no value is ever printed,
33
+ * and a store that does not answer is one line on stderr (stdout is the
34
+ * protocol under mcp). NOWHERE_STORED_KEYS=0 keeps them out of a command,
35
+ * and so does an agent's run (NOWHERE_AGENT_RUN=1, which the studio's host
36
+ * sets for its agents), whose keys are the run's own. `catalogOnly` loads
37
+ * only the catalog's variables (nowhere make: its agent's guard keeps those
38
+ * secret, and no other name of the creator's reaches the agent).
39
+ */
40
+ async function loadStoredKeys({ catalogOnly = false } = {}) {
41
+ if (process.env.NOWHERE_STORED_KEYS === '0' || process.env.NOWHERE_AGENT_RUN === '1') return
42
+ try {
43
+ const { keyEntries, loadKeys } = await import('../lib/keys.mjs')
44
+ const only = catalogOnly ? (name) => keyEntries().some((entry) => entry.auth.envVar === name) : null
45
+ loadKeys(process.env, { only, warn: (line) => process.stderr.write(`[Oda] ${line}\n`) })
46
+ } catch (err) {
47
+ process.stderr.write(`[Oda] the stored keys were not loaded: ${err?.message ?? err}\n`)
48
+ }
49
+ }
50
+
51
+ function parse(argv) {
52
+ const flags = {}
53
+ const rest = []
54
+ for (let i = 0; i < argv.length; i++) {
55
+ const a = argv[i]
56
+ if (a.startsWith('--')) {
57
+ const [k, v] = a.slice(2).split('=')
58
+ if (v !== undefined) flags[k] = v
59
+ else if (argv[i + 1] && !argv[i + 1].startsWith('--') && ['title', 'port', 'project'].includes(k)) flags[k] = argv[++i]
60
+ else flags[k] = true
61
+ } else rest.push(a)
62
+ }
63
+ return { flags, rest }
64
+ }
65
+
66
+ const out = (s) => process.stdout.write(`${s}\n`)
67
+ const fail = (s) => {
68
+ process.stderr.write(`${s}\n`)
69
+ process.exit(1)
70
+ }
71
+
72
+ const [command, ...argv] = process.argv.slice(2)
73
+ const { flags, rest } = parse(argv)
74
+
75
+ try {
76
+ switch (command) {
77
+ case undefined:
78
+ case 'help':
79
+ case '--help':
80
+ case '-h':
81
+ out(HELP)
82
+ break
83
+
84
+ case '--version':
85
+ case '-v':
86
+ case 'version': {
87
+ const { VERSION } = await import('../lib/resources.mjs')
88
+ out(VERSION)
89
+ break
90
+ }
91
+
92
+ case 'new': {
93
+ if (!rest[0]) fail('Which folder? oda new <folder>')
94
+ const { createProject } = await import('../lib/scaffold.mjs')
95
+ const root = await createProject(rest[0], typeof flags.title === 'string' ? flags.title : undefined)
96
+ out(`Made ${root}\n\nNext:\n cd ${path.relative(process.cwd(), root) || '.'}\n oda dev # the live preview\n\nOr open Claude Code / Codex there (after \`oda setup claude\` or \`oda setup codex\`) and ask it for a space.`)
97
+ break
98
+ }
99
+
100
+ case 'dev': {
101
+ const { requireProject } = await import('../lib/project.mjs')
102
+ const { startDevServer, findRunning } = await import('../lib/devServer.mjs')
103
+ const { openUrl } = await import('../lib/open.mjs')
104
+ const root = requireProject(rest[0])
105
+ if (flags.headless) {
106
+ // The preview with its page in headless Chrome, kept until Ctrl+C:
107
+ // the tool commands that follow (nowhere view, play, status, ...)
108
+ // find it through .nowhere/dev.json and use its page rather than
109
+ // starting a Chrome of their own for each command. It uses no key,
110
+ // so none is loaded into it.
111
+ const { connectHeadless } = await import('../lib/headlessPreview.mjs')
112
+ const preview = await connectHeadless(root, { port: Number(flags.port) || 0, log: (l) => out(` ${l}`) })
113
+ // From here a Ctrl+C, a kill or a closed terminal stops what this
114
+ // started, even while the page is still coming.
115
+ const stop = async () => {
116
+ await preview.close()
117
+ process.exit(0)
118
+ }
119
+ for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(signal, stop)
120
+ let opened = false
121
+ try {
122
+ opened = await preview.ensurePage(30_000)
123
+ } catch (err) {
124
+ await preview.close()
125
+ fail(err?.message ?? String(err))
126
+ }
127
+ if (!opened) {
128
+ await preview.close()
129
+ fail('Headless Chrome did not open the preview page within 30 s.')
130
+ }
131
+ if (!preview.own && !preview.chrome()) {
132
+ out(`A preview for this project is already running, with a page open: ${preview.url}`)
133
+ break
134
+ }
135
+ out(`oda dev --headless: ${path.basename(root)}\n ${preview.url}\n\nThe page runs in headless Chrome; oda view, play, status and the other tool commands use it. Ctrl+C stops it${preview.own ? ' and the preview' : ''}.`)
136
+ break
137
+ }
138
+ const running = await findRunning(root)
139
+ if (running) {
140
+ out(`A preview for this project is already running: ${running.url}`)
141
+ if (!flags['no-open']) openUrl(running.url)
142
+ break
143
+ }
144
+ const dev = await startDevServer({ root, port: Number(flags.port) || 0, log: (l) => out(` ${l}`) })
145
+ out(`oda dev: ${path.basename(root)}\n ${dev.url}\n\nSaving a file updates the preview. Ctrl+C stops it.`)
146
+ if (!flags['no-open']) openUrl(dev.url)
147
+ const stop = async () => {
148
+ await dev.close()
149
+ process.exit(0)
150
+ }
151
+ process.on('SIGINT', stop)
152
+ process.on('SIGTERM', stop)
153
+ break
154
+ }
155
+
156
+ case 'check': {
157
+ const { requireProject, checkProject } = await import('../lib/project.mjs')
158
+ const { connectPreview, mountFailure } = await import('../lib/preview.mjs')
159
+ const root = requireProject(rest[0])
160
+ const checked = await checkProject(root)
161
+ const lines = []
162
+ let ok = checked.ok
163
+ if (!checked.ok) lines.push('✗ Not ready to publish:', ...checked.problems.map((p) => ` - ${p.replace(/\n/g, '\n ')}`))
164
+ // When a preview is open, the game is also run there. A preview that is
165
+ // running with no page on it is left so: a check opens no browser.
166
+ const live = checked.bundle ? await connectPreview(root, { start: false, open: false }) : null
167
+ if (live && (await live.ensurePage(1000))) {
168
+ const ran = await live.request('mount', { code: checked.bundle }, 30_000)
169
+ // The same verdict as nw_check's: a throw, a material that failed to
170
+ // build, a file that failed to load.
171
+ const failure = mountFailure(ran)
172
+ if (failure) {
173
+ ok = false
174
+ const [head, ...rest] = failure.split('\n')
175
+ lines.push(`✗ In the preview: ${head}`, ...rest.filter(Boolean).map((e) => ` - ${e}`))
176
+ } else lines.push('✓ Runs in the preview without throwing, and every material and file it loads is good.')
177
+ } else if (checked.bundle) lines.push(`· Not run: ${live ? 'the preview has no page open' : 'no preview is open'} (oda dev runs it too).`)
178
+ if (checked.ok) lines.unshift('✓ Builds, and passes the schema, the planet contract and the budgets.')
179
+ // Then the live nowhere: what its server takes and its player plays,
180
+ // and a dry run of this planet, unless --offline. A question that got
181
+ // no answer is said as not checked, never as a pass, and exits 2.
182
+ const { checkProduction, checkExitCode } = await import('../lib/project.mjs')
183
+ let production = null
184
+ if (flags.offline) lines.push('· Not checked against production (--offline).')
185
+ else {
186
+ production = await checkProduction(root, checked)
187
+ lines.push(...production.lines)
188
+ }
189
+ lines.push(...checked.notes.map((n) => `· ${n}`))
190
+ const code = checkExitCode(ok, production)
191
+ if (code === 2) lines.push('· Exit 2: the project passed every check here; the live Oda was not asked, so this is not a pass for production.')
192
+ out(lines.join('\n'))
193
+ process.exit(code)
194
+ }
195
+
196
+ case 'publish': {
197
+ const { requireProject } = await import('../lib/project.mjs')
198
+ const { connectPreview } = await import('../lib/preview.mjs')
199
+ const { describeOutcome, publishProject } = await import('../lib/publishFlow.mjs')
200
+ const root = requireProject(rest[0])
201
+ // The planet's picture and splat come from an open preview, or one
202
+ // opened for the purpose.
203
+ const preview = flags['no-preview'] ? null : await connectPreview(root, { open: true })
204
+ const outcome = await publishProject(root, { preview, say: (l) => out(l) })
205
+ await preview?.close()
206
+ const said = describeOutcome(outcome)
207
+ out(said.text)
208
+ process.exit(said.ok ? 0 : 1)
209
+ }
210
+
211
+ case 'make': {
212
+ // Its own arguments: --request takes text and --image repeats.
213
+ const { MAKE_HELP, parseMakeArgs, runMake } = await import('../lib/make.mjs')
214
+ const parsed = parseMakeArgs(argv)
215
+ if (parsed.help) {
216
+ out(MAKE_HELP)
217
+ break
218
+ }
219
+ if (parsed.error) {
220
+ process.stderr.write(`${parsed.error}\n`)
221
+ process.exit(2)
222
+ }
223
+ // Nothing the agent starts opens a browser either (a nowhere dev or
224
+ // check in its Bash): the runner has no window, ever.
225
+ process.env.NOWHERE_NO_OPEN = '1'
226
+ await loadStoredKeys({ catalogOnly: true })
227
+ const made = await runMake(parsed.options)
228
+ process.exit(made.exit)
229
+ }
230
+
231
+ case 'login': {
232
+ const { account } = await import('../lib/account.mjs')
233
+ const auth = account()
234
+ const now = await auth.status()
235
+ if (now.signedIn) {
236
+ out(`Signed in as ${now.email ?? now.name}.`)
237
+ break
238
+ }
239
+ out('Opening the browser to sign in to Oda with Google…')
240
+ const r = await auth.signIn()
241
+ if (!r.ok) fail(`Sign-in did not finish: ${r.error}`)
242
+ out(`Signed in as ${r.status.email ?? r.status.name}.`)
243
+ process.exit(0)
244
+ }
245
+
246
+ case 'logout': {
247
+ const { account } = await import('../lib/account.mjs')
248
+ const r = await account().signOut()
249
+ if (!r.ok) fail(r.error)
250
+ out('Signed out.')
251
+ break
252
+ }
253
+
254
+ case 'whoami': {
255
+ const { account } = await import('../lib/account.mjs')
256
+ const now = await account().status()
257
+ out(now.signedIn ? `${now.email ?? now.name}` : 'Not signed in. oda login')
258
+ process.exit(now.signedIn ? 0 : 1)
259
+ }
260
+
261
+ case 'mcp': {
262
+ await loadStoredKeys()
263
+ const { runMcp } = await import('../lib/mcp.mjs')
264
+ const project = typeof flags.project === 'string' ? flags.project : undefined
265
+ await runMcp({ project, headless: flags.headless === true || process.env.ODA_MCP_HEADLESS === '1' || (await studioRunIn(project)) })
266
+ break
267
+ }
268
+
269
+ // The tools from a terminal (lib/tools.mjs): their arguments are the
270
+ // tool's own fields, so the raw words after the command go through, not
271
+ // parse()'s reading of them.
272
+ case 'tools':
273
+ case 'tool':
274
+ case 'view':
275
+ case 'play':
276
+ case 'eval':
277
+ case 'logs':
278
+ case 'status':
279
+ case 'screenshot':
280
+ case 'look':
281
+ case 'reference':
282
+ case 'compare':
283
+ case 'asset':
284
+ case 'blender':
285
+ case 'guide':
286
+ case 'image': {
287
+ // The listings and the help use no key.
288
+ if (!['tools', 'guide'].includes(command) && !argv.includes('--help') && !argv.includes('-h')) await loadStoredKeys()
289
+ const { runTools } = await import('../lib/tools.mjs')
290
+ process.exit(await runTools(command, argv))
291
+ }
292
+
293
+ case 'keys': {
294
+ // Its own words (set <id> [value], list [id], test <id>, remove <id>,
295
+ // path), read by lib/keys.mjs.
296
+ const { runKeys } = await import('../lib/keys.mjs')
297
+ process.exit(await runKeys(argv))
298
+ }
299
+
300
+ case 'setup': {
301
+ const { setupClaude, setupCodex } = await import('../lib/setup.mjs')
302
+ if (rest[0] === 'claude') out(setupClaude())
303
+ else if (rest[0] === 'codex') out(setupCodex())
304
+ else fail('oda setup claude, or oda setup codex')
305
+ break
306
+ }
307
+
308
+ case 'docs': {
309
+ const { DOCS } = await import('../lib/resources.mjs')
310
+ out(fs.readFileSync(DOCS, 'utf8'))
311
+ break
312
+ }
313
+
314
+ case 'schema': {
315
+ const { schema } = await import('../lib/resources.mjs')
316
+ const kind = rest[0] === 'scene' ? 'scene' : 'config'
317
+ out(JSON.stringify((await schema()).jsonSchemaFor(kind), null, 2))
318
+ break
319
+ }
320
+
321
+ default:
322
+ fail(`Unknown command "${command}".\n\n${HELP}`)
323
+ }
324
+ } catch (err) {
325
+ fail(err?.message ?? String(err))
326
+ }
327
+
328
+ /** Is the Oda Studio running a request through an agent app in this project
329
+ * right now (apps/studio/electron/agent/appRun.mjs writes the mark)? Then
330
+ * the preview stays in headless Chrome: a browser window would open over
331
+ * the creator's work in the studio. Not every app hands its environment on
332
+ * to the servers it starts, so the mark is a file. */
333
+ async function studioRunIn(project) {
334
+ try {
335
+ const fs = await import('node:fs')
336
+ const os = await import('node:os')
337
+ const dir = process.env.NOWHERE_CONFIG_DIR || path.join(os.homedir(), '.config', 'nowhere')
338
+ const mark = JSON.parse(fs.readFileSync(path.join(dir, 'studio-run.json'), 'utf8'))
339
+ const here = fs.realpathSync(project ?? process.cwd())
340
+ if (fs.realpathSync(String(mark.project)) !== here || Date.now() - Number(mark.at) > 12 * 60 * 60 * 1000) return false
341
+ // A studio that crashed leaves its mark behind: it counts only while
342
+ // the process that wrote it is still there.
343
+ try {
344
+ process.kill(Number(mark.pid), 0)
345
+ return true
346
+ } catch (err) {
347
+ return err?.code === 'EPERM'
348
+ }
349
+ } catch {
350
+ return false
351
+ }
352
+ }
@@ -0,0 +1,57 @@
1
+ // The nowhere account, for publishing: the studio's own sign-in (vendor/
2
+ // auth.cjs: Google through nowhere's Supabase, PKCE, a loopback port for the
3
+ // browser to come back to), with the session kept in a file only this user can
4
+ // read instead of the OS keychain the studio uses.
5
+ //
6
+ // ~/.config/nowhere/session.json (NOWHERE_CONFIG_DIR to move it)
7
+ // ~/.config/nowhere/keys.json the keys for the terminal (keys.mjs), beside it
8
+
9
+ import fs from 'node:fs'
10
+ import os from 'node:os'
11
+ import path from 'node:path'
12
+ import { openUrl } from './open.mjs'
13
+ import { vendor } from './resources.mjs'
14
+
15
+ const DIR = process.env.NOWHERE_CONFIG_DIR || path.join(os.homedir(), '.config', 'nowhere')
16
+ const FILE = path.join(DIR, 'session.json')
17
+
18
+ /** The folder, for the key store (keys.mjs) to keep keys.json beside session.json. */
19
+ export const CONFIG_DIR = DIR
20
+
21
+ function readAll() {
22
+ try {
23
+ const value = JSON.parse(fs.readFileSync(FILE, 'utf8'))
24
+ return value && typeof value === 'object' ? value : {}
25
+ } catch {
26
+ return {}
27
+ }
28
+ }
29
+
30
+ function writeAll(value) {
31
+ fs.mkdirSync(DIR, { recursive: true, mode: 0o700 })
32
+ const tmp = `${FILE}.${process.pid}.tmp`
33
+ fs.writeFileSync(tmp, JSON.stringify(value), { mode: 0o600 })
34
+ fs.renameSync(tmp, FILE)
35
+ fs.chmodSync(FILE, 0o600)
36
+ }
37
+
38
+ const fileSecrets = {
39
+ getSecret: (name) => readAll()[name] ?? null,
40
+ setSecret: (name, value) => writeAll({ ...readAll(), [name]: value }),
41
+ clearSecret: (name) => {
42
+ const all = readAll()
43
+ delete all[name]
44
+ writeAll(all)
45
+ },
46
+ }
47
+
48
+ let configured = null
49
+ export function account() {
50
+ if (!configured) {
51
+ configured = vendor('auth.cjs')
52
+ configured.configure({ secrets: fileSecrets, openExternal: (url) => openUrl(url) })
53
+ }
54
+ return configured
55
+ }
56
+
57
+ export const sessionFile = FILE
@@ -0,0 +1,57 @@
1
+ // Where `nowhere make` finds the studio agent's own modules (the host, the
2
+ // director, the roles, the tools and what they import): vendored beside this
3
+ // package by its build (vendor/agent/), or, in the private monorepo before
4
+ // that build has vendored them, the studio's (apps/studio/electron/agent/).
5
+ // One tree for every module, chosen by where the host is, so the host and
6
+ // everything it imports always come from the same place: a vendored
7
+ // shared.mjs beside the studio's host would read another model table and
8
+ // another connector catalog.
9
+
10
+ import { existsSync } from 'node:fs'
11
+ import { createRequire } from 'node:module'
12
+ import path from 'node:path'
13
+ import { pathToFileURL } from 'node:url'
14
+ import { PKG, VENDOR } from './resources.mjs'
15
+
16
+ export const VENDOR_AGENT = path.join(VENDOR, 'agent')
17
+ export const MONOREPO_AGENT = path.resolve(PKG, '..', '..', 'apps', 'studio', 'electron', 'agent')
18
+
19
+ /** The package that runs Claude: an optional dependency of this one (it is
20
+ * about the size of the Claude Code binary), so the other commands work
21
+ * without it. */
22
+ export const SDK_PACKAGE = '@anthropic-ai/claude-agent-sdk'
23
+ export const SDK_VERSION = '0.3.290'
24
+ export const NO_SDK = `oda make runs Claude through the Claude Agent SDK, which this copy of oda-engine does not have (it is an optional part of it). Install it with: npm install -g ${SDK_PACKAGE}@${SDK_VERSION}`
25
+
26
+ /** The agent's folder and which tree it is ('vendor' or 'monorepo'), or
27
+ * null when neither has the host. */
28
+ export function agentTree({ vendor = VENDOR_AGENT, monorepo = MONOREPO_AGENT, exists = existsSync } = {}) {
29
+ if (exists(path.join(vendor, 'host.mjs'))) return { dir: vendor, from: 'vendor' }
30
+ if (exists(path.join(monorepo, 'host.mjs'))) return { dir: monorepo, from: 'monorepo' }
31
+ return null
32
+ }
33
+
34
+ const NO_AGENT = 'This copy of oda-engine does not carry the studio agent that oda make runs (vendor/agent/host.mjs). Reinstall it, or run its build in a checkout.'
35
+
36
+ /** The file `rel` (relative to the agent's folder, e.g. 'host.mjs' or
37
+ * '../connectors.cjs') in the tree in use. */
38
+ export function agentPath(rel, tree = agentTree()) {
39
+ if (!tree) throw new Error(NO_AGENT)
40
+ return path.join(tree.dir, rel)
41
+ }
42
+
43
+ /** An ES module of the agent's (host.mjs, shared.mjs, director/...). */
44
+ export async function agentModule(rel, tree = agentTree()) {
45
+ return import(pathToFileURL(agentPath(rel, tree)).href)
46
+ }
47
+
48
+ /** A CommonJS module of the agent's (cards.cjs, '../connectors.cjs', '../git.cjs'). */
49
+ export function agentRequire(rel, tree = agentTree()) {
50
+ const file = agentPath(rel, tree)
51
+ return createRequire(file)(file)
52
+ }
53
+
54
+ /** Whether an import failed because the Agent SDK is not installed. */
55
+ export function missingSdk(err) {
56
+ return (err?.code === 'ERR_MODULE_NOT_FOUND' || err?.code === 'MODULE_NOT_FOUND') && String(err?.message ?? '').includes(SDK_PACKAGE)
57
+ }