@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,249 @@
1
+ import { readFileSync } from "node:fs"
2
+ import { dirname, join } from "node:path"
3
+ import { err } from "@arcforge/err"
4
+ import { fsx } from "../../../utils/fs"
5
+ import { Frame } from "../../frame"
6
+ import type { CognetBlueprint } from "@arcforge/types"
7
+ import type { CognetArtifact } from "./bundle"
8
+ import type { ScanWarning } from "../types"
9
+ import type { ResolvedDeclaration } from "../scan/configImports"
10
+ import { bundleCognet } from "./bundle"
11
+ import { readManifest } from "./manifest"
12
+ import { DEFAULT_COGNET, resolveCognet } from "./resolve"
13
+
14
+ /** The `sourceDir` the last compile recorded, or null when unavailable. */
15
+ function readManifestSourceDir(root: string): string | null {
16
+ try {
17
+ const raw = readFileSync(Frame({ root: root, kind: "agent" }).file("cognet", "manifest.json"), "utf8")
18
+ const parsed = JSON.parse(raw) as { sourceDir?: unknown }
19
+ return typeof parsed.sourceDir === "string" ? parsed.sourceDir : null
20
+ } catch {
21
+ // No manifest, or one written before sourceDir was recorded. Both mean
22
+ // "unknown", which the caller handles — never a guess.
23
+ return null
24
+ }
25
+ }
26
+
27
+ type CognetOpts = {
28
+ /** Agent root — the directory containing axon.config.ts. */
29
+ root: string
30
+ }
31
+
32
+ /**
33
+ * Where a brain comes from — the two forms a declaration resolves to.
34
+ *
35
+ * A registry cognet is installed into node_modules and found by name; a source
36
+ * cognet is a directory on disk. Both end at the same place (a directory
37
+ * bundleCognet() compiles), but only one of them can be looked up, so they must
38
+ * not both be a bare string.
39
+ *
40
+ * A source cognet arrives two ways: an author imports its config from anywhere
41
+ * on disk, or they write one INLINE at `<agent>/cognet/` and declare nothing.
42
+ * Both produce `kind: "source"` — where the directory sits is not a fact the
43
+ * rest of the pipeline should have to know.
44
+ */
45
+ export type CognetSource =
46
+ | { kind: "registry"; specifier: string }
47
+ | { kind: "source"; dir: string }
48
+
49
+ /**
50
+ * The folder an agent writes its own brain in.
51
+ *
52
+ * A cognet here needs no `cognet:` line: the directory existing IS the
53
+ * declaration, the same way `src/tools/` needs no `tools:` list. That is the
54
+ * point of inlining — an agent with a bespoke brain should read as one
55
+ * project, not as two that happen to reference each other.
56
+ */
57
+ export const INLINE_COGNET_DIR = "cognet"
58
+
59
+ /**
60
+ * The inline cognet's directory, if the agent has one.
61
+ *
62
+ * Recognized by its ENTRY, not by a config file: `cognet.config.ts` is
63
+ * optional for an inline brain (identity comes from the agent — see
64
+ * bundleCognet), so requiring it here would make the smallest possible
65
+ * cognet, a lone `cognet/main.ts` holding a `loop()`, invisible to every
66
+ * stage that asks this question.
67
+ */
68
+ export function inlineCognetDir(agentRoot: string): string | null {
69
+ const dir = join(agentRoot, INLINE_COGNET_DIR)
70
+ const hasEntry = fsx.isFile(join(dir, "main.ts")) || fsx.isFile(join(dir, "src", "main.ts"))
71
+ return hasEntry ? dir : null
72
+ }
73
+
74
+ /**
75
+ * A loaded config's cognet declaration as a CognetSource.
76
+ *
77
+ * The one place the evaluated value, the statically-resolved path, and the
78
+ * inline `cognet/` folder are reconciled, so no caller has to know that a
79
+ * string means "registry", an object means "look at cognetPath", and a
80
+ * directory on disk means "compile that". Returns undefined when the agent
81
+ * declared nothing at all — it tracks the registry default, which is not the
82
+ * same as declaring it.
83
+ *
84
+ * Declaring BOTH is an error, not a precedence question. An agent has one
85
+ * brain; a `cognet:` line beside a populated `cognet/` folder states two, and
86
+ * every way of resolving that silently is worse than saying so. Picking the
87
+ * explicit one ignores a whole directory of source the author wrote and will
88
+ * keep editing; picking the folder overrules what they typed. Neither is
89
+ * guessable from the outside, so this throws and names both.
90
+ *
91
+ * `unresolved` throws rather than falling back: an author who wrote an import
92
+ * the build cannot follow has a broken config, and quietly compiling @axon/zero
93
+ * instead would hide it behind a brain that runs.
94
+ */
95
+ export function cognetSourceOf(config: {
96
+ /** Agent root — how an inline `cognet/` is seen. Carried by LoadedConfig. */
97
+ root: string
98
+ value: { cognet?: unknown }
99
+ cognetPath: ResolvedDeclaration | null
100
+ }): CognetSource | undefined {
101
+ const declared = config.value.cognet
102
+ const inline = inlineCognetDir(config.root)
103
+
104
+ // Nothing written: the folder speaks for itself, or the agent tracks the
105
+ // registry default.
106
+ if (declared === undefined) {
107
+ return inline ? { kind: "source", dir: inline } : undefined
108
+ }
109
+
110
+ if (inline) {
111
+ throw err("COGNET_AMBIGUOUS", {
112
+ detail: `this agent declares cognet: in axon.config.ts AND has an inline cognet at ${inline} — `
113
+ + "an agent has one brain. Remove the cognet: line to use the folder, "
114
+ + "or delete/rename the folder to use the declaration.",
115
+ context: { root: config.root, inline, declared },
116
+ })
117
+ }
118
+
119
+ if (typeof declared === "string") {
120
+ return { kind: "registry", specifier: declared }
121
+ }
122
+
123
+ // An imported binding — the path is only knowable statically.
124
+ const resolved = config.cognetPath
125
+ if (resolved?.kind === "source") {
126
+ return { kind: "source", dir: dirname(resolved.configPath) }
127
+ }
128
+ if (resolved?.kind === "registry") {
129
+ return { kind: "registry", specifier: resolved.name }
130
+ }
131
+
132
+ throw err("COGNET_NOT_FOUND", {
133
+ detail: resolved?.detail
134
+ ?? "cognet: was given a value that is neither a registry name nor a resolvable source import",
135
+ })
136
+ }
137
+
138
+ /**
139
+ * Cognet — the agent's brain, from declared specifier to loadable artifact.
140
+ *
141
+ * Owns the whole toolchain: resolve the specifier to installed source,
142
+ * compile it into .agent/cognet/, and read back the manifest the blueprint
143
+ * carries.
144
+ *
145
+ * Compilation lives HERE, behind load(), because a blueprint is not complete
146
+ * without a compiled brain — scan reads the manifest that compilation writes.
147
+ * That ordering used to be every caller's job to remember: prepare, the dev
148
+ * reload, and the bench preload each called bundleCognet() and then
149
+ * Blueprint.load() on the next line, and a caller that forgot got a silently
150
+ * stale brain rather than an error. Two verbs with a mandatory order are one
151
+ * verb.
152
+ */
153
+ export function Cognet(opts: CognetOpts) {
154
+ const root = opts.root
155
+
156
+ /**
157
+ * The source the last compile() resolved.
158
+ *
159
+ * A source cognet's directory is only knowable by statically resolving the
160
+ * config's import, which needs the config FILE — and a caller holding just
161
+ * the evaluated blueprint (the dev watcher) has no way back to it. Rather
162
+ * than thread the resolution through every consumer, the toolchain that
163
+ * did the resolving remembers it.
164
+ */
165
+ let compiled: CognetSource | undefined
166
+
167
+ /**
168
+ * Where this agent's brain source lives, for a caller that wants to watch
169
+ * or compile it.
170
+ *
171
+ * Takes the config's declared cognet in either form: a registry specifier
172
+ * resolves through node_modules, while an already-resolved source
173
+ * directory is passed straight back. Callers hold `CognetSource` rather
174
+ * than a bare string so the two origins cannot be confused — a source path
175
+ * fed to the registry resolver would fail with a spelling-mistake error.
176
+ *
177
+ * With NO source, an inline `cognet/` is checked before falling back to
178
+ * the registry default. Callers reach this path when they hold a blueprint
179
+ * but not the config it came from (the dev watcher), and for an inline
180
+ * agent the default would be flatly wrong — it would resolve @axon/zero
181
+ * and watch a directory in node_modules while the author edits their own
182
+ * brain and sees nothing reload.
183
+ */
184
+ function sourceDir(source?: CognetSource): string {
185
+ if (source?.kind === "source") return source.dir
186
+ if (!source) {
187
+ const inline = inlineCognetDir(root)
188
+ if (inline) return inline
189
+ }
190
+ return resolveCognet(source?.specifier ?? DEFAULT_COGNET, root)
191
+ }
192
+
193
+ return {
194
+ sourceDir: sourceDir,
195
+
196
+ /**
197
+ * Compile the declared cognet into .agent/cognet/.
198
+ *
199
+ * Idempotent and content-gated by bundleCognet() itself — an unchanged
200
+ * source recompiles to the same hash and rewrites nothing.
201
+ */
202
+ async compile(source?: CognetSource): Promise<CognetArtifact> {
203
+ compiled = source
204
+ const dir = sourceDir(source)
205
+ return bundleCognet({
206
+ sourceDir: dir,
207
+ agentRoot: root,
208
+ // Compared by path rather than trusting the source's kind: an
209
+ // inline brain can also arrive as an explicit `source` (a
210
+ // watcher re-resolving one), and what relaxes the config
211
+ // requirement is WHERE it lives, not how it was named.
212
+ inline: dir === inlineCognetDir(root),
213
+ })
214
+ },
215
+
216
+ /**
217
+ * The source directory of the brain this agent last compiled — what a
218
+ * dev watcher needs in order to rebuild on edit.
219
+ *
220
+ * Read from the manifest the compile WROTE, not from in-memory state:
221
+ * the watcher is built from a different Cognet() instance than the one
222
+ * prepare compiled with, so `compiled` is unset there. It used to fall
223
+ * back to resolving DEFAULT_COGNET, which meant an agent running any
224
+ * other brain failed at boot with "@axon/zero is declared but not
225
+ * present" — naming a cognet nothing had ever declared.
226
+ *
227
+ * Null when nothing has been compiled yet; a caller that cannot watch
228
+ * a brain that does not exist should skip rather than guess.
229
+ */
230
+ get compiledFrom(): string | null {
231
+ if (compiled) return sourceDir(compiled)
232
+ const recorded = readManifestSourceDir(root)
233
+ return recorded && fsx.exists(recorded) ? recorded : null
234
+ },
235
+
236
+ /**
237
+ * The compiled brain as the blueprint carries it (path + hash).
238
+ *
239
+ * A missing or dangling manifest is a warning with an absent entry,
240
+ * never a throw: core's normalizer refuses loudly (NO_COGNET) at the
241
+ * one seam that should own that message.
242
+ */
243
+ async read(): Promise<{ entry: CognetBlueprint | null; warnings: ScanWarning[] }> {
244
+ return readManifest(root)
245
+ },
246
+ }
247
+ }
248
+
249
+ export type CognetT = ReturnType<typeof Cognet>
@@ -0,0 +1,10 @@
1
+ // cognet — the agent's brain: resolve a specifier, compile it, read it back.
2
+ // Cognet() is the module's single entry point.
3
+
4
+ export { Cognet, cognetSourceOf, inlineCognetDir, INLINE_COGNET_DIR, type CognetT, type CognetSource } from "./cognet"
5
+ export type { CognetArtifact } from "./bundle"
6
+ export { DEFAULT_COGNET, cognetName } from "./resolve"
7
+
8
+ // The ABI gate. prepare() compares a cognet against this kernel; publish
9
+ // records the declared value on the version row without comparing.
10
+ export { cognetAbi, readCognetAbi, readCognetModels, readCognetEngines } from "./abi"
@@ -0,0 +1,38 @@
1
+ import { isAbsolute, join, resolve } from "node:path"
2
+ import type { CognetBlueprint } from "@arcforge/types"
3
+ import { fsx } from "../../../utils/fs"
4
+ import { Frame } from "../../frame"
5
+ import type { ScanWarning } from "../types"
6
+
7
+ type ManifestShape = CognetBlueprint & { path: string; hash: string }
8
+
9
+ /**
10
+ * readManifest — reads the brain slot the compile step wrote:
11
+ * <agent>/.agent/cognet/manifest.json → blueprint.cognet (path+hash form).
12
+ *
13
+ * A reader, never a builder: bundling belongs to prepare/dev. Missing
14
+ * manifest = warning + absent field — core's normalizer then refuses
15
+ * loudly (NO_COGNET), so an unprepared agent fails at the one seam with
16
+ * one message, not here with a second.
17
+ */
18
+ export async function readManifest(root: string): Promise<{ entry: CognetBlueprint | null; warnings: ScanWarning[] }> {
19
+ const manifestPath = Frame({ root: root, kind: "agent" }).file("cognet", "manifest.json")
20
+ const manifest = await fsx.readJson<ManifestShape>(manifestPath)
21
+
22
+ if (!manifest) {
23
+ return {
24
+ entry: null,
25
+ warnings: [{ domain: "cognet", error: `no compiled cognet at ${manifestPath} — run \`axon prepare\`` }],
26
+ }
27
+ }
28
+
29
+ const artifactPath = isAbsolute(manifest.path) ? manifest.path : resolve(root, manifest.path)
30
+ if (!fsx.exists(artifactPath)) {
31
+ return {
32
+ entry: null,
33
+ warnings: [{ domain: "cognet", error: `cognet manifest points at a missing bundle: ${artifactPath} — run \`axon prepare\`` }],
34
+ }
35
+ }
36
+
37
+ return { entry: { ...manifest, path: artifactPath }, warnings: [] }
38
+ }
@@ -0,0 +1,113 @@
1
+ import { dirname, join, resolve } from "node:path"
2
+ import { err } from "@arcforge/err"
3
+ import { fsx } from "../../../utils/fs"
4
+
5
+ /**
6
+ * Cognet specifier → source project directory.
7
+ *
8
+ * A cognet is an ordinary registry artifact installed as an ordinary package:
9
+ * `cognet: "@axon/zero"` in axon.config.ts becomes a package.json dependency,
10
+ * Bun fetches it through the registry's npm surface, and it lands in
11
+ * node_modules like anything else. This function is the last step — finding
12
+ * the installed source tree so bundleCognet() can compile it.
13
+ *
14
+ * It used to resolve against a directory shipped inside the CLI bundle, which
15
+ * meant exactly one cognet existed and it could only ever be the one the CLI
16
+ * was built with. The old comment here predicted this change: "when cognets
17
+ * become installable, the install target resolves HERE and nothing else in
18
+ * the pipeline moves." That is what happened — bundleCognet() is unchanged.
19
+ *
20
+ * The default is @axon/zero, published like any other cognet and installed
21
+ * like any other dependency. There is deliberately no bundled fallback: a
22
+ * cognet the agent declares but has not installed is a prepare-time error,
23
+ * never a silent substitution of something else.
24
+ */
25
+ export const DEFAULT_COGNET = "@axon/zero"
26
+
27
+ /**
28
+ * The dangling symlink standing where a package should be, if that is why it
29
+ * did not resolve.
30
+ *
31
+ * Grafted projects hold one symlink per top-level entry, pointing into the
32
+ * machine-wide tree cache. When that cache evicts the tree, every link goes
33
+ * dangling at once and the package reads as simply absent — which is true but
34
+ * deeply misleading, because the manifest is correct and the user changed
35
+ * nothing.
36
+ */
37
+ function danglingLink(agentRoot: string, name: string): { link: string; target: string } | null {
38
+ // The scope directory is what gets linked ("@axon"), not the package
39
+ // inside it, so that is where a broken graft shows up.
40
+ const [scope] = name.split("/")
41
+ let dir = resolve(agentRoot)
42
+ while (true) {
43
+ for (const candidate of [join(dir, "node_modules", ...name.split("/")), join(dir, "node_modules", scope!)]) {
44
+ const target = fsx.readLink(candidate)
45
+ if (target && !fsx.exists(target)) return { link: candidate, target }
46
+ }
47
+ const parent = dirname(dir)
48
+ if (parent === dir) return null
49
+ dir = parent
50
+ }
51
+ }
52
+
53
+ /**
54
+ * Walk up from the agent root looking for the installed package, the way a
55
+ * module resolver would — an agent inside a workspace resolves against the
56
+ * workspace's node_modules, not only its own.
57
+ */
58
+ export function resolveCognet(specifier: string, agentRoot: string): string {
59
+ const name = cognetName(specifier)
60
+
61
+ let dir = resolve(agentRoot)
62
+ while (true) {
63
+ const candidate = join(dir, "node_modules", ...name.split("/"))
64
+ if (fsx.exists(join(candidate, "cognet.config.ts"))) return candidate
65
+ const parent = dirname(dir)
66
+ if (parent === dir) break
67
+ dir = parent
68
+ }
69
+
70
+ // A DANGLING link is a different fact from an absent package, and blaming
71
+ // the user's config for it sends them looking for a typo that is not
72
+ // there. It means node_modules was grafted onto a shared cache tree that
73
+ // has since been deleted — machine state, nothing to do with the manifest.
74
+ //
75
+ // Reported separately because the remedy is different too: a missing
76
+ // package is fixed by declaring or installing it, while this is fixed by
77
+ // reinstalling, and no amount of editing axon.config.ts will touch it.
78
+ const dangling = danglingLink(agentRoot, name)
79
+ if (dangling) {
80
+ throw err("COGNET_NOT_FOUND", {
81
+ detail:
82
+ `cognet "${name}" is installed but its files are gone: ${dangling.link} points at ` +
83
+ `${dangling.target}, which no longer exists.\n` +
84
+ `This is a stale node_modules, not a problem with your config — the shared dependency ` +
85
+ `cache it was linked into has been cleared.\n` +
86
+ `Fix: delete node_modules and run \`axon prepare\`.`,
87
+ context: { specifier, name, agentRoot, link: dangling.link, target: dangling.target },
88
+ })
89
+ }
90
+
91
+ // Deliberately does NOT say "run axon prepare": prepare is what resolves
92
+ // the cognet, so this message is usually printed BY prepare, and telling
93
+ // someone to run the command that just failed is a dead end. State what
94
+ // was looked for and where — the reconcile step is what makes this
95
+ // reachable-but-absent case self-healing, and if it still surfaces, the
96
+ // useful fact is the path that was searched.
97
+ throw err("COGNET_NOT_FOUND", {
98
+ detail: `cognet "${name}" is declared but not present in node_modules under ${agentRoot}`,
99
+ context: { specifier, name, agentRoot },
100
+ })
101
+ }
102
+
103
+ /** "@axon/zero@1.2.0" → "@axon/zero". The version range is Bun's concern, not ours. */
104
+ export function cognetName(specifier: string): string {
105
+ if (!specifier.startsWith("@")) {
106
+ throw err("COGNET_NOT_FOUND", {
107
+ detail: `"${specifier}" is not a scoped cognet name — expected @scope/name`,
108
+ context: { specifier },
109
+ })
110
+ }
111
+ const at = specifier.indexOf("@", 1)
112
+ return at === -1 ? specifier : specifier.slice(0, at)
113
+ }
@@ -0,0 +1,51 @@
1
+ import type { ScanWarning } from "./types"
2
+
3
+ /**
4
+ * Merge named surfaces with precedence: the agent always wins, then modules
5
+ * in declaration order (first wins). Losers are skipped and reported —
6
+ * a shadowed prompt is a warning the CLI shows, not a silent disappearance.
7
+ */
8
+ export function merge<T extends { name: string }>(
9
+ surface: string,
10
+ agent: T[],
11
+ modules: Array<{ owner: string; entries: T[] }>,
12
+ ): { merged: T[]; warnings: ScanWarning[] } {
13
+ const merged: T[] = []
14
+ const warnings: ScanWarning[] = []
15
+ const owners = new Map<string, string>()
16
+
17
+ // The agent's own entries can collide with each other — two files in
18
+ // src/tools/ both exporting `search`. Precedence cannot resolve that: there
19
+ // is no "winner" rule between two files the same author wrote, and letting
20
+ // both through would render two declarations of one global. First wins, and
21
+ // the duplicate is reported so the author knows one of their exports is not
22
+ // reachable.
23
+ for (const entry of agent) {
24
+ if (owners.has(entry.name)) {
25
+ warnings.push({
26
+ domain: surface,
27
+ error: `"${entry.name}" is declared more than once by the agent — only the first is used`,
28
+ })
29
+ continue
30
+ }
31
+ owners.set(entry.name, "agent")
32
+ merged.push(entry)
33
+ }
34
+
35
+ for (const group of modules) {
36
+ for (const entry of group.entries) {
37
+ const owner = owners.get(entry.name)
38
+ if (owner) {
39
+ warnings.push({
40
+ domain: surface,
41
+ error: `"${entry.name}" from module "${group.owner}" shadowed by ${owner === "agent" ? "the agent" : `module "${owner}"`} — skipped`,
42
+ })
43
+ continue
44
+ }
45
+ owners.set(entry.name, group.owner)
46
+ merged.push(entry)
47
+ }
48
+ }
49
+
50
+ return { merged, warnings }
51
+ }
@@ -0,0 +1,29 @@
1
+ // blueprint — agent directory in, AxonPartialBlueprint out.
2
+ // Blueprint() is the module's single entry point.
3
+
4
+ export { Blueprint, type BlueprintT, type BlueprintResult } from "./blueprint"
5
+ export type { Scanned, ScanWarning } from "./types"
6
+
7
+ // Standalone scanners for consumers outside the blueprint composition
8
+ // (typegen needs components; dev tooling may scan single domains).
9
+ export { Components, type PromptComponent } from "./scan/components"
10
+
11
+ // The config authority — Project.prepare reads declared modules through the
12
+ // same loader Blueprint composes with. One implementation, promoted on purpose.
13
+ export { Config, withProviderGlobals, type LoadedConfig } from "./scan/config"
14
+
15
+ // The brain toolchain. prepare() gates a cognet's ABI before compiling it;
16
+ // publish() records the declared abi on the version row.
17
+ export { Cognet, cognetSourceOf, inlineCognetDir, INLINE_COGNET_DIR, type CognetT, type CognetSource, type CognetArtifact, DEFAULT_COGNET, cognetName, cognetAbi, readCognetAbi, readCognetModels, readCognetEngines } from "./cognet"
18
+ export { flatten, sourceRoot, type NormalisedEntry } from "./modules/entries"
19
+
20
+ /**
21
+ * The authored server surface, re-scannable agent-side.
22
+ *
23
+ * Routes, middleware and plugins are the three things the blueprint carries
24
+ * as FUNCTIONS, which is why the agent has to rebuild them rather than
25
+ * receive them — see rehydrateServer in link/agent-main.ts.
26
+ */
27
+ export { Routes } from "./scan/routes"
28
+ export { Middleware } from "./scan/middleware"
29
+ export { Plugins } from "./scan/plugins"
@@ -0,0 +1,117 @@
1
+ import { dirname } from "node:path"
2
+ import type { ModuleConfig, ModuleEntry } from "@arcforge/types"
3
+ import { resolveModulePaths, type ResolvedModulePath } from "../scan/moduleImports"
4
+
5
+ /**
6
+ * Declared-entry normalisation. A ModuleEntry in axon.config.ts is one of:
7
+ * "name" · ModuleConfig · ["name", opts] · [ModuleConfig, opts]
8
+ * Everything downstream works with the canonical two-kind form.
9
+ *
10
+ * A source module's identity is its `configPath` — the absolute path to its
11
+ * module.config.ts, resolved STATICALLY from the import that declared it (see
12
+ * scan/moduleImports). It is threaded in positionally: `modulePaths[i]`
13
+ * corresponds to the i-th entry of the config's `modules: [...]` array.
14
+ * `defineModule()` no longer stamps a path, so this is the only source of one.
15
+ */
16
+ export type NormalisedEntry =
17
+ | { kind: "registry"; name: string; options: Record<string, unknown> }
18
+ | { kind: "source"; config: ModuleConfig; configPath: string; options: Record<string, unknown> }
19
+
20
+ function options(entry: ModuleEntry): Record<string, unknown> {
21
+ if (Array.isArray(entry)) {
22
+ const [, opts] = entry as [unknown, Record<string, unknown>]
23
+ return opts ?? {}
24
+ }
25
+ return {}
26
+ }
27
+
28
+ function payload(entry: ModuleEntry): string | ModuleConfig {
29
+ if (Array.isArray(entry)) return (entry as [string | ModuleConfig, unknown])[0]
30
+ return entry as string | ModuleConfig
31
+ }
32
+
33
+ /**
34
+ * Flatten entries, expanding sub-modules declared inside source configs.
35
+ * Depth-first, sub before parent (dependencies available before the parent
36
+ * boots).
37
+ *
38
+ * DEDUPE APPLIES TO DEPENDENCIES, NOT TO DECLARATIONS. Two modules that each
39
+ * depend on `@axon/fs` must yield one fs — that is what the dedupe is for,
40
+ * and it still holds. But an agent listing the same module twice at the TOP
41
+ * LEVEL is stating intent: two screens is two capture feeds, two cameras is
42
+ * two eyes. Collapsing those silently dropped the second one and gave no
43
+ * indication why the second monitor never appeared.
44
+ *
45
+ * So: a repeated dependency collapses, a repeated declaration does not.
46
+ * Nobody writes the same module twice at the top level by accident.
47
+ *
48
+ * The platform deliberately does NOT invent an identity for the copies. What
49
+ * distinguishes two screens is the output name, and only the module knows
50
+ * that — so every instance's options reach the module's plugin (via
51
+ * `axon.modules.all()`) and the module derives its own channels from them.
52
+ *
53
+ * Source paths arrive positionally for the TOP-LEVEL entries. A nested source
54
+ * module's imports live in its OWN module.config.ts, so its children's paths
55
+ * are resolved lazily from that file when we descend into it.
56
+ */
57
+ export async function flatten(entries: ModuleEntry[], modulePaths: ResolvedModulePath[]): Promise<NormalisedEntry[]> {
58
+ const seen = new Set<string>()
59
+ const result: NormalisedEntry[] = []
60
+
61
+ /**
62
+ * `depth > 0` means we are walking a module's declared dependencies,
63
+ * where a repeat is redundancy. At depth 0 it is the agent's own list,
64
+ * where a repeat is a request for another instance.
65
+ */
66
+ async function walk(list: ModuleEntry[], paths: ResolvedModulePath[], depth = 0) {
67
+ for (let i = 0; i < list.length; i++) {
68
+ const entry = list[i]!
69
+ const resolved = paths[i]
70
+ const raw = payload(entry)
71
+ const opts = options(entry)
72
+
73
+ // Registry: a bare string entry, OR an imported config whose
74
+ // specifier resolved to a node_modules package (a registry module
75
+ // reached by importing its config rather than naming it).
76
+ if (typeof raw === "string") {
77
+ if (depth > 0 && seen.has(raw)) continue
78
+ seen.add(raw)
79
+ result.push({ kind: "registry", name: raw, options: opts })
80
+ continue
81
+ }
82
+ if (resolved?.kind === "registry") {
83
+ if (depth > 0 && seen.has(resolved.name)) continue
84
+ seen.add(resolved.name)
85
+ result.push({ kind: "registry", name: resolved.name, options: opts })
86
+ continue
87
+ }
88
+
89
+ // Source: an imported (or inline) ModuleConfig whose specifier is
90
+ // relative. Its path is the statically-resolved configPath; an
91
+ // unresolved entry is dropped here and surfaced as a warning by
92
+ // Modules().
93
+ const config = raw
94
+ const configPath = resolved?.kind === "source" ? resolved.configPath : undefined
95
+ if (!configPath) continue
96
+
97
+ // Descend into this source module's own declared sub-modules,
98
+ // resolving THEIR paths from this module.config.ts.
99
+ if (config.modules?.length) {
100
+ const childPaths = await resolveModulePaths(configPath)
101
+ await walk(config.modules, childPaths, depth + 1)
102
+ }
103
+
104
+ if (depth > 0 && seen.has(configPath)) continue
105
+ seen.add(configPath)
106
+ result.push({ kind: "source", config, configPath, options: opts })
107
+ }
108
+ }
109
+
110
+ await walk(entries, modulePaths)
111
+ return result
112
+ }
113
+
114
+ /** The directory a source entry's module.config.ts lives in. */
115
+ export function sourceRoot(entry: Extract<NormalisedEntry, { kind: "source" }>): string {
116
+ return dirname(entry.configPath)
117
+ }