@arcforge/platform 2.0.166

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 (207) hide show
  1. package/README.md +31 -0
  2. package/package.json +69 -0
  3. package/src/bin/supervisor.ts +102 -0
  4. package/src/bin/test-api.ts +30 -0
  5. package/src/bin/test-preload.ts +308 -0
  6. package/src/bin/update-helper.ts +32 -0
  7. package/src/build/bench/CLAUDE.md +106 -0
  8. package/src/build/bench/SPEC.md +209 -0
  9. package/src/build/bench/agents.ts +105 -0
  10. package/src/build/bench/axes.ts +84 -0
  11. package/src/build/bench/bench.ts +96 -0
  12. package/src/build/bench/discover.ts +147 -0
  13. package/src/build/bench/index.ts +7 -0
  14. package/src/build/bench/log.ts +47 -0
  15. package/src/build/bench/matrix.ts +23 -0
  16. package/src/build/bench/preload.ts +440 -0
  17. package/src/build/bench/prepare.ts +61 -0
  18. package/src/build/bench/projection.ts +112 -0
  19. package/src/build/bench/resolve.ts +54 -0
  20. package/src/build/bench/runner.ts +309 -0
  21. package/src/build/bench/schema/extract.ts +148 -0
  22. package/src/build/bench/schema/index.ts +2 -0
  23. package/src/build/bench/schema/schema.ts +95 -0
  24. package/src/build/bench/schema/worker.ts +30 -0
  25. package/src/build/bench/typegen.ts +119 -0
  26. package/src/build/bench/workspace/files.ts +139 -0
  27. package/src/build/bench/workspace/handle.ts +133 -0
  28. package/src/build/bench/workspace/index.ts +11 -0
  29. package/src/build/bench/workspace/workspace.ts +14 -0
  30. package/src/build/blueprint/blueprint.ts +398 -0
  31. package/src/build/blueprint/cognet/abi.ts +207 -0
  32. package/src/build/blueprint/cognet/bundle-worker.ts +93 -0
  33. package/src/build/blueprint/cognet/bundle.ts +664 -0
  34. package/src/build/blueprint/cognet/cognet.ts +249 -0
  35. package/src/build/blueprint/cognet/index.ts +10 -0
  36. package/src/build/blueprint/cognet/manifest.ts +38 -0
  37. package/src/build/blueprint/cognet/resolve.ts +113 -0
  38. package/src/build/blueprint/collisions.ts +51 -0
  39. package/src/build/blueprint/index.ts +29 -0
  40. package/src/build/blueprint/modules/entries.ts +117 -0
  41. package/src/build/blueprint/modules/index.ts +300 -0
  42. package/src/build/blueprint/modules/meta.ts +174 -0
  43. package/src/build/blueprint/scan/boot.ts +34 -0
  44. package/src/build/blueprint/scan/cognetImports.ts +56 -0
  45. package/src/build/blueprint/scan/components.ts +45 -0
  46. package/src/build/blueprint/scan/config.ts +234 -0
  47. package/src/build/blueprint/scan/configImports.ts +232 -0
  48. package/src/build/blueprint/scan/declare-worker.ts +61 -0
  49. package/src/build/blueprint/scan/declare.ts +393 -0
  50. package/src/build/blueprint/scan/h3-globals.ts +137 -0
  51. package/src/build/blueprint/scan/knowledge.ts +101 -0
  52. package/src/build/blueprint/scan/middleware.ts +110 -0
  53. package/src/build/blueprint/scan/moduleImports.ts +79 -0
  54. package/src/build/blueprint/scan/plugins.ts +93 -0
  55. package/src/build/blueprint/scan/promptPackages.ts +45 -0
  56. package/src/build/blueprint/scan/prompts.ts +164 -0
  57. package/src/build/blueprint/scan/published.ts +131 -0
  58. package/src/build/blueprint/scan/resolve.ts +398 -0
  59. package/src/build/blueprint/scan/routes.ts +109 -0
  60. package/src/build/blueprint/scan/scripts.ts +119 -0
  61. package/src/build/blueprint/scan/tool-bundle-worker.ts +69 -0
  62. package/src/build/blueprint/scan/tools.ts +610 -0
  63. package/src/build/blueprint/types.ts +28 -0
  64. package/src/build/extensions/config.ts +261 -0
  65. package/src/build/extensions/edit.ts +684 -0
  66. package/src/build/extensions/extensions.ts +731 -0
  67. package/src/build/extensions/index.ts +10 -0
  68. package/src/build/extensions/load.ts +350 -0
  69. package/src/build/extensions/registrations.ts +189 -0
  70. package/src/build/extensions/store.ts +200 -0
  71. package/src/build/frame/frame.ts +145 -0
  72. package/src/build/frame/index.ts +5 -0
  73. package/src/build/frame/migrate.ts +246 -0
  74. package/src/build/project/bundle/agent.ts +382 -0
  75. package/src/build/project/bundle/artifacts.ts +88 -0
  76. package/src/build/project/bundle/assets.ts +385 -0
  77. package/src/build/project/bundle/bundle.ts +160 -0
  78. package/src/build/project/bundle/imports.ts +102 -0
  79. package/src/build/project/bundle/index.ts +16 -0
  80. package/src/build/project/bundle/module.ts +130 -0
  81. package/src/build/project/bundle/source.ts +136 -0
  82. package/src/build/project/bundle/stage.ts +97 -0
  83. package/src/build/project/bundle/types.ts +111 -0
  84. package/src/build/project/cognet.ts +156 -0
  85. package/src/build/project/create/agent.ts +52 -0
  86. package/src/build/project/create/bench.ts +81 -0
  87. package/src/build/project/create/cognet.ts +102 -0
  88. package/src/build/project/create/extension.ts +63 -0
  89. package/src/build/project/create/module.ts +43 -0
  90. package/src/build/project/create/profile.ts +102 -0
  91. package/src/build/project/create/prompt.ts +68 -0
  92. package/src/build/project/create/templates.ts +88 -0
  93. package/src/build/project/deploy.ts +96 -0
  94. package/src/build/project/index.ts +40 -0
  95. package/src/build/project/installer.ts +616 -0
  96. package/src/build/project/kinds.ts +374 -0
  97. package/src/build/project/links.ts +33 -0
  98. package/src/build/project/manifest/bunfig.ts +139 -0
  99. package/src/build/project/manifest/config.ts +246 -0
  100. package/src/build/project/manifest/env.ts +184 -0
  101. package/src/build/project/manifest/index.ts +9 -0
  102. package/src/build/project/manifest/manifest.ts +49 -0
  103. package/src/build/project/manifest/model.ts +124 -0
  104. package/src/build/project/manifest/package.ts +386 -0
  105. package/src/build/project/manifest/text.ts +19 -0
  106. package/src/build/project/models/fetch.ts +123 -0
  107. package/src/build/project/models/index.ts +8 -0
  108. package/src/build/project/models/models.ts +111 -0
  109. package/src/build/project/models/specifier.ts +106 -0
  110. package/src/build/project/models/store.ts +202 -0
  111. package/src/build/project/modules/hash.ts +31 -0
  112. package/src/build/project/modules/index.ts +5 -0
  113. package/src/build/project/modules/lock.ts +78 -0
  114. package/src/build/project/modules/modules.ts +155 -0
  115. package/src/build/project/prepare.ts +709 -0
  116. package/src/build/project/project.ts +253 -0
  117. package/src/build/project/projects.ts +164 -0
  118. package/src/build/project/propagation.ts +120 -0
  119. package/src/build/project/publish/verify.ts +312 -0
  120. package/src/build/project/publish.ts +155 -0
  121. package/src/build/project/reconcile.ts +93 -0
  122. package/src/build/project/specifier.ts +42 -0
  123. package/src/build/project/tree.ts +615 -0
  124. package/src/build/project/treecache.ts +356 -0
  125. package/src/build/project/typegen/axon-dts.ts +362 -0
  126. package/src/build/project/typegen/cognet-dts.ts +91 -0
  127. package/src/build/project/typegen/components.ts +45 -0
  128. package/src/build/project/typegen/env.ts +59 -0
  129. package/src/build/project/typegen/generators.ts +108 -0
  130. package/src/build/project/typegen/hooks.ts +71 -0
  131. package/src/build/project/typegen/index.ts +137 -0
  132. package/src/build/project/typegen/prompt-dts.ts +40 -0
  133. package/src/build/project/typegen/prompts.ts +36 -0
  134. package/src/build/project/typegen/registry-dts.ts +109 -0
  135. package/src/build/project/typegen/scripts.ts +37 -0
  136. package/src/build/project/typegen/tools.ts +31 -0
  137. package/src/build/project/typegen/tsconfig.ts +243 -0
  138. package/src/build/project/typegen/tui-dts.ts +120 -0
  139. package/src/build/project/typegen/write.ts +40 -0
  140. package/src/build/project/verify.ts +268 -0
  141. package/src/build/project/watcher.ts +266 -0
  142. package/src/build/runtime/agent.ts +550 -0
  143. package/src/build/runtime/escalations.ts +159 -0
  144. package/src/build/runtime/index.ts +15 -0
  145. package/src/build/runtime/instances.ts +604 -0
  146. package/src/build/runtime/profile.ts +91 -0
  147. package/src/build/runtime/progress.ts +143 -0
  148. package/src/build/runtime/requests.ts +167 -0
  149. package/src/build/runtime/resolve.ts +159 -0
  150. package/src/build/runtime/runtime.ts +233 -0
  151. package/src/build/runtime/sessions/index.ts +5 -0
  152. package/src/build/runtime/sessions/record.ts +145 -0
  153. package/src/build/runtime/sessions/sessions.ts +240 -0
  154. package/src/build/runtime/zeno.ts +120 -0
  155. package/src/index.ts +11 -0
  156. package/src/link/agent-main.ts +395 -0
  157. package/src/link/index.ts +70 -0
  158. package/src/link/services.ts +120 -0
  159. package/src/platform.ts +293 -0
  160. package/src/procs/index.ts +15 -0
  161. package/src/procs/tree.ts +177 -0
  162. package/src/services/cloud.ts +419 -0
  163. package/src/services/control/client.ts +126 -0
  164. package/src/services/control/dispatch.ts +156 -0
  165. package/src/services/control/index.ts +17 -0
  166. package/src/services/control/protocol.ts +179 -0
  167. package/src/services/control/server.ts +241 -0
  168. package/src/services/deployments.ts +81 -0
  169. package/src/services/files.ts +329 -0
  170. package/src/services/index.ts +5 -0
  171. package/src/services/mic/capture.ts +248 -0
  172. package/src/services/mic/config.ts +109 -0
  173. package/src/services/mic/fft.ts +93 -0
  174. package/src/services/mic/index.ts +139 -0
  175. package/src/services/mic/visualizer.ts +46 -0
  176. package/src/services/ollama/catalog.ts +122 -0
  177. package/src/services/ollama/http.ts +124 -0
  178. package/src/services/ollama/index.ts +13 -0
  179. package/src/services/ollama/models.ts +153 -0
  180. package/src/services/ollama/ollama.ts +89 -0
  181. package/src/services/ollama/registry.ts +112 -0
  182. package/src/services/ollama/types.ts +72 -0
  183. package/src/services/prompts.ts +76 -0
  184. package/src/services/registry.ts +220 -0
  185. package/src/services/resources/hardware.ts +125 -0
  186. package/src/services/resources/index.ts +6 -0
  187. package/src/services/resources/reservations.ts +162 -0
  188. package/src/services/resources/resources.ts +156 -0
  189. package/src/services/running/index.ts +1 -0
  190. package/src/services/running/running.ts +200 -0
  191. package/src/services/store/disk.ts +97 -0
  192. package/src/services/store/index.ts +15 -0
  193. package/src/services/store/store.ts +729 -0
  194. package/src/services/store/types.ts +303 -0
  195. package/src/services/test/child.ts +150 -0
  196. package/src/services/test/events.ts +102 -0
  197. package/src/services/test/files.ts +26 -0
  198. package/src/services/test/frames.ts +39 -0
  199. package/src/services/test/index.ts +7 -0
  200. package/src/services/test/runner.ts +122 -0
  201. package/src/services/test/types.ts +26 -0
  202. package/src/services/update/contract.ts +77 -0
  203. package/src/services/update/index.ts +12 -0
  204. package/src/services/update/installer.ts +139 -0
  205. package/src/services/update/updates.ts +137 -0
  206. package/src/utils/fs.ts +148 -0
  207. package/src/utils/tsast.ts +102 -0
