@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,69 @@
1
+ /**
2
+ * tool-bundle-worker — bundles a batch of local tool files into self-contained
3
+ * ESM source, one Bun.build() over all entrypoints, reported on stdout as JSON.
4
+ *
5
+ * Why a subprocess (same reasoning as cognet/bundle-worker): Bun.build() is a
6
+ * native, single-threaded compute burst with no cooperative yield points —
7
+ * inline it would freeze VTerm's render/input loop for the whole compile.
8
+ * Spawned off the process that owns the terminal instead.
9
+ *
10
+ * Why bundle at all: tools load via import() INSIDE the sandbox. If a tool were
11
+ * passed as a raw path, its file (and every file it imports) would have to be
12
+ * mounted into the box — which either dangles imports or re-exposes the project.
13
+ * Bundling collapses each tool to one self-contained module the box materializes
14
+ * from source, so nothing of the project needs mounting.
15
+ *
16
+ * Contract: argv[2] is a JSON array of absolute entry paths. Prints exactly one
17
+ * JSON line to stdout — { ok: true, tools: { [path]: code } } on success,
18
+ * { ok: false, message } on failure — then exits 0. Exit code is not the
19
+ * signal; the caller reads the JSON line (mirrors cognet/bundle-worker).
20
+ */
21
+
22
+ // Standalone worker: no imports, so TS treats this as a script rather than a
23
+ // module and rejects top-level await. An empty export makes it a module.
24
+ export {}
25
+
26
+ const raw = process.argv[2]
27
+ if (!raw) {
28
+ console.log(JSON.stringify({ ok: false, message: "tool-bundle-worker: no entry paths given" }))
29
+ process.exit(0)
30
+ }
31
+
32
+ let entryPaths: string[]
33
+ try {
34
+ entryPaths = JSON.parse(raw) as string[]
35
+ } catch (error) {
36
+ console.log(JSON.stringify({ ok: false, message: `tool-bundle-worker: bad argv JSON: ${String(error)}` }))
37
+ process.exit(0)
38
+ }
39
+
40
+ const tools: Record<string, string> = {}
41
+
42
+ // One build per entry so a single malformed tool fails only itself, and each
43
+ // entry's output maps cleanly back to its source path. Bun.build resolves each
44
+ // tool's own import graph (siblings, node_modules) into the one output.
45
+ for (const entryPath of entryPaths) {
46
+ const build = await Bun.build({
47
+ entrypoints: [entryPath],
48
+ target: "bun",
49
+ format: "esm",
50
+ minify: false,
51
+ })
52
+
53
+ if (!build.success) {
54
+ const message = build.logs.map(l => String(l)).join("\n")
55
+ console.log(JSON.stringify({ ok: false, message: `bundling ${entryPath} failed:\n${message}` }))
56
+ process.exit(0)
57
+ }
58
+
59
+ const entry = build.outputs.find(o => o.kind === "entry-point")
60
+ if (!entry) {
61
+ console.log(JSON.stringify({ ok: false, message: `no entry-point output for ${entryPath}` }))
62
+ process.exit(0)
63
+ }
64
+
65
+ tools[entryPath] = await entry.text()
66
+ }
67
+
68
+ console.log(JSON.stringify({ ok: true, tools }))
69
+ process.exit(0)
@@ -0,0 +1,610 @@
1
+ import { createHash } from "node:crypto"
2
+ import { existsSync, mkdirSync } from "node:fs"
3
+ import { rename, rm } from "node:fs/promises"
4
+ import { join, resolve } from "node:path"
5
+ import type { AxonTool } from "@arcforge/types"
6
+ import { err } from "@arcforge/err"
7
+ import { fsx } from "../../../utils/fs"
8
+ import { Frame } from "../../frame"
9
+ import type { Scanned } from "../types"
10
+ import type { DeclaredFile } from "./declare"
11
+ import { publishedTools } from "./published"
12
+
13
+ /**
14
+ * The subprocess entry that actually runs declareTools() — see its own doc
15
+ * comment for why this isn't inline.
16
+ *
17
+ * The published CLI is a single bundled app.js, so `import.meta.dir` is the
18
+ * package root there, not this source directory. Like the capsule process
19
+ * and the update helper, the worker is bundled beside it and preferred when
20
+ * present; the .ts source is the workspace/development path.
21
+ *
22
+ * Getting this wrong is silent in development and total in production —
23
+ * every tool declaration in every installed agent fails, which is exactly
24
+ * what happened before the worker was added to packageFiles.
25
+ */
26
+ const packagedWorker = resolve(import.meta.dir, "declare-worker.js")
27
+ const DECLARE_WORKER_PATH = existsSync(packagedWorker)
28
+ ? packagedWorker
29
+ : resolve(import.meta.dir, "declare-worker.ts")
30
+
31
+ // Same packaged-vs-source resolution as the declare worker: in the published
32
+ // single-file CLI the worker is bundled beside app.js; in the workspace it is
33
+ // the .ts source. Getting this wrong is silent in dev and total in production.
34
+ const packagedToolBundleWorker = resolve(import.meta.dir, "tool-bundle-worker.js")
35
+ const TOOL_BUNDLE_WORKER_PATH = existsSync(packagedToolBundleWorker)
36
+ ? packagedToolBundleWorker
37
+ : resolve(import.meta.dir, "tool-bundle-worker.ts")
38
+
39
+ type DeclareWorkerResult =
40
+ | { ok: true; files: [string, DeclaredFile][] }
41
+ | { ok: false; message: string }
42
+
43
+ type ToolBundleResult =
44
+ | { ok: true; tools: Record<string, string> }
45
+ | { ok: false; message: string }
46
+
47
+ /**
48
+ * Runs declare-worker.ts as a subprocess and reads its one JSON stdout
49
+ * line. ts.createProgram() is native, single-threaded compiler work with
50
+ * no cooperative yield points — inline, it freezes VTerm's render/input
51
+ * loop for the whole call. A subprocess moves that freeze off the
52
+ * process that owns the terminal. Only reached on a cache miss (see
53
+ * cachedDeclarations() below) — the common case (unchanged tool source
54
+ * across a reboot) never pays this cost at all.
55
+ */
56
+ async function runDeclareWorker(fileNames: string[]): Promise<DeclareWorkerResult> {
57
+ return declareServer.request(JSON.stringify(fileNames))
58
+ }
59
+
60
+ /**
61
+ * The long-lived declare worker.
62
+ *
63
+ * One process, reused for every scan in this process's lifetime, because the
64
+ * worker's cost is dominated by parsing TypeScript's standard library to build
65
+ * a program — a fixed ~1.0s that a fresh process pays every time and a warm one
66
+ * pays once (see declare-worker.ts's serve mode). A run that scans an agent
67
+ * plus its modules, or a test suite that scans fifteen roots, is the difference
68
+ * between fifteen seconds and one.
69
+ *
70
+ * Requests are serialized rather than pipelined: the worker is one synchronous
71
+ * compiler and answers one line at a time, so overlapping writes would
72
+ * interleave two requests into one stream. The queue is what makes concurrent
73
+ * callers safe without them knowing this exists.
74
+ *
75
+ * A worker that dies takes only the request in flight with it — `spawn()` runs
76
+ * again on the next call, and the caller sees a normal failure result rather
77
+ * than a hang.
78
+ */
79
+ const declareServer = DeclareServer()
80
+
81
+ function DeclareServer() {
82
+ let proc: ReturnType<typeof Bun.spawn> | null = null
83
+ let lines: AsyncIterableIterator<string> | null = null
84
+ let queue: Promise<unknown> = Promise.resolve()
85
+ /** Whether the exit hooks are installed — once per process, not per spawn. */
86
+ let reaperArmed = false
87
+
88
+ /**
89
+ * Kill the worker whenever this process ends, however it ends.
90
+ *
91
+ * ── Why an exit hook rather than a shutdown() call ──────────────────────
92
+ *
93
+ * A child is NOT killed when its parent exits — it is reparented to init
94
+ * and keeps running. So the worker has to be killed explicitly, and the
95
+ * only place that catches every exit is here: a graceful shutdown, a
96
+ * `process.exit()` from the third ctrl+c, an uncaught throw, and a SIGINT
97
+ * or SIGTERM from the terminal all end the process without necessarily
98
+ * passing through any shutdown path we control.
99
+ *
100
+ * Hanging this off the teardown chain instead would have covered exactly
101
+ * the one case that was already working, and missed every case where the
102
+ * user is force-quitting — which is when a leaked 280MB compiler process
103
+ * matters most.
104
+ *
105
+ * ── Only `exit`, and that is enough ────────────────────────────────────
106
+ *
107
+ * SIGINT and SIGTERM are deliberately NOT handled here. VTerm's terminal
108
+ * driver already handles both — it restores the terminal and calls
109
+ * `process.exit(0)`, which fires `exit` and reaches this. Adding our own
110
+ * handlers would mean two listeners racing to tear down the same process,
111
+ * and a `process.kill(self, signal)` to re-raise would fight the driver's
112
+ * own exit rather than cooperate with it.
113
+ *
114
+ * Synchronous, deliberately: `exit` handlers cannot await, and
115
+ * `proc.kill()` is a synchronous signal send, which is exactly what fits.
116
+ */
117
+ function armReaper(): void {
118
+ if (reaperArmed) return
119
+ reaperArmed = true
120
+ process.once("exit", stop)
121
+ }
122
+
123
+ function spawn(): void {
124
+ proc = Bun.spawn(["bun", "run", DECLARE_WORKER_PATH, "--serve"], {
125
+ stdin: "pipe",
126
+ stdout: "pipe",
127
+ stderr: "pipe",
128
+ // NOT a kill-on-parent-exit switch — `killSignal` only names the
129
+ // signal `.kill()` sends when something calls it. Nothing did, so
130
+ // this worker outlived every process that spawned one: a ~280MB
131
+ // TypeScript compiler, reparented to init, one per session,
132
+ // forever. Verified in the wild at 1h47m old with its parent long
133
+ // gone. `reap()` below is what actually makes the comment true.
134
+ killSignal: "SIGKILL",
135
+ })
136
+
137
+ // A spawned child with piped stdio KEEPS THE EVENT LOOP ALIVE, and
138
+ // this worker is deliberately long-lived — it stays resident between
139
+ // requests so the next one skips a cold TypeScript start. Together
140
+ // those meant a CLI command that had finished all its work simply
141
+ // never exited: `axon prepare` printed its summary and hung, on
142
+ // exactly the projects that have tools to declare (the others never
143
+ // spawn a worker, which is what made it look intermittent).
144
+ //
145
+ // unref() drops it from the loop's reference count without killing
146
+ // it: the worker still answers requests for as long as the process
147
+ // genuinely has work, and stops being a reason for the process to
148
+ // stay alive once it does not. `reap()` below still kills it on exit.
149
+ proc.unref()
150
+
151
+ lines = readLines(proc.stdout as ReadableStream<Uint8Array>)
152
+ armReaper()
153
+ }
154
+
155
+ function stop(): void {
156
+ proc?.kill()
157
+ proc = null
158
+ lines = null
159
+ }
160
+
161
+ async function send(payload: string): Promise<DeclareWorkerResult> {
162
+ if (!proc || proc.killed) spawn()
163
+
164
+ const writer = (proc!.stdin as { write(chunk: string): void; flush?(): void })
165
+ writer.write(`${payload}\n`)
166
+ writer.flush?.()
167
+
168
+ const next = await lines!.next()
169
+ if (next.done) {
170
+ // The worker exited rather than answering. Drop the handle so the
171
+ // next call starts a fresh one instead of writing into a dead pipe.
172
+ const stderr = await new Response(proc!.stderr as ReadableStream<Uint8Array>).text().catch(() => "")
173
+ stop()
174
+ return { ok: false, message: `declare-worker exited without answering${stderr ? `\n${stderr}` : ""}` }
175
+ }
176
+
177
+ return JSON.parse(next.value) as DeclareWorkerResult
178
+ }
179
+
180
+ return {
181
+ /** Queue a request behind any in flight, so two callers never share a line. */
182
+ request(payload: string): Promise<DeclareWorkerResult> {
183
+ const result = queue.then(() => send(payload))
184
+ // The chain must survive a rejection, or one failure wedges every
185
+ // later request behind it forever.
186
+ queue = result.catch(() => { })
187
+ return result
188
+ },
189
+ }
190
+ }
191
+
192
+ /** Split a byte stream into trimmed, non-empty lines. */
193
+ async function* readLines(stream: ReadableStream<Uint8Array>): AsyncIterableIterator<string> {
194
+ const decoder = new TextDecoder()
195
+ let buffer = ""
196
+
197
+ for await (const chunk of stream) {
198
+ buffer += decoder.decode(chunk, { stream: true })
199
+ let index = buffer.indexOf("\n")
200
+ while (index !== -1) {
201
+ const line = buffer.slice(0, index).trim()
202
+ buffer = buffer.slice(index + 1)
203
+ if (line) yield line
204
+ index = buffer.indexOf("\n")
205
+ }
206
+ }
207
+ }
208
+
209
+ /**
210
+ * Bundles a batch of tool files to self-contained ESM source via a subprocess
211
+ * (same off-thread reason as the declare worker — Bun.build() would freeze the
212
+ * terminal loop inline). Tools load by import() inside the sandbox; bundling
213
+ * collapses each to one module the box materializes from source, so no tool
214
+ * file — and none of the project around it — is ever mounted into the box.
215
+ */
216
+ async function runToolBundleWorker(entryPaths: string[]): Promise<ToolBundleResult> {
217
+ const proc = Bun.spawn(["bun", "run", TOOL_BUNDLE_WORKER_PATH, JSON.stringify(entryPaths)], {
218
+ stdout: "pipe",
219
+ stderr: "pipe",
220
+ })
221
+ const [stdout, stderr, exitCode] = await Promise.all([
222
+ new Response(proc.stdout).text(),
223
+ new Response(proc.stderr).text(),
224
+ proc.exited,
225
+ ])
226
+
227
+ const line = stdout.trim().split("\n").at(-1)
228
+ if (!line) {
229
+ return { ok: false, message: `tool-bundle-worker produced no output (exit ${exitCode})${stderr ? `\n${stderr}` : ""}` }
230
+ }
231
+ return JSON.parse(line) as ToolBundleResult
232
+ }
233
+
234
+ // ─── Declaration cache ───────────────────────────────────────────────────────
235
+
236
+ type DeclareCacheFile = {
237
+ inputHash: string
238
+ files: [string, DeclaredFile][]
239
+ }
240
+
241
+ /**
242
+ * Where this root's tool caches live.
243
+ *
244
+ * Prefers an existing frame (same detection bench/typegen.ts uses) so the
245
+ * cache sits in the `cache/` area with the rest of that project's disposable
246
+ * output. When the root has no frame at all, `.module/cache` is CREATED
247
+ * rather than giving up.
248
+ *
249
+ * Returning null here meant "no cache", and the roots that hit it were exactly
250
+ * the ones that most need one: a source module being developed in place has no
251
+ * `.module/` until something builds it, so every boot re-ran ts.createProgram()
252
+ * and Bun.build() in two spawned workers — 1.4s per module, on every boot and
253
+ * every watcher reload, forever, because nothing ever wrote the cache that
254
+ * would have prevented it. One agent with one source module was paying ~1.4s of
255
+ * a ~1.8s blueprint load for work whose inputs had not changed.
256
+ *
257
+ * Creating the directory is safe: it is the same generated-output location the
258
+ * module's own build would use, it is already gitignored by convention, and the
259
+ * cache is keyed on a content hash so a stale entry cannot survive an edit.
260
+ */
261
+ function cacheDir(root: string): string | null {
262
+ // Whichever frame this root already has, its `cache/` area. Probing the
263
+ // kinds in order rather than detecting the kind properly keeps this a
264
+ // filesystem question — the scanner runs on module roots that may not be
265
+ // a project at all.
266
+ for (const kind of ["agent", "module", "cognet"] as const) {
267
+ const frame = Frame({ root: root, kind: kind })
268
+ if (fsx.exists(frame.dir)) {
269
+ try {
270
+ return frame.ensure("cache")
271
+ } catch {
272
+ return null
273
+ }
274
+ }
275
+ }
276
+ try {
277
+ return Frame({ root: root, kind: "module" }).ensure("cache")
278
+ } catch {
279
+ // A read-only root (a module vendored into node_modules by a package
280
+ // manager that chowned it, a container mount) still scans correctly —
281
+ // it just pays the uncached cost. Never fail a boot over a cache.
282
+ return null
283
+ }
284
+ }
285
+
286
+ /** Hash every tool file's content, sorted — order-independent, content-only (a rename with identical bodies is still a cache hit is NOT desired here, so path is part of the hash too). */
287
+ function hashToolFiles(toolFiles: string[], sources: Map<string, string>): string {
288
+ const hash = createHash("sha256")
289
+ for (const file of [...toolFiles].sort()) {
290
+ hash.update(file)
291
+ hash.update("\0")
292
+ hash.update(sources.get(file) ?? "")
293
+ }
294
+ return hash.digest("hex")
295
+ }
296
+
297
+ /**
298
+ * declareTools() is real ts.createProgram() work — expensive (500ms-1.5s
299
+ * cold) and, worse, entirely synchronous/blocking (see runDeclareWorker's
300
+ * doc comment). Gated the same way bundleCognet() gates Bun.build(): hash
301
+ * the actual inputs, skip straight to the cached result when unchanged.
302
+ * The common case (reboot, nothing in src/tools/ touched) never spawns
303
+ * the worker at all.
304
+ */
305
+ async function cachedDeclarations(root: string, toolFiles: string[], sources: Map<string, string>): Promise<Map<string, DeclaredFile>> {
306
+ const inputHash = hashToolFiles(toolFiles, sources)
307
+ const dir = cacheDir(root)
308
+ const cachePath = dir ? join(dir, "tools-declare-cache.json") : null
309
+
310
+ if (cachePath) {
311
+ const cached = await readCache<DeclareCacheFile>(cachePath)
312
+ if (cached && cached.inputHash === inputHash && Array.isArray(cached.files) && cached.files.length === toolFiles.length) {
313
+ return new Map(cached.files)
314
+ }
315
+ }
316
+
317
+ const result = await runDeclareWorker(toolFiles)
318
+ if (!result.ok) {
319
+ // The reason FIRST, the root after it.
320
+ //
321
+ // The root still has to be named — an agent's own src/tools failing and
322
+ // an installed module's failing share one error code, and the message
323
+ // alone cannot otherwise tell you which broke. But it was leading, and
324
+ // a profile path is ~90 columns, so in a terminal the one actionable
325
+ // sentence ("references type X but no definition could be resolved")
326
+ // was pushed off the end while two lines of path nobody can act on
327
+ // survived. The worker's message is also a thrown Error, so it carries
328
+ // a stack that means nothing to a user installing a module — cut to
329
+ // the first line, which is the sentence.
330
+ const reason = result.message.split("\n")[0]!.replace(/^Error:\s*/, "").trim()
331
+ throw err("TOOL_DECLARE_FAILED", { detail: `${reason}\n in ${root}`, context: { root } })
332
+ }
333
+
334
+ // A declaration for every file we asked about, or this is not a result
335
+ // worth keeping. The worker reports ok:true for anything that did not
336
+ // throw, so a partial answer arrives looking exactly like a complete one —
337
+ // and caching it against the source hash is what turned a single failure
338
+ // into a permanent one, served from disk on every subsequent boot.
339
+ if (result.files.length !== toolFiles.length) {
340
+ const declared = new Set(result.files.map(([file]) => file))
341
+ const missing = toolFiles.filter(file => !declared.has(file))
342
+ throw err("TOOL_DECLARE_FAILED", {
343
+ detail: `${root}: no declaration produced for ${missing.join(", ")}`,
344
+ context: { root, missing },
345
+ })
346
+ }
347
+
348
+ if (cachePath) await writeCache(cachePath, { inputHash, files: result.files } satisfies DeclareCacheFile)
349
+
350
+ return new Map(result.files)
351
+ }
352
+
353
+ // ─── Bundle cache ──────────────────────────────────────────────────────────────
354
+
355
+ type BundleCacheFile = {
356
+ inputHash: string
357
+ tools: Record<string, string>
358
+ }
359
+
360
+ /**
361
+ * Bundles the tool files to self-contained source, gated by the SAME content
362
+ * hash as declarations — Bun.build() is expensive and blocking, so the common
363
+ * case (reboot, nothing in src/tools/ touched) reads the cache and never spawns
364
+ * the worker. Rides the existing watcher→rescan reload path for freshness: a
365
+ * changed tool file changes the hash, which misses the cache and rebundles.
366
+ */
367
+ async function cachedToolBundles(root: string, toolFiles: string[], sources: Map<string, string>): Promise<Map<string, string>> {
368
+ const inputHash = hashToolFiles(toolFiles, sources)
369
+ const dir = cacheDir(root)
370
+ const cachePath = dir ? join(dir, "tools-bundle-cache.json") : null
371
+
372
+ if (cachePath) {
373
+ const cached = await readCache<BundleCacheFile>(cachePath)
374
+ if (cached && cached.inputHash === inputHash && cached.tools && Object.keys(cached.tools).length === toolFiles.length) {
375
+ return new Map(Object.entries(cached.tools))
376
+ }
377
+ }
378
+
379
+ const result = await runToolBundleWorker(toolFiles)
380
+ if (!result.ok) {
381
+ throw err("TOOL_BUNDLE_FAILED", { detail: `${root}: ${result.message}`, context: { root } })
382
+ }
383
+
384
+ // Same completeness rule as declarations: a tool with no bundle cannot be
385
+ // loaded into the sandbox, so a partial result is a failed scan, not a
386
+ // smaller one.
387
+ const bundled = Object.keys(result.tools)
388
+ if (bundled.length !== toolFiles.length) {
389
+ const missing = toolFiles.filter(file => !(file in result.tools))
390
+ throw err("TOOL_BUNDLE_FAILED", {
391
+ detail: `${root}: no bundle produced for ${missing.join(", ")}`,
392
+ context: { root, missing },
393
+ })
394
+ }
395
+
396
+ if (cachePath) await writeCache(cachePath, { inputHash, tools: result.tools } satisfies BundleCacheFile)
397
+
398
+ return new Map(Object.entries(result.tools))
399
+ }
400
+
401
+ /**
402
+ * Read a cache file, treating anything unreadable as a miss.
403
+ *
404
+ * A cache is derived data — it exists only to skip work whose answer is already
405
+ * known. Corrupt JSON (a kill mid-write; Bun.write is not atomic) means the
406
+ * answer is NOT known, which is a miss and a rebuild. Letting CORRUPT_JSON
407
+ * propagate made a truncated cache fatal to the whole scan, and the scan's own
408
+ * catch then degraded that to "this agent has no tools" — a wipe caused
409
+ * entirely by a file that existed to make things faster.
410
+ */
411
+ async function readCache<T>(path: string): Promise<T | null> {
412
+ try {
413
+ return await fsx.readJson<T>(path)
414
+ } catch {
415
+ return null
416
+ }
417
+ }
418
+
419
+ /**
420
+ * Write a cache file atomically: a temp file in the same directory, then a
421
+ * rename. Bun.write() alone can leave a truncated file if the process dies
422
+ * mid-write, and while readCache() now treats that as a miss, a cache that
423
+ * cannot be half-written is better than one that is merely tolerated.
424
+ */
425
+ async function writeCache(path: string, value: unknown): Promise<void> {
426
+ const temp = `${path}.${process.pid}.tmp`
427
+ try {
428
+ await Bun.write(temp, JSON.stringify(value))
429
+ await rename(temp, path)
430
+ } catch {
431
+ // A cache that cannot be written is a slower scan, never a failed one.
432
+ await rm(temp, { force: true }).catch(() => {})
433
+ }
434
+ }
435
+
436
+ /**
437
+ * Tools — one source: src/tools/*.ts. Every export lands in the agent's
438
+ * global scope under its own name; the filename groups, it does not
439
+ * namespace. Real author source, run through actual TypeScript
440
+ * declaration emission (declareTools) so return types are the compiler's
441
+ * real inference (Promise<string>, never Promise<unknown>) and any ambient
442
+ * type an export references is captured and carried alongside it.
443
+ *
444
+ * package.json dependencies are deliberately NOT scanned. A dependency is
445
+ * available to the agent project's SOURCE — the author may import it — but
446
+ * the capsule is a separate OS process, and being importable here grants
447
+ * nothing there. Treating them as tools produced entries the capsule could
448
+ * never load: filtered out at the capsule boundary, but still rendered into
449
+ * the editor's ambient declarations, which is how an agent came to be told
450
+ * it could call @vue/compiler-sfc internals. An author who wants a package
451
+ * callable re-exports it from src/tools/ deliberately.
452
+ */
453
+ export type ToolsOpts = {
454
+ /**
455
+ * Whether a tool that will not compile is FATAL.
456
+ *
457
+ * True for an agent's own `src/tools/` — the scope is the contract between
458
+ * what the author wrote and what the model is told it can call, so a
459
+ * missing tool means the running agent is not the agent that was asked
460
+ * for. That is an invalid state, and invalid states crash.
461
+ *
462
+ * False for a MODULE's tools, and the distinction is the whole point: an
463
+ * agent that installed a broken module is not an invalid agent, it is the
464
+ * agent it was before the install. Crashing the whole runtime over one
465
+ * dependency leaves the user unable to boot the terminal they need in
466
+ * order to remove it — which is exactly the trap a bad publish set.
467
+ *
468
+ * Defaults to true: a caller that has not thought about it gets the strict
469
+ * behaviour, and only the module scanner opts out deliberately.
470
+ */
471
+ required?: boolean
472
+ }
473
+
474
+ export async function Tools(root: string, opts: ToolsOpts = {}): Promise<Scanned<AxonTool>> {
475
+ const entries: AxonTool[] = []
476
+ const warnings: Scanned<AxonTool>["warnings"] = []
477
+
478
+ // ── src/tools/*.ts ───────────────────────────────────────────────────────
479
+ const toolsDir = join(root, "src", "tools")
480
+ const toolFiles: string[] = []
481
+ for (const file of await fsx.list(toolsDir)) {
482
+ if (!file.endsWith(".ts") || file.endsWith(".d.ts") || file.endsWith(".test.ts")) continue
483
+ toolFiles.push(join(toolsDir, file))
484
+ }
485
+
486
+ if (toolFiles.length > 0) {
487
+ const sources = new Map<string, string>()
488
+ for (const filePath of toolFiles) sources.set(filePath, (await fsx.readText(filePath)) ?? "")
489
+
490
+ // One ts.Program over the whole directory — a tool file importing a
491
+ // shared type from a sibling file needs the checker to see both.
492
+ //
493
+ // ── Fatal for an agent, degraded for a module ────────────────────────
494
+ //
495
+ // These THROW when `required` (an agent's own src/tools/): the scope is
496
+ // the contract between what the author wrote and what the model is told
497
+ // it can call, so a missing tool means the running agent is not the
498
+ // agent that was asked for. Invalid state, so it crashes.
499
+ //
500
+ // A MODULE's tools are the opposite. An agent that installed something
501
+ // broken is not invalid — it is the agent it was before the install —
502
+ // and crashing the runtime leaves the user unable to boot the terminal
503
+ // they need in order to uninstall it.
504
+ //
505
+ // Degrading was tried before and reverted for two good reasons, both
506
+ // of which had to be fixed first rather than argued away:
507
+ //
508
+ // 1. The warning reached nobody. Scan warnings are committed as
509
+ // `build:warning`, which classified as DEBUG and was therefore
510
+ // hidden at default verbosity — so "warn and skip" was
511
+ // indistinguishable from silence. It is now info-level and renders
512
+ // as its own row (see visibility.ts, session-event.vue).
513
+ //
514
+ // 2. The empty result was CACHED against the source hash, so one
515
+ // failure survived every reboot with no recovery but deleting the
516
+ // cache by hand. cachedDeclarations/cachedToolBundles only ever
517
+ // write a cache on success, so a failed scan retries next boot —
518
+ // which is what makes a republish or an upstream fix take effect
519
+ // without the user knowing a cache exists.
520
+ let declared: Map<string, DeclaredFile>
521
+ let bundled: Map<string, string>
522
+
523
+ // A PUBLISHED module ships the answer. Read it rather than
524
+ // re-deriving it, for correctness before speed:
525
+ //
526
+ // `declareTools()` asks TypeScript to emit declarations, and TypeScript
527
+ // treats node_modules as external library code — it silently SKIPS
528
+ // declaration emit for anything inside it. A module whose tool file
529
+ // imports a sibling therefore got one .d.ts where it needed two, and
530
+ // every type declared in that sibling became unresolvable. The scan
531
+ // then blamed the author for a missing re-export their source already
532
+ // had (@axon/arxiv, `QueryOptions`).
533
+ //
534
+ // The manifest's declarations were emitted in the module's OWN
535
+ // directory at publish time, where the compiler behaves. They are
536
+ // strictly more correct than anything derivable from the installed
537
+ // copy — and reading them costs one file read instead of a
538
+ // ts.createProgram() and a bundle pass.
539
+ //
540
+ // Null means "not a complete published manifest" and falls through to
541
+ // compiling, which is the pre-existing behaviour for an agent's own
542
+ // src/tools/ and for anything installed from source.
543
+ const published = await publishedTools(root, toolFiles)
544
+ if (published) {
545
+ declared = published.declared
546
+ bundled = published.bundled
547
+ } else {
548
+ try {
549
+ declared = await cachedDeclarations(root, toolFiles, sources)
550
+ // Bundle each tool to self-contained source so the capsule never
551
+ // imports it by path — the box needs nothing of the project mounted.
552
+ bundled = await cachedToolBundles(root, toolFiles, sources)
553
+ } catch (cause) {
554
+ if (opts.required !== false) throw cause
555
+
556
+ // Nothing from this root enters scope. That is the invariant that
557
+ // keeps degradation honest: the model is never told about a tool
558
+ // whose source the capsule cannot load, so it cannot call one that
559
+ // does not exist.
560
+ warnings.push({
561
+ domain: "tools",
562
+ error: cause instanceof Error ? cause.message : String(cause),
563
+ // The structured failure travels with it, so the UI can render
564
+ // the same error card it would for a crash — in warning
565
+ // colours, because nothing crashed.
566
+ ...(cause && typeof cause === "object" && "isAxonError" in cause
567
+ ? { cause: cause as never }
568
+ : {}),
569
+ })
570
+ return { entries, warnings }
571
+ }
572
+ }
573
+
574
+ for (const filePath of toolFiles) {
575
+ const file = filePath.slice(toolsDir.length + 1)
576
+ const result = declared.get(filePath)
577
+
578
+ // A file that exports nothing callable contributes nothing — an
579
+ // author's shared internal module (the documented `_http.ts`
580
+ // pattern) is exactly this and is not an error.
581
+ if (!result || result.fns.length === 0) continue
582
+
583
+ const source = bundled.get(filePath)
584
+ if (source === undefined) {
585
+ // Declaration and bundling are independent passes over the same
586
+ // files; if they disagree about which succeeded, the tool would
587
+ // enter scope with no source for the sandbox to load.
588
+ throw err("TOOL_BUNDLE_FAILED", {
589
+ detail: `${root}: ${file} declared but produced no bundle`,
590
+ context: { root, file: filePath },
591
+ })
592
+ }
593
+
594
+ entries.push({
595
+ name: file.slice(0, -3),
596
+ fns: result.fns,
597
+ origin: "src",
598
+ // Self-contained bundled source is authoritative: the capsule
599
+ // materializes it inside the box, so no tool path is mounted.
600
+ // entryPath is retained for editor/typecheck tooling that reads
601
+ // the author's real file, not for capsule loading.
602
+ entryPath: filePath,
603
+ source,
604
+ ...(result.ambientTypes.length > 0 ? { ambientTypes: result.ambientTypes } : {}),
605
+ })
606
+ }
607
+ }
608
+
609
+ return { entries, warnings }
610
+ }