@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,130 @@
1
+ import { join } from "node:path"
2
+ import { Scripts } from "../../blueprint/scan/scripts"
3
+ import { Tools } from "../../blueprint/scan/tools"
4
+ import { fsx } from "../../../utils/fs"
5
+ import { Frame, FRAME } from "../../frame"
6
+ import { Assets } from "./assets"
7
+ import type { ArtifactsT } from "./artifacts"
8
+ import type { StageT } from "./stage"
9
+ import type { BundleResult, ModuleImage } from "./types"
10
+
11
+ type ModuleOpts = {
12
+ root: string
13
+ artifacts: ArtifactsT
14
+ stage: StageT
15
+ }
16
+
17
+ /**
18
+ * Module bundle — .module/build/image.json + manifest.json + source.tar.gz,
19
+ * the registry publish.
20
+ *
21
+ * Modules ship as source with one addition no other kind has: a surface
22
+ * manifest of their tools and scripts, scanned with the same scanners the
23
+ * blueprint uses. It rides along because it is the module's public surface —
24
+ * shipping it means the registry can render "what this gives your agent"
25
+ * straight from the artifact rather than from metadata recorded beside it.
26
+ */
27
+ export function Module(opts: ModuleOpts) {
28
+ const { root, artifacts, stage } = opts
29
+ const frame = Frame({ root: root, kind: "module" })
30
+
31
+ return {
32
+ async build(): Promise<BundleResult> {
33
+ const pkg = await artifacts.identity()
34
+ const bundleDir = await artifacts.open(frame.path("build"), [
35
+ "image.json",
36
+ "package.json",
37
+ "manifest.json",
38
+ "source.tar.gz",
39
+ // Assets from a previous publish, archive and staging tree
40
+ // alike. Cleared by name like every other output: a deleted
41
+ // asset must not survive into the next publish, and nothing
42
+ // else signals that it should be gone.
43
+ "assets.tar.gz",
44
+ ".assets",
45
+ ])
46
+
47
+ const image: ModuleImage = {
48
+ kind: "module",
49
+ moduleId: pkg.name,
50
+ version: pkg.version,
51
+ public: pkg.public,
52
+ builtAt: new Date().toISOString(),
53
+ ...(pkg.description ? { description: pkg.description } : {}),
54
+ }
55
+ await artifacts.image(bundleDir, image)
56
+ // package.json rides along — modules.publish() reads it.
57
+ await artifacts.package(bundleDir, pkg.raw)
58
+
59
+ const [tools, scripts] = await Promise.all([Tools(root), Scripts(root)])
60
+ await artifacts.json(bundleDir, "manifest.json", {
61
+ name: pkg.name,
62
+ version: pkg.version,
63
+ kind: "module" as const,
64
+ tools: tools.entries,
65
+ scripts: scripts.entries,
66
+ prompts: [],
67
+ })
68
+
69
+ // Tar entries, relative to the project root — so they name the
70
+ // frame's areas the same way the writers that produced them do.
71
+ const manifestEntry = `${frame.name}/${FRAME.build}/manifest.json`
72
+ const globalsEntry = `${frame.name}/${FRAME.types}/tool-globals.d.ts`
73
+
74
+ const entries = ["module.config.ts", "package.json", manifestEntry]
75
+ if (fsx.exists(join(root, "src"))) entries.unshift("src")
76
+ // `server/` is where a module DOES things. Its plugins are loaded
77
+ // by the runtime at boot (the scanner sets `serverPath` from this
78
+ // directory), so a module whose whole purpose is a plugin shipped
79
+ // as an inert package without it — installed, declared, scanned,
80
+ // and silently doing nothing.
81
+ //
82
+ // Every sensory module was in exactly that state: screenshare,
83
+ // camera, microphone, mouse and compute all have a `server/` and
84
+ // none of them reached a consumer. The agent bundler has always
85
+ // included "server" for the same reason; this is the same concept,
86
+ // one omission.
87
+ if (fsx.exists(join(root, "server"))) entries.unshift("server")
88
+ // `data/knowledge/` is where a module KNOWS things — reference
89
+ // material the consuming agent's brain can read, discovered by the
90
+ // build and namespaced under this module's name.
91
+ //
92
+ // Same omission this file already fixed once for `server/`: the
93
+ // module installs, the scanner runs, and the surface is silently
94
+ // empty. @axon/docs shipped 194 markdown files as a package
95
+ // containing none of them, which reads to its author as knowledge
96
+ // that mysteriously does not exist rather than as a bundle that
97
+ // never carried it.
98
+ //
99
+ // Only `data/knowledge/`, never `data/` — the other rooms under it
100
+ // (workspace/, modules/) are an AGENT's runtime scratch, and a
101
+ // module has no business shipping either.
102
+ if (fsx.exists(join(root, "data", "knowledge"))) entries.unshift(join("data", "knowledge"))
103
+ if (fsx.exists(join(root, "README.md"))) entries.push("README.md")
104
+ // The module's tool declarations ride along: they are its public
105
+ // surface, same reason the manifest does.
106
+ if (fsx.exists(join(root, globalsEntry))) {
107
+ entries.push(globalsEntry)
108
+ }
109
+
110
+ // README assets — their own tarball, never a member of this one.
111
+ // Every publishable kind has a registry page, so every publishable
112
+ // kind carries assets; this was wired into the source bundler first
113
+ // and an agent's mp4 silently never reached storage, which reads to
114
+ // its author as a broken player rather than a missing upload.
115
+ const assets = await Assets({ root, stage }).collect(bundleDir)
116
+
117
+ const tarball = join(bundleDir, "source.tar.gz")
118
+ await stage.npm(bundleDir, tarball, entries)
119
+
120
+ return {
121
+ image,
122
+ tarball,
123
+ assets: assets.assets,
124
+ ...(assets.tarball ? { assetsTarball: assets.tarball } : {}),
125
+ }
126
+ },
127
+ }
128
+ }
129
+
130
+ export type ModuleBundleT = ReturnType<typeof Module>
@@ -0,0 +1,136 @@
1
+ import { join } from "node:path"
2
+ import { err } from "@arcforge/err"
3
+ import { KERNEL_ABI_VERSION } from "@arcforge/types"
4
+ import { readCognetAbi } from "../../blueprint"
5
+ import { fsx } from "../../../utils/fs"
6
+ import { KINDS } from "../kinds"
7
+ import { Frame } from "../../frame"
8
+ import { Assets, type AssetReport } from "./assets"
9
+ import type { ArtifactsT } from "./artifacts"
10
+ import type { StageT } from "./stage"
11
+ import type { BundleResult, SourceImage } from "./types"
12
+
13
+ type SourceOpts = {
14
+ root: string
15
+ artifacts: ArtifactsT
16
+ stage: StageT
17
+ }
18
+
19
+ /**
20
+ * Source bundle — cognets, benches and prompts, packaged for the registry.
21
+ *
22
+ * All three are published as SOURCE. A cognet is compiled by the CONSUMER
23
+ * against the core runtime it will actually run against (a prebuilt bundle
24
+ * would carry a frozen copy of core's internals into an agent whose kernel has
25
+ * moved), and a bench is a definition others run against their own agents.
26
+ * Neither has a build step here; the artifact is the authoring tree.
27
+ *
28
+ * The npm `package/` prefix Stage() applies is what makes them installable by
29
+ * `bun add` — and that is exactly how an agent acquires its cognet:
30
+ * `cognet: "@axon/zero"` becomes a package.json dependency resolved through
31
+ * the registry's npm surface, no bespoke install path.
32
+ *
33
+ * Per-kind differences are read from the kind table, never branched on here.
34
+ */
35
+ export function Source(opts: SourceOpts) {
36
+ const { root, artifacts, stage } = opts
37
+
38
+ return {
39
+ async build(kind: SourceImage["kind"]): Promise<BundleResult> {
40
+ const spec = KINDS[kind]
41
+
42
+ if (!fsx.exists(join(root, spec.config))) {
43
+ throw err("BUNDLE_INVALID", {
44
+ detail: `no ${spec.config} at ${root}`,
45
+ context: { root, kind },
46
+ })
47
+ }
48
+
49
+ const pkg = await artifacts.identity()
50
+ const bundleDir = await artifacts.open(Frame({ root: root, kind: kind }).path("build"), [
51
+ "image.json",
52
+ "package.json",
53
+ "source.tar.gz",
54
+ // Assets from a previous publish, both the archive and the
55
+ // staging tree. Cleared by name like every other output: a
56
+ // deleted asset must not survive into the next publish, and
57
+ // there is no other signal that it should be gone.
58
+ "assets.tar.gz",
59
+ ".assets",
60
+ ])
61
+
62
+ // A cognet's ABI is the kernel contract it targets, and it is the
63
+ // only thing that says which kernels can load it. Lifted out of
64
+ // cognet.config.ts HERE so the registry can record it: otherwise
65
+ // the value stays sealed in the tarball and the resolve path can
66
+ // only offer "latest" and hope.
67
+ //
68
+ // Unpinned falls back to THIS CLI's kernel rather than throwing.
69
+ // Publish compiles the candidate from source with this CLI to
70
+ // prove a consumer could, so an unpinned cognet genuinely was
71
+ // validated against this ABI — recording it is a fact, and the
72
+ // row must carry one either way or the resolver cannot place it.
73
+ const abi = kind === "cognet"
74
+ ? (await readCognetAbi(root)) ?? KERNEL_ABI_VERSION
75
+ : undefined
76
+
77
+ const image: SourceImage = {
78
+ kind,
79
+ name: pkg.name,
80
+ version: pkg.version,
81
+ public: pkg.public,
82
+ builtAt: new Date().toISOString(),
83
+ ...(pkg.description ? { description: pkg.description } : {}),
84
+ ...(abi !== undefined ? { abi } : {}),
85
+ }
86
+ await artifacts.image(bundleDir, image)
87
+ // package.json rides along — publish reads name/version/visibility from it.
88
+ await artifacts.package(bundleDir, pkg.raw)
89
+
90
+ const entries = [spec.config, "package.json"]
91
+ if (fsx.exists(join(root, "src"))) entries.unshift("src")
92
+ if (fsx.exists(join(root, "plugins"))) entries.push("plugins")
93
+ if (fsx.exists(join(root, "README.md"))) entries.push("README.md")
94
+
95
+ // Root-level modules the source imports. `src/main.ts` doing
96
+ // `import { brain } from "../config"` is ordinary TypeScript, and
97
+ // a whitelist of src/plugins/config silently dropped that file
98
+ // from the tarball — the consumer then failed to compile with an
99
+ // unresolvable import naming a path that exists in the author's
100
+ // repo and nowhere else. Publishing must ship what the source
101
+ // actually references, not what a fixed layout predicts.
102
+ for (const name of await fsx.list(root)) {
103
+ if (entries.includes(name)) continue
104
+ if (!/\.(ts|tsx|js|mjs|json)$/.test(name)) continue
105
+ if (name.startsWith(".") || name.endsWith(".test.ts")) continue
106
+ if (name === "tsconfig.json" || name === "bun.lock") continue
107
+ if (!fsx.isFile(join(root, name))) continue
108
+ entries.push(name)
109
+ }
110
+
111
+ // Whatever else this kind declares as its own (prompt packs ship
112
+ // their top-level units) — data from the kind table, not a branch.
113
+ if (spec.files) {
114
+ entries.push(...(await spec.files(root)).filter(entry => !entries.includes(entry)))
115
+ }
116
+
117
+ // README assets — their OWN tarball, never a member of source.tar.gz.
118
+ // Docs media on the install path means every consumer downloads it:
119
+ // measured at 99% of @axon/ember-theme's payload for bytes only the
120
+ // website ever reads. `entries` deliberately never contains "assets".
121
+ const assets = await Assets({ root, stage }).collect(bundleDir)
122
+
123
+ const tarball = join(bundleDir, "source.tar.gz")
124
+ await stage.npm(bundleDir, tarball, entries)
125
+
126
+ return {
127
+ image,
128
+ tarball,
129
+ assets: assets.assets,
130
+ ...(assets.tarball ? { assetsTarball: assets.tarball } : {}),
131
+ }
132
+ },
133
+ }
134
+ }
135
+
136
+ export type SourceBundleT = ReturnType<typeof Source>
@@ -0,0 +1,97 @@
1
+ import { dirname, join, sep } from "node:path"
2
+ import { cp, mkdir, rm } from "node:fs/promises"
3
+ import { err } from "@arcforge/err"
4
+ import { fsx } from "../../../utils/fs"
5
+
6
+ type StageOpts = {
7
+ root: string
8
+ }
9
+
10
+ /**
11
+ * Stage — assembling a tree and packaging it into a tarball.
12
+ *
13
+ * Owns the npm `package/` staging form used by every source-published kind
14
+ * (module, cognet, bench, prompt): npm tarballs put everything under a
15
+ * "package/" directory, and every package manager strips exactly that one
16
+ * leading component on extract. Staging with that prefix is what makes the
17
+ * published artifact installable by `bun add` rather than only by our own
18
+ * extractor.
19
+ *
20
+ * Agents stage differently — their tree is assembled in place with rebased
21
+ * imports and no prefix — so Agent() builds its own tree and uses tar()
22
+ * directly. That is the one real difference between the two staging forms,
23
+ * and it is why this leaf exposes both.
24
+ */
25
+ export function Stage(opts: StageOpts) {
26
+ const root = opts.root
27
+
28
+ return {
29
+ /**
30
+ * Copy `entries` into a scratch `package/` tree and tar it.
31
+ * The scratch dir is always removed, success or failure.
32
+ *
33
+ * A missing entry is skipped rather than an error: callers build the
34
+ * list from a fixed layout and let the parts a project does not have
35
+ * fall away (`if (exists(src)) entries.unshift("src")`).
36
+ *
37
+ * README assets are NOT staged here — they are a separate artifact with
38
+ * their own tarball (see assets.ts), because shipping docs media inside
39
+ * source.tar.gz puts it on the install path for every consumer.
40
+ */
41
+ async npm(bundleDir: string, tarball: string, entries: string[]): Promise<void> {
42
+ const stageDir = join(bundleDir, ".stage")
43
+ try {
44
+ const packageDir = join(stageDir, "package")
45
+ await rm(stageDir, { recursive: true, force: true })
46
+ await mkdir(packageDir, { recursive: true })
47
+
48
+ for (const entry of entries) {
49
+ const source = join(root, entry)
50
+ if (!fsx.exists(source)) continue
51
+ const destination = join(packageDir, entry)
52
+ await mkdir(dirname(destination), { recursive: true })
53
+ await cp(source, destination, { recursive: true })
54
+ }
55
+
56
+ await tar(stageDir, tarball, ["package"])
57
+ } finally {
58
+ await rm(stageDir, { recursive: true, force: true })
59
+ }
60
+ },
61
+
62
+ /** Package an already-assembled tree. Agents build their own stage, then call this. */
63
+ tar,
64
+ }
65
+ }
66
+
67
+ export type StageT = ReturnType<typeof Stage>
68
+
69
+ /**
70
+ * Package entries into a gzipped tar.
71
+ *
72
+ * `--format=posix` (PAX) rather than tar's GNU default, because a path over
73
+ * 100 bytes does not fit the original tar header. GNU tar encodes those by
74
+ * emitting a `@LongLink` PSEUDO-ENTRY carrying the real name, followed by the
75
+ * actual entry — so any reader listing the archive naively sees phantom files
76
+ * literally called `@LongLink`. That is what appeared in the registry's source
77
+ * tree, and nested `node_modules/@axon/zero/node_modules/@arcforge/...` paths
78
+ * cross 100 bytes routinely, so it was not rare.
79
+ *
80
+ * PAX stores long names in a proper extended header instead. Every modern
81
+ * reader — bun, npm, GNU tar, BSD tar, Python tarfile — handles it, and the
82
+ * archive lists as exactly the files it contains.
83
+ */
84
+ async function tar(cwd: string, out: string, entries: string[]): Promise<void> {
85
+ const normalized = entries.map(entry => entry.split(sep).join("/"))
86
+ const result = await Bun.$`tar --format=posix -czf ${out} ${normalized}`.cwd(cwd).quiet().nothrow()
87
+ if (result.exitCode !== 0) {
88
+ const stderr = result.stderr.toString()
89
+ if (result.exitCode === 127 || stderr.includes("not found")) {
90
+ throw err("BUNDLE_TAR_MISSING", { detail: stderr })
91
+ }
92
+ throw err("BUNDLE_TAR_FAILED", {
93
+ detail: `exit ${result.exitCode}: ${stderr}`,
94
+ context: { exitCode: result.exitCode },
95
+ })
96
+ }
97
+ }
@@ -0,0 +1,111 @@
1
+ /**
2
+ * The publishable artifact records — what a bundle writes to image.json and
3
+ * what publish/deploy read back to identify what they are uploading.
4
+ */
5
+
6
+ import type { AssetReport } from "./assets"
7
+
8
+ export type AgentImage = {
9
+ kind: "agent"
10
+ agentId: string
11
+ version: string
12
+ public: boolean
13
+ axonVersion: string
14
+ builtAt: string
15
+ /** From package.json — same source as ModuleImage. */
16
+ description?: string
17
+ connections?: Record<string, unknown>
18
+ }
19
+
20
+ export type ModuleImage = {
21
+ kind: "module"
22
+ moduleId: string
23
+ version: string
24
+ public: boolean
25
+ builtAt: string
26
+ description?: string
27
+ }
28
+
29
+ /**
30
+ * Cognets, benches and prompts: published as source, no build step, no
31
+ * per-kind metadata beyond the package identity. They share one image shape
32
+ * because there is genuinely nothing kind-specific to record.
33
+ */
34
+ export type SourceImage = {
35
+ kind: "cognet" | "bench" | "prompt"
36
+ name: string
37
+ version: string
38
+ public: boolean
39
+ builtAt: string
40
+ description?: string
41
+ /**
42
+ * The kernel ABI this cognet targets, lifted out of cognet.config.ts so
43
+ * publish can record it on the version row. Cognets only — nothing else
44
+ * declares a kernel contract.
45
+ */
46
+ abi?: string
47
+ }
48
+
49
+ export type BundleImage = AgentImage | ModuleImage | SourceImage
50
+
51
+ /** What a kind's bundler returns. Internal to the module — callers get a BundleArtifact. */
52
+ export type BundleResult = {
53
+ image: BundleImage
54
+ tarball: string
55
+ /**
56
+ * README assets that were packaged. Source-published kinds only — an agent's
57
+ * bundle is a deploy image nobody reads a README from.
58
+ */
59
+ assets?: AssetReport[]
60
+ /**
61
+ * Absolute path to `assets.tar.gz`, absent when the project has no assets.
62
+ * A SEPARATE upload from `tarball`, so docs media stays off the install path.
63
+ */
64
+ assetsTarball?: string
65
+ }
66
+
67
+ /**
68
+ * The identity every kind's image carries, however it spells its name field.
69
+ * Callers register against this and nothing else.
70
+ */
71
+ export type BundleIdentity = {
72
+ name: string
73
+ version: string
74
+ public: boolean
75
+ description?: string
76
+ }
77
+
78
+ /**
79
+ * A completed bundle: what it is, where it was written, what to upload.
80
+ *
81
+ * These three travel together deliberately. `dir` is only meaningful because
82
+ * the build that filled it has run — exposing it separately from the build
83
+ * made that ordering load-bearing and invisible, and a caller that got it
84
+ * wrong uploaded a stale tarball with no error.
85
+ */
86
+ export type BundleArtifact = {
87
+ /**
88
+ * The full image record as written to image.json. Kind-specific — narrow
89
+ * it on `image.kind` to reach agentId/axonVersion/abi. Callers that only
90
+ * need to register the artifact should use `identity` instead.
91
+ */
92
+ image: BundleImage
93
+ /** The image's registrable fields, normalised across kinds. */
94
+ identity: BundleIdentity
95
+ /** The bundle directory — what publish/deploy upload from. */
96
+ dir: string
97
+ /** Absolute path to source.tar.gz inside `dir` — CODE ONLY. */
98
+ tarball: string
99
+ /**
100
+ * README assets packaged for this version, for the CLI's publish report.
101
+ * Empty for kinds that do not carry assets.
102
+ */
103
+ assets: AssetReport[]
104
+ /**
105
+ * Absolute path to `assets.tar.gz` inside `dir`, or null when there are no
106
+ * assets. Uploaded as its own publish part and unpacked server-side; it is
107
+ * deliberately NOT inside `tarball`, so `axon install` never fetches docs
108
+ * media (that cost was 99% of one extension's payload).
109
+ */
110
+ assetsTarball: string | null
111
+ }
@@ -0,0 +1,156 @@
1
+ import { err } from "@arcforge/err"
2
+ import { KERNEL_ABI_VERSION } from "@arcforge/types"
3
+ import { DEFAULT_COGNET, inlineCognetDir } from "../blueprint"
4
+ import type { ManifestT } from "./manifest"
5
+ import type { InstallerT, ModuleUpdate } from "./installer"
6
+ import type { TreeT } from "./tree"
7
+
8
+ type CognetOpts = {
9
+ manifest: ManifestT
10
+ installer: InstallerT
11
+ tree: TreeT
12
+ }
13
+
14
+ export type CognetT = ReturnType<typeof Cognet>
15
+
16
+ /**
17
+ * The agent's brain, as an updatable dependency.
18
+ *
19
+ * A cognet is an ordinary registry package (`@axon/zero` in package.json),
20
+ * installed by the same installer as everything else — so this owns no
21
+ * resolution, fetching or pinning of its own. What it owns is the two facts
22
+ * that make a cognet different from a module:
23
+ *
24
+ * ONE, NOT MANY. An agent has exactly one brain, so the surface is a single
25
+ * answer rather than a list. Swapping it for a different cognet is a change
26
+ * of mind, not a version bump, and is deliberately not offered here.
27
+ *
28
+ * ABI-GATED. A cognet bundle is fused to one kernel contract. "Latest" on
29
+ * its own can name a version this runtime cannot load, so every resolution
30
+ * here passes KERNEL_ABI_VERSION and an incompatible version is never
31
+ * selected — rather than being installed and failing later at compile time.
32
+ *
33
+ * Not exposed for a SOURCE cognet (an inline `cognet/` directory or a local
34
+ * import): that is a checked-out tree the author edits, with no version to
35
+ * move it to. Callers get null and should say so rather than offer an update
36
+ * that cannot mean anything.
37
+ */
38
+ export function Cognet(opts: CognetOpts) {
39
+ const { manifest, installer, tree } = opts
40
+
41
+ /**
42
+ * The installed cognet's package name, or null when this agent runs a
43
+ * source cognet.
44
+ *
45
+ * Falls back to DEFAULT_COGNET when the config declares nothing, because
46
+ * that is exactly what prepare installs in the same case — an agent that
47
+ * chose no brain still HAS one, and reporting null would hide the most
48
+ * common agent of all from its own update command.
49
+ */
50
+ async function name(): Promise<string | null> {
51
+ // An inline cognet/ directory is a source tree the author edits —
52
+ // checked FIRST because it wins over an absent declaration and, when
53
+ // both exist, prepare itself refuses the agent as ambiguous. Either
54
+ // way there is no published version to move to.
55
+ if (inlineCognetDir(manifest.root)) return null
56
+
57
+ const declared = await manifest.config.cognet()
58
+ // No `cognet:` key and no inline folder: the agent tracks the registry
59
+ // default. Reporting null here would hide the most common agent of all
60
+ // from its own update command — prepare installs DEFAULT_COGNET in
61
+ // exactly this case.
62
+ if (!declared) return DEFAULT_COGNET
63
+
64
+ // A registry declaration is a bare scoped name, optionally pinned.
65
+ // Anything else (a relative path) is a source cognet.
66
+ if (!declared.startsWith("@")) return null
67
+
68
+ // Strip a pinned version — package.json keys on the name alone.
69
+ // lastIndexOf, not indexOf: the scope's own "@" leads the string.
70
+ const at = declared.lastIndexOf("@")
71
+ return at > 0 ? declared.slice(0, at) : declared
72
+ }
73
+
74
+ return {
75
+ /**
76
+ * What this agent's brain could move to, or null when there is
77
+ * nothing updatable (a source cognet).
78
+ *
79
+ * Read-only and safe to call on a palette render: it asks the registry
80
+ * what exists and touches no manifest, tree or bundle. Mirrors
81
+ * `installer.updates()` per-entry semantics exactly — `current: null`
82
+ * is declared-but-not-installed, `latest: null` is a registry that
83
+ * could not be reached, and neither is ever `outdated`, so a caller
84
+ * reading that flag can never act on a version it does not know.
85
+ */
86
+ async updates(): Promise<ModuleUpdate | null> {
87
+ const packageName = await name()
88
+ if (!packageName) return null
89
+
90
+ const declared = await manifest.package.dependencies.all()
91
+ const range = declared[packageName] ?? ""
92
+ const current = tree.installedVersion(packageName)
93
+
94
+ try {
95
+ const latest = await installer.resolve(packageName, undefined, KERNEL_ABI_VERSION)
96
+ return {
97
+ name: packageName,
98
+ range,
99
+ current,
100
+ latest,
101
+ outdated: current !== null && latest !== current,
102
+ }
103
+ } catch {
104
+ return { name: packageName, range, current, latest: null, outdated: false }
105
+ }
106
+ },
107
+
108
+ /**
109
+ * Move the brain to an explicit version.
110
+ *
111
+ * Just `install()` at a ref, exactly as `installer.update()` is: the
112
+ * pinning, the registry-origin bookkeeping and the already-installed
113
+ * short circuit are all what an update needs, and a second code path
114
+ * would be the same operation free to disagree with the first.
115
+ *
116
+ * `declare: false` because the cognet is not a module — prepare
117
+ * installs it the same way, and adding it to `modules: [...]` would
118
+ * make the blueprint load the brain twice.
119
+ *
120
+ * `keepRange` so moving a version does not silently convert the
121
+ * author's `^1.0.10` into a hard pin.
122
+ *
123
+ * The version is REQUIRED. The caller has already resolved it and
124
+ * shown the user what they are agreeing to; re-resolving here could
125
+ * land somewhere newer than that between the row rendering and the
126
+ * keypress.
127
+ */
128
+ async update(version: string): Promise<void> {
129
+ const packageName = await name()
130
+ if (!packageName) {
131
+ throw err("COGNET_NOT_FOUND", {
132
+ detail: "this agent runs a source cognet — there is no published version to update to",
133
+ })
134
+ }
135
+
136
+ const [result] = await installer.install([`${packageName}@${version}`], {
137
+ declare: false,
138
+ keepRange: true,
139
+ abi: KERNEL_ABI_VERSION,
140
+ })
141
+
142
+ if (result?.status === "not-found") {
143
+ throw err("COGNET_NOT_FOUND", {
144
+ detail: `no published ${packageName}@${version} for kernel ABI ${KERNEL_ABI_VERSION}`,
145
+ context: { name: packageName, version },
146
+ })
147
+ }
148
+ if (result?.status === "error") {
149
+ throw err("COGNET_NOT_FOUND", {
150
+ detail: result.error,
151
+ context: { name: packageName, version },
152
+ })
153
+ }
154
+ },
155
+ }
156
+ }
@@ -0,0 +1,52 @@
1
+ import { join } from "node:path"
2
+ import { mkdir, writeFile } from "node:fs/promises"
3
+ import { err } from "@arcforge/err"
4
+ import { resolveDefaultBaseUrl } from "@arcforge/cloud"
5
+ import { fsx } from "../../../utils/fs"
6
+ import {
7
+ AGENT_CONFIG_TEMPLATE,
8
+ BOOT_VUE,
9
+ BUNFIG_TEMPLATE,
10
+ GITIGNORE_TEMPLATE,
11
+ PACKAGE_JSON_TEMPLATE,
12
+ } from "./templates"
13
+ import { bareName, type ScaffoldOpts } from "../kinds"
14
+
15
+ /**
16
+ * Scaffold a new agent at <dir>/<name>/. Refuses to overwrite an existing
17
+ * directory. Returns the agent root.
18
+ *
19
+ * Source only — the .agent/ frame and the tsconfigs pointing at it are
20
+ * prepare()'s, written after dependencies are installed.
21
+ *
22
+ * DELIBERATELY MINIMAL: an agent is its config plus its boot, and nothing
23
+ * else is written until the author asks for it. Every surface an agent CAN
24
+ * have (src/tools, src/scripts, server/api, modules, data/knowledge, tests)
25
+ * is discovered by scanning a directory that may not exist — fsx.list()
26
+ * returns [] on ENOENT — so an empty folder and an absent one mean the same
27
+ * thing to the runtime. Scaffolding them anyway bought nothing and made a
28
+ * new agent read like a framework the author had to grow into. `data/` is
29
+ * absent for the same reason: the session writer mkdirs its own parent.
30
+ *
31
+ * `apiBase` becomes the agent's registry URL in bunfig.toml, defaulting to
32
+ * whatever backend this process talks to — so an agent scaffolded against
33
+ * local staging installs from local staging.
34
+ */
35
+ export async function scaffoldAgent(opts: ScaffoldOpts): Promise<string> {
36
+ const root = join(opts.dir, bareName(opts.name))
37
+ if (fsx.exists(root)) {
38
+ throw err("PROJECT_EXISTS", { detail: `${root} already exists`, context: { root } })
39
+ }
40
+
41
+ await mkdir(join(root, "src"), { recursive: true })
42
+
43
+ await Promise.all([
44
+ writeFile(join(root, "axon.config.ts"), AGENT_CONFIG_TEMPLATE()),
45
+ writeFile(join(root, "src", "boot.vue"), BOOT_VUE),
46
+ writeFile(join(root, ".gitignore"), GITIGNORE_TEMPLATE),
47
+ writeFile(join(root, "package.json"), PACKAGE_JSON_TEMPLATE(opts.name, opts.frameworkVersion)),
48
+ writeFile(join(root, "bunfig.toml"), BUNFIG_TEMPLATE(opts.apiBase ?? resolveDefaultBaseUrl())),
49
+ ])
50
+
51
+ return root
52
+ }