@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,120 @@
1
+ import { err } from "@arcforge/err"
2
+ import { AxonSession } from "@arcforge/session"
3
+ import { AxonBus } from "@arcforge/core"
4
+ import type { AxonBlueprint, AxonEngineRawEvent, InferCall } from "@arcforge/types"
5
+ import type { AxonCloudClient } from "@arcforge/cloud"
6
+ import { Inference } from "@arcforge/core"
7
+
8
+ /**
9
+ * What the SUPERVISOR holds on a confined agent's behalf.
10
+ *
11
+ * The three assets that must never enter the box, assembled in one place so
12
+ * the rule is readable rather than scattered:
13
+ *
14
+ * inference — holds the provider credential. The agent names a ROLE and
15
+ * receives tokens; it can cause inference and can never obtain,
16
+ * transfer, or outlive the key that performs it.
17
+ * session — the audit log. The agent APPENDS through commit and can never
18
+ * rewrite: an attacker who can edit the record has erased the
19
+ * evidence of everything else.
20
+ * escalate — the human decider. A program able to reach it could raise and
21
+ * answer its own escalations.
22
+ */
23
+
24
+ type ServicesOpts = {
25
+ blueprint: AxonBlueprint
26
+ cloud: AxonCloudClient
27
+ /** Where the log lives. Opened here, on the supervisor's side. */
28
+ sessionId: string
29
+ }
30
+
31
+ export async function SupervisorSideServices(opts: ServicesOpts) {
32
+ /**
33
+ * The supervisor's own bus for this agent.
34
+ *
35
+ * A linked agent has no in-heap runtime to announce on, so this is where
36
+ * its events become observable: every commit the agent makes lands in the
37
+ * session AND fans out here, which is the same contract `runtime.bus`
38
+ * gives an in-process one. Surfaces subscribe to it identically.
39
+ */
40
+ const bus = AxonBus()
41
+
42
+ // The log is opened BEFORE the agent exists, so a boot that fails still
43
+ // leaves a readable record of how far it got.
44
+ const session = await AxonSession({
45
+ blueprint: { ...opts.blueprint, session: { id: opts.sessionId } } as AxonBlueprint,
46
+ bus,
47
+ })
48
+
49
+ /**
50
+ * Roles resolved ONCE, on this side.
51
+ *
52
+ * The agent never resolves a role: resolution means reaching the user's
53
+ * providers over the network and building a driver from a credential,
54
+ * which is exactly the work the boundary exists to keep out of the box.
55
+ */
56
+ const engines = await Inference({ blueprint: opts.blueprint, cloud: opts.cloud, session })
57
+
58
+ return {
59
+ session,
60
+
61
+ /**
62
+ * The resolved inference roles — the SUPERVISOR's, because it is the
63
+ * side that holds the credential and did the resolving.
64
+ *
65
+ * Exposed so a model switch can rebind the live binding. `setModel`
66
+ * reached for `runtime.kernel.engines`, which exists only for an
67
+ * in-heap agent: for a linked one it was null, the rebind silently did
68
+ * nothing, and the header had no resolved capability to render.
69
+ */
70
+ engines,
71
+
72
+ /**
73
+ * The primary role's resolved binding, flattened for the wire.
74
+ *
75
+ * The agent cannot compute this: resolving needs the credential,
76
+ * which is the one thing the boundary keeps on this side. So the
77
+ * answer is carried on the blueprint (see AxonBlueprint.engine) and
78
+ * `/_axon/health` reports it from there rather than from a kernel
79
+ * that, for a confined agent, has no engines at all.
80
+ *
81
+ * Null for a cognet with no roles or no primary — a pure control loop
82
+ * genuinely has no model.
83
+ */
84
+ get engine(): { provider: string; model: string | null } | null {
85
+ const bound = engines?.resolution.bound
86
+ if (!bound?.length) return null
87
+
88
+ const primary = bound.find(entry => entry.requirement.primary)
89
+ ?? bound.find(entry => entry.role === "main")
90
+ if (!primary) return null
91
+
92
+ return { provider: primary.capability.provider, model: primary.capability.id }
93
+ },
94
+
95
+ /** Where a surface watches this agent — the linked counterpart of runtime.bus. */
96
+ bus,
97
+
98
+ /** One inference call, performed here, streamed back as raw deltas. */
99
+ async *infer(call: InferCall, signal: AbortSignal): AsyncGenerator<AxonEngineRawEvent> {
100
+ const bound = engines?.get(call.role)
101
+ if (!bound) {
102
+ throw err("ENGINE_ROLE_UNBOUND_LINK", { detail: `no engine bound to "${call.role}"`, context: { role: call.role } })
103
+ }
104
+ const driver = bound.driver
105
+ if (driver.kind !== undefined && driver.kind !== "generate") {
106
+ throw err("ENGINE_KIND_MISMATCH_LINK", { detail: `role "${call.role}" is bound to a ${driver.kind} driver`, context: { role: call.role, kind: driver.kind } })
107
+ }
108
+ for await (const event of driver.stream({ ...call.request, signal } as never)) {
109
+ if (signal.aborted) break
110
+ yield event
111
+ }
112
+ },
113
+
114
+ async close() {
115
+ await session.end()
116
+ },
117
+ }
118
+ }
119
+
120
+ export type SupervisorSideServicesT = Awaited<ReturnType<typeof SupervisorSideServices>>
@@ -0,0 +1,293 @@
1
+ import type { FrameworkSource } from "./build/project/manifest/package"
2
+ import { Store, storeRoot } from "./services/store"
3
+ import { Ollama } from "./services/ollama"
4
+ import { Mic } from "./services/mic"
5
+ import { Files } from "./services/files"
6
+ import { Cloud } from "./services/cloud"
7
+ import { Deployments } from "./services/deployments"
8
+ import { Projects } from "./build/project"
9
+ import { Profile, Runtime } from "./build/runtime"
10
+ import type { AgentSupervisor } from "./build/runtime/instances"
11
+ import { Extensions, ProfileConfigFile } from "./build/extensions"
12
+ import { Resources } from "./services/resources"
13
+
14
+ import { TestRunner } from "./services/test"
15
+ import { Registry, PromptCache } from "./services/registry"
16
+ import { Prompts } from "./services/prompts"
17
+ import { Updates } from "./services/update"
18
+ import { join, resolve } from "node:path"
19
+ import type { Distribution } from "./services/cloud"
20
+ import type { ProviderEntry } from "@arcforge/types"
21
+
22
+ const BUILD_DISTRIBUTION: Distribution = process.env.NODE_ENV === "production" ? "production" : "development"
23
+
24
+ /**
25
+ * Platform — the composition root of the Axon developer platform.
26
+ * Headless: no terminal, no reactivity, no prompts. The TUI and the Fleet
27
+ * extension are I/O adapters over this one object.
28
+ *
29
+ * Owns exactly the process-lifetime state:
30
+ * store — ~/.axon (credentials, settings, caches)
31
+ * cloud — a real AxonCloud client plus disk wiring (profiles, providers)
32
+ * projects — every project kind: find, open, create, prepare, publish
33
+ * profile — the user's own directory (main.ts, plugins, extensions)
34
+ * agents — every agent running on this machine, and the focused one
35
+ * ollama — local models: what's installed, what's available, pulling more
36
+ * tests — native Bun execution projected into structured lifecycle events
37
+ * plus the domain operations both surfaces invoke.
38
+ *
39
+ * Anything stateless (Blueprint, Capsule, Air, core) is a library the
40
+ * operations import — Platform does not re-export the world.
41
+ */
42
+ export function Platform(opts: PlatformOpts) {
43
+ const cwd = resolve(opts.cwd ?? process.cwd())
44
+ const distribution = opts.distribution ?? BUILD_DISTRIBUTION
45
+
46
+ /**
47
+ * Settings live in `profile.config.ts`, which only build/extensions can
48
+ * read — and Extensions is constructed further down, in terms of the very
49
+ * store being built here. So the store takes thunks and the binding is
50
+ * completed once both exist.
51
+ *
52
+ * A cached synchronous snapshot, because `extraRoots()` is synchronous and
53
+ * every caller of it is: parsing TypeScript per call, on a path resolved
54
+ * during an agent scan, is not something to do lazily.
55
+ */
56
+ let settingsCache: { paths?: string[] } = {}
57
+
58
+ const store = Store({
59
+ root: opts.store ?? storeRoot(distribution),
60
+ settings: () => settingsCache,
61
+ setSetting: async (key, value) => {
62
+ const result = await extensions.setSetting(key, value)
63
+ await refreshSettings()
64
+ return result
65
+ },
66
+ })
67
+ const cloud = Cloud({ store: store, distribution: distribution })
68
+
69
+ const ollama = Ollama() // local models via the Ollama daemon
70
+ const mic = Mic() // mic capture + visualizer service
71
+ // The user's working tree, for referencing paths by hand. Rooted at the
72
+ // invocation directory rather than at any agent's project: `@` means "a
73
+ // file in what I'm working on", and an agent lives under ~/.axon.
74
+ const files = Files({ root: cwd })
75
+ const tests = TestRunner() // standalone event-based Bun runner
76
+
77
+ // A bench project's `agent` axis may name a registry ref, which has to be
78
+ // fetched and prepared before any cell can boot — so a bench needs both
79
+ // the registry and project preparation. Both are defined below in terms of
80
+ // `projects`, so they arrive as thunks rather than values: construction is
81
+ // wiring, and nothing here calls anything.
82
+ /**
83
+ * The active profile's declared inference sources.
84
+ *
85
+ * ASYNC because reading them evaluates the user's own `profile.config.ts`
86
+ * — the same single evaluator the extension loader uses, so the two can
87
+ * never disagree about what a profile declares. Read per prepare rather
88
+ * than cached: a profile switch or a config edit must be visible on the
89
+ * next agent boot, and prepare is already doing far more expensive work.
90
+ *
91
+ * Silent on failure by design. A broken profile config reports through
92
+ * the extension loader, which owns telling a user their config is wrong;
93
+ * a second message from here would only make the first one ambiguous.
94
+ */
95
+ async function profileProviders(): Promise<readonly ProviderEntry[] | undefined> {
96
+ const root = store.profiles.active()?.root
97
+ if (!root) return undefined
98
+ const { providers } = await ProfileConfigFile(root)
99
+ // Undefined travels: it means "never configured", which the pool
100
+ // answers with the default. Returning [] here would tell every
101
+ // profile written before this field existed that it has no inference.
102
+ return providers
103
+ }
104
+
105
+ /**
106
+ * This machine's local-inference capacity and what is holding it.
107
+ *
108
+ * Constructed here because it is machine state every surface shares: the
109
+ * TUI shows it, Fleet lists it, and a provider consults it before loading
110
+ * weights. The budget is read from the active profile per call — a user
111
+ * who raises their ceiling must not have to restart the terminal.
112
+ */
113
+ const resources = Resources({
114
+ budget: () => undefined,
115
+ })
116
+
117
+ const projects = Projects({
118
+ cloud: cloud.client,
119
+ // Read fresh per call, never captured: the active profile changes
120
+ // while the process runs, and every agent prepared afterwards must
121
+ // see the new user's providers rather than the boot-time one's.
122
+ profileProviders: () => profileProviders(),
123
+ frameworkVersion: opts.version,
124
+ ...(opts.frameworkSource ? { frameworkSource: opts.frameworkSource } : {}),
125
+ ...(opts.repoRoot ? { repoRoot: opts.repoRoot } : {}),
126
+ bench: {
127
+ tests: tests,
128
+ clone: (ref, cwd, options) => registry.clone(ref, cwd, options),
129
+ prepare: async root => { await (await projects.open(root)).prepare() },
130
+ },
131
+ }) // project management, every kind
132
+
133
+ // `clone` arrives as a thunk for the same reason the bench axis does:
134
+ // `registry` is constructed below, in terms of `projects`.
135
+ const agents = Runtime({
136
+ ...(opts.daemon ? { daemon: opts.daemon } : {}),
137
+ store: store,
138
+ projects: projects,
139
+ cloud: cloud.client,
140
+ cwd: cwd,
141
+ clone: (ref, cwd, options) => registry.clone(ref, cwd, options),
142
+ ...(opts.control ? { control: opts.control } : {}),
143
+ }) // every agent running on this machine
144
+
145
+ const registry = Registry({
146
+ cloud: cloud.client,
147
+ async prepare(root) {
148
+ // Clone resolves across the shared namespace, so a cloned artifact
149
+ // may be an agent, module, cognet or bench. project.prepare() is
150
+ // kind-aware — let it dispatch on what was actually cloned.
151
+ const project = await projects.open(root)
152
+ await project.prepare()
153
+ },
154
+ }) // immutable registry source retrieval
155
+
156
+ // Prompts are fetched to a machine-wide cache and rendered off that path —
157
+ // never installed into an agent. See services/prompts.ts.
158
+ const prompts = Prompts({ cache: PromptCache({ cloud: cloud.client, root: store.root }) })
159
+
160
+ const updates = Updates({ cloud: cloud.client, store: store, currentVersion: opts.version })
161
+ const deployments = Deployments({ cloud: cloud.client }) // the user's deployed agents, cached
162
+
163
+ // The user's own directory, as a project. Beside `projects` rather than
164
+ // inside `agents`: Runtime() is every agent running on this machine, and a
165
+ // profile is not an agent — it is where a person configures the terminal.
166
+ const profile = Profile({ store: store, projects: projects, frameworkVersion: opts.version })
167
+
168
+ // The user's TUI config — their main.ts and plugins/, plus the extensions
169
+ // they enable. A thunk for `install` for the same reason zeno's clone is
170
+ // one: registry is constructed below, in terms of projects.
171
+ /**
172
+ * Re-read the config's settings into the cache.
173
+ *
174
+ * Called after every write here, and by the TUI after every config load —
175
+ * so a hand edit takes effect on save exactly like a `:` command does.
176
+ */
177
+ async function refreshSettings(): Promise<void> {
178
+ // No profile yet (a first boot before login) is a real "nothing is
179
+ // declared", not a failure — there is no config to read.
180
+ if (!store.profiles.active()) {
181
+ settingsCache = {}
182
+ return
183
+ }
184
+ // Deliberately NOT caught. An unreadable profile.config.ts used to
185
+ // land here as an empty cache, which made "your config is broken"
186
+ // and "your config declares nothing" the same observable state —
187
+ // and that is precisely how a declared `paths` entry could silently
188
+ // stop being scanned. The loader owns explaining the breakage; this
189
+ // owns not pretending it did not happen.
190
+ settingsCache = (await extensions.settings()) as { paths?: string[] }
191
+ }
192
+
193
+ const extensions = Extensions({
194
+ root: () => profile.root,
195
+ install: async (ref, dir) => {
196
+ // The resolved version comes back from the registry and is handed
197
+ // up so the caller can PIN it — both in the config entry and as
198
+ // the directory the shared store files it under. Without it the
199
+ // install would have to guess, and a pin that guesses is not a pin.
200
+ const cloned = await registry.clone(ref, join(dir, ".."), { dir: dir.split("/").at(-1)! })
201
+ return { version: cloned.version }
202
+ },
203
+ // Resolution only — no download, no write. `updates()` asks what the
204
+ // registry publishes; installing it stays a separate, explicit act.
205
+ latest: async name => (await cloud.client.registry.artifacts.resolve(name)).version,
206
+ })
207
+
208
+ return {
209
+ cloud: cloud,
210
+ store: store,
211
+ deployments: deployments,
212
+ projects: projects,
213
+ profile: profile,
214
+ extensions: extensions,
215
+ /**
216
+ * Re-read `profile.config.ts` settings into the store's cache.
217
+ *
218
+ * Called by whoever loads the config — every load, including the
219
+ * watcher's. Without it, `paths` added by hand would not be scanned
220
+ * until the next process start.
221
+ */
222
+ refreshSettings: refreshSettings,
223
+ agents: agents,
224
+ registry: registry,
225
+ prompts: prompts,
226
+ tests: tests,
227
+ mic: mic,
228
+ files: files,
229
+ ollama: ollama,
230
+ /** This machine's local-inference capacity, and what is holding it. */
231
+ resources: resources,
232
+ updates: updates,
233
+ }
234
+ }
235
+
236
+ export type PlatformT = ReturnType<typeof Platform>
237
+
238
+ type PlatformOpts = {
239
+ /**
240
+ * Who supervises a spawned agent.
241
+ *
242
+ * The platform no longer supervises. Everything about BUILDING an agent
243
+ * still lives here — resolve, prepare, blueprint.load — and the moment
244
+ * there is a process to boot, that is the daemon's.
245
+ *
246
+ * OPTIONAL, and `spawn` is what refuses when it is absent. Most consumers
247
+ * of a Platform never boot an agent — they read the store, publish a
248
+ * project, browse the registry — and requiring a supervisor for those
249
+ * would make every one of them construct a daemon it will not use.
250
+ *
251
+ * Deliberately NOT defaulted to a locally-built one. That would look
252
+ * convenient and would silently put the credential back in whichever
253
+ * process happened to call spawn, which is exactly what moved out.
254
+ */
255
+ daemon?: AgentSupervisor
256
+ /**
257
+ * The consuming app's version (the TUI's package.json version, the
258
+ * Fleet extension's, …). Injected rather than read from this
259
+ * package's own manifest: it is stamped into created projects as
260
+ * their framework version and reported by the updater, so it must be
261
+ * the shipped app's version, not the library's.
262
+ */
263
+ version: string
264
+ /**
265
+ * Where a scaffolded project's framework dependencies resolve from.
266
+ *
267
+ * Defaults to "published" — the exact CLI version, which is what a real
268
+ * user installs. The TEST SUITE passes "workspace" with a repoRoot, so a
269
+ * fixture links this repo's tree instead of npm and the suite validates
270
+ * the commit rather than the last release. See FrameworkSource.
271
+ */
272
+ frameworkSource?: FrameworkSource
273
+ /** Repo root for "workspace" resolution. Required with it, ignored without. */
274
+ repoRoot?: string
275
+ /** Override the store root (~/.axon) — tests point this at a scratch dir. */
276
+ store?: string
277
+ /** Invocation directory inherited by every agent capsule booted by this platform. */
278
+ cwd?: string
279
+ /** Build distribution override for tests. Normal callers use the compile-time default. */
280
+ distribution?: Distribution
281
+
282
+ /**
283
+ * The local control channel this process serves, published on every
284
+ * instance record it spawns so an editor can find and dial it.
285
+ *
286
+ * Supplied by the app that HAS one — the TUI serves conversations an
287
+ * editor can drive; a headless `axon run` does not and passes nothing.
288
+ * A thunk because the server binds a port and Platform() construction is
289
+ * wiring only: the app starts listening when it is ready, and each spawn
290
+ * reads whatever is live at that moment.
291
+ */
292
+ control?: () => { port: number; token: string } | null
293
+ }
@@ -0,0 +1,15 @@
1
+ /**
2
+ * procs — the process tree of every agent on this machine.
3
+ *
4
+ * `procTree()` folds a session's event log into the tree any surface renders.
5
+ * It is pure and source-agnostic by construction, which is the whole reason it
6
+ * lives here rather than inside the capsule: the TUI used to build this by
7
+ * reaching through `runtime.kernel.userland` into a live capsule handle, so an
8
+ * attached deployment's process list was structurally always empty.
9
+ *
10
+ * The supervisor half — spawning and confining the agent processes themselves —
11
+ * is `build/runtime/instances.ts`. These two are one tree conceptually (an
12
+ * agent process, and the children it spawned) and become one manager when the
13
+ * agent boundary moves out to the whole process.
14
+ */
15
+ export { procTree, appendOutput, type ProcNode, type ProcLogEvent } from "./tree"
@@ -0,0 +1,177 @@
1
+ import type { AxonEventMap, CapsuleEventMap } from "@arcforge/types"
2
+
3
+ /**
4
+ * One process in an agent's tree, as any surface renders it.
5
+ *
6
+ * `main` is the agent's own runtime — the root every other row hangs under.
7
+ * Everything else is something the agent spawned: `managed` for a live handle
8
+ * (process.spawn), `run` for a blocking command (process.run).
9
+ *
10
+ * "down" is distinct from "exited": an exited process reported a code, a
11
+ * process that is down was alive when its agent stopped reporting. A remote
12
+ * agent that goes unreachable leaves rows in exactly that state, and calling
13
+ * them "exited" would invent an exit nobody observed.
14
+ */
15
+ export type ProcNode = {
16
+ procId: string
17
+ kind: "main" | "managed" | "run"
18
+ command: string
19
+ pid?: number
20
+ cwd?: string
21
+ status: "running" | "exited" | "down"
22
+ exitCode?: number
23
+ startedAt: number
24
+ endedAt?: number
25
+ /** The agent's own runtime — parent of every other row. */
26
+ main?: boolean
27
+ /** Last buffered output lines (stdout+stderr merged), oldest first. */
28
+ output: string[]
29
+ }
30
+
31
+ /**
32
+ * The envelope shape this fold reads.
33
+ *
34
+ * Deliberately structural rather than `AxonKernelEvent`: capsule events are
35
+ * classified INTO kernelLog at runtime (isKernelEvent matches "capsule:"), but
36
+ * `AxonKernelEvent` is typed from AxonKernelEventMap alone, so the declared
37
+ * type of that array does not admit the events it actually holds. Reading the
38
+ * union of everything (AxonEventMap) and narrowing on `type` here keeps this
39
+ * honest without asserting the log is something it is not.
40
+ *
41
+ * That mismatch is worth fixing at the source — AxonKernelEvent should be
42
+ * derived from what isKernelEvent() accepts — but widening it touches every
43
+ * kernelLog consumer and does not belong in this change.
44
+ */
45
+ export type ProcLogEvent = {
46
+ [K in keyof AxonEventMap]: { type: K; at?: number; data: AxonEventMap[K] }
47
+ }[keyof AxonEventMap]
48
+
49
+ /** How many output lines a row retains. Bounded: a watcher left running for a day is not a memory leak. */
50
+ const OUTPUT_MAX = 200
51
+
52
+ /**
53
+ * Fold a session's event log into a process tree.
54
+ *
55
+ * PURE — events in, tree out. No handles, no live objects, no source
56
+ * awareness. That is the entire point: the TUI used to build this by reaching
57
+ * through `runtime.kernel.userland` into the live capsule handle, which works
58
+ * only for an agent running in this process. A deployment's process list was
59
+ * therefore always empty, and the composable said so
60
+ * ("processes are local-only ... its own capsule's business").
61
+ *
62
+ * The session log already carried everything needed. `process:proc:start`,
63
+ * `:complete` and `:failed` are DURABLE events (only the byte streams are in
64
+ * CAPSULE_TRANSIENT_EVENTS), so a remote agent's mirrored log holds its
65
+ * process history — nothing was ever reading it. Folding the log instead of
66
+ * reading a handle makes local and remote the same code path, which is what
67
+ * Fleet already does for its flame graph.
68
+ *
69
+ * Byte streams are transient, so `output` fills only from live bus events. A
70
+ * mirrored remote log yields correct rows with empty output, which is honest:
71
+ * that output was never persisted anywhere to recover.
72
+ */
73
+ export function procTree(
74
+ events: readonly ProcLogEvent[],
75
+ opts?: {
76
+ /** The agent's own runtime, when the caller knows it — becomes the `main` row. */
77
+ main?: { pid?: number; status: "running" | "exited" | "down"; startedAt?: number }
78
+ },
79
+ ): ProcNode[] {
80
+ const byId = new Map<string, ProcNode>()
81
+
82
+ for (const event of events) {
83
+ switch (event.type) {
84
+ case "process:proc:start": {
85
+ const data = event.data as { procId: string; pid: number; command: string; cwd: string; kind: "managed" | "run" }
86
+ byId.set(data.procId, {
87
+ procId: data.procId,
88
+ kind: data.kind,
89
+ command: data.command,
90
+ pid: data.pid,
91
+ cwd: data.cwd,
92
+ status: "running",
93
+ startedAt: typeof event.at === "number" ? event.at : Date.now(),
94
+ output: [],
95
+ })
96
+ break
97
+ }
98
+ case "process:proc:complete": {
99
+ const data = event.data as { procId: string; code: number }
100
+ const node = byId.get(data.procId)
101
+ if (!node) break
102
+ node.status = "exited"
103
+ node.exitCode = data.code
104
+ if (typeof event.at === "number") node.endedAt = event.at
105
+ break
106
+ }
107
+ case "process:proc:failed": {
108
+ // The span BROKE rather than settled — the child never produced
109
+ // an exit code. Recording a fabricated one would claim an
110
+ // observation nobody made; the row is exited with none.
111
+ const data = event.data as { procId: string }
112
+ const node = byId.get(data.procId)
113
+ if (!node) break
114
+ node.status = "exited"
115
+ if (typeof event.at === "number") node.endedAt = event.at
116
+ break
117
+ }
118
+ case "process:proc:denied": {
119
+ // Nothing ever started, so there is no span to close. The row
120
+ // exists so a caller awaiting the handle settles rather than
121
+ // hanging, and so a refusal is visible rather than silent.
122
+ const data = event.data as { procId: string; command: string }
123
+ const existing = byId.get(data.procId)
124
+ if (existing) {
125
+ existing.status = "exited"
126
+ existing.exitCode = -1
127
+ break
128
+ }
129
+ byId.set(data.procId, {
130
+ procId: data.procId,
131
+ kind: "managed",
132
+ command: data.command,
133
+ status: "exited",
134
+ exitCode: -1,
135
+ startedAt: typeof event.at === "number" ? event.at : Date.now(),
136
+ output: [],
137
+ })
138
+ break
139
+ }
140
+ }
141
+ }
142
+
143
+ const children = [...byId.values()].sort((a, b) => a.startedAt - b.startedAt)
144
+ if (!opts?.main) return children
145
+
146
+ return [
147
+ {
148
+ procId: "main",
149
+ kind: "main",
150
+ command: "agent · ts runtime",
151
+ ...(opts.main.pid !== undefined ? { pid: opts.main.pid } : {}),
152
+ status: opts.main.status,
153
+ startedAt: opts.main.startedAt ?? children[0]?.startedAt ?? Date.now(),
154
+ main: true,
155
+ output: [],
156
+ },
157
+ ...children,
158
+ ]
159
+ }
160
+
161
+ /**
162
+ * Append a live byte-stream chunk to a row's output.
163
+ *
164
+ * Separate from the fold because these events are TRANSIENT — they never reach
165
+ * the log, so they can only arrive from a live bus. A surface watching a local
166
+ * agent calls this from its bus subscription; a surface reading a mirrored
167
+ * remote log simply never does, and gets correct rows with empty output.
168
+ */
169
+ export function appendOutput(tree: ProcNode[], procId: string, data: string): void {
170
+ const node = tree.find(entry => entry.procId === procId)
171
+ if (!node) return
172
+ for (const line of data.split(/\r?\n/)) {
173
+ if (!line) continue
174
+ node.output.push(line)
175
+ }
176
+ if (node.output.length > OUTPUT_MAX) node.output.splice(0, node.output.length - OUTPUT_MAX)
177
+ }