@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,14 @@
1
+ import type { BenchResolvedWorkspaceDefinition } from "@arcforge/types"
2
+ import { prepareWorkspaceTemplate } from "./files"
3
+
4
+ export function Workspace(opts: { root: string; definition: BenchResolvedWorkspaceDefinition }) {
5
+ let prepared: Awaited<ReturnType<typeof prepareWorkspaceTemplate>> | undefined
6
+ return {
7
+ async prepare() {
8
+ prepared ??= await prepareWorkspaceTemplate(opts.root, opts.definition)
9
+ return prepared
10
+ },
11
+ }
12
+ }
13
+
14
+ export type WorkspaceT = ReturnType<typeof Workspace>
@@ -0,0 +1,398 @@
1
+ import { createHash } from "node:crypto"
2
+ import { join } from "node:path"
3
+ import type { AxonPartialBlueprint, EngineRequirements } from "@arcforge/types"
4
+ import { err } from "@arcforge/err"
5
+ import { fsx } from "../../utils/fs"
6
+ import { merge } from "./collisions"
7
+ import { Config } from "./scan/config"
8
+ import { Modules } from "./modules"
9
+ import { Boot } from "./scan/boot"
10
+ import { Plugins } from "./scan/plugins"
11
+ import { Prompts } from "./scan/prompts"
12
+ import { Knowledge } from "./scan/knowledge"
13
+ import { Routes } from "./scan/routes"
14
+ import { Middleware } from "./scan/middleware"
15
+ import { Scripts } from "./scan/scripts"
16
+ import { Tools } from "./scan/tools"
17
+ import { Cognet, cognetSourceOf, readCognetModels, readCognetEngines, type CognetT } from "./cognet"
18
+ import { Models } from "../project/models"
19
+ import { Frame } from "../frame"
20
+ import type { LoadedConfig } from "./scan/config"
21
+ import type { ScanWarning } from "./types"
22
+
23
+ type BlueprintOpts = {
24
+ /** Agent root — the directory containing axon.config.ts. */
25
+ root: string
26
+ }
27
+
28
+ export type BlueprintResult = {
29
+ blueprint: AxonPartialBlueprint
30
+ warnings: ScanWarning[]
31
+ }
32
+
33
+ /**
34
+ * Blueprint — turns an agent directory into the AxonPartialBlueprint that
35
+ * core's normalizer accepts. Pure composition: Config loads the authored
36
+ * truth (throws when broken), scanners discover the surfaces (warn when
37
+ * degraded), Modules runs the same scanners per module root, collisions
38
+ * merge with agent-wins precedence.
39
+ *
40
+ * Knows a root directory — not projects, not auth, not deployment.
41
+ */
42
+ export function Blueprint(opts: BlueprintOpts) {
43
+ const root = opts.root
44
+ const cognet = Cognet({ root: root })
45
+
46
+ let current: AxonPartialBlueprint | null = null
47
+
48
+ return {
49
+ get current(): AxonPartialBlueprint {
50
+ if (!current) throw err("BLUEPRINT_NOT_LOADED")
51
+ return current
52
+ },
53
+
54
+ /** The brain toolchain for this root — a caller that watches its source needs sourceDir(). */
55
+ cognet: cognet,
56
+
57
+ /**
58
+ * Scan the directory into an AxonPartialBlueprint.
59
+ *
60
+ * `compile` recompiles the brain first. Off by default: a plain read
61
+ * (typegen, a status view) must not spawn a bundler. On for anything
62
+ * that will BOOT the result — prepare, a dev reload — because the scan
63
+ * reads the manifest compilation writes, so skipping it there silently
64
+ * yields the previous brain.
65
+ */
66
+ async load(loadOpts: {
67
+ compile?: boolean
68
+ /**
69
+ * Resolved model paths — local name → absolute path.
70
+ *
71
+ * Optional because the blueprint resolves them itself when not
72
+ * given: `axon dev` boots through a path that never ran prepare's
73
+ * resolution, so requiring the caller to supply them meant the
74
+ * runtime silently handed the brain an empty map. Prepare still
75
+ * passes them, since it has already done the work and a second
76
+ * resolve would be wasted.
77
+ *
78
+ * Resolution here is cache-only in practice — prepare fetched and
79
+ * verified anything missing, and a boot that had to download would
80
+ * be a boot that should have failed at prepare.
81
+ */
82
+ models?: Readonly<Record<string, string>>
83
+ /**
84
+ * The machine-wide policy CEILING, from the profile that owns this
85
+ * agent. Every capability an agent declares is bounded by it, and
86
+ * an agent can only ever narrow within it.
87
+ *
88
+ * Supplied by the caller rather than read here, for the same
89
+ * reason `models` can be: this module knows a root directory, not
90
+ * profiles, not auth, not deployment. Reading a profile would give
91
+ * it an opinion about which user is running — and a deployment,
92
+ * which has no profile at all, would need that opinion to be
93
+ * conditional. The caller knows; this carries.
94
+ *
95
+ * Absent means no ceiling, which is the honest state for a
96
+ * deployment and for `axon run` outside a profile.
97
+ */
98
+ profilePolicy?: AxonPartialBlueprint["profilePolicy"]
99
+ /**
100
+ * The inference sources the owning profile declares.
101
+ *
102
+ * Carried, never read here, for exactly the reason above: this
103
+ * module knows a directory, not which user is running. A blueprint
104
+ * travels, and a deployment has no profile at all — so baking one
105
+ * machine's Ollama daemon in would describe a localhost that is not
106
+ * there.
107
+ */
108
+ profileProviders?: AxonPartialBlueprint["profileProviders"]
109
+ } = {}): Promise<BlueprintResult> {
110
+ const warnings: ScanWarning[] = []
111
+
112
+ // Authored truth — a broken config is no agent. Throws.
113
+ const config = await Config(root)
114
+
115
+ // `engine:` is deprecated and READ BY NOTHING. Warn rather than
116
+ // throw for the window: an agent carrying it already boots on the
117
+ // profile pool, so failing now would break working agents to tell
118
+ // them about a field that was being ignored anyway. The warning is
119
+ // the only signal an author gets that their declared model is not
120
+ // the one running.
121
+ if ("engine" in config.value && config.value.engine !== undefined) {
122
+ const cause = err("CONFIG_ENGINE_DEPRECATED", { context: { root } })
123
+ warnings.push({ domain: "config", error: cause.message, cause })
124
+ }
125
+
126
+ // Before the scan, never after: Cognet.read() below reads exactly
127
+ // what this writes.
128
+ if (loadOpts.compile) await cognet.compile(cognetSourceOf(config))
129
+
130
+ // Agent surfaces + modules, in parallel.
131
+ const [prompts, scripts, tools, routes, plugins, middleware, knowledge, boot, modules, brain] = await Promise.all([
132
+ Prompts(root),
133
+ Scripts(root),
134
+ Tools(root),
135
+ Routes(root),
136
+ Plugins(root),
137
+ Middleware(root),
138
+ Knowledge(root),
139
+ Boot(root),
140
+ Modules({ root, declared: config.modules, modulePaths: config.modulePaths }),
141
+ cognet.read(),
142
+ ])
143
+ for (const scanned of [prompts, scripts, tools, routes, plugins, middleware, knowledge]) warnings.push(...scanned.warnings)
144
+ warnings.push(...boot.warnings, ...modules.warnings, ...brain.warnings)
145
+
146
+ // Merge module surfaces under agent-wins precedence.
147
+ const groups = modules.surfaces.map(s => ({ owner: s.name, entries: s }))
148
+ const mergedPrompts = merge(
149
+ "prompts",
150
+ prompts.entries,
151
+ groups.map(g => ({ owner: g.owner, entries: g.entries.prompts })),
152
+ )
153
+ const mergedScripts = merge("scripts", scripts.entries, groups.map(g => ({ owner: g.owner, entries: g.entries.scripts })))
154
+ const mergedTools = merge("tools", tools.entries, groups.map(g => ({ owner: g.owner, entries: g.entries.tools })))
155
+ warnings.push(...mergedPrompts.warnings, ...mergedScripts.warnings, ...mergedTools.warnings)
156
+
157
+ /**
158
+ * Knowledge appends rather than merging, because a module's
159
+ * entries were namespaced by the scanner that found them —
160
+ * `@axon/docs/agent.md` cannot collide with the agent's own
161
+ * `agent.md`, so there is no precedence question to resolve.
162
+ *
163
+ * That is the opposite call from prompts and tools, which share a
164
+ * flat namespace and need agent-wins. Here the collision was
165
+ * designed out instead of adjudicated: two corpora on the same
166
+ * subject is the normal case, and one silently shadowing the other
167
+ * would be the model told it can read a file it never gets.
168
+ */
169
+ const mergedKnowledge = [...knowledge.entries, ...modules.surfaces.flatMap(s => s.knowledge)]
170
+
171
+ // Module routes append after agent routes — server mounts first-wins.
172
+ const moduleRoutes = modules.surfaces.flatMap(s => s.routes)
173
+
174
+ // Module plugins run after agent plugins, in module declaration
175
+ // order — same shape as routes: one merged, origin-blind list the
176
+ // server applies.
177
+ const modulePlugins = modules.surfaces.flatMap(s => s.plugins)
178
+
179
+ // Module middleware runs AFTER the agent's own, in module
180
+ // declaration order. The agent author's gate goes first: a module
181
+ // cannot slip a handler ahead of an auth check the agent wrote,
182
+ // and cannot short-circuit a request before that check runs.
183
+ const moduleMiddleware = modules.surfaces.flatMap(s => s.middleware)
184
+
185
+ // Weights: whatever the caller resolved, or resolve them here.
186
+ // A brain that declared models and received none is broken in a
187
+ // way that only shows up at first inference.
188
+ const models = loadOpts.models ?? await resolveDeclaredModels(cognet, config)
189
+
190
+ // The roles this brain needs, read from its own config at build
191
+ // time so the runtime can resolve them BEFORE loading the bundle.
192
+ // A required role nothing can fill has to stop the boot, and a
193
+ // brain that has already loaded is one that will reach for a
194
+ // missing engine mid-wake.
195
+ const engines = await resolveDeclaredEngines(cognet, config)
196
+
197
+ const agent = await identity(root)
198
+
199
+ const blueprint: AxonPartialBlueprint = {
200
+ agent,
201
+ ...("boot" in boot ? { boot: boot.boot } : {}),
202
+ ...("bootFilePath" in boot ? { bootFilePath: boot.bootFilePath } : {}),
203
+ config: config.value,
204
+ ...(loadOpts.profilePolicy ? { profilePolicy: loadOpts.profilePolicy } : {}),
205
+ ...(loadOpts.profileProviders?.length ? { profileProviders: loadOpts.profileProviders } : {}),
206
+ // absent = unprepared agent; core's normalizer refuses loudly (NO_COGNET)
207
+ ...(brain.entry
208
+ ? {
209
+ cognet: {
210
+ ...brain.entry,
211
+ ...(Object.keys(models).length ? { models } : {}),
212
+ ...(Object.keys(engines).length ? { engines } : {}),
213
+ },
214
+ }
215
+ : {}),
216
+ env: await resolvedEnv(root),
217
+ // The supervisor's own credentials — read from the host here,
218
+ // where the CLI legitimately owns process.env, and deliberately
219
+ // NOT merged into `env`, which is what reaches the box.
220
+ hostEnv: hostEnv(),
221
+ tools: mergedTools.merged,
222
+ prompts: mergedPrompts.merged,
223
+ scripts: mergedScripts.merged,
224
+ knowledge: mergedKnowledge,
225
+ modules: modules.modules,
226
+ server: {
227
+ routes: [...routes.entries, ...moduleRoutes],
228
+ middleware: [...middleware.entries, ...moduleMiddleware],
229
+ plugins: [...plugins.entries, ...modulePlugins],
230
+ },
231
+ paths: {
232
+ root,
233
+ // Runtime output lives in the frame — see the note on
234
+ // paths.data in core's AxonBlueprint().
235
+ data: Frame({ root: root, kind: "agent" }).path("data"),
236
+ },
237
+ }
238
+
239
+ current = blueprint
240
+ return { blueprint, warnings }
241
+ },
242
+ }
243
+ }
244
+
245
+ export type BlueprintT = ReturnType<typeof Blueprint>
246
+
247
+ /**
248
+ * The cognet's declared weights, resolved to absolute paths.
249
+ *
250
+ * Reads the same textual declaration prepare does, then resolves through the
251
+ * shared cache. In the ordinary case everything is already there and this is
252
+ * pure filesystem work — prepare fetched and verified it. A cognet that
253
+ * declares nothing costs one file read.
254
+ */
255
+ async function resolveDeclaredModels(
256
+ cognet: CognetT,
257
+ config: LoadedConfig,
258
+ ): Promise<Readonly<Record<string, string>>> {
259
+ let sourceDir: string
260
+ try {
261
+ sourceDir = cognet.sourceDir(cognetSourceOf(config))
262
+ } catch {
263
+ // No resolvable cognet source — the missing-brain error belongs to
264
+ // the normalizer, not here.
265
+ return {}
266
+ }
267
+
268
+ const declared = await readCognetModels(sourceDir)
269
+ if (Object.keys(declared).length === 0) return {}
270
+
271
+ const { paths } = await Models().resolve(declared)
272
+ return paths
273
+ }
274
+
275
+ /**
276
+ * The `engines:` a cognet declares, or none.
277
+ *
278
+ * Mirrors resolveDeclaredModels exactly, including its silence when the
279
+ * source cannot be located: a missing brain is the normalizer's error to
280
+ * raise, and reporting it twice from two layers would only make the first
281
+ * one wrong.
282
+ */
283
+ async function resolveDeclaredEngines(
284
+ cognet: CognetT,
285
+ config: LoadedConfig,
286
+ ): Promise<EngineRequirements> {
287
+ try {
288
+ return await readCognetEngines(cognet.sourceDir(cognetSourceOf(config)))
289
+ } catch {
290
+ return {}
291
+ }
292
+ }
293
+
294
+ // ─── Identity ─────────────────────────────────────────────────────────────────
295
+
296
+ /** name/version from package.json (required — an agent is a package), hash from sources. */
297
+ async function identity(root: string) {
298
+ const text = await fsx.readText(join(root, "package.json"))
299
+ if (text === null) {
300
+ throw err("AGENT_INVALID", { detail: `no package.json at ${root}`, context: { root } })
301
+ }
302
+ const pkg = JSON.parse(text) as { name?: string; version?: string }
303
+
304
+ return {
305
+ name: pkg.name ?? root.split("/").pop()!,
306
+ version: pkg.version ?? "0.0.0",
307
+ hash: { type: "sha256" as const, value: await sourceHash(root) },
308
+ }
309
+ }
310
+
311
+ /** Deterministic hash over the agent's authored sources. */
312
+ async function sourceHash(root: string): Promise<string> {
313
+ const hash = createHash("sha256")
314
+
315
+ const files = [
316
+ join(root, "axon.config.ts"),
317
+ join(root, "package.json"),
318
+ ...(await fsx.walk(join(root, "src"))).map(f => f.absPath),
319
+ ]
320
+
321
+ for (const file of files.sort()) {
322
+ const content = await fsx.readText(file)
323
+ if (content !== null) {
324
+ hash.update(file)
325
+ hash.update(content)
326
+ }
327
+ }
328
+
329
+ return hash.digest("hex")
330
+ }
331
+
332
+ // ─── Environment ──────────────────────────────────────────────────────────────
333
+
334
+ /**
335
+ * The one place process.env is read. The runtime, capsule, server, and
336
+ * engine all consume blueprint.env — never process.env directly.
337
+ *
338
+ * Agent secrets live in <root>/.env, never in the host shell's env — the
339
+ * TUI process's cwd is not the agent's cwd and must never be assumed to be.
340
+ *
341
+ * ── This is the agent's OWN .env, and nothing else ─────────────────────────
342
+ *
343
+ * It used to be `{ ...process.env }` with the agent's `.env` overlaid on top,
344
+ * which meant the blueprint carried every variable in the invoking shell — and
345
+ * the blueprint is what reaches the agent. An `fs` policy denying `.env` on
346
+ * disk was undone by the same secrets arriving as environment.
347
+ *
348
+ * The host is no longer read here at all. What crosses is decided later, at the
349
+ * one seam that knows the policy (`confine/env.ts`): this file's `.env`, plus
350
+ * whatever `policy.env.allow` explicitly grants. Reading the host here would
351
+ * put the decision above the layer that has the policy to make it.
352
+ */
353
+ /**
354
+ * The host variables the SUPERVISOR needs.
355
+ *
356
+ * An explicit list, never a spread. The whole point of the split is that the
357
+ * host's environment stops here; a `{ ...process.env }` on this side would
358
+ * simply move the leak rather than close it, since the supervisor is the thing
359
+ * holding the credentials.
360
+ */
361
+ function hostEnv(): Record<string, string> {
362
+ const wanted = [
363
+ "AXON_API_KEY",
364
+ "AXON_CONNECT_TOKEN",
365
+ "AXON_API_BASE",
366
+ "AXON_JWT_PUBLIC_KEY",
367
+ "AXON_HOME",
368
+ ]
369
+ const out: Record<string, string> = {}
370
+ for (const key of wanted) {
371
+ const value = process.env[key]
372
+ if (value !== undefined) out[key] = value
373
+ }
374
+ return out
375
+ }
376
+
377
+ async function resolvedEnv(root: string): Promise<Record<string, string>> {
378
+ const content = await fsx.readText(join(root, ".env"))
379
+ return content ? parseDotenv(content) : {}
380
+ }
381
+
382
+ /** Parse key=value pairs from a .env file's contents. Comments and blank lines skipped. */
383
+ function parseDotenv(content: string): Record<string, string> {
384
+ const result: Record<string, string> = {}
385
+ for (const line of content.split(/\r?\n/)) {
386
+ const trimmed = line.trim()
387
+ if (!trimmed || trimmed.startsWith("#")) continue
388
+ const eqIdx = trimmed.indexOf("=")
389
+ if (eqIdx < 0) continue
390
+ const key = trimmed.slice(0, eqIdx).trim()
391
+ let val = trimmed.slice(eqIdx + 1).trim()
392
+ if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
393
+ val = val.slice(1, -1)
394
+ }
395
+ if (key) result[key] = val
396
+ }
397
+ return result
398
+ }
@@ -0,0 +1,207 @@
1
+ import { join } from "node:path"
2
+ import { err } from "@arcforge/err"
3
+ import { KERNEL_ABI_VERSION } from "@arcforge/types"
4
+ import type { EngineRequirement, EngineRequirements, Modality } from "@arcforge/types"
5
+ import { fsx } from "../../../utils/fs"
6
+
7
+ /**
8
+ * Verify an installed cognet does not target an ABI this kernel cannot provide.
9
+ *
10
+ * A cognet MAY pin `abi` in cognet.config.ts, and the runtime already checks
11
+ * it when the compiled bundle loads (see core/src/cognet/cognet.ts). That
12
+ * check was sufficient while cognets shipped inside the CLI: the two could
13
+ * not disagree. Now that a cognet is an independently versioned registry
14
+ * artifact, an agent can pin `@axon/zero@0.1.0` against a CLI whose kernel has
15
+ * moved on — and the runtime check fires at agent BOOT, from inside a compiled
16
+ * bundle, long after the mistake was made.
17
+ *
18
+ * This is the same check moved to the moment the pairing is chosen: prepare
19
+ * time, naming both versions and the file to edit.
20
+ *
21
+ * An UNPINNED cognet passes trivially and gets this kernel's ABI. That is not
22
+ * a hole: the bundle is compiled from source by this CLI, against this kernel,
23
+ * so it targets this ABI by construction. A pin exists to make a cognet REFUSE
24
+ * a kernel it has not been validated against — an assertion the author opts
25
+ * into, not a field every cognet must restate.
26
+ *
27
+ * Read with a regex rather than by evaluating the config: this runs before
28
+ * anything has compiled the cognet, and evaluating an arbitrary published
29
+ * config to read one field is a far larger operation than reading the field.
30
+ */
31
+ export async function cognetAbi(sourceDir: string, specifier: string): Promise<string> {
32
+ const declared = await readCognetAbi(sourceDir)
33
+ if (declared === null) return KERNEL_ABI_VERSION
34
+
35
+ if (declared !== KERNEL_ABI_VERSION) {
36
+ throw err("COGNET_ABI_MISMATCH", {
37
+ detail:
38
+ `cognet "${specifier}" pins kernel ABI ${declared}, but this Axon provides ABI ${KERNEL_ABI_VERSION} — `
39
+ + `install a cognet version built for ABI ${KERNEL_ABI_VERSION}, or update Axon`,
40
+ context: { specifier, declaredAbi: declared, kernelAbi: KERNEL_ABI_VERSION },
41
+ })
42
+ }
43
+
44
+ return declared
45
+ }
46
+
47
+ /**
48
+ * The ABI a cognet source project PINS, or null when it pins none.
49
+ *
50
+ * Split out from cognetAbi() because three callers need the value for
51
+ * different reasons: prepare compares a pin against this kernel (cognetAbi),
52
+ * the compile step stamps the resolved value into the artifact, and PUBLISH
53
+ * records it on the version row so the registry can answer "newest cognet that
54
+ * fits ABI N" without downloading a tarball.
55
+ *
56
+ * Publishing must not COMPARE against the publishing machine's kernel — a
57
+ * cognet pinning ABI 10 is perfectly publishable from a CLI running ABI 9, and
58
+ * refusing it would make the registry unable to hold anything but the present.
59
+ * It may still fall back to it, because publish compiles from source with this
60
+ * CLI: an unpinned cognet genuinely was validated against this kernel, so
61
+ * stamping that on the row is a fact rather than a guess.
62
+ *
63
+ * Null, never a throw. An absent pin is the ordinary case — see CognetConfig's
64
+ * `abi` — and every caller has a truthful default: this kernel's ABI.
65
+ */
66
+ export async function readCognetAbi(sourceDir: string): Promise<string | null> {
67
+ const source = await fsx.readText(join(sourceDir, "cognet.config.ts"))
68
+ if (source === null) return null
69
+
70
+ return source.match(/\babi\s*:\s*["'`]([^"'`]+)["'`]/)?.[1] ?? null
71
+ }
72
+
73
+ /**
74
+ * The `models:` a cognet source project declares.
75
+ *
76
+ * Read textually, for the same reason the ABI is: this runs before anything
77
+ * has compiled the cognet, and evaluating an arbitrary published config to
78
+ * read one field is a far larger operation than reading the field. It also
79
+ * runs on a cognet that has not had its dependencies installed yet, where
80
+ * evaluation would fail outright.
81
+ *
82
+ * Deliberately narrow: it matches the `models: { ... }` object literal and
83
+ * pulls `key: "specifier"` pairs out of it. A computed or imported value is
84
+ * not recognised, and that is the honest limit of a textual read — declaring
85
+ * weights is a static fact about a brain, not something a config should be
86
+ * computing.
87
+ */
88
+ export async function readCognetModels(sourceDir: string): Promise<Record<string, string>> {
89
+ const source = await fsx.readText(join(sourceDir, "cognet.config.ts"))
90
+ if (source === null) return {}
91
+
92
+ const block = source.match(/\bmodels\s*:\s*\{([\s\S]*?)\}/)
93
+ if (!block?.[1]) return {}
94
+
95
+ const models: Record<string, string> = {}
96
+ for (const entry of block[1].matchAll(/["'`]?([A-Za-z_$][\w$]*)["'`]?\s*:\s*["'`]([^"'`]+)["'`]/g)) {
97
+ models[entry[1]!] = entry[2]!
98
+ }
99
+ return models
100
+ }
101
+
102
+ /**
103
+ * The `engines:` a cognet source project declares.
104
+ *
105
+ * Read textually, for the same reasons `models:` is: this runs before
106
+ * anything has compiled the cognet and before its dependencies are
107
+ * installed, so evaluating the config is not available even in principle.
108
+ *
109
+ * Unlike `models:`, the value is a map of OBJECTS, so the block cannot be
110
+ * found with a lazy `\{([\s\S]*?)\}` — the first `}` closes the first role,
111
+ * not the map. Braces are matched instead, which is the smallest thing that
112
+ * reads this shape correctly rather than the smallest thing that looks like
113
+ * it does.
114
+ *
115
+ * Declaring inference is a static fact about a brain, exactly like declaring
116
+ * weights: a computed or imported value is not recognised, and that is the
117
+ * honest limit rather than a bug to work around.
118
+ */
119
+ export async function readCognetEngines(sourceDir: string): Promise<EngineRequirements> {
120
+ const source = await fsx.readText(join(sourceDir, "cognet.config.ts"))
121
+ if (source === null) return {}
122
+
123
+ const body = balanced(source, /\bengines\s*:\s*\{/)
124
+ if (body === null) return {}
125
+
126
+ const engines: EngineRequirements = {}
127
+ for (const [role, block] of roles(body)) {
128
+ const requirement = parseRequirement(block)
129
+ if (requirement) engines[role] = requirement
130
+ }
131
+ return engines
132
+ }
133
+
134
+ /** The text inside the first `{...}` following `opener`, with nesting respected. */
135
+ function balanced(source: string, opener: RegExp): string | null {
136
+ const start = source.match(opener)
137
+ if (start?.index === undefined) return null
138
+
139
+ let depth = 0
140
+ const from = start.index + start[0].length - 1
141
+ for (let i = from; i < source.length; i++) {
142
+ if (source[i] === "{") depth++
143
+ else if (source[i] === "}") {
144
+ depth--
145
+ if (depth === 0) return source.slice(from + 1, i)
146
+ }
147
+ }
148
+ return null
149
+ }
150
+
151
+ /** `name: { ... }` pairs at the top level of an engines block. */
152
+ function roles(body: string): Array<[string, string]> {
153
+ const found: Array<[string, string]> = []
154
+ const header = /["'`]?([A-Za-z_$][\w$]*)["'`]?\s*:\s*\{/g
155
+
156
+ for (let match = header.exec(body); match; match = header.exec(body)) {
157
+ const block = balanced(body.slice(match.index), /\{/)
158
+ if (block === null) continue
159
+ found.push([match[1]!, block])
160
+ // Skip past this role's body so a nested key is never read as a role.
161
+ header.lastIndex = match.index + match[0].length + block.length
162
+ }
163
+ return found
164
+ }
165
+
166
+ /**
167
+ * One role's declaration.
168
+ *
169
+ * `type`, `in` and `out` are required — a requirement missing any of them
170
+ * cannot be matched against a capability, so it is DROPPED rather than
171
+ * defaulted. Guessing `text -> text` here would bind a role to a model that
172
+ * cannot serve it, which is the one failure this layer exists to move to
173
+ * prepare time.
174
+ */
175
+ function parseRequirement(block: string): EngineRequirement | null {
176
+ const type = block.match(/\btype\s*:\s*["'`](generate|transform|stream)["'`]/)?.[1]
177
+ if (!type) return null
178
+
179
+ const modality = (field: "in" | "out"): Modality[] => {
180
+ const list = block.match(new RegExp(`\\b${field}\\s*:\\s*\\[([^\\]]*)\\]`))
181
+ if (list?.[1]) {
182
+ return [...list[1].matchAll(/["'`]([a-z]+)["'`]/g)].map(m => m[1] as Modality)
183
+ }
184
+ const single = block.match(new RegExp(`\\b${field}\\s*:\\s*["'\`]([a-z]+)["'\`]`))
185
+ return single?.[1] ? [single[1] as Modality] : []
186
+ }
187
+
188
+ const inputs = modality("in")
189
+ const outputs = modality("out")
190
+ if (inputs.length === 0 || outputs.length === 0) return null
191
+
192
+ // Numeric separators are ordinary in a config (`100_000`), and a parse
193
+ // that read one as 100 would silently admit a model far too small.
194
+ const context = block.match(/\bcontext\s*:\s*([\d_]+)/)?.[1]
195
+ const flag = (name: string): boolean => new RegExp(`\\b${name}\\s*:\\s*true\\b`).test(block)
196
+
197
+ return {
198
+ type: type as EngineRequirement["type"],
199
+ in: inputs,
200
+ out: outputs,
201
+ ...(context ? { context: Number(context.replaceAll("_", "")) } : {}),
202
+ ...(flag("structured") ? { structured: true } : {}),
203
+ ...(flag("parallel") ? { parallel: true } : {}),
204
+ ...(flag("optional") ? { optional: true } : {}),
205
+ ...(flag("primary") ? { primary: true } : {}),
206
+ }
207
+ }