@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,393 @@
1
+ import { dirname, join } from "node:path"
2
+ import ts from "typescript"
3
+ import type { ToolFnEntry } from "@arcforge/types"
4
+ import { err } from "@arcforge/err"
5
+ import { resolveSignatureTypes, assertNoDanglingTypes, rewriteImportPaths } from "./resolve"
6
+
7
+ export type DeclaredFile = {
8
+ /** One entry per top-level exported function/const in this file. */
9
+ fns: ToolFnEntry[]
10
+ /** Interface/type-alias/un-exported-helper declarations this file's exports reference, deduped, in first-encountered order. */
11
+ ambientTypes: string[]
12
+ }
13
+
14
+ const COMPILER_OPTIONS: ts.CompilerOptions = {
15
+ declaration: true,
16
+ emitDeclarationOnly: true,
17
+ target: ts.ScriptTarget.ESNext,
18
+ module: ts.ModuleKind.ESNext,
19
+ moduleResolution: ts.ModuleResolutionKind.Bundler,
20
+ strict: true,
21
+ skipLibCheck: true,
22
+ // Declaration emit fails loudly on an implicit any parameter otherwise —
23
+ // tool authors write plain, unannotated JS-shaped TS; forcing strict
24
+ // parameter typing here would make the SCANNER reject code the runtime
25
+ // happily executes. Emission still infers real return types either way.
26
+ noImplicitAny: false,
27
+ allowImportingTsExtensions: true,
28
+ }
29
+
30
+ /**
31
+ * Real TypeScript declaration emission over a directory of tool source
32
+ * files — replaces hand-rolled AST pattern matching (which could only ever
33
+ * read explicit annotations, rendering "unknown" for anything inferred)
34
+ * with the actual compiler: real inferred types (Promise<string>, not
35
+ * Promise<unknown>), JSDoc preserved verbatim by tsc itself, and any
36
+ * ambient type an exported function references followed and captured.
37
+ *
38
+ * One ts.Program per directory (not per file) — files in the same
39
+ * directory can reference each other's types (a tool importing a shared
40
+ * `type Foo` from a sibling file), and the checker needs the whole set to
41
+ * resolve those correctly.
42
+ *
43
+ * Declarations are FLATTENED: tsc's default output keeps ambient types in
44
+ * their own emitted file with an `import type` back to it (correct, but
45
+ * means a reader has to follow the import). Fleet/the model context both
46
+ * need one self-contained block per tool — see `ambientTypes` on the
47
+ * result, meant to be rendered inline by the caller (renderScope() for
48
+ * the model, tool-globals.d.ts for the IDE), not as a relative import.
49
+ *
50
+ * TWO HALVES, TWO SOURCES. Signatures are read back from the EMITTED .d.ts,
51
+ * because that is where tsc has already resolved inference and JSDoc. The types
52
+ * those signatures name are resolved from the ORIGINAL SOURCE through the
53
+ * checker (resolve.ts), because emitted text has lost the identifiers a
54
+ * resolver needs — a re-export names a module, an unannotated return becomes
55
+ * `import("pkg").T`, and a `Pick<T, "a">` points at a declaration in another
56
+ * file. Reading types out of the emitted text is what made re-exports,
57
+ * narrowing, and transitive fields fail; the split is the fix.
58
+ */
59
+ /**
60
+ * TypeScript's own lib.*.d.ts files, parsed once per process.
61
+ *
62
+ * Building a program re-reads and re-parses the entire standard library —
63
+ * about a megabyte of declarations — and that, not the tool source, is where
64
+ * the second is spent: a program over ONE trivial tool file costs ~1.0s, and
65
+ * ~0.07s once these are cached. A caller that declares several roots in one
66
+ * process (the tool scan does, and the test suite does it fifteen times over)
67
+ * pays the full parse once instead of once per root.
68
+ *
69
+ * Deliberately keyed to lib files ONLY. Project sources are excluded because
70
+ * they are exactly what changes between two calls — caching a tool file would
71
+ * serve the previous edit's declarations, which is the silent-wrong-output
72
+ * failure this scanner exists to avoid. The lib cannot change within a
73
+ * process: it ships with the compiler this module already imported.
74
+ */
75
+ const libFiles = new Map<string, ts.SourceFile | undefined>()
76
+
77
+ /** The directory TypeScript's own lib.*.d.ts files ship in. */
78
+ const libDir = normalize(ts.getDefaultLibFilePath(COMPILER_OPTIONS).replace(/[^/\\]+$/, ""))
79
+
80
+ /** True for a path inside TypeScript's own lib directory. */
81
+ function isLibFile(fileName: string): boolean {
82
+ return fileName.startsWith(libDir)
83
+ }
84
+
85
+ /**
86
+ * A path TypeScript will emit declarations for.
87
+ *
88
+ * TypeScript treats anything under `node_modules` as EXTERNAL LIBRARY CODE and
89
+ * silently skips declaration emit for it. That is correct for a package that
90
+ * ships its own `.d.ts`, and exactly wrong here: an installed Axon module ships
91
+ * TypeScript SOURCE that the consumer's scanner has to declare in order to
92
+ * build the tool scope.
93
+ *
94
+ * The failure it produced was quiet and misleading. A tool file importing a
95
+ * sibling got one `.d.ts` where it needed two, every type declared in that
96
+ * sibling became unresolvable, and the scanner blamed the author for a missing
97
+ * re-export their source already had (@axon/arxiv, `QueryOptions`).
98
+ *
99
+ * Rewriting the segment is the narrowest fix that works, because it changes
100
+ * only the thing TypeScript keys its decision on. The path stays absolute,
101
+ * unique and structurally identical, so imports resolve exactly as before —
102
+ * and `unshadow` maps every emitted path back before any caller sees it.
103
+ *
104
+ * Prefixed with a NUL-free sentinel unlikely to collide with a real directory:
105
+ * a project genuinely containing `__axon_modules__` would otherwise have two
106
+ * distinct files map to one path.
107
+ */
108
+ const NODE_MODULES = "/node_modules/"
109
+ const SHADOWED = "/__axon_modules__/"
110
+
111
+ function shadow(path: string): string {
112
+ return path.split(NODE_MODULES).join(SHADOWED)
113
+ }
114
+
115
+ function unshadow(path: string): string {
116
+ return path.split(SHADOWED).join(NODE_MODULES)
117
+ }
118
+
119
+ export function declareTools(fileNames: string[]): Map<string, DeclaredFile> {
120
+ const emitted = new Map<string, string>()
121
+
122
+ const host = ts.createCompilerHost(COMPILER_OPTIONS)
123
+
124
+ // Reads follow the shadow back to the real file on disk. Everything above
125
+ // this line thinks in shadowed paths; everything below it, and the whole
126
+ // filesystem, thinks in real ones.
127
+ const realFileExists = host.fileExists.bind(host)
128
+ host.fileExists = fileName => realFileExists(unshadow(fileName))
129
+ const realReadFile = host.readFile.bind(host)
130
+ host.readFile = fileName => realReadFile(unshadow(fileName))
131
+ if (host.realpath) {
132
+ const realRealpath = host.realpath.bind(host)
133
+ // Resolving through realpath would undo the shadow — tsc calls it while
134
+ // resolving modules and would get back a node_modules path, silently
135
+ // reinstating the emit skip this exists to avoid.
136
+ host.realpath = fileName => shadow(realRealpath(unshadow(fileName)))
137
+ }
138
+ const realDirectoryExists = host.directoryExists?.bind(host)
139
+ if (realDirectoryExists) host.directoryExists = dir => realDirectoryExists(unshadow(dir))
140
+ const realGetDirectories = host.getDirectories?.bind(host)
141
+ if (realGetDirectories) host.getDirectories = dir => realGetDirectories(unshadow(dir))
142
+ const realReadDirectory = host.readDirectory?.bind(host)
143
+ if (realReadDirectory) {
144
+ host.readDirectory = (dir, extensions, exclude, include, depth) =>
145
+ realReadDirectory(unshadow(dir), extensions, exclude, include, depth).map(shadow)
146
+ }
147
+
148
+ // Serve lib declarations from the process-wide cache; everything else
149
+ // reads from disk exactly as before.
150
+ const readSourceFile = host.getSourceFile.bind(host)
151
+ host.getSourceFile = (fileName, languageVersion, onError, shouldCreate) => {
152
+ if (!isLibFile(normalize(unshadow(fileName)))) {
153
+ // Read the real file, but hand tsc a SourceFile whose name is the
154
+ // shadowed path — the name is what emit keys on, so it has to be
155
+ // the one that is not under node_modules.
156
+ const parsed = readSourceFile(unshadow(fileName), languageVersion, onError, shouldCreate)
157
+ if (parsed && parsed.fileName !== fileName) {
158
+ Object.defineProperty(parsed, "fileName", { value: fileName, configurable: true })
159
+ }
160
+ return parsed
161
+ }
162
+ const cached = libFiles.get(fileName)
163
+ if (cached !== undefined || libFiles.has(fileName)) return cached
164
+
165
+ const parsed = readSourceFile(fileName, languageVersion, onError, shouldCreate)
166
+ libFiles.set(fileName, parsed)
167
+ return parsed
168
+ }
169
+ // Keyed on the normalized path: tsc resolves every internal path to forward
170
+ // slashes with `.`/`..` segments collapsed, and calls writeFile with THAT,
171
+ // not with the string it was handed. A lookup keyed on the raw input then
172
+ // misses for any path that is merely spelled differently — "/a/./b.ts", or
173
+ // a Windows path carrying backslashes. That miss used to be answered with
174
+ // `continue`, so the file silently vanished from the result and the scan
175
+ // reported a successful empty declaration set.
176
+ // Emitted paths are mapped back, so every caller sees real locations.
177
+ host.writeFile = (fileName, text) => emitted.set(normalize(unshadow(fileName)), text)
178
+
179
+ const program = ts.createProgram(fileNames.map(shadow), COMPILER_OPTIONS, host)
180
+ program.emit()
181
+ const result = new Map<string, DeclaredFile>()
182
+
183
+ const checker = program.getTypeChecker()
184
+
185
+ // The emitted .d.ts of each file, parsed. Used ONLY to read back the
186
+ // signatures tsc inferred (extractFnEntries) — type RESOLUTION works from
187
+ // the original source via the checker, since emitted text has already lost
188
+ // the identifiers a resolver needs. See resolve.ts.
189
+ const emittedSources = new Map<string, ts.SourceFile>()
190
+ for (const [file, text] of emitted) {
191
+ emittedSources.set(file, ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS))
192
+ }
193
+
194
+ for (const fileName of fileNames) {
195
+ const normalized = normalize(fileName)
196
+ const dtsPath = declarationPathFor(normalized)
197
+ const src = emittedSources.get(dtsPath)
198
+
199
+ // No declaration emitted for a file we were asked to declare. The file
200
+ // does not exist, does not compile, or its imports do not resolve —
201
+ // every one of which means the agent's scope is not what the author
202
+ // wrote. There is no partial success to return here: a scan that
203
+ // silently omits a tool produces an agent the model was never told
204
+ // about, and the caller caches that emptiness against the source hash,
205
+ // so it survives every reboot until the file changes.
206
+ if (!src) {
207
+ throw err("TOOL_DECLARE_FAILED", {
208
+ detail: `${fileName}: no TypeScript declaration could be emitted — the file is missing, does not compile, or has an unresolvable import${diagnosticsFor(program, fileName)}`,
209
+ context: { file: fileName },
210
+ })
211
+ }
212
+
213
+ const rawFns = extractFnEntries(src)
214
+
215
+ // Types are resolved from the ORIGINAL SOURCE, not the emitted .d.ts.
216
+ //
217
+ // The emitted file is text that has already lost what the resolver
218
+ // needs: a re-export line names a module rather than a shape, an
219
+ // unannotated return becomes `import("pkg").T`, and a `Pick<T, "a">`
220
+ // keeps a name whose declaration lives in another program file. The
221
+ // source still carries real identifiers the checker can resolve, so
222
+ // that is what gets walked. See resolve.ts for the full reasoning.
223
+ const sourceFile = program.getSourceFile(shadow(normalized))
224
+ if (!sourceFile) {
225
+ throw err("TOOL_DECLARE_FAILED", {
226
+ detail: `${fileName}: the file was emitted but is not in the program — this is a scanner bug, not an author error`,
227
+ context: { file: fileName },
228
+ })
229
+ }
230
+
231
+ const signatures = exportedSignatureNodes(sourceFile)
232
+ const resolved = resolveSignatureTypes(signatures, { checker, fileName })
233
+
234
+ // tsc spells an unnamed imported type as `import("pkg").T`. Where the
235
+ // walk resolved it, the declaration is inlined beside this signature,
236
+ // so the bare name is what the model should read.
237
+ const fns = rawFns.map(fn => ({ ...fn, declaration: rewriteImportPaths(fn.declaration, resolved) }))
238
+
239
+ // What actually ships is the rendered text; verify THAT rather than the
240
+ // walk that produced it. A name the model reads with nothing behind it
241
+ // is the silent-wrong-output failure this seam exists to prevent.
242
+ assertNoDanglingTypes(fns.map(fn => fn.declaration), resolved, fileName)
243
+
244
+ result.set(fileName, { fns, ambientTypes: resolved.map(r => r.text) })
245
+ }
246
+
247
+ return result
248
+ }
249
+
250
+ /**
251
+ * The nodes whose type references make up a file's public surface.
252
+ *
253
+ * Exactly the exported functions, exported variables (an arrow const, or an
254
+ * object of methods — the `export const hindsight = { … }` shape), and exported
255
+ * classes. Everything a tool's caller can name lives in one of these, and
256
+ * nothing else in the file is part of the contract.
257
+ *
258
+ * Type-only exports are included deliberately: `export type { RecallResponse }
259
+ * from "pkg"` is an author stating that this type is part of what they expose,
260
+ * and honouring that statement is the whole point of the re-export form.
261
+ */
262
+ function exportedSignatureNodes(src: ts.SourceFile): ts.Node[] {
263
+ const nodes: ts.Node[] = []
264
+
265
+ ts.forEachChild(src, node => {
266
+ if (ts.isFunctionDeclaration(node) && hasExportModifier(node)) {
267
+ nodes.push(node)
268
+ } else if (ts.isClassDeclaration(node) && hasExportModifier(node)) {
269
+ nodes.push(node)
270
+ } else if (ts.isVariableStatement(node) && hasExportModifier(node)) {
271
+ nodes.push(node)
272
+ } else if (ts.isTypeAliasDeclaration(node) && hasExportModifier(node)) {
273
+ nodes.push(node)
274
+ } else if (ts.isInterfaceDeclaration(node) && hasExportModifier(node)) {
275
+ nodes.push(node)
276
+ } else if (ts.isExportDeclaration(node) && node.exportClause && ts.isNamedExports(node.exportClause)) {
277
+ for (const element of node.exportClause.elements) nodes.push(element)
278
+ }
279
+ })
280
+
281
+ return nodes
282
+ }
283
+
284
+ /**
285
+ * tsc's normalized spelling of a path: forward slashes, `.`/`..` collapsed.
286
+ * The single source of truth for how `emitted` is keyed and looked up — the two
287
+ * must use the same function or the lookup misses on nothing but spelling.
288
+ */
289
+ function normalize(path: string): string {
290
+ return ts.sys.resolvePath(path.replace(/\\/g, "/"))
291
+ }
292
+
293
+ /** Compiler diagnostics for one file, appended to an error so the message says WHY. */
294
+ function diagnosticsFor(program: ts.Program, fileName: string): string {
295
+ const source = program.getSourceFile(fileName) ?? program.getSourceFile(normalize(fileName))
296
+ if (!source) return ""
297
+ const messages = program
298
+ .getSemanticDiagnostics(source)
299
+ .concat(program.getSyntacticDiagnostics(source))
300
+ .map(d => ts.flattenDiagnosticMessageText(d.messageText, " "))
301
+ return messages.length > 0 ? `:\n${messages.map(m => ` - ${m}`).join("\n")}` : ""
302
+ }
303
+
304
+ /** tsc's own output path convention for a given input file under the same rootDir. */
305
+ function declarationPathFor(fileName: string): string {
306
+ return fileName.replace(/\.tsx?$/, ".d.ts")
307
+ }
308
+
309
+
310
+
311
+
312
+ function hasExportModifier(node: ts.Node): boolean {
313
+ return ts.canHaveModifiers(node) ? (ts.getModifiers(node)?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false) : false
314
+ }
315
+
316
+ /**
317
+ * Declare the function as it is actually CALLABLE, not as it was written.
318
+ *
319
+ * The capsule wraps every tool export in an async mediation wrapper
320
+ * (capsule/process/scope.ts) — policy is checked before the body runs, and a
321
+ * policy rule may escalate to the user, which is a round trip that cannot be
322
+ * synchronous. So the value the agent holds returns a Promise whatever the
323
+ * author wrote, and a sync-authored tool declared `(): number` is a lie the
324
+ * model acts on: told `add(a, b): number`, it writes `add(1, 2) * 2` and gets
325
+ * NaN with no error raised anywhere.
326
+ *
327
+ * Authors keep writing sync bodies — that works and stays supported. This only
328
+ * changes what the model and the editor are TOLD, so both agree with the
329
+ * runtime. An already-Promise return is left alone (never Promise<Promise<T>>).
330
+ */
331
+ function awaitable(declaration: string, node: ts.FunctionDeclaration, src: ts.SourceFile): string {
332
+ const returnType = node.type
333
+ if (!returnType) return declaration
334
+
335
+ // A type predicate (`x is string`) or assertion signature (`asserts x`) is
336
+ // only legal in a bare return-type position — `Promise<x is string>` does
337
+ // not parse. Such a tool is unusable across the capsule boundary anyway
338
+ // (the narrowing is erased by serialization), so leave the declaration
339
+ // exactly as the author wrote it rather than emitting broken TypeScript.
340
+ if (ts.isTypePredicateNode(returnType)) return declaration
341
+
342
+ const text = returnType.getText(src)
343
+ if (/^Promise\s*</.test(text)) return declaration
344
+
345
+ // The return type is the tail of the declaration: everything from the last
346
+ // top-level `:` onwards. Rebasing character offsets from the AST onto
347
+ // `declaration` is not safe — the caller has already stripped a leading
348
+ // `export declare ` and a trailing `;`, so AST positions no longer line up.
349
+ // Matching the type text at the END of the string does line up, because
350
+ // that is exactly where a return type sits.
351
+ const suffix = declaration.lastIndexOf(text)
352
+ if (suffix === -1 || suffix + text.length !== declaration.length) return declaration
353
+
354
+ return `${declaration.slice(0, suffix)}Promise<${text}>`
355
+ }
356
+
357
+ function extractJsDoc(node: ts.Node, src: ts.SourceFile): string | undefined {
358
+ const trivia = src.getFullText().slice(node.getFullStart(), node.getStart(src))
359
+ const match = trivia.match(/\/\*\*([\s\S]*?)\*\/\s*$/)
360
+ if (!match) return undefined
361
+ const lines = match[1]!.split("\n").map(l => l.replace(/^\s*\*\s?/, "").trimEnd())
362
+ while (lines.length > 0 && lines[0]!.trim() === "") lines.shift()
363
+ while (lines.length > 0 && lines[lines.length - 1]!.trim() === "") lines.pop()
364
+ return lines.length > 0 ? lines.join("\n") : undefined
365
+ }
366
+
367
+ /** Top-level exported function/const declarations from an emitted .d.ts, as ToolFnEntry — the file-level declaration emit reshaped back to the per-function granularity renderScope()/tool-globals.d.ts both need. */
368
+ function extractFnEntries(src: ts.SourceFile): ToolFnEntry[] {
369
+ const fns: ToolFnEntry[] = []
370
+
371
+ ts.forEachChild(src, node => {
372
+ if (ts.isFunctionDeclaration(node) && hasExportModifier(node) && node.name) {
373
+ const name = node.name.getText(src)
374
+ const jsdoc = extractJsDoc(node, src)
375
+ // tsc emits "export declare function foo(...): T;" — strip the
376
+ // ambient-context keywords the ExecutionScope block already
377
+ // supplies (declare) and the module-level marker (export),
378
+ // leaving a bare `function foo(...): T`.
379
+ const declText = node.getText(src).replace(/^export\s+declare\s+/, "").replace(/;\s*$/, "")
380
+ fns.push({ name, declaration: awaitable(declText, node, src), ...(jsdoc !== undefined ? { jsdoc } : {}) })
381
+ } else if (ts.isVariableStatement(node) && hasExportModifier(node)) {
382
+ for (const decl of node.declarationList.declarations) {
383
+ if (!ts.isIdentifier(decl.name)) continue
384
+ const name = decl.name.getText(src)
385
+ const jsdoc = extractJsDoc(node, src)
386
+ const declText = decl.getText(src)
387
+ fns.push({ name, declaration: `const ${declText}`, ...(jsdoc !== undefined ? { jsdoc } : {}) })
388
+ }
389
+ }
390
+ })
391
+
392
+ return fns
393
+ }
@@ -0,0 +1,137 @@
1
+ import * as h3 from "h3"
2
+
3
+ /**
4
+ * The h3 utility surface auto-imported into agent server files — routes,
5
+ * middleware, and server plugins. Agent authors never import h3, exactly as
6
+ * Nitro users never do: same names, same behavior, no shims. These ARE the
7
+ * real h3 implementations.
8
+ *
9
+ * ONE list, three consumers: routes.ts and middleware.ts install it at scan
10
+ * time, and typegen/axon-dts.ts declares it into .agent/axon.d.ts. They had
11
+ * drifted apart — the .d.ts declared ~25 helpers while the runtime installed
12
+ * 6, so `setHeader`/`sendStream`/`getCookie` and friends typechecked cleanly
13
+ * and threw ReferenceError the moment a route ran. A single exported list is
14
+ * what makes that class of bug unrepresentable: adding a name here reaches
15
+ * the runtime and the types in the same edit.
16
+ *
17
+ * Mirrors Nitro's auto-import set (h3's public utilities, minus the app/
18
+ * router construction functions an agent author has no business calling —
19
+ * Axon owns the app and the router).
20
+ */
21
+ export const H3_GLOBALS = [
22
+ // ── Event handler API ────────────────────────────────────────────────
23
+ "defineEventHandler",
24
+ "defineLazyEventHandler",
25
+ "defineWebSocketHandler",
26
+ "defineRequestMiddleware",
27
+ "defineResponseMiddleware",
28
+ "eventHandler",
29
+ "lazyEventHandler",
30
+ "dynamicEventHandler",
31
+ "isEvent",
32
+ "isEventHandler",
33
+ "toEventHandler",
34
+
35
+ // ── Request ──────────────────────────────────────────────────────────
36
+ "readBody",
37
+ "readValidatedBody",
38
+ "readRawBody",
39
+ "readFormData",
40
+ "readMultipartFormData",
41
+ "getQuery",
42
+ "getValidatedQuery",
43
+ "getRouterParam",
44
+ "getRouterParams",
45
+ "getValidatedRouterParams",
46
+ "getMethod",
47
+ "isMethod",
48
+ "assertMethod",
49
+ "getRequestURL",
50
+ "getRequestHost",
51
+ "getRequestIP",
52
+ "getRequestPath",
53
+ "getRequestProtocol",
54
+ "getRequestFingerprint",
55
+ "getRequestWebStream",
56
+ "toWebRequest",
57
+
58
+ // ── Headers ──────────────────────────────────────────────────────────
59
+ "getHeader",
60
+ "getHeaders",
61
+ "getRequestHeader",
62
+ "getRequestHeaders",
63
+ "setHeader",
64
+ "setHeaders",
65
+ "appendHeader",
66
+ "appendHeaders",
67
+ "getResponseHeader",
68
+ "getResponseHeaders",
69
+ "setResponseHeader",
70
+ "setResponseHeaders",
71
+ "appendResponseHeader",
72
+ "appendResponseHeaders",
73
+ "removeResponseHeader",
74
+ "clearResponseHeaders",
75
+
76
+ // ── Cookies & sessions ───────────────────────────────────────────────
77
+ "getCookie",
78
+ "setCookie",
79
+ "deleteCookie",
80
+ "parseCookies",
81
+ "splitCookiesString",
82
+ "useSession",
83
+ "getSession",
84
+ "updateSession",
85
+ "clearSession",
86
+ "sealSession",
87
+ "unsealSession",
88
+
89
+ // ── Response ─────────────────────────────────────────────────────────
90
+ "send",
91
+ "sendNoContent",
92
+ "sendRedirect",
93
+ "sendStream",
94
+ "sendIterable",
95
+ "sendWebResponse",
96
+ "sendError",
97
+ "sendProxy",
98
+ "proxyRequest",
99
+ "fetchWithEvent",
100
+ "getProxyRequestHeaders",
101
+ "setResponseStatus",
102
+ "getResponseStatus",
103
+ "getResponseStatusText",
104
+ "defaultContentType",
105
+ "isStream",
106
+ "isWebResponse",
107
+ "writeEarlyHints",
108
+ "serveStatic",
109
+
110
+ // ── Server-sent events ───────────────────────────────────────────────
111
+ "createEventStream",
112
+
113
+ // ── Errors ───────────────────────────────────────────────────────────
114
+ "createError",
115
+ "isError",
116
+ "sanitizeStatusCode",
117
+ "sanitizeStatusMessage",
118
+
119
+ // ── CORS ─────────────────────────────────────────────────────────────
120
+ "handleCors",
121
+ "appendCorsHeaders",
122
+ "appendCorsPreflightHeaders",
123
+ "isPreflightRequest",
124
+ "isCorsOriginAllowed",
125
+ ] as const satisfies readonly (keyof typeof h3)[]
126
+
127
+ /**
128
+ * Install the h3 surface onto globalThis. Idempotent (`??=`) and safe to call
129
+ * from every scanner — routes and middleware both run it before importing
130
+ * author files, and a module's scan runs it again per module root.
131
+ */
132
+ export function installH3Globals(): void {
133
+ const g = globalThis as Record<string, unknown>
134
+ for (const name of H3_GLOBALS) {
135
+ g[name] ??= h3[name]
136
+ }
137
+ }
@@ -0,0 +1,101 @@
1
+ import { join } from "node:path"
2
+ import { stat } from "node:fs/promises"
3
+ import type { AxonKnowledge } from "@arcforge/types"
4
+ import { fsx } from "../../../utils/fs"
5
+ import type { Scanned } from "../types"
6
+
7
+ /**
8
+ * How many bytes of a file are read looking for frontmatter.
9
+ *
10
+ * The catalogue must stay cheap to build: reading 200 files in full to
11
+ * extract 200 one-line descriptions would make the scan cost proportional to
12
+ * the corpus rather than to its file count.
13
+ */
14
+ const FRONTMATTER_BYTES = 4096
15
+
16
+ /**
17
+ * Pull a one-line summary out of YAML frontmatter.
18
+ *
19
+ * `description` wins over `title`, and both are read because real corpora are
20
+ * uneven — the Axon docs carry a title on 193 of 194 files and a description
21
+ * on 32. Reading only the richer field leaves most of a good catalogue as
22
+ * bare filenames, which is the difference between a model that can route and
23
+ * one that guesses.
24
+ *
25
+ * Deliberately narrow: two keys, string values, no nesting or multi-line
26
+ * scalars. A YAML dependency would buy nothing for one line, and anything
27
+ * unreadable is simply an entry with no description — ordinary, not an error.
28
+ * A .sqlite file has no frontmatter and is still legitimate knowledge.
29
+ */
30
+ function describe(head: string): string {
31
+ if (!head.startsWith("---")) return ""
32
+ const end = head.indexOf("\n---", 3)
33
+ if (end < 0) return ""
34
+
35
+ let title = ""
36
+ for (const line of head.slice(3, end).split("\n")) {
37
+ const match = /^\s*(description|title)\s*:\s*(.+?)\s*$/.exec(line)
38
+ if (!match) continue
39
+ const value = match[2]!.replace(/^["'](.*)["']$/, "$1")
40
+ if (match[1] === "description") return value
41
+ title ||= value
42
+ }
43
+ return title
44
+ }
45
+
46
+ /**
47
+ * Knowledge — `data/knowledge/`, for an agent and for a module alike.
48
+ *
49
+ * Both layouts are identical on purpose: a module mirrors the agent's
50
+ * directory, so there is one convention to learn and the scanner needs no
51
+ * branch. What differs is `origin`, and that is what decides writability
52
+ * downstream — a module's files live under node_modules and the next install
53
+ * would destroy anything written there.
54
+ *
55
+ * `prefix` namespaces a module's entries so its `axon/agent.md` cannot
56
+ * collide with the agent's own. Without it, whichever scanned last would
57
+ * silently win a name the model is being told it can read.
58
+ *
59
+ * Discovery only. Nothing here reads a file's body — that is the kernel's
60
+ * job at runtime, and a build that inlined 1.2MB of markdown into a blueprint
61
+ * would carry it through every serialization the blueprint makes.
62
+ */
63
+ export async function Knowledge(root: string, opts: { prefix?: string; required?: boolean } = {}): Promise<Scanned<AxonKnowledge>> {
64
+ const dir = join(root, "data", "knowledge")
65
+ const entries: AxonKnowledge[] = []
66
+ const warnings: Scanned<AxonKnowledge>["warnings"] = []
67
+
68
+ for (const { absPath, relPath } of await fsx.walk(dir)) {
69
+ // Editor swap files, .DS_Store, .gitkeep — noise a model must never
70
+ // spend context reading past.
71
+ if (relPath.split("/").some(part => part.startsWith("."))) continue
72
+
73
+ try {
74
+ const info = await stat(absPath)
75
+ if (!info.isFile()) continue
76
+
77
+ const head = await Bun.file(absPath).slice(0, FRONTMATTER_BYTES).text()
78
+ const name = opts.prefix ? `${opts.prefix}/${relPath}` : relPath
79
+
80
+ entries.push({
81
+ name,
82
+ description: describe(head),
83
+ size: info.size,
84
+ path: absPath,
85
+ origin: opts.prefix ? "module" : "agent",
86
+ ...(opts.prefix ? { module: opts.prefix } : {}),
87
+ })
88
+ } catch (cause) {
89
+ // One unreadable file must not cost the model every other entry —
90
+ // a broken symlink or a permissions quirk is a missing entry, not
91
+ // a broken agent. The strict/degrade split every other scanner
92
+ // draws does not apply: there is no code here to half-load.
93
+ warnings.push({
94
+ domain: "knowledge",
95
+ error: `knowledge: could not read ${relPath} — ${cause instanceof Error ? cause.message : String(cause)}`,
96
+ })
97
+ }
98
+ }
99
+
100
+ return { entries, warnings }
101
+ }