@@ -0,0 +1,234 @@
1
+ import { join } from "node:path"
2
+ import { AsyncLocalStorage } from "node:async_hooks"
3
+ import { defineModule, definePrompt } from "@arcforge/types"
4
+ import { defineCognet } from "@arcforge/cognet"
5
+ import type { AxonConfig, ModuleEntry } from "@arcforge/types"
6
+ import { Axon, Ollama, Codex, OpenRouter, HuggingFace, Mock } from "@arcforge/engines"
7
+ import { err } from "@arcforge/err"
8
+ import { fsx } from "../../../utils/fs"
9
+ import { resolveModulePaths, type ResolvedModulePath } from "./moduleImports"
10
+ import { resolveCognetPath } from "./cognetImports"
11
+ import type { ResolvedDeclaration } from "./configImports"
12
+
13
+ /**
14
+ * Config — loads and evaluates axon.config.ts. The ONE place in the
15
+ * blueprint pipeline that executes user code; everything else is static
16
+ * analysis and filesystem walking.
17
+ *
18
+ * A broken config THROWS. A missing or unreadable config is not a degraded
19
+ * agent — it is no agent. Scanners warn; config fails loudly.
20
+ */
21
+
22
+ export type LoadedConfig = {
23
+ /**
24
+ * The directory the config was loaded from.
25
+ *
26
+ * Carried rather than re-passed alongside, because some declarations are
27
+ * made by the FILESYSTEM rather than by the config object — an inline
28
+ * `cognet/` folder is a declaration with nothing written in the config at
29
+ * all. A resolver handed only `value` cannot see those, and making every
30
+ * caller remember to pass the root beside the config is how one of them
31
+ * eventually doesn't.
32
+ */
33
+ root: string
34
+ /** The object passed to defineAgent(). */
35
+ value: AxonConfig
36
+ /** Declared module entries, raw — Modules() normalises and flattens. */
37
+ modules: ModuleEntry[]
38
+ /**
39
+ * Statically-resolved source path for each entry in `modules`, by position.
40
+ * `modulePaths[i]` corresponds to `modules[i]`. A source module carries its
41
+ * absolute `module.config.ts` path here; a registry string carries its name;
42
+ * an entry whose import cannot be resolved carries the reason. This is the
43
+ * ONLY source of a source module's path — `defineModule()` no longer stamps
44
+ * one.
45
+ */
46
+ modulePaths: ResolvedModulePath[]
47
+ /**
48
+ * Statically-resolved origin of the config's `cognet:` entry, or null when
49
+ * the field is absent (the agent declared no brain and tracks the registry
50
+ * default). A source cognet carries its absolute `cognet.config.ts` path
51
+ * here — the only place it exists, since `defineCognet()` stamps nothing.
52
+ */
53
+ cognetPath: ResolvedDeclaration | null
54
+ }
55
+
56
+ type ConfigEvaluation = {
57
+ capture(config: AxonConfig): void
58
+ }
59
+
60
+ const CONFIG_EVALUATION = Symbol.for("axon.config.evaluation")
61
+ const evaluationStorage = (() => {
62
+ const shared = globalThis as typeof globalThis & {
63
+ [CONFIG_EVALUATION]?: AsyncLocalStorage<ConfigEvaluation>
64
+ }
65
+ return shared[CONFIG_EVALUATION] ??= new AsyncLocalStorage<ConfigEvaluation>()
66
+ })()
67
+
68
+ /**
69
+ * Synchronous fallback register for the single active evaluation.
70
+ *
71
+ * AsyncLocalStorage is the primary mechanism, but on some Bun versions the
72
+ * ALS context does NOT propagate into a dynamic import()'s module
73
+ * evaluation — so getStore() returns undefined inside the config's
74
+ * synchronous top-level defineAgent() call, and a freshly-scaffolded agent
75
+ * fails its very first boot with "defineAgent() called outside config
76
+ * evaluation" (AX-BLUEPRINT-004).
77
+ *
78
+ * A config module evaluates synchronously as one atomic unit, so as long as
79
+ * only ONE evaluation is in flight at a time, `current` is unambiguous — the
80
+ * defineAgent() call that runs belongs to it. Concurrency is handled by the
81
+ * lock below (evaluations are serialized), not by a stack: a stack would
82
+ * cross-capture, because Bun schedules concurrent import()s and only then
83
+ * runs their synchronous evaluations back-to-back. Held on globalThis so
84
+ * every module copy sees the same current/lock.
85
+ */
86
+ const CONFIG_EVALUATION_STATE = Symbol.for("axon.config.evaluation.state")
87
+ const state = (() => {
88
+ const shared = globalThis as typeof globalThis & {
89
+ [CONFIG_EVALUATION_STATE]?: { current: ConfigEvaluation | null; lock: Promise<void> }
90
+ }
91
+ return shared[CONFIG_EVALUATION_STATE] ??= { current: null, lock: Promise.resolve() }
92
+ })()
93
+
94
+ /**
95
+ * Config files are ordinary modules and therefore share one global object.
96
+ * Install their authoring API once; the active capture is resolved per call.
97
+ */
98
+ function installAuthoringGlobals(): void {
99
+ const g = globalThis as Record<string, unknown>
100
+ g.defineAgent = (config: AxonConfig) => {
101
+ // ALS first (correct even under deep async), the serialized `current`
102
+ // as the fallback for runtimes that drop ALS across import() eval.
103
+ const evaluation = evaluationStorage.getStore() ?? state.current
104
+ if (!evaluation) throw err("CONFIG_EVALUATION_ESCAPED")
105
+ evaluation.capture(config)
106
+ return config
107
+ }
108
+ g.defineModule ??= defineModule
109
+ // A config that imports a source cognet evaluates that cognet.config.ts
110
+ // in this same context, so its defineCognet() call must resolve here.
111
+ // Pure identity, same as defineModule — the real authoring surface is the
112
+ // one @arcforge/cognet installs inside a compiled brain.
113
+ g.defineCognet ??= defineCognet
114
+ g.definePrompt ??= definePrompt
115
+ g.defineArgs ??= () => ({})
116
+ g.defineProps ??= () => ({})
117
+ // Provider factories — what `providers:` takes, in an agent config and a
118
+ // profile config alike. These names were the ENGINE constructors until
119
+ // `engine:` was removed; one name, one meaning again.
120
+ // `??=` deliberately: an embedding host may have installed its own, and
121
+ // the AUTHORITATIVE binding for the duration of an evaluation is applied
122
+ // by withProviderGlobals() below rather than trusted from module load.
123
+ g.Axon ??= Axon
124
+ g.Ollama ??= Ollama
125
+ g.Codex ??= Codex
126
+ g.OpenRouter ??= OpenRouter
127
+ g.HuggingFace ??= HuggingFace
128
+ g.Mock ??= Mock
129
+ }
130
+
131
+ /**
132
+ * Run `body` with the provider factories bound, then put back whatever was
133
+ * there before.
134
+ *
135
+ * `Axon` is a CONTESTED global name. A `*.axon.ts` script run by `axon exec`
136
+ * has `Axon()` bound to the agent-booting factory for the whole run — and
137
+ * booting an agent evaluates axon.config.ts and profile.config.ts, both of
138
+ * which call `Axon()` meaning the PROVIDER factory. Under `??=` at module
139
+ * load the script's binding was already present, so the provider factory was
140
+ * never installed and `providers: [Axon()]` silently produced `{}` instead of
141
+ * `{ provider: "axon" }` — surfacing much later as
142
+ * `PROVIDER_UNKNOWN: "undefined"` from a boot that looked unrelated.
143
+ *
144
+ * Binding unconditionally around the evaluation is what makes the two
145
+ * meanings coexist: inside a config file the name is always the provider
146
+ * factory, and the script's binding is restored the moment the file is read.
147
+ * Safe because both callers already serialize evaluation behind a lock, so
148
+ * these writes never overlap another evaluation.
149
+ */
150
+ export async function withProviderGlobals<T>(body: () => Promise<T>): Promise<T> {
151
+ const g = globalThis as Record<string, unknown>
152
+ const factories = { Axon, Ollama, Codex, OpenRouter, HuggingFace, Mock }
153
+ const previous = Object.fromEntries(Object.keys(factories).map(name => [name, g[name]]))
154
+ Object.assign(g, factories)
155
+ try {
156
+ return await body()
157
+ } finally {
158
+ Object.assign(g, previous)
159
+ }
160
+ }
161
+
162
+ installAuthoringGlobals()
163
+
164
+ export async function Config(root: string): Promise<LoadedConfig> {
165
+ const configPath = join(root, "axon.config.ts")
166
+ if (!fsx.exists(configPath)) {
167
+ throw err("CONFIG_NOT_FOUND", { context: { root } })
168
+ }
169
+
170
+ let captured: AxonConfig | null = null
171
+ const evaluation: ConfigEvaluation = { capture: config => { captured = config } }
172
+
173
+ // Serialize evaluations so the synchronous `current` fallback is
174
+ // unambiguous (see state above). Chain onto the shared lock; the release
175
+ // is published before we start so the next caller waits on us.
176
+ let release!: () => void
177
+ const previous = state.lock
178
+ state.lock = new Promise<void>(resolve => { release = resolve })
179
+ await previous
180
+
181
+ try {
182
+ state.current = evaluation
183
+ // Cache-bust so watch-mode re-runs pick up edits. Date.now() alone
184
+ // collides trivially — repeated calls in the same tick share a
185
+ // millisecond, so Bun's module cache would silently serve a stale
186
+ // import and skip re-invoking defineAgent(). randomUUID() is unique
187
+ // per call regardless of timing.
188
+ //
189
+ // Registered on both the ALS and the serialized `current`: the
190
+ // config's top-level defineAgent() reads whichever is populated (see
191
+ // installAuthoringGlobals) — covering runtimes that drop ALS context
192
+ // crossing into a dynamic import()'s module evaluation.
193
+ try {
194
+ await withProviderGlobals(() =>
195
+ evaluationStorage.run(
196
+ evaluation,
197
+ // A BARE PATH, deliberately — not pathToFileURL().
198
+ //
199
+ // The module loaders elsewhere convert first, because a
200
+ // query appended to a bare path makes the runtime read the
201
+ // whole string as a URL and resolve the module's own bare
202
+ // specifiers against it (see core/src/modules/load.ts).
203
+ // That does not apply here: an agent config imports nothing
204
+ // from node_modules, and converting BREAKS the thing this
205
+ // call depends on — the evaluationStorage ALS context has
206
+ // to survive into the dynamic import's module evaluation so
207
+ // the config's top-level defineAgent() can register. A
208
+ // file:// URL loses it, and the config then evaluates
209
+ // without ever calling defineAgent().
210
+ () => import(`${configPath}?t=${crypto.randomUUID()}`),
211
+ ),
212
+ )
213
+ } catch (cause) {
214
+ const reason = cause instanceof Error ? cause.message : String(cause)
215
+ throw err("CONFIG_LOAD_FAILED", { detail: `${configPath} — ${reason}`, context: { configPath }, cause })
216
+ }
217
+
218
+ if (!captured) {
219
+ throw err("CONFIG_INVALID", { detail: `${configPath} did not call defineAgent()`, context: { configPath } })
220
+ }
221
+
222
+ const value: AxonConfig = captured
223
+ return {
224
+ root,
225
+ value,
226
+ modules: (value.modules ?? []) as ModuleEntry[],
227
+ modulePaths: await resolveModulePaths(configPath),
228
+ cognetPath: await resolveCognetPath(configPath),
229
+ }
230
+ } finally {
231
+ state.current = null
232
+ release()
233
+ }
234
+ }
@@ -0,0 +1,232 @@
1
+ import { dirname, resolve } from "node:path"
2
+ import type TsNamespace from "typescript"
3
+ import { fsx } from "../../../utils/fs"
4
+
5
+ /**
6
+ * Static analysis of axon.config.ts — the shared machinery behind resolving
7
+ * a declared thing (a module, a cognet) back to the file that declares it.
8
+ *
9
+ * Both resolvers answer the same question: an author wrote either a registry
10
+ * STRING or an imported BINDING, and the build needs to know which, plus
11
+ * where the source lives if it is the latter. The answer comes from the
12
+ * `import` statement that brought the binding in — the one place the path is
13
+ * written down — resolved against the config's own directory. No runtime
14
+ * stack, no `import.meta`, no dependence on a bundler preserving a filename.
15
+ * Same bytes in, same paths out.
16
+ *
17
+ * This lives apart from its two callers because they had already started to
18
+ * diverge as copies: moduleImports.ts owned all of it, and cognet resolution
19
+ * needed four of the five helpers verbatim. Two near-identical resolvers
20
+ * drifting apart is the same failure that let the h3 globals declare a
21
+ * surface the runtime did not install.
22
+ */
23
+
24
+ /**
25
+ * `typescript` is ~175ms of module evaluation. Imported eagerly it is paid by
26
+ * everything that touches the blueprint — this module sits behind Config, so
27
+ * "read an agent's config" would mean "load the whole compiler" whether or
28
+ * not there is anything to parse. Bound on first use instead.
29
+ */
30
+ let ts!: typeof TsNamespace
31
+ let loading: Promise<void> | null = null
32
+
33
+ export function loadTs(): Promise<void> {
34
+ loading ??= import("typescript").then(mod => { ts = mod.default })
35
+ return loading
36
+ }
37
+
38
+ /** The bound compiler namespace. Only valid after `await loadTs()`. */
39
+ export function tsc(): typeof TsNamespace {
40
+ return ts
41
+ }
42
+
43
+ /**
44
+ * How a declared entry resolved.
45
+ *
46
+ * Shared by modules and cognets because the distinction is identical: a
47
+ * relative import is source on disk that the build compiles in place; a bare
48
+ * specifier or a plain string names a package the registry installs.
49
+ */
50
+ export type ResolvedDeclaration =
51
+ /** Source on disk: absolute path to its *.config.ts. */
52
+ | { kind: "source"; configPath: string }
53
+ /** A registry artifact declared as a string or bare specifier — no source path. */
54
+ | { kind: "registry"; name: string }
55
+ /** An entry whose import could not be resolved to a file on disk. */
56
+ | { kind: "unresolved"; detail: string }
57
+
58
+ /** Read and parse a config file. Returns null when it does not exist. */
59
+ export async function parseConfig(configFilePath: string): Promise<TsNamespace.SourceFile | null> {
60
+ const content = await fsx.readText(configFilePath)
61
+ if (content === null) return null
62
+
63
+ await loadTs()
64
+ return ts.createSourceFile(configFilePath, content, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS)
65
+ }
66
+
67
+ /**
68
+ * A BARE specifier (@scope/pkg/..., pkg/...) names a package in node_modules
69
+ * — already installed and resolved by the package manager. Only a RELATIVE
70
+ * specifier is source living outside node_modules whose path resolves against
71
+ * the config dir.
72
+ */
73
+ export function isRelativeSpecifier(specifier: string): boolean {
74
+ return specifier.startsWith("./") || specifier.startsWith("../") || specifier.startsWith("/")
75
+ }
76
+
77
+ /**
78
+ * The package name of a bare specifier — "@scope/pkg/module.config" →
79
+ * "@scope/pkg", "pkg/module.config" → "pkg". This is the registry name the
80
+ * artifact is installed and addressed by.
81
+ */
82
+ export function packageOf(specifier: string): string {
83
+ const parts = specifier.split("/")
84
+ if (specifier.startsWith("@")) return parts.slice(0, 2).join("/")
85
+ return parts[0]!
86
+ }
87
+
88
+ /** Map every `import Foo from "spec"` default binding to its specifier. */
89
+ export function collectDefaultImports(src: TsNamespace.SourceFile): Map<string, string> {
90
+ const imports = new Map<string, string>()
91
+ for (const stmt of src.statements) {
92
+ if (!ts.isImportDeclaration(stmt)) continue
93
+ if (!ts.isStringLiteral(stmt.moduleSpecifier)) continue
94
+ const name = stmt.importClause?.name
95
+ if (name) imports.set(name.text, stmt.moduleSpecifier.text)
96
+ }
97
+ return imports
98
+ }
99
+
100
+ /**
101
+ * Find the value assigned to `key:` inside a defineAgent/defineModule call.
102
+ * Returns the initializer expression, or null when the key is absent.
103
+ */
104
+ export function findConfigProperty(
105
+ src: TsNamespace.SourceFile,
106
+ key: string,
107
+ ): TsNamespace.Expression | null {
108
+ let found: TsNamespace.Expression | null = null
109
+
110
+ function visit(node: TsNamespace.Node) {
111
+ if (found) return
112
+ if (
113
+ ts.isCallExpression(node) &&
114
+ ts.isIdentifier(node.expression) &&
115
+ (node.expression.text === "defineAgent" || node.expression.text === "defineModule") &&
116
+ node.arguments[0] &&
117
+ ts.isObjectLiteralExpression(node.arguments[0])
118
+ ) {
119
+ for (const prop of node.arguments[0].properties) {
120
+ if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name) && prop.name.text === key) {
121
+ found = prop.initializer
122
+ return
123
+ }
124
+ }
125
+ }
126
+ ts.forEachChild(node, visit)
127
+ }
128
+
129
+ ts.forEachChild(src, visit)
130
+ return found
131
+ }
132
+
133
+ /**
134
+ * Resolve an import specifier to the *.config.ts it names. The specifier
135
+ * usually points at the config's basename without extension
136
+ * (".../module.config"); try the file directly, then common extensions, then
137
+ * the named config inside a directory.
138
+ */
139
+ export async function resolveSpecifier(
140
+ specifier: string,
141
+ fromDir: string,
142
+ configNames: readonly string[],
143
+ ): Promise<string | null> {
144
+ const base = resolve(fromDir, specifier)
145
+
146
+ // A specifier that already names a file resolves to itself and nothing
147
+ // else. Appending an extension or a config name to it produces paths like
148
+ // `module.config.ts/module.config.ts` — nonsense the loop below would
149
+ // stat, and whose ENOTDIR the caller has no business handling.
150
+ if (/\.(ts|tsx|js|mjs|cjs)$/.test(specifier)) {
151
+ return fsx.isFile(base) ? base : null
152
+ }
153
+
154
+ // Extension-bearing candidates first, then the config inside a directory,
155
+ // and only then the bare path. Order matters: `./brain` names a DIRECTORY
156
+ // whose config is `./brain/cognet.config.ts`, but the bare path exists too
157
+ // — matching it would hand callers a directory where they expect a file,
158
+ // and dirname() of that points at the wrong parent entirely.
159
+ const candidates = [
160
+ `${base}.ts`,
161
+ `${base}.js`,
162
+ ...configNames.map(name => resolve(base, name)),
163
+ ]
164
+ for (const candidate of candidates) {
165
+ if (fsx.isFile(candidate)) return candidate
166
+ }
167
+
168
+ // The bare specifier last, and only when it is genuinely a file.
169
+ return fsx.isFile(base) ? base : null
170
+ }
171
+
172
+ /**
173
+ * Resolve one identifier — the shared body of both resolvers.
174
+ *
175
+ * `factory` is the inline-declaration call this entry may legally be written
176
+ * as (`defineModule` / `defineCognet`); written inline, the source IS the
177
+ * config file itself.
178
+ */
179
+ export async function resolveBinding(opts: {
180
+ element: TsNamespace.Expression
181
+ imports: Map<string, string>
182
+ configDir: string
183
+ configFilePath: string
184
+ configNames: readonly string[]
185
+ factory: string
186
+ /** What to call this in an error — "module" / "cognet". */
187
+ label: string
188
+ }): Promise<ResolvedDeclaration> {
189
+ const { element, imports, configDir, configFilePath, configNames, factory, label } = opts
190
+
191
+ // "registry-name"
192
+ if (tsc().isStringLiteral(element)) {
193
+ return { kind: "registry", name: element.text }
194
+ }
195
+
196
+ // Ident (imported binding)
197
+ if (tsc().isIdentifier(element)) {
198
+ const specifier = imports.get(element.text)
199
+ if (!specifier) {
200
+ return {
201
+ kind: "unresolved",
202
+ detail: `${label} "${element.text}" is not a default import — a source ${label} must be imported from its ${configNames[0]}`,
203
+ }
204
+ }
205
+
206
+ if (!isRelativeSpecifier(specifier)) {
207
+ return { kind: "registry", name: packageOf(specifier) }
208
+ }
209
+
210
+ const path = await resolveSpecifier(specifier, configDir, configNames)
211
+ if (!path) {
212
+ return { kind: "unresolved", detail: `cannot resolve ${label} import "${specifier}" from ${configFilePath}` }
213
+ }
214
+ return { kind: "source", configPath: path }
215
+ }
216
+
217
+ // defineX({ ... }) written inline — the source IS this config file.
218
+ if (
219
+ tsc().isCallExpression(element) &&
220
+ tsc().isIdentifier(element.expression) &&
221
+ element.expression.text === factory
222
+ ) {
223
+ return { kind: "source", configPath: configFilePath }
224
+ }
225
+
226
+ return { kind: "unresolved", detail: `unrecognised ${label} entry — use an imported ${label} or a registry name` }
227
+ }
228
+
229
+ /** The directory a resolved source declaration lives in. */
230
+ export function sourceDirOf(resolved: Extract<ResolvedDeclaration, { kind: "source" }>): string {
231
+ return dirname(resolved.configPath)
232
+ }
@@ -0,0 +1,61 @@
1
+ /**
2
+ * declare-worker — the ONLY thing this process does: run declareTools()
3
+ * over one directory's tool files and report the result on stdout as
4
+ * JSON, then exit. ts.createProgram() (module resolution + type-checking)
5
+ * is native, single-threaded compiler work with no cooperative yield
6
+ * points — inline, it freezes VTerm's render/input loop for the whole
7
+ * call (commonly 500ms-1.5s cold). Spawned as a subprocess instead, same
8
+ * reasoning and shape as bundle-worker.ts.
9
+ *
10
+ * Contract: argv[2] is a JSON-encoded string[] of absolute tool file
11
+ * paths. Prints exactly one JSON line to stdout — { ok: true, files: [[path,
12
+ * DeclaredFile], ...] } on success, { ok: false, message } on failure —
13
+ * then exits 0 either way, same non-exit-code-signals-failure reasoning
14
+ * as bundle-worker.ts.
15
+ */
16
+ import { declareTools } from "./declare"
17
+
18
+ /** One request → one JSON line, in the shape the caller parses. */
19
+ function declare(raw: string): string {
20
+ try {
21
+ const fileNames = JSON.parse(raw) as string[]
22
+ const declared = declareTools(fileNames)
23
+ return JSON.stringify({ ok: true, files: [...declared.entries()] })
24
+ } catch (error) {
25
+ const message = error instanceof Error ? (error.stack ?? error.message) : String(error)
26
+ return JSON.stringify({ ok: false, message })
27
+ }
28
+ }
29
+
30
+ /**
31
+ * SERVE MODE — `declare-worker --serve`, one request per stdin line.
32
+ *
33
+ * Same contract per line as the one-shot form, and it exists for one reason:
34
+ * declareTools() parses TypeScript's entire standard library to build its
35
+ * program, which is ~1.0s of the ~1.0s a small scan costs. That parse is
36
+ * cached per PROCESS (see declare.ts), so a process that answers once throws
37
+ * the cache away and the next scan pays it again. Staying alive turns the
38
+ * second and every later request into ~0.07s.
39
+ *
40
+ * Worth it because scanning several roots in one run is the normal case, not
41
+ * an edge: an agent scans its own tools plus one root per installed module.
42
+ * Exits when stdin closes, so the worker cannot outlive the caller that
43
+ * spawned it.
44
+ */
45
+ if (process.argv[2] === "--serve") {
46
+ for await (const line of console) {
47
+ const request = line.trim()
48
+ if (!request) continue
49
+ console.log(declare(request))
50
+ }
51
+ process.exit(0)
52
+ }
53
+
54
+ const raw = process.argv[2]
55
+ if (!raw) {
56
+ console.log(JSON.stringify({ ok: false, message: "declare-worker: no file list given" }))
57
+ process.exit(0)
58
+ }
59
+
60
+ console.log(declare(raw))
61
+ process.exit(0)