@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,220 @@
1
+ import { execFile } from "node:child_process"
2
+ import { createHash } from "node:crypto"
3
+ import { existsSync } from "node:fs"
4
+ import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises"
5
+ import { basename, join, resolve } from "node:path"
6
+ import type { AxonCloudClient } from "@arcforge/cloud"
7
+ import { err } from "@arcforge/err"
8
+ import { parseSpecifier } from "../build/project/specifier"
9
+
10
+ /**
11
+ * Registry source retrieval. This deliberately has no repository semantics:
12
+ * it resolves one immutable published artifact and materializes it once.
13
+ * Git history, remotes, updates, and merges remain Git's job.
14
+ */
15
+ /**
16
+ * PromptCache — published prompts on disk, machine-wide, never installed into
17
+ * an agent.
18
+ *
19
+ * A prompt is CONTENT, not code: nothing links against it, it has no ABI, and
20
+ * it has no runtime presence in the agent. Installing one used to mean a
21
+ * registry resolve, a full node_modules rewrite, a lockfile change, an
22
+ * axon.config.ts edit and an agent reload — about a second of churn, and a
23
+ * permanent dependency — to obtain a few KB of text. Worse, the tree rewrite
24
+ * raced the agent's own file watcher, so a reload could fire while
25
+ * @arcforge/cognet was momentarily absent and report a compile failure for an
26
+ * install that actually succeeded.
27
+ *
28
+ * So prompts are fetched here instead: content-addressed by name and version
29
+ * under ~/.axon/cache/prompts/, shared by every agent on the machine, and
30
+ * rendered straight off that path. Rendering still happens IN the focused
31
+ * agent's runtime — that is what gives a template its `axon` handle and the
32
+ * agent's own resolved env (see core's promptContext) — but the runtime only
33
+ * ever needed an absolute filePath, never a node_modules entry, which is the
34
+ * coupling this removes.
35
+ *
36
+ * Versioned rather than a mutable "latest" directory: a cached render stays
37
+ * reproducible, and an upgrade is a new directory rather than a silent change
38
+ * under a prompt the user already trusts.
39
+ */
40
+ export function PromptCache(opts: { cloud: AxonCloudClient; root: string }) {
41
+ /** ~/.axon/cache/prompts/<scope>/<name>/<version>/ */
42
+ function pathFor(name: string, version: string): string {
43
+ return join(opts.root, "cache", "prompts", ...name.split("/"), version)
44
+ }
45
+
46
+ return {
47
+ /**
48
+ * The local directory for a published prompt, downloading it only if
49
+ * this machine has never fetched that exact version.
50
+ *
51
+ * Resolution still goes to the registry (that is what turns "@axon/tdd"
52
+ * into a version), so a first use needs the network; the payload
53
+ * fetch is what the cache skips. A prompt fetched once renders offline
54
+ * forever after.
55
+ */
56
+ async ensure(ref: string): Promise<{ name: string; version: string; root: string }> {
57
+ if (!ref) throw err("CLONE_REF_REQUIRED")
58
+
59
+ const { name, version: requested } = parseSpecifier(ref)
60
+ const resolved = await opts.cloud.registry.resolve(name, requested)
61
+ const target = pathFor(resolved.name, resolved.version)
62
+
63
+ if (!existsSync(target) || (await readdir(target)).length === 0) {
64
+ await extract(await download(resolved.downloadUrl), target)
65
+ }
66
+
67
+ return { name: resolved.name, version: resolved.version, root: target }
68
+ },
69
+
70
+ /** Every version of every prompt already on disk — what renders with no network. */
71
+ async cached(): Promise<{ name: string; version: string; root: string }[]> {
72
+ const base = join(opts.root, "cache", "prompts")
73
+ if (!existsSync(base)) return []
74
+
75
+ const found: { name: string; version: string; root: string }[] = []
76
+ // <scope>/<name>/<version> — scopes are always present, since the
77
+ // registry refuses unscoped artifact names.
78
+ for (const scope of await readdir(base)) {
79
+ for (const pkg of await readdir(join(base, scope)).catch(() => [])) {
80
+ for (const version of await readdir(join(base, scope, pkg)).catch(() => [])) {
81
+ found.push({ name: `${scope}/${pkg}`, version, root: join(base, scope, pkg, version) })
82
+ }
83
+ }
84
+ }
85
+ return found
86
+ },
87
+ }
88
+ }
89
+
90
+ export type PromptCacheT = ReturnType<typeof PromptCache>
91
+
92
+ export function Registry(opts: { cloud: AxonCloudClient; prepare(root: string): Promise<void> }) {
93
+ async function clone(ref: string, cwd: string, options: { dir?: string } = {}) {
94
+ if (!ref) throw err("CLONE_REF_REQUIRED")
95
+
96
+ const { name, version: requestedVersion } = parseSpecifier(ref)
97
+ const resolved = await opts.cloud.registry.resolve(name, requestedVersion)
98
+ const target = resolve(cwd, options.dir ?? directoryName(resolved.name))
99
+ await extract(await download(resolved.downloadUrl), target)
100
+ await opts.prepare(target)
101
+
102
+ return { ...resolved, root: target }
103
+ }
104
+
105
+ async function fork(ref: string, cwd: string, options: { as?: string; dir?: string } = {}) {
106
+ if (!options.as) throw err("FORK_NAME_REQUIRED")
107
+
108
+ if (!ref) throw err("FORK_REF_REQUIRED")
109
+ const { name, version: requestedVersion } = parseSpecifier(ref)
110
+ const resolved = await opts.cloud.registry.resolve(name, requestedVersion)
111
+ const target = resolve(cwd, options.dir ?? directoryName(options.as))
112
+ await extract(await download(resolved.downloadUrl), target)
113
+
114
+ const cloneResult = { ...resolved, root: target }
115
+ const packagePath = join(cloneResult.root, "package.json")
116
+ const raw = JSON.parse(await readFile(packagePath, "utf-8")) as Record<string, unknown>
117
+ const previousAxon = raw.axon && typeof raw.axon === "object" && !Array.isArray(raw.axon)
118
+ ? raw.axon as Record<string, unknown>
119
+ : {}
120
+
121
+ raw.name = options.as
122
+ raw.version = "0.1.0"
123
+ raw.axon = {
124
+ ...previousAxon,
125
+ forkedFrom: { name: cloneResult.name, version: cloneResult.version },
126
+ }
127
+ await writeFile(packagePath, JSON.stringify(raw, null, 2) + "\n")
128
+ await opts.prepare(target)
129
+
130
+ return { ...cloneResult, name: options.as, version: "0.1.0" }
131
+ }
132
+
133
+ return { clone, fork }
134
+ }
135
+
136
+ export type RegistryT = ReturnType<typeof Registry>
137
+
138
+ function directoryName(name: string): string {
139
+ return basename(name)
140
+ }
141
+
142
+ /**
143
+ * Runs `tar`, returning its result rather than throwing on a non-zero exit
144
+ * — the caller distinguishes "listing failed" from "extraction failed".
145
+ *
146
+ * node:child_process rather than Bun.$: this module is reached from the
147
+ * Fleet extension host, which runs Node, and `Bun` is simply undefined
148
+ * there. The platform's own header calls the TUI and the extension "I/O
149
+ * adapters over this one object", which is only true if the object itself
150
+ * is runtime-portable — a Bun builtin on the clone path made it false, and
151
+ * clone threw for one of the two adapters.
152
+ */
153
+ function tar(args: string[]): Promise<{ exitCode: number; stdout: string; stderr: string }> {
154
+ return new Promise(resolve => {
155
+ execFile("tar", args, { maxBuffer: 64 * 1024 * 1024 }, (error, stdout, stderr) => {
156
+ resolve({
157
+ // execFile reports a spawn failure (no tar on PATH) with no
158
+ // code — 1 keeps that an ordinary failure for the caller.
159
+ exitCode: error ? (typeof error.code === "number" ? error.code : 1) : 0,
160
+ stdout,
161
+ stderr: stderr || (error ? error.message : ""),
162
+ })
163
+ })
164
+ })
165
+ }
166
+
167
+ async function download(url: string): Promise<ArrayBuffer> {
168
+ const response = await fetch(url)
169
+ if (!response.ok) {
170
+ throw err("ARTIFACT_DOWNLOAD_FAILED", {
171
+ detail: `${response.status} ${response.statusText}`,
172
+ context: { status: response.status },
173
+ })
174
+ }
175
+ return response.arrayBuffer()
176
+ }
177
+
178
+ async function extract(buffer: ArrayBuffer, target: string): Promise<void> {
179
+ let created = false
180
+ if (existsSync(target)) {
181
+ if ((await readdir(target)).length > 0) {
182
+ throw err("CLONE_TARGET_EXISTS", { detail: `${target} is not empty`, context: { target } })
183
+ }
184
+ } else {
185
+ await mkdir(target, { recursive: true })
186
+ created = true
187
+ }
188
+
189
+ const archive = join(target, `.axon-clone-${createHash("sha256").update(new Uint8Array(buffer)).digest("hex")}.tar.gz`)
190
+ try {
191
+ await writeFile(archive, new Uint8Array(buffer))
192
+
193
+ // npm tarballs nest everything under a single "package/" directory and
194
+ // every package manager strips exactly that component on extract (see
195
+ // Stage()'s own comment). Modules and cognets are staged that way
196
+ // so `bun add` can install them; agent bundles are not. Detect which
197
+ // shape this archive is rather than assuming, so one extractor handles
198
+ // both — without this, a cloned module landed at <target>/package/ and
199
+ // `prepare` reported PROJECT_NOT_FOUND at a directory that looked empty.
200
+ const listing = await tar(["-tzf", archive])
201
+ const paths = listing.stdout.split("\n").filter(Boolean)
202
+ const npmPrefixed = paths.length > 0 && paths.every(entry => entry === "package/" || entry.startsWith("package/"))
203
+
204
+ const result = npmPrefixed
205
+ ? await tar(["-xzf", archive, "-C", target, "--strip-components=1"])
206
+ : await tar(["-xzf", archive, "-C", target])
207
+ if (result.exitCode !== 0) {
208
+ throw err("ARTIFACT_EXTRACT_FAILED", {
209
+ detail: result.stderr.trim(),
210
+ context: { exitCode: result.exitCode },
211
+ })
212
+ }
213
+ } catch (error) {
214
+ // A failed extraction must not leave a half-project that then blocks retry.
215
+ if (created) await rm(target, { recursive: true, force: true })
216
+ throw error
217
+ } finally {
218
+ await rm(archive, { force: true })
219
+ }
220
+ }
@@ -0,0 +1,125 @@
1
+ import { totalmem } from "node:os"
2
+
3
+ /**
4
+ * What this machine can offer local inference.
5
+ *
6
+ * PROBED, never assumed, and honest about not knowing. There is no portable
7
+ * API for video memory: NVIDIA answers through nvidia-smi, Apple silicon
8
+ * shares system memory with the GPU, and AMD/Intel on Linux report through
9
+ * sysfs paths that vary by driver. So `vram` is `undefined` on a machine we
10
+ * cannot measure, and every consumer has to handle that rather than reading
11
+ * a fabricated zero.
12
+ *
13
+ * UNKNOWN MEANS UNBOUNDED, never empty. A probe that failed and a card with
14
+ * no free memory are opposite facts, and treating the first as the second
15
+ * would refuse every local model on any machine we cannot read — which is
16
+ * most of them. The user's declared budget is what governs where we cannot
17
+ * measure.
18
+ */
19
+
20
+ export type Hardware = {
21
+ /** Total video memory in bytes. Undefined when unmeasurable — never zero. */
22
+ vram?: number
23
+ /** Total system memory in bytes. Always known. */
24
+ ram: number
25
+ /** How `vram` was learned, for a surface that wants to say so. */
26
+ source: "nvidia" | "apple" | "unknown"
27
+ }
28
+
29
+ /** Bytes, from an nvidia-smi MiB figure. */
30
+ function fromMiB(text: string): number | null {
31
+ const value = Number.parseInt(text.trim(), 10)
32
+ return Number.isFinite(value) && value > 0 ? value * 1024 * 1024 : null
33
+ }
34
+
35
+ /**
36
+ * NVIDIA's total video memory, through nvidia-smi.
37
+ *
38
+ * The tool ships with the driver, so its absence is the signal that there is
39
+ * no NVIDIA GPU here — not an error worth reporting. Multi-GPU machines
40
+ * report one line each; the FIRST is used rather than the sum, because a
41
+ * model loads onto one card and a total across cards would advertise room no
42
+ * single load can use.
43
+ */
44
+ function nvidiaVram(): number | null {
45
+ try {
46
+ const probe = Bun.spawnSync([
47
+ "nvidia-smi",
48
+ "--query-gpu=memory.total",
49
+ "--format=csv,noheader,nounits",
50
+ ])
51
+ if (probe.exitCode !== 0) return null
52
+
53
+ const first = probe.stdout.toString().trim().split("\n")[0]
54
+ return first ? fromMiB(first) : null
55
+ } catch {
56
+ return null
57
+ }
58
+ }
59
+
60
+ /**
61
+ * Apple silicon shares one pool between CPU and GPU.
62
+ *
63
+ * So "video memory" is a fraction of system memory rather than a separate
64
+ * number — macOS lets the GPU address most of it but not all, and the exact
65
+ * ceiling is a driver detail that moves. Two thirds is deliberately
66
+ * conservative: over-reporting here means accepting a load that then thrashes
67
+ * the whole machine, which is worse than refusing one that would have fit.
68
+ */
69
+ function appleVram(): number | null {
70
+ if (process.platform !== "darwin") return null
71
+ return Math.floor(totalmem() * (2 / 3))
72
+ }
73
+
74
+ /**
75
+ * Read this machine once.
76
+ *
77
+ * Synchronous and cheap enough to call per boot: one subprocess on NVIDIA,
78
+ * arithmetic everywhere else. Not cached here — a caller that wants it cached
79
+ * holds it, and a long-running process re-reading after a driver change is a
80
+ * feature rather than a cost.
81
+ */
82
+ export function probeHardware(): Hardware {
83
+ const nvidia = nvidiaVram()
84
+ if (nvidia !== null) return { vram: nvidia, ram: totalmem(), source: "nvidia" }
85
+
86
+ const apple = appleVram()
87
+ if (apple !== null) return { vram: apple, ram: totalmem(), source: "apple" }
88
+
89
+ return { ram: totalmem(), source: "unknown" }
90
+ }
91
+
92
+ const UNITS: Record<string, number> = {
93
+ b: 1,
94
+ kb: 1024,
95
+ mb: 1024 ** 2,
96
+ gb: 1024 ** 3,
97
+ tb: 1024 ** 4,
98
+ }
99
+
100
+ /**
101
+ * `"8GB"` → bytes.
102
+ *
103
+ * Null for anything unparseable, which callers treat as "no ceiling declared"
104
+ * rather than as zero — see ResourceBudget. Accepts a bare number as bytes so
105
+ * a programmatic caller need not format a string it is about to have parsed.
106
+ */
107
+ export function parseSize(value: string | number | undefined): number | null {
108
+ if (value === undefined) return null
109
+ if (typeof value === "number") return Number.isFinite(value) && value > 0 ? value : null
110
+
111
+ const match = value.trim().toLowerCase().match(/^([\d.]+)\s*(b|kb|mb|gb|tb)?$/)
112
+ if (!match?.[1]) return null
113
+
114
+ const size = Number.parseFloat(match[1])
115
+ if (!Number.isFinite(size) || size <= 0) return null
116
+
117
+ return Math.floor(size * (UNITS[match[2] ?? "b"] ?? 1))
118
+ }
119
+
120
+ /** Bytes → `"7.4GB"`, for a surface that shows a person a number. */
121
+ export function formatSize(bytes: number): string {
122
+ if (bytes >= UNITS.gb!) return `${(bytes / UNITS.gb!).toFixed(1)}GB`
123
+ if (bytes >= UNITS.mb!) return `${Math.round(bytes / UNITS.mb!)}MB`
124
+ return `${bytes}B`
125
+ }
@@ -0,0 +1,6 @@
1
+ export { Resources } from "./resources"
2
+ export type { ResourcesT, ResourceState } from "./resources"
3
+ export { Reservations } from "./reservations"
4
+ export type { ReservationsT, Reservation } from "./reservations"
5
+ export { probeHardware, parseSize, formatSize } from "./hardware"
6
+ export type { Hardware } from "./hardware"
@@ -0,0 +1,162 @@
1
+ import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
2
+ import { homedir } from "node:os"
3
+ import { join } from "node:path"
4
+
5
+ /**
6
+ * What one agent is holding on this machine.
7
+ *
8
+ * MACHINE-WIDE, not per-process: two agents on one laptop share a GPU, and
9
+ * each keeping its own idea of free memory is precisely how both decide they
10
+ * have room for the same six gigabytes. So the state is on disk, one file per
11
+ * reservation, and every process reads the whole directory before deciding.
12
+ *
13
+ * Keyed by machine rather than by profile for the same reason. A budget is a
14
+ * fact about hardware; two profiles on one laptop are two accounts, not two
15
+ * GPUs.
16
+ */
17
+ export type Reservation = {
18
+ /** The holder — probed for liveness, so a dead one is self-clearing. */
19
+ pid: number
20
+ /** Which agent, for a surface that lists what is loaded. */
21
+ agent: string
22
+ /** The cognet role this serves — "asr", "vad". */
23
+ role: string
24
+ /** Model id, e.g. "onnx-community/whisper-base.en". */
25
+ model: string
26
+ /** Bytes held. */
27
+ bytes: number
28
+ /** When it was taken, unix ms. */
29
+ at: number
30
+ }
31
+
32
+ /**
33
+ * Where reservations live.
34
+ *
35
+ * Both store roots are READ, one is written — the same rule running/ follows
36
+ * and for the same reason: an installed CLI and a source build are different
37
+ * binaries describing the SAME machine, and an observer that saw only its own
38
+ * would report a GPU as free while the other binary's agent was using it.
39
+ */
40
+ const ROOTS = [
41
+ join(homedir(), ".axon", "cache", "resources"),
42
+ join(homedir(), ".axon-dev", "cache", "resources"),
43
+ ]
44
+
45
+ /** True if a process with this pid exists — probes, sends nothing. */
46
+ function isAlive(pid: number): boolean {
47
+ try {
48
+ process.kill(pid, 0)
49
+ return true
50
+ } catch {
51
+ return false
52
+ }
53
+ }
54
+
55
+ /**
56
+ * A record that fails to parse is treated as absent.
57
+ *
58
+ * Same posture as running/: a write torn mid-flush must not empty a reader's
59
+ * whole view, and the next write supersedes it. Being wrong here in the
60
+ * permissive direction risks over-committing memory once; being wrong in the
61
+ * strict direction breaks every reader on one bad file.
62
+ */
63
+ function read(path: string): Reservation | null {
64
+ try {
65
+ const record = JSON.parse(readFileSync(path, "utf-8")) as Reservation
66
+ return typeof record.pid === "number" && typeof record.bytes === "number" ? record : null
67
+ } catch {
68
+ return null
69
+ }
70
+ }
71
+
72
+ export type ReservationsOpts = {
73
+ /** Where this process WRITES. Reads always span every root. */
74
+ root?: string
75
+ }
76
+
77
+ export function Reservations(opts: ReservationsOpts = {}) {
78
+ const writeRoot = opts.root ?? ROOTS[1]!
79
+
80
+ function ensure(): string {
81
+ mkdirSync(writeRoot, { recursive: true })
82
+ return writeRoot
83
+ }
84
+
85
+ /**
86
+ * Every live reservation on this machine.
87
+ *
88
+ * Dead holders are REAPED as they are found rather than by a background
89
+ * sweep: every reader already has to probe liveness to answer honestly,
90
+ * so cleaning up while it looks costs nothing and means no reaper exists
91
+ * to fail. A process killed with -9 releases its memory to the driver
92
+ * immediately; this makes the record agree.
93
+ */
94
+ function live(): Reservation[] {
95
+ const found: Reservation[] = []
96
+
97
+ for (const root of new Set([...ROOTS, writeRoot])) {
98
+ if (!existsSync(root)) continue
99
+
100
+ for (const name of readdirSync(root)) {
101
+ const path = join(root, name)
102
+ const record = read(path)
103
+
104
+ if (!record || !isAlive(record.pid)) {
105
+ // Best-effort: another process reaping the same record at
106
+ // the same moment is the ordinary case, not a fault.
107
+ try { rmSync(path, { force: true }) } catch { /* raced */ }
108
+ continue
109
+ }
110
+ found.push(record)
111
+ }
112
+ }
113
+
114
+ return found
115
+ }
116
+
117
+ return {
118
+ live,
119
+
120
+ /** Bytes currently held across every live holder. */
121
+ held(): number {
122
+ return live().reduce((total, entry) => total + entry.bytes, 0)
123
+ },
124
+
125
+ /**
126
+ * Record a hold.
127
+ *
128
+ * Written AFTER the load succeeds, never before: a reservation for a
129
+ * model that failed to load would shrink the machine's apparent
130
+ * capacity for as long as the process lived, and nothing would ever
131
+ * clear it. Over-committing briefly while a load is in flight is the
132
+ * lesser fault — it self-corrects, a phantom hold does not.
133
+ */
134
+ take(entry: Omit<Reservation, "pid" | "at">): string {
135
+ const record: Reservation = { ...entry, pid: process.pid, at: Date.now() }
136
+ const path = join(ensure(), `${process.pid}-${entry.role}-${Bun.randomUUIDv7()}.json`)
137
+ writeFileSync(path, JSON.stringify(record), "utf-8")
138
+ return path
139
+ },
140
+
141
+ /** Release one hold. A no-op when already gone — unloading twice is not an error. */
142
+ release(path: string): void {
143
+ try { rmSync(path, { force: true }) } catch { /* already gone */ }
144
+ },
145
+
146
+ /** Release everything this process holds — shutdown, and the one place a clean exit matters. */
147
+ releaseAll(): void {
148
+ for (const root of new Set([...ROOTS, writeRoot])) {
149
+ if (!existsSync(root)) continue
150
+ for (const name of readdirSync(root)) {
151
+ const path = join(root, name)
152
+ const record = read(path)
153
+ if (record?.pid === process.pid) {
154
+ try { rmSync(path, { force: true }) } catch { /* raced */ }
155
+ }
156
+ }
157
+ }
158
+ },
159
+ }
160
+ }
161
+
162
+ export type ReservationsT = ReturnType<typeof Reservations>
@@ -0,0 +1,156 @@
1
+ import { err } from "@arcforge/err"
2
+ import type { ResourceBudget } from "@arcforge/types"
3
+ import { formatSize, parseSize, probeHardware, type Hardware } from "./hardware"
4
+ import { Reservations, type Reservation, type ReservationsT } from "./reservations"
5
+
6
+ /**
7
+ * Resources — what local inference may use on this machine, and what it is
8
+ * using now.
9
+ *
10
+ * A PLATFORM service, not a kernel one. Hardware is environment, and ring 0
11
+ * must not grow a machine model: a cognet asks for a role and receives a
12
+ * working handle, exactly as it never learns which provider filled it. This
13
+ * is what the provider consults before loading weights, and what Fleet reads
14
+ * to show a person their own machine.
15
+ *
16
+ * ── Refuse, never evict ──────────────────────────────────────────────────
17
+ *
18
+ * A load that does not fit is refused with a message naming what is holding
19
+ * the memory. It does NOT evict another agent's model, deliberately: eviction
20
+ * needs a policy — least-recently-used? lowest-priority? — and nobody has
21
+ * tuned one. A refusal is a bad experience a user can act on; a silent
22
+ * eviction is another agent mysteriously slowing down.
23
+ *
24
+ * That does mean a second agent can fail where a first succeeded, which is a
25
+ * real cost. It is the honest one until there is a policy worth defending.
26
+ */
27
+
28
+ export type ResourceState = {
29
+ hardware: Hardware
30
+ /** The declared ceiling in bytes, or null when none was declared or it was unreadable. */
31
+ budget: number | null
32
+ /** Bytes held by live holders across every binary on this machine. */
33
+ held: number
34
+ /**
35
+ * Bytes a new load may take, or null when nothing bounds it.
36
+ *
37
+ * Null is UNBOUNDED, not zero — an unmeasurable GPU with no declared
38
+ * budget genuinely has no known limit, and refusing every load there
39
+ * would make local inference unavailable on most machines.
40
+ */
41
+ available: number | null
42
+ /** What is loaded right now, for a surface that lists it. */
43
+ reservations: Reservation[]
44
+ }
45
+
46
+ type ResourcesOpts = {
47
+ /**
48
+ * The active profile's declared ceiling, read fresh per call.
49
+ *
50
+ * A FUNCTION for the same reason providers are: the active profile changes
51
+ * while the process runs, and a captured value keeps serving the one that
52
+ * was active at boot.
53
+ */
54
+ budget?: () => ResourceBudget | undefined
55
+ /** Injectable so tests never touch a developer's real reservation directory. */
56
+ reservations?: ReservationsT
57
+ }
58
+
59
+ export function Resources(opts: ResourcesOpts = {}) {
60
+ const hardware = probeHardware()
61
+ const reservations = opts.reservations ?? Reservations()
62
+
63
+ /**
64
+ * The effective ceiling.
65
+ *
66
+ * The declared budget wins where it exists, even above the measured
67
+ * hardware — a user who says 4GB on a 24GB card means it. Where nothing
68
+ * is declared, the hardware is the ceiling. Where neither is known, there
69
+ * is no ceiling, and that is reported honestly rather than guessed at.
70
+ */
71
+ function ceiling(): number | null {
72
+ const declared = parseSize(opts.budget?.()?.vram)
73
+ if (declared !== null) return declared
74
+ return hardware.vram ?? null
75
+ }
76
+
77
+ function state(): ResourceState {
78
+ const live = reservations.live()
79
+ const held = live.reduce((total, entry) => total + entry.bytes, 0)
80
+ const limit = ceiling()
81
+
82
+ return {
83
+ hardware,
84
+ budget: parseSize(opts.budget?.()?.vram),
85
+ held,
86
+ // Never negative: over-commitment is possible (a load that grew
87
+ // past its estimate) and reporting it as a negative allowance
88
+ // would make every caller handle a sign.
89
+ available: limit === null ? null : Math.max(0, limit - held),
90
+ reservations: live,
91
+ }
92
+ }
93
+
94
+ return {
95
+ get hardware(): Hardware {
96
+ return hardware
97
+ },
98
+
99
+ state,
100
+
101
+ /**
102
+ * Would a load of this size fit?
103
+ *
104
+ * True when nothing bounds it — see ResourceState.available. Callers
105
+ * that want the reason use `admit`, which throws with one.
106
+ */
107
+ fits(bytes: number): boolean {
108
+ const { available } = state()
109
+ return available === null || bytes <= available
110
+ },
111
+
112
+ /**
113
+ * Take a hold, or refuse with a message naming what is in the way.
114
+ *
115
+ * Returns a RELEASE FUNCTION rather than a handle: the only thing a
116
+ * caller may do with a reservation is give it back, and a function is
117
+ * the smallest shape that says so. Idempotent — releasing twice is
118
+ * not an error, because a shutdown path racing an unload is ordinary.
119
+ */
120
+ admit(entry: { agent: string; role: string; model: string; bytes: number }): () => void {
121
+ const current = state()
122
+
123
+ if (current.available !== null && entry.bytes > current.available) {
124
+ const holders = current.reservations
125
+ .map(held => ` ${held.agent} · ${held.role} · ${held.model} — ${formatSize(held.bytes)}`)
126
+ .join("\n")
127
+
128
+ throw err("RESOURCES_EXHAUSTED", {
129
+ detail: `${entry.model} needs ${formatSize(entry.bytes)}, `
130
+ + `${formatSize(current.available)} available of ${formatSize(current.budget ?? hardware.vram ?? 0)}.`
131
+ + (holders ? `\n\nheld by:\n${holders}` : ""),
132
+ context: {
133
+ model: entry.model,
134
+ needs: entry.bytes,
135
+ available: current.available,
136
+ },
137
+ })
138
+ }
139
+
140
+ const path = reservations.take(entry)
141
+ let released = false
142
+ return () => {
143
+ if (released) return
144
+ released = true
145
+ reservations.release(path)
146
+ }
147
+ },
148
+
149
+ /** Release everything this process holds. The shutdown path. */
150
+ releaseAll(): void {
151
+ reservations.releaseAll()
152
+ },
153
+ }
154
+ }
155
+
156
+ export type ResourcesT = ReturnType<typeof Resources>
@@ -0,0 +1 @@
1
+ export { Running, type RunningT } from "./running"