@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,81 @@
1
+ import { mkdir, writeFile } from "node:fs/promises"
2
+ import { join } from "node:path"
3
+ import { err } from "@arcforge/err"
4
+ import { fsx } from "../../../utils/fs"
5
+ import { bareName, type ScaffoldOpts } from "../kinds"
6
+
7
+ const config = () => `/**
8
+ * What this benchmark measures.
9
+ *
10
+ * A TypeScript type, not a config block: a doc comment is where a description
11
+ * naturally lives, and a union is how you write a fixed set of categories.
12
+ * \`axon bench prepare\` extracts this into .bench/schema.json so the manifest
13
+ * carries the schema as a value — coverage can only report "expected 2,
14
+ * observed 1" if it knows about measurements that never fired.
15
+ */
16
+ type Schema = {
17
+ /** Whether the task completed successfully. */
18
+ success: boolean
19
+ }
20
+
21
+ export default defineBench<Schema>({
22
+ // The agent's world. Copied fresh per iteration, so every run starts from
23
+ // an identical workspace/ — nothing outside it is visible to the agent.
24
+ workspace: { source: "./workspace", retain: "failed" },
25
+
26
+ // Each key is an axis of variation; multiple keys multiply into a grid.
27
+ // Start with one: changing a single variable is what makes a result
28
+ // attributable to that variable.
29
+ matrix: {
30
+ // model: [OpenRouter({ model: "anthropic/claude-sonnet-4.6" })],
31
+ },
32
+
33
+ // Repetitions per test x cell. Models are stochastic — one sample is an
34
+ // anecdote, not a measurement.
35
+ trials: 1,
36
+ })
37
+ `
38
+
39
+ const test = `import { expect, it } from "bun:test"
40
+
41
+ it("completes the example task", async () => {
42
+ // expect() is for the harness: if the world is not what the scenario
43
+ // assumes, this trial measures nothing and should stop.
44
+ expect(true).toBe(true)
45
+
46
+ // observe() is for the subject: recorded whatever the value is. A model
47
+ // that scores badly is a finding, not a failing test.
48
+ bench.observe("success", true)
49
+ })
50
+ `
51
+
52
+ const readme = (name: string) => `# ${name}
53
+
54
+ Describe the benchmark methodology and limitations.
55
+
56
+ - workspace/ — the agent's world, copied fresh per iteration
57
+ - fixtures/ — author-side inputs: agents under test, setup data, rubrics. Never visible to the workspace agent
58
+ - tests/ — the scenarios, and where measurements are recorded
59
+ `
60
+
61
+ /**
62
+ * Scaffold a benchmark at <dir>/<name>/. Source only — the .bench/ frame is
63
+ * prepare()'s, written from the config's axes after dependencies land.
64
+ */
65
+ export async function scaffoldBench(opts: ScaffoldOpts): Promise<string> {
66
+ const root = join(opts.dir, bareName(opts.name))
67
+ if (fsx.exists(root)) throw err("PROJECT_EXISTS", { detail: `${root} already exists`, context: { root } })
68
+ await Promise.all([
69
+ mkdir(join(root, "tests"), { recursive: true }),
70
+ mkdir(join(root, "fixtures"), { recursive: true }),
71
+ mkdir(join(root, "workspace"), { recursive: true }),
72
+ ])
73
+ await Promise.all([
74
+ writeFile(join(root, "bench.config.ts"), config()),
75
+ writeFile(join(root, "tests", "example.bench.ts"), test),
76
+ writeFile(join(root, "README.md"), readme(opts.name)),
77
+ writeFile(join(root, "package.json"), JSON.stringify({ name: opts.name, version: "0.1.0", private: false, type: "module" }, null, 2) + "\n"),
78
+ writeFile(join(root, ".gitignore"), ".bench/runs/\n.bench/workspace/\n"),
79
+ ])
80
+ return root
81
+ }
@@ -0,0 +1,102 @@
1
+ import { join } from "node:path"
2
+ import { mkdir, writeFile } from "node:fs/promises"
3
+ import { err } from "@arcforge/err"
4
+ import { fsx } from "../../../utils/fs"
5
+ import { INLINE_COGNET_DIR } from "../../blueprint/cognet"
6
+ import { bareName, type ScaffoldOpts } from "../kinds"
7
+
8
+ const CONFIG_TEMPLATE = (name: string) => `// ${name} — what this brain declares.
9
+ //
10
+ // Identity comes from package.json and behavior from src/main.ts; the compile
11
+ // step composes the three. The kernel ABI is stamped in at compile time, so
12
+ // there is nothing to pin unless you want this brain to REFUSE a kernel it
13
+ // has not been validated against.
14
+ export default defineCognet({
15
+ mode: { kind: "invocation" },
16
+ })
17
+ `
18
+
19
+ const MAIN_TEMPLATE = (name: string) => `// ${name} — a raw script: this file IS the brain.
20
+ //
21
+ // Runs once at load(), with the ambient globals live (kernel, loop, phase,
22
+ // system, blueprint — typed by the generated frame, run \`axon prepare\`).
23
+ // Module scope is resident RAM: alive across wakes, rebuildable from the
24
+ // log, gone without loss on kill -9 — never authoritative.
25
+
26
+ loop(async ({ stimuli, signal, stop }) => {
27
+ await phase("sense", async () => {
28
+ // one deterministic fold: new entries → your own resident model.
29
+ // kernel.store.session.get({ after: seq }) is the same door for
30
+ // cold-boot hydration and steady-state diffs — the equivalence
31
+ // that makes kill -9 free.
32
+ })
33
+
34
+ await phase("think", async () => {
35
+ // strategy. yours. the kernel has no opinion past this comment.
36
+ // const messages = ...render from your model...
37
+ // for await (const event of kernel.stream({ messages, signal })) { ... }
38
+ })
39
+
40
+ await phase("act", async () => {
41
+ // effects leave ONLY through the two verbs:
42
+ // kernel.output(type, data) — unmediated emission (chunk: {of, final} to stream)
43
+ // kernel.run(code) — mediated capsule execution, committed for you
44
+ })
45
+
46
+ // quiescent? nothing pending → this wake is over. the brain stays warm.
47
+ stop()
48
+ })
49
+ `
50
+
51
+ /**
52
+ * Scaffold a new cognet. Returns its root.
53
+ *
54
+ * Standalone at <dir>/<name>/, or INLINE at <agent>/cognet/ when run from an
55
+ * agent root — where the folder itself is the declaration and the agent needs
56
+ * no `cognet:` line. See INLINE_COGNET_DIR.
57
+ *
58
+ * Source only. The generated frame (the authoring globals + tsconfig) is
59
+ * prepare()'s to write, and can only be written once dependencies are on disk
60
+ * — writing it here is what made `axon cognet init` fail its own
61
+ * FRAMEWORK_NOT_INSTALLED assert on a directory created moments earlier.
62
+ */
63
+ export async function scaffoldCognet(opts: ScaffoldOpts): Promise<string> {
64
+ // Inside an agent, the brain lands at <agent>/cognet/ and IS that agent's
65
+ // — the folder is the declaration, so nothing is written into
66
+ // axon.config.ts. Standalone, it lands at <dir>/<name>/ like every other
67
+ // kind. Mirrors scaffoldModule(), which reads the same way.
68
+ const insideAgent = fsx.exists(join(opts.dir, "axon.config.ts"))
69
+ const root = insideAgent
70
+ ? join(opts.dir, INLINE_COGNET_DIR)
71
+ : join(opts.dir, bareName(opts.name))
72
+ if (fsx.exists(root)) {
73
+ throw err("PROJECT_EXISTS", { detail: `${root} already exists`, context: { root } })
74
+ }
75
+
76
+ await mkdir(join(root, "src"), { recursive: true })
77
+
78
+ const files: Promise<unknown>[] = [
79
+ writeFile(join(root, "cognet.config.ts"), CONFIG_TEMPLATE(opts.name)),
80
+ writeFile(join(root, "src", "main.ts"), MAIN_TEMPLATE(opts.name)),
81
+ ]
82
+
83
+ // A standalone cognet is a package: it has an identity to publish, its own
84
+ // dependencies, and its own generated frame to ignore. An inline one is
85
+ // none of those — it is part of the agent, compiled from the agent's
86
+ // node_modules and shipped inside the agent's bundle. Giving it a
87
+ // package.json would declare a second publishable package in one project.
88
+ if (!insideAgent) {
89
+ files.push(
90
+ writeFile(join(root, "package.json"), JSON.stringify(
91
+ { name: opts.name, version: "0.1.0", description: "", type: "module", private: false },
92
+ null,
93
+ 2,
94
+ ) + "\n"),
95
+ writeFile(join(root, ".gitignore"), "node_modules/\n.cognet/\n"),
96
+ )
97
+ }
98
+
99
+ await Promise.all(files)
100
+
101
+ return root
102
+ }
@@ -0,0 +1,63 @@
1
+ import { mkdir, writeFile } from "node:fs/promises"
2
+ import { join } from "node:path"
3
+ import { err } from "@arcforge/err"
4
+ import { fsx } from "../../../utils/fs"
5
+ import { bareName, type ScaffoldOpts } from "../kinds"
6
+
7
+ const PACKAGE_TEMPLATE = (name: string, version: string): string => `${JSON.stringify(
8
+ {
9
+ name,
10
+ version: "0.1.0",
11
+ private: false,
12
+ type: "module",
13
+ dependencies: {
14
+ "@arcforge/types": version,
15
+ "@types/bun": "^1.2.0",
16
+ },
17
+ },
18
+ null,
19
+ 4,
20
+ )}\n`
21
+
22
+ /**
23
+ * Empty, and that is the whole file.
24
+ *
25
+ * It marks the directory as an extension — a kind is identified by its config
26
+ * file, and `main.ts` cannot be that marker since a profile has one too.
27
+ * Behaviour lives in main.ts, identity in package.json.
28
+ */
29
+ const CONFIG_TEMPLATE = `export default defineExtension({})\n`
30
+
31
+ const MAIN_TEMPLATE = (name: string): string => `// Everything here is typed — try \`commands.\` or \`palette.\`.
32
+ //
33
+ // This is the same file a user writes in their own profile: an extension is a
34
+ // main.ts, packaged. Split it up with an import whenever you like, and put
35
+ // lifecycle hooks (boot, shutdown, agent:ready) in plugins/.
36
+
37
+ commands.register("${bareName(name)}", {
38
+ async run() {
39
+ tui.info("hello from ${bareName(name)}")
40
+ },
41
+ description: "An example command",
42
+ })
43
+ `
44
+
45
+ /**
46
+ * Scaffold an extension — a published, installable unit of TUI behaviour.
47
+ *
48
+ * The same layout as a profile: a main.ts that registers, and a plugins/ folder
49
+ * that hooks. That is not a coincidence to be tidied away — it is the design.
50
+ */
51
+ export async function scaffoldExtension(input: ScaffoldOpts): Promise<string> {
52
+ const root = join(input.dir, bareName(input.name))
53
+ if (fsx.exists(root)) throw err("PROJECT_EXISTS", { context: { path: root } })
54
+
55
+ await mkdir(join(root, "plugins"), { recursive: true })
56
+ await Promise.all([
57
+ writeFile(join(root, "package.json"), PACKAGE_TEMPLATE(input.name, input.frameworkVersion)),
58
+ writeFile(join(root, "extension.config.ts"), CONFIG_TEMPLATE),
59
+ writeFile(join(root, "main.ts"), MAIN_TEMPLATE(input.name)),
60
+ ])
61
+
62
+ return root
63
+ }
@@ -0,0 +1,43 @@
1
+ import { join } from "node:path"
2
+ import { mkdir, writeFile } from "node:fs/promises"
3
+ import { err } from "@arcforge/err"
4
+ import { fsx } from "../../../utils/fs"
5
+ import { MODULE_CONFIG_TEMPLATE } from "./templates"
6
+ import { bareName, type ScaffoldOpts } from "../kinds"
7
+
8
+ /**
9
+ * Scaffold a new module. Inside an agent (dir has axon.config.ts) it lands
10
+ * at <dir>/modules/<name>/; standalone at <dir>/<name>/. Returns the
11
+ * module root.
12
+ *
13
+ * Source only — the .module/ frame (axon.d.ts + tsconfig) is prepare()'s.
14
+ */
15
+ export async function scaffoldModule(opts: ScaffoldOpts): Promise<string> {
16
+ const insideAgent = fsx.exists(join(opts.dir, "axon.config.ts"))
17
+ const root = insideAgent
18
+ ? join(opts.dir, "modules", bareName(opts.name))
19
+ : join(opts.dir, bareName(opts.name))
20
+ if (fsx.exists(root)) {
21
+ throw err("PROJECT_EXISTS", { detail: `${root} already exists`, context: { root } })
22
+ }
23
+
24
+ await Promise.all([
25
+ mkdir(join(root, "src", "tools"), { recursive: true }),
26
+ mkdir(join(root, "src", "prompts"), { recursive: true }),
27
+ mkdir(join(root, "server", "api"), { recursive: true }),
28
+ ])
29
+
30
+ const pkg = JSON.stringify(
31
+ { name: opts.name, version: "0.1.0", description: "", type: "module", private: false },
32
+ null,
33
+ 2
34
+ ) + "\n"
35
+
36
+ await Promise.all([
37
+ writeFile(join(root, "module.config.ts"), MODULE_CONFIG_TEMPLATE()),
38
+ writeFile(join(root, "package.json"), pkg),
39
+ writeFile(join(root, ".gitignore"), "node_modules/\n.module/\n"),
40
+ ])
41
+
42
+ return root
43
+ }
@@ -0,0 +1,102 @@
1
+ import { mkdir, writeFile } from "node:fs/promises"
2
+ import { join } from "node:path"
3
+ import { fsx } from "../../../utils/fs"
4
+ import type { ScaffoldOpts } from "../kinds"
5
+
6
+ /**
7
+ * A profile's manifest.
8
+ *
9
+ * `@arcforge/types` is a real dependency, pinned to the running CLI's version
10
+ * and resolved from the REGISTRY — a profile lives under ~/.axon, outside any
11
+ * workspace, so `workspace:*` cannot resolve there. It exists to make
12
+ * `tsconfig.base.json` (which the type frame extends) resolvable.
13
+ *
14
+ * `@types/bun` is declared OUTRIGHT rather than inherited through it: the base
15
+ * config sets `"types": ["bun"]`, an explicit `types` field disables automatic
16
+ * @types discovery, and a `file:`-linked dependency does not bring its own
17
+ * dependencies with it. Without this line a user's plugin loses `Bun`,
18
+ * `process` and `fetch`, and every symbol degrades to any. prepare() declares
19
+ * the same pair (see FrameworkSet) — this is only what a first boot starts
20
+ * from.
21
+ */
22
+ const PACKAGE_TEMPLATE = (version: string): string => `${JSON.stringify(
23
+ {
24
+ name: "axon-profile",
25
+ private: true,
26
+ type: "module",
27
+ dependencies: {
28
+ "@arcforge/types": version,
29
+ "@types/bun": "^1.2.0",
30
+ },
31
+ },
32
+ null,
33
+ 4,
34
+ )}\n`
35
+
36
+ /**
37
+ * The user's config entry point.
38
+ *
39
+ * Deliberately near-empty. This is the first file a person opens, and a wall of
40
+ * commented-out examples is a worse introduction than three lines and working
41
+ * autocomplete — every global is typed, so `commands.` in an editor is a better
42
+ * tour than anything written here.
43
+ */
44
+ const MAIN_TEMPLATE = `// Your Axon config. Everything here is typed — try \`commands.\` or \`palette.\`.
45
+ //
46
+ // Split it up whenever you like; an import is all it takes:
47
+ //
48
+ // import "./keybindings"
49
+ //
50
+ // Lifecycle hooks (boot, shutdown, agent:ready) go in plugins/ — every file
51
+ // in that folder loads automatically.
52
+
53
+ commands.register("hello", {
54
+ async run() {
55
+ tui.info("hello from main.ts")
56
+ },
57
+ description: "An example command",
58
+ })
59
+ `
60
+
61
+ const CONFIG_TEMPLATE = `export default defineProfile({
62
+ // Extensions load in this order. A registry name ("@axon/vim") is fetched
63
+ // and installed; a path ("./extensions/mine") is used where it sits.
64
+ extensions: [],
65
+ })
66
+ `
67
+
68
+ /**
69
+ * Scaffold a profile — the user's own Axon directory.
70
+ *
71
+ * Unlike every other kind this is never run by a person: it fires on boot for
72
+ * whoever logs in, so it must be safe to call against a directory that already
73
+ * half-exists. Each file is written only if absent, and nothing is ever
74
+ * overwritten — a user's main.ts is theirs, and a profile that gained
75
+ * plugins/ in a later release should acquire the missing folder without
76
+ * touching what was already there.
77
+ */
78
+ export async function scaffoldProfile(input: ScaffoldOpts): Promise<string> {
79
+ const root = input.dir
80
+
81
+ // `extensions/` is deliberately NOT created. An install makes it when there
82
+ // is something to put in it, and a user who writes their own extends
83
+ // main.ts or drops a file in plugins/. Scaffolding it empty on every boot
84
+ // advertised a directory most profiles never use, and an empty folder that
85
+ // reappears after you delete it reads as the tool not listening.
86
+ await mkdir(join(root, "plugins"), { recursive: true })
87
+ await mkdir(join(root, "store"), { recursive: true })
88
+
89
+ await Promise.all([
90
+ write(join(root, "package.json"), PACKAGE_TEMPLATE(input.frameworkVersion)),
91
+ write(join(root, "main.ts"), MAIN_TEMPLATE),
92
+ write(join(root, "profile.config.ts"), CONFIG_TEMPLATE),
93
+ ])
94
+
95
+ return root
96
+ }
97
+
98
+ /** Write only when absent. Never clobbers a file the user may have edited. */
99
+ async function write(path: string, contents: string): Promise<void> {
100
+ if (fsx.exists(path)) return
101
+ await writeFile(path, contents)
102
+ }
@@ -0,0 +1,68 @@
1
+ import { join } from "node:path"
2
+ import { mkdir, writeFile } from "node:fs/promises"
3
+ import { err } from "@arcforge/err"
4
+ import { fsx } from "../../../utils/fs"
5
+ import { bareName, type ScaffoldOpts } from "../kinds"
6
+
7
+ const CONFIG_TEMPLATE = (name: string) => `// ${name} — a prompt package: one or more units of work, shareable on their own.
8
+ //
9
+ // Every top-level .vue/.md file in this folder is an invokable prompt.
10
+ // components/ holds fragments they compose and is never invokable itself.
11
+ //
12
+ // Empty by design — name, version and description live in package.json.
13
+ export default definePrompt({})
14
+ `
15
+
16
+ const PROMPT_TEMPLATE = (name: string) => `<template>
17
+ <h1>${name}</h1>
18
+
19
+ <p>
20
+ Describe the task here. This is what the agent is told to do — be
21
+ specific about the goal, where to look, and what to produce.
22
+ </p>
23
+
24
+ <h2>Rules</h2>
25
+ <p>
26
+ State the constraints. What must not change, what to skip, when to
27
+ stop.
28
+ </p>
29
+ </template>
30
+ `
31
+
32
+ const PACKAGE_TEMPLATE = (name: string) => JSON.stringify({
33
+ name,
34
+ version: "0.1.0",
35
+ description: "",
36
+ type: "module",
37
+ private: false,
38
+ files: ["prompt.config.ts", "*.vue", "*.md", "components"],
39
+ }, null, 4) + "\n"
40
+
41
+ /**
42
+ * Scaffold a prompt package at <dir>/<name>/.
43
+ *
44
+ * Deliberately the smallest project kind there is: a manifest, a config for
45
+ * identity, and one prompt file. There is nothing to install and nothing to
46
+ * compile — a prompt is text an agent is handed, so `axon prepare` on one
47
+ * has nothing to do, and publishing is the whole lifecycle.
48
+ *
49
+ * The folder is the package and every top-level .vue/.md in it is a prompt,
50
+ * so a single-prompt package and a pack are the same shape — a pack is just
51
+ * one with more files, not a different kind of thing.
52
+ */
53
+ export async function scaffoldPrompt(input: ScaffoldOpts): Promise<string> {
54
+ const root = join(input.dir, bareName(input.name))
55
+ if (fsx.exists(root)) throw err("PROJECT_EXISTS", { context: { path: root } })
56
+
57
+ await mkdir(join(root, "components"), { recursive: true })
58
+ await Promise.all([
59
+ writeFile(join(root, "package.json"), PACKAGE_TEMPLATE(input.name)),
60
+ writeFile(join(root, "prompt.config.ts"), CONFIG_TEMPLATE(input.name)),
61
+ writeFile(join(root, `${bareName(input.name)}.vue`), PROMPT_TEMPLATE(bareName(input.name))),
62
+ // components/ is meaningless empty and git drops empty dirs, so it
63
+ // ships with the note that explains why it exists.
64
+ writeFile(join(root, "components", "README.md"), "Fragments composed by the prompts in this package. Never invokable on their own.\n"),
65
+ ])
66
+
67
+ return root
68
+ }
@@ -0,0 +1,88 @@
1
+ // ── Agent templates ───────────────────────────────────────────────────────────
2
+
3
+ // https://axon.arclabs.it/docs/v2/agent/config
4
+ //
5
+ // Identity (name, version, description) lives in package.json, so the config
6
+ // carries none of it — which is why this takes no arguments.
7
+ //
8
+ // EMPTY BY DESIGN. Inference is not the agent's to declare: a user's
9
+ // providers live on their profile and every agent inherits them, which is
10
+ // what makes installing an agent a download rather than a setup. Scaffolding
11
+ // `providers: [Axon()]` here would bake the author's own source setup into
12
+ // every agent they publish — the exact coupling the profile cascade exists to
13
+ // remove. An agent adds `providers:` only when it needs a source its user
14
+ // would not otherwise have, and `model:` only to express a preference.
15
+ export const AGENT_CONFIG_TEMPLATE = () => `// https://axon.arclabs.it/docs/v2/agent/config
16
+ export default defineAgent({})
17
+ `
18
+
19
+ export const GITIGNORE_TEMPLATE = `.env
20
+ node_modules/
21
+ .agent/
22
+ data/knowledge/*/index/
23
+ `
24
+
25
+ export const BOOT_VUE = `<template></template>
26
+
27
+ <script setup lang="ts">
28
+ // Boot runs once when the agent starts.
29
+ // Load knowledge, set context, or run any startup logic here.
30
+ </script>
31
+ `
32
+
33
+ /**
34
+ * bunfig.toml — the @axon scope → registry mapping, plus the test preload
35
+ * that makes Axon() a global in test files.
36
+ *
37
+ * The scope block is what lets `bun install` fetch Axon modules directly:
38
+ * without it Bun looks for @axon/* on npmjs.com and fails. Public modules
39
+ * need no credential, which is why this file is safe to commit and why a
40
+ * fresh clone installs with no setup.
41
+ *
42
+ * The trailing "/-" is load-bearing — Bun resolves the package name
43
+ * against this URL as a RELATIVE reference, replacing the final segment.
44
+ * Without a throwaway segment to consume, "@axon/x" would be requested
45
+ * from "/api/registry/" and 404.
46
+ */
47
+ export const BUNFIG_TEMPLATE = (apiBase: string) => `[install.scopes]
48
+ axon = { url = "${apiBase}/api/registry/npm/-" }
49
+ `
50
+
51
+ /**
52
+ * The scaffolded project's package.json.
53
+ *
54
+ * @arcforge/types + @arcforge/engines are pinned to the EXACT CLI version:
55
+ * the generated .agent/axon.d.ts is produced by this CLI, so the installed
56
+ * framework types must match it exactly — a range would let them drift. h3 is
57
+ * a real dependency because the generated .d.ts references `import("h3")`
58
+ * handler types. All three resolve through ordinary node resolution once
59
+ * `bun install` runs — no machine-local tsconfig paths.
60
+ */
61
+ export const PACKAGE_JSON_TEMPLATE = (name: string, frameworkVersion: string) =>
62
+ JSON.stringify(
63
+ {
64
+ name,
65
+ version: "0.1.0",
66
+ private: false,
67
+ type: "module",
68
+ dependencies: {
69
+ "@arcforge/types": frameworkVersion,
70
+ "@arcforge/engines": frameworkVersion,
71
+ h3: "^1.13.0",
72
+ },
73
+ },
74
+ null,
75
+ 2
76
+ ) + "\n"
77
+
78
+ // ── TypeScript config templates ───────────────────────────────────────────────
79
+
80
+ // ── Module templates ──────────────────────────────────────────────────────────
81
+
82
+ export const MODULE_CONFIG_TEMPLATE = () => `export default defineModule({
83
+ // env: {
84
+ // MY_API_KEY: { required: true, description: "API key for the service" },
85
+ // },
86
+ })
87
+ `
88
+
@@ -0,0 +1,96 @@
1
+ import { HttpError } from "@arcforge/cloud"
2
+ import type { AxonCloudClient, DeploymentHandle, DeployOptions, DeployStep } from "@arcforge/cloud"
3
+ import { err } from "@arcforge/err"
4
+ import type { BundleT } from "./bundle"
5
+ import type { ManifestT } from "./manifest"
6
+
7
+ export type DeployResult = {
8
+ name: string
9
+ registeredId: string
10
+ url: string
11
+ /** Handle to the deployment just created — stop/redeploy/delete/secrets. */
12
+ deployment: DeploymentHandle
13
+ }
14
+
15
+ type DeployOpts = {
16
+ bundle: BundleT
17
+ manifest: ManifestT
18
+ cloud: AxonCloudClient
19
+ }
20
+
21
+ /**
22
+ * Deploy — provision running compute for an agent. Agents only: modules
23
+ * never run alone (see Project.deploy's caller — module kind throws
24
+ * before this is reached).
25
+ *
26
+ * Delegates to Agents.deploy(), the registry's crown verb: register
27
+ * (idempotent) → publish → provision → wait until running. On an immutable
28
+ * version collision, advances the project's patch version, rebuilds, and
29
+ * resumes the composed flow instead of making deploy a manual two-step.
30
+ */
31
+ export function Deploy(opts: DeployOpts) {
32
+ const { bundle, manifest, cloud } = opts
33
+
34
+ return async function deploy(options: DeployOptions & { onProgress?: (step: DeployStep) => void } = {}): Promise<DeployResult> {
35
+ // Referenced explicitly rather than relied on through the `...options`
36
+ // spread below. It reached the cloud client by name collision — both
37
+ // sides happen to call the field `onProgress` — so renaming either
38
+ // would have silently stopped every deploy reporting progress, with no
39
+ // type error anywhere.
40
+ const report = options.onProgress ?? (() => {})
41
+
42
+ const env = await manifest.env.production()
43
+
44
+ // The bundle completes before the cloud is touched at all, so it is a
45
+ // step the caller can render honestly. Without it a failure during
46
+ // publish marks the bundle as the thing that failed.
47
+ report({ step: "bundling" })
48
+ const session = bundle.session("agent")
49
+ let artifact = await session.current()
50
+
51
+ while (true) {
52
+ try {
53
+ const { agent, deployment, url } = await cloud.registry.agents.deploy({
54
+ path: artifact.dir,
55
+ name: artifact.identity.name,
56
+ ...options,
57
+ env,
58
+ })
59
+
60
+ return { name: artifact.identity.name, registeredId: agent.id, url, deployment }
61
+ } catch (error) {
62
+ if (!(error instanceof HttpError) || error.status !== 409) {
63
+ if (error instanceof HttpError && error.data?.code === "DEPLOY_RUNTIME_FAILED") {
64
+ const reason = typeof error.data.reason === "string" ? error.data.reason : "RevisionFailed"
65
+ const detail = typeof error.data.detail === "string" ? error.data.detail : error.message
66
+ throw err("DEPLOY_RUNTIME_FAILED", {
67
+ detail,
68
+ context: { reason },
69
+ cause: error,
70
+ })
71
+ }
72
+ if (error instanceof HttpError && error.status >= 500) {
73
+ const requestId = typeof error.data?.requestId === "string"
74
+ ? error.data.requestId
75
+ : "unavailable"
76
+ throw err("DEPLOY_PROVISION_FAILED", {
77
+ detail: `Cloud request failed with status ${error.status} (request ID: ${requestId})`,
78
+ context: { status: error.status, path: error.path, requestId },
79
+ cause: error,
80
+ })
81
+ }
82
+ throw error
83
+ }
84
+ const from = artifact.identity.version
85
+ await manifest.package.bump(from)
86
+ artifact = await session.rebuild()
87
+ // The retry re-bundles, so the caller's step list has to
88
+ // re-open rather than appearing frozen mid-publish.
89
+ report({ step: "bumped", from, to: artifact.identity.version })
90
+ report({ step: "bundling" })
91
+ }
92
+ }
93
+ }
94
+ }
95
+
96
+ export type DeployT = ReturnType<typeof Deploy>