@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,200 @@
1
+ import { existsSync, readdirSync } from "node:fs"
2
+ import { rm } from "node:fs/promises"
3
+ import { homedir } from "node:os"
4
+ import { join } from "node:path"
5
+ import { rcompare, valid } from "semver"
6
+
7
+ /**
8
+ * ExtensionStore — fetched extensions, shared by every profile on the machine.
9
+ *
10
+ * ── Why not per profile ─────────────────────────────────────────────────────
11
+ *
12
+ * A registry extension is an ARTIFACT: source, a generated type frame, and a
13
+ * `node_modules` holding `@arcforge/types` and `@types/bun`. Nothing in it
14
+ * depends on the profile that fetched it — the frame is generated from the
15
+ * contract, and the tsconfig `extends` out of the extension's own
16
+ * node_modules, which travels with it.
17
+ *
18
+ * So a copy per profile was a full `bun install` and a `prepare()` per profile
19
+ * for identical bytes. Profiles now REFERENCE what the machine holds, which is
20
+ * the same shape `~/.axon/models/` already uses for weights: one copy, many
21
+ * consumers, "so ten agents share one copy of a 150MB model".
22
+ *
23
+ * ── Keyed by version, not content ───────────────────────────────────────────
24
+ *
25
+ * `<scope>/<name>/<version>/`. A model weight is content-addressed because its
26
+ * hash IS its identity and nobody thinks in versions; an extension is the
27
+ * opposite — the version is exactly what a user reasons about, and it is what
28
+ * `profile.config.ts` pins. Content-addressing would only dedup identical
29
+ * bytes across versions, which is worth nothing here.
30
+ *
31
+ * Versioned also means two profiles can hold DIFFERENT versions at once
32
+ * without either silently changing under the other. That is the property a
33
+ * shared store has to have to be safe.
34
+ *
35
+ * ── Local extensions never come here ────────────────────────────────────────
36
+ *
37
+ * A path entry (`./themes`) is the user's own source: it changes as they edit
38
+ * it, hot reload watches it in place, and copying it into a shared store would
39
+ * make the copy the thing that loads. Only registry entries are stored.
40
+ */
41
+
42
+ type ExtensionStoreOpts = {
43
+ /** Override the store root. Tests point this at a scratch dir. */
44
+ root?: string
45
+ }
46
+
47
+ /** One stored extension. */
48
+ export type StoredExtension = {
49
+ /** Scoped registry name — "@cody/ember-theme". */
50
+ name: string
51
+ version: string
52
+ /** Absolute path to its directory — what the loader imports from. */
53
+ root: string
54
+ }
55
+
56
+ function defaultRoot(): string {
57
+ return process.env.AXON_EXTENSIONS_DIR ?? join(homedir(), ".axon", "cache", "extensions")
58
+ }
59
+
60
+ /**
61
+ * Split "@cody/ember-theme@0.1.0" into its name and version.
62
+ *
63
+ * The leading `@` of a scope is not a separator, so the version delimiter is
64
+ * the LAST `@` — and only when it is not at position zero. A bare name returns
65
+ * a null version, which is what an unpinned entry looks like.
66
+ */
67
+ export function parseRef(ref: string): { name: string; version: string | null } {
68
+ const at = ref.lastIndexOf("@")
69
+ if (at <= 0) return { name: ref, version: null }
70
+ return { name: ref.slice(0, at), version: ref.slice(at + 1) }
71
+ }
72
+
73
+ /** The inverse of parseRef. */
74
+ export function formatRef(name: string, version: string): string {
75
+ return `${name}@${version}`
76
+ }
77
+
78
+ export function ExtensionStore(opts: ExtensionStoreOpts = {}) {
79
+ const root = opts.root ?? defaultRoot()
80
+
81
+ /** Where a given name+version lives. Pure — no I/O. */
82
+ function pathFor(name: string, version: string): string {
83
+ return join(root, ...name.split("/"), version)
84
+ }
85
+
86
+ /** A directory is a usable extension when it carries the marker config. */
87
+ function isUsable(dir: string): boolean {
88
+ return existsSync(join(dir, "extension.config.ts"))
89
+ }
90
+
91
+ return {
92
+ get root() {
93
+ return root
94
+ },
95
+
96
+ pathFor,
97
+ isUsable,
98
+
99
+ /**
100
+ * Every version of `name` present, NEWEST FIRST.
101
+ *
102
+ * Ordered by semver, not lexically. It was lexical, defended as "a
103
+ * list that is almost always one element long" — and that assumption
104
+ * dies the moment a user updates twice: `"0.10.0" < "0.9.0"` as
105
+ * strings, so an unpinned entry resolved to the OLDER copy and stayed
106
+ * there. `semver` is already a dependency of this package (see
107
+ * services/update), so the comparator costs an import.
108
+ *
109
+ * A directory whose name is not valid semver is DROPPED rather than
110
+ * sorted to one end. Only an install writes these, and it writes the
111
+ * version the registry resolved — so a non-semver directory is
112
+ * something else that got in, and guessing where it belongs in a
113
+ * version order is how a stray folder becomes "the newest version".
114
+ *
115
+ * Prereleases are ORDERED, not excluded. npm hides them from a range
116
+ * because a range is a standing request that must not drift onto
117
+ * unstable ground; this list only ever answers an unpinned entry,
118
+ * which is the legacy shape. Nothing in publishing produces a
119
+ * prerelease today, so the only way one is present is that a user
120
+ * pinned it deliberately — and a pinned ref never reaches here.
121
+ * Excluding them would mean an explicitly fetched version silently
122
+ * failing to resolve.
123
+ */
124
+ versions(name: string): string[] {
125
+ const dir = join(root, ...name.split("/"))
126
+ if (!existsSync(dir)) return []
127
+ return readdirSync(dir, { withFileTypes: true })
128
+ .filter(entry => entry.isDirectory() && isUsable(join(dir, entry.name)))
129
+ .map(entry => entry.name)
130
+ .filter(version => valid(version) !== null)
131
+ .sort(rcompare)
132
+ },
133
+
134
+ /**
135
+ * Resolve a ref to what is on disk, or null.
136
+ *
137
+ * A pinned ref resolves to exactly that version or to nothing — never
138
+ * to a neighbour, because silently loading a version the config does
139
+ * not name is how a pinned config stops meaning anything.
140
+ *
141
+ * An unpinned ref takes the newest present. That is the legacy shape,
142
+ * kept working so a config written before pinning still loads.
143
+ */
144
+ resolve(ref: string): StoredExtension | null {
145
+ const { name, version } = parseRef(ref)
146
+
147
+ if (version) {
148
+ const dir = pathFor(name, version)
149
+ return isUsable(dir) ? { name, version, root: dir } : null
150
+ }
151
+
152
+ // versions() is newest-first, so the newest IS the first.
153
+ const newest = this.versions(name)[0]
154
+ if (!newest) return null
155
+ return { name, version: newest, root: pathFor(name, newest) }
156
+ },
157
+
158
+ /** Every stored extension, for `axon ext prune` and diagnostics. */
159
+ list(): StoredExtension[] {
160
+ if (!existsSync(root)) return []
161
+
162
+ const out: StoredExtension[] = []
163
+ // Two levels for a scoped name (@cody/theme), one for a bare one.
164
+ for (const outer of readdirSync(root, { withFileTypes: true })) {
165
+ if (!outer.isDirectory()) continue
166
+ const outerPath = join(root, outer.name)
167
+
168
+ if (outer.name.startsWith("@")) {
169
+ for (const inner of readdirSync(outerPath, { withFileTypes: true })) {
170
+ if (!inner.isDirectory()) continue
171
+ const name = `${outer.name}/${inner.name}`
172
+ for (const version of this.versions(name)) {
173
+ out.push({ name, version, root: pathFor(name, version) })
174
+ }
175
+ }
176
+ continue
177
+ }
178
+
179
+ for (const version of this.versions(outer.name)) {
180
+ out.push({ name: outer.name, version, root: pathFor(outer.name, version) })
181
+ }
182
+ }
183
+ return out
184
+ },
185
+
186
+ /**
187
+ * Delete one stored version.
188
+ *
189
+ * Deliberately NOT what uninstall calls. Uninstalling from a profile
190
+ * only undeclares — another profile may be loading the same copy, and
191
+ * removing it would break a terminal the user was not touching.
192
+ * Reclaiming disk is its own explicit act.
193
+ */
194
+ async remove(name: string, version: string): Promise<void> {
195
+ await rm(pathFor(name, version), { recursive: true, force: true })
196
+ },
197
+ }
198
+ }
199
+
200
+ export type ExtensionStoreT = ReturnType<typeof ExtensionStore>
@@ -0,0 +1,145 @@
1
+ import { mkdirSync } from "node:fs"
2
+ import { join } from "node:path"
3
+
4
+ /**
5
+ * Where a project's generated output lives.
6
+ *
7
+ * This stage owns one thing: the shape of the dot-directory every project
8
+ * kind keeps its generated files in. It is deliberately the lowest layer in
9
+ * `build/` — it imports nothing, so both `blueprint/` (whose tool scanner
10
+ * caches into the frame) and `project/` (which writes almost everything else
11
+ * there) can depend on it without either depending on the other. That
12
+ * direction is the package's rule: blueprint uses neither of its siblings.
13
+ *
14
+ * `kinds.ts` made the frame's NAME data (`spec.dir` — ".agent", ".module",
15
+ * …). This makes its INTERIOR data too, for the same reason: every generated
16
+ * file needs a home that is decided once, not re-derived by whichever writer
17
+ * happens to need it. Before this, twenty call sites built
18
+ * `join(root, ".agent", …)` by hand and the frame was a flat pile — type
19
+ * declarations, tool caches, a Dockerfile and a tarball all as siblings, with
20
+ * nothing but a filename to say which was regenerable.
21
+ *
22
+ * That distinction is the whole point of the grouping:
23
+ *
24
+ * types/ generated .d.ts + tsconfigs — regenerable
25
+ * cache/ tool caches, module lock — regenerable, disposable
26
+ * build/ Dockerfile, image.json, tarball — regenerable
27
+ * cognet/ the compiled brain — regenerable, but PINNED (see below)
28
+ * data/ sessions, state, sensory — NOT regenerable. user history.
29
+ *
30
+ * Everything except `data/` can be deleted and rebuilt by `axon prepare`,
31
+ * which is what makes the migration in `migrate.ts` safe to write as
32
+ * delete-and-regenerate rather than a careful move.
33
+ */
34
+ export const FRAME = {
35
+ types: "types",
36
+ cache: "cache",
37
+ build: "build",
38
+ cognet: "cognet",
39
+ data: "data",
40
+ } as const
41
+
42
+ export type FrameArea = keyof typeof FRAME
43
+
44
+ /**
45
+ * The set of project kinds — DEFINED here, and re-exported by `kinds.ts` as
46
+ * `ProjectKind` for every existing caller.
47
+ *
48
+ * It lives at this layer because a kind's frame is the one thing every stage
49
+ * needs to know about it. `kinds.ts` owns the kind TABLE (config filenames,
50
+ * scaffolders, bundlers) and pulls in every scaffolder to build it, so
51
+ * importing it from here would drag all of `project/` into `blueprint/` —
52
+ * the exact dependency this stage exists to avoid. The union itself carries
53
+ * no such weight, so it sits at the bottom where both sides can reach it.
54
+ */
55
+ export type ProjectKind = "agent" | "module" | "cognet" | "bench" | "prompt" | "extension" | "profile"
56
+
57
+ /**
58
+ * Frame directory names that are NOT the kind's own name dotted.
59
+ *
60
+ * A profile's frame is `.axon`, not `.profile`. The directory a user sees at
61
+ * `~/.axon/profiles/<email>/` is the one place the product's own name means
62
+ * something to them — it is their Axon folder, not an implementation detail of
63
+ * a project kind they never chose. Every other kind derives (see below), and
64
+ * this map exists so that stays true for all of them but one.
65
+ */
66
+ const FRAME_DIRS: Partial<Record<ProjectKind, string>> = {
67
+ profile: ".axon",
68
+ }
69
+
70
+ type FrameOpts = {
71
+ root: string
72
+ kind: ProjectKind
73
+ }
74
+
75
+ /**
76
+ * Frame — where a project's generated output lives.
77
+ *
78
+ * One handle per project root, resolving every interior path. Callers ask for
79
+ * an area and get a path; they never spell the frame directory or a
80
+ * subfolder name themselves. A new area is a row in FRAME, not a new
81
+ * `join()` at a call site.
82
+ *
83
+ * `ensure()` is separate from the path getters on purpose: reading a path is
84
+ * free and side-effect-free (a bundler asking "where would this go" must not
85
+ * create directories), while the writers that actually need the directory
86
+ * call `ensure()` at the moment they write.
87
+ */
88
+ export function Frame(opts: FrameOpts) {
89
+ // The frame directory is the kind's own name, dotted — .agent, .module,
90
+ // .cognet, .bench, .prompt. Derived rather than stored: `kinds.ts` used to
91
+ // carry a `dir` field that repeated the kind name back, which is a second
92
+ // copy of the same fact and therefore a thing that can drift. FRAME_DIRS
93
+ // holds the one kind that cannot derive (profile → .axon).
94
+ const name = FRAME_DIRS[opts.kind] ?? `.${opts.kind}`
95
+ const dir = join(opts.root, name)
96
+
97
+ function area(name: FrameArea): string {
98
+ return join(dir, FRAME[name])
99
+ }
100
+
101
+ function ensure(name: FrameArea): string {
102
+ const path = area(name)
103
+ mkdirSync(path, { recursive: true })
104
+ return path
105
+ }
106
+
107
+ return {
108
+ /** The frame directory itself — `<root>/.agent`. */
109
+ get dir() { return dir },
110
+
111
+ /** The frame directory's name, with its leading dot — ".agent". */
112
+ get name() { return name },
113
+
114
+ /** Resolve an area's path without touching disk. */
115
+ path: area,
116
+
117
+ /** Resolve an area's path, creating it if absent. */
118
+ ensure: ensure,
119
+
120
+ /** A file inside an area, without touching disk. */
121
+ file(name: FrameArea, filename: string): string {
122
+ return join(area(name), filename)
123
+ },
124
+ }
125
+ }
126
+
127
+ export type FrameT = ReturnType<typeof Frame>
128
+
129
+ /**
130
+ * The frame-relative path of the compiled brain, as it appears INSIDE a
131
+ * published bundle.
132
+ *
133
+ * Pinned deliberately, and the one interior path that is not free to move:
134
+ * `bundle/agent.ts` writes this exact string into the shipped
135
+ * `manifest.json`, and a deployed container resolves the brain through it. A
136
+ * layout change here does not break a rebuild — it breaks agents that are
137
+ * already running in production, which no amount of re-preparing on this
138
+ * machine can fix.
139
+ *
140
+ * It matches the local layout today (`.agent/cognet/`) and must keep
141
+ * matching. If the local frame ever moves the brain, this stays put and the
142
+ * bundle staging step becomes an explicit remap rather than a copy — see
143
+ * `stageCognet()`.
144
+ */
145
+ export const BUNDLE_COGNET_DIR = "cognet"
@@ -0,0 +1,5 @@
1
+ // frame — where a project's generated output lives, and converting projects
2
+ // that still use the old flat layout.
3
+
4
+ export { Frame, FRAME, BUNDLE_COGNET_DIR, type FrameT, type FrameArea, type ProjectKind } from "./frame"
5
+ export { migrateFrame, type FrameMigration } from "./migrate"
@@ -0,0 +1,246 @@
1
+ import { readdir, rename, rm, mkdir, cp } from "node:fs/promises"
2
+ import { dirname, join } from "node:path"
3
+ import { err } from "@arcforge/err"
4
+ import { fsx } from "../../utils/fs"
5
+ import { Frame, type ProjectKind } from "./frame"
6
+
7
+ /**
8
+ * Migrating a project from the flat frame to the grouped one.
9
+ *
10
+ * The old frame was a single flat directory: axon.d.ts, tsconfig.json,
11
+ * tools-declare-cache.json, Dockerfile, image.json and source.tar.gz all
12
+ * siblings. The new one groups them (see FRAME in frame.ts). Every existing
13
+ * project on every developer's machine has the old shape, so `prepare` must
14
+ * convert it — silently, once, and without ever putting user data at risk.
15
+ *
16
+ * The strategy follows from the regenerable/irreplaceable split:
17
+ *
18
+ * REGENERABLE (types, cache, build) — DELETED, not moved. Moving a stale
19
+ * .d.ts leaves it stale; prepare regenerates all of it moments later
20
+ * anyway. Deleting is both simpler and more correct than a careful move.
21
+ *
22
+ * IRREPLACEABLE (data: sessions, state, sensory) — genuinely moved, with
23
+ * the care that implies. Session logs are user history; there is no
24
+ * regenerating them.
25
+ *
26
+ * Everything here is idempotent and safe to interrupt. A migration killed
27
+ * halfway leaves a project that is partly converted, and re-running finishes
28
+ * the job — which is why directories move one at a time, each with its own
29
+ * move-then-delete, rather than as one bulk operation.
30
+ */
31
+
32
+ /**
33
+ * Files the OLD flat frame wrote directly into `.agent/`.
34
+ *
35
+ * Listed explicitly rather than "delete everything that is not a known
36
+ * directory": the frame is created by us but lives in the user's project, and
37
+ * a blanket delete of unrecognized files is how a tool destroys something it
38
+ * did not put there. Anything not on this list is left alone.
39
+ */
40
+ const FLAT_TYPES = [
41
+ "axon.d.ts",
42
+ "axon-test.d.ts",
43
+ "axon-test.tsconfig.json",
44
+ "tsconfig.json",
45
+ "globals.d.ts",
46
+ "tool-globals.d.ts",
47
+ "prompts.d.ts",
48
+ "scripts.d.ts",
49
+ "components.d.ts",
50
+ "env.d.ts",
51
+ "hooks.d.ts",
52
+ ]
53
+
54
+ const FLAT_CACHE = [
55
+ "tools-declare-cache.json",
56
+ "tools-bundle-cache.json",
57
+ ]
58
+
59
+ const FLAT_BUILD = [
60
+ "Dockerfile",
61
+ ".dockerignore",
62
+ "image.json",
63
+ "source.tar.gz",
64
+ "manifest.json",
65
+ "axon.manifest.json",
66
+ ]
67
+
68
+ /**
69
+ * The module lock — the one regenerable file worth moving rather than
70
+ * deleting. Technically prepare can rebuild it, but doing so forces a full
71
+ * re-link of every source module, so the cheap move is the kinder default.
72
+ */
73
+ const LOCK_FILE = "source-modules.lock.json"
74
+
75
+ /** Runtime output directories that move from `<root>/data` into the frame. */
76
+ const DATA_DIRS = ["sessions", "state", "sensory"]
77
+
78
+ /**
79
+ * Whether a project still has the old flat frame.
80
+ *
81
+ * Keyed on a generated TYPE declaration sitting directly in the frame root.
82
+ * That file is written by every framed kind and only ever by typegen, so its
83
+ * presence at the top level is unambiguous evidence of the old layout — as
84
+ * opposed to `Dockerfile` or `image.json`, which only some kinds ever write
85
+ * and which a user could plausibly have put there.
86
+ */
87
+ function isFlat(frameDir: string): boolean {
88
+ return FLAT_TYPES.some(name => fsx.exists(join(frameDir, name)))
89
+ || FLAT_CACHE.some(name => fsx.exists(join(frameDir, name)))
90
+ }
91
+
92
+ /** Delete a list of files from the flat frame. Absent files are already migrated. */
93
+ async function discard(frameDir: string, names: string[]): Promise<number> {
94
+ let removed = 0
95
+ for (const name of names) {
96
+ const path = join(frameDir, name)
97
+ if (!fsx.exists(path)) continue
98
+ await rm(path, { recursive: true, force: true })
99
+ removed += 1
100
+ }
101
+ return removed
102
+ }
103
+
104
+ /**
105
+ * Move one directory, preferring rename and falling back to copy+delete.
106
+ *
107
+ * `rename` is atomic but fails with EXDEV when source and target sit on
108
+ * different filesystems — which is the normal case when a project root is a
109
+ * bind mount or a container volume. The fallback is copy-then-delete IN THAT
110
+ * ORDER: an interrupt between the two leaves both copies, which re-running
111
+ * resolves, whereas delete-first would lose the data outright.
112
+ */
113
+ async function moveDir(from: string, to: string): Promise<void> {
114
+ await mkdir(dirname(to), { recursive: true })
115
+ try {
116
+ await rename(from, to)
117
+ return
118
+ } catch (error) {
119
+ const code = error instanceof Error && "code" in error ? error.code : null
120
+ if (code !== "EXDEV") throw error
121
+ }
122
+
123
+ await cp(from, to, { recursive: true })
124
+ await rm(from, { recursive: true, force: true })
125
+ }
126
+
127
+ /**
128
+ * Move runtime output from `<root>/data/*` into `<root>/.agent/data/*`.
129
+ *
130
+ * `data/knowledge` is deliberately NOT in DATA_DIRS: it is author-owned
131
+ * source that gets committed, and it stays at the project root. That split is
132
+ * the point of the whole move — after it, everything under the frame is
133
+ * disposable and everything the user wrote is outside it.
134
+ *
135
+ * Merges entry by entry, and refuses only on a real collision.
136
+ *
137
+ * The destination is routinely non-empty by the time this runs, and NOT
138
+ * because anything went wrong: the runtime opens its build-log session at the
139
+ * new path before `prepare` is called, so the very act of running `axon
140
+ * prepare` on an unmigrated agent creates `.agent/data/sessions/<id>.jsonl`
141
+ * first. Treating a populated destination as a conflict therefore failed
142
+ * every agent that had ever run — the one case this most needed to handle.
143
+ *
144
+ * So the unit of conflict is a NAME, not a directory. Sessions are UUIDs and
145
+ * state files are namespaced, so the two sides are disjoint in practice and
146
+ * the merge is exact. A genuine same-name collision on both sides is the only
147
+ * thing that cannot be resolved without choosing whose history to discard,
148
+ * and that still throws having moved nothing.
149
+ */
150
+ async function migrateData(root: string, frameDataDir: string): Promise<string[]> {
151
+ const legacyRoot = join(root, "data")
152
+ if (!fsx.exists(legacyRoot)) return []
153
+
154
+ const moved: string[] = []
155
+ for (const name of DATA_DIRS) {
156
+ const from = join(legacyRoot, name)
157
+ if (!fsx.exists(from)) continue
158
+
159
+ const to = join(frameDataDir, name)
160
+ if (!fsx.exists(to)) {
161
+ await moveDir(from, to)
162
+ moved.push(name)
163
+ continue
164
+ }
165
+
166
+ // Both sides exist. Check every entry BEFORE moving any of them, so a
167
+ // refusal leaves the tree exactly as it was found.
168
+ const incoming = await readdir(from)
169
+ const existing = new Set(await readdir(to))
170
+ const collisions = incoming.filter(entry => existing.has(entry))
171
+ if (collisions.length > 0) {
172
+ throw err("FRAME_MIGRATION_CONFLICT", {
173
+ detail: `${name}/ has ${collisions.length} entr${collisions.length === 1 ? "y" : "ies"} `
174
+ + `in both ${legacyRoot} and ${frameDataDir}: ${collisions.slice(0, 5).join(", ")}`,
175
+ context: { from, to, root, collisions },
176
+ })
177
+ }
178
+
179
+ for (const entry of incoming) {
180
+ await moveDir(join(from, entry), join(to, entry))
181
+ }
182
+ await rm(from, { recursive: true, force: true })
183
+ moved.push(name)
184
+ }
185
+
186
+ // Only if nothing is left. `data/knowledge` keeps the directory alive for
187
+ // most agents, and an unexpected leftover is the user's file, not ours.
188
+ if ((await readdir(legacyRoot)).length === 0) {
189
+ await rm(legacyRoot, { recursive: true, force: true })
190
+ }
191
+
192
+ return moved
193
+ }
194
+
195
+ export type FrameMigration = {
196
+ /** Whether anything was converted. False means the project was already current. */
197
+ migrated: boolean
198
+ /** Regenerable files discarded — prepare rewrites them in this same run. */
199
+ discarded: number
200
+ /** Runtime output directories physically moved into the frame. */
201
+ dataMoved: string[]
202
+ }
203
+
204
+ /**
205
+ * Convert a project's frame to the grouped layout, if it isn't already.
206
+ *
207
+ * Runs at the top of `prepare`, before typegen writes anything, so the
208
+ * regenerable files it discards are rebuilt in the same run and the project
209
+ * is never left without its types.
210
+ */
211
+ export async function migrateFrame(root: string, kind: ProjectKind): Promise<FrameMigration> {
212
+ const frame = Frame({ root: root, kind: kind })
213
+
214
+ // A project with no frame at all is new, not old — nothing to convert.
215
+ if (!fsx.exists(frame.dir)) {
216
+ return { migrated: false, discarded: 0, dataMoved: [] }
217
+ }
218
+
219
+ const flat = isFlat(frame.dir)
220
+
221
+ let discarded = 0
222
+ if (flat) {
223
+ discarded += await discard(frame.dir, FLAT_TYPES)
224
+ discarded += await discard(frame.dir, FLAT_CACHE)
225
+ discarded += await discard(frame.dir, FLAT_BUILD)
226
+
227
+ const lock = join(frame.dir, LOCK_FILE)
228
+ if (fsx.exists(lock)) {
229
+ await mkdir(frame.path("cache"), { recursive: true })
230
+ await moveDir(lock, frame.file("cache", LOCK_FILE))
231
+ }
232
+ }
233
+
234
+ // Independent of the flat check: an agent can have been through a
235
+ // types/cache/build migration already and still hold runtime output at
236
+ // the old path, and a project that never had a frame still might.
237
+ const dataMoved = kind === "agent"
238
+ ? await migrateData(root, frame.path("data"))
239
+ : []
240
+
241
+ return {
242
+ migrated: flat || dataMoved.length > 0,
243
+ discarded: discarded,
244
+ dataMoved: dataMoved,
245
+ }
246
+ }