@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,110 @@
1
+ import { basename, join } from "node:path"
2
+ import { defineMiddleware } from "@arcforge/types"
3
+ import type { AxonMiddleware } from "@arcforge/types"
4
+ import { err } from "@arcforge/err"
5
+ import { fsx } from "../../../utils/fs"
6
+ import type { Scanned } from "../types"
7
+ import { installH3Globals } from "./h3-globals"
8
+
9
+ /**
10
+ * Middleware files use the ambient `defineMiddleware` global plus the same h3
11
+ * helpers route files get — agent authors never import either. Install the
12
+ * real implementations before importing middleware files (idempotent).
13
+ */
14
+ function installMiddlewareGlobals(): void {
15
+ const g = globalThis as Record<string, unknown>
16
+ g.defineMiddleware ??= defineMiddleware
17
+ installH3Globals()
18
+ }
19
+
20
+ /**
21
+ * Middleware — server/middleware/ of ONE root. Each file default-exports a
22
+ * defineMiddleware() result and runs on EVERY request, ahead of plugins,
23
+ * the reserved /_axon/* surface, and user routes alike.
24
+ *
25
+ * ORDER IS THE FILENAME. Nitro's contract, kept exactly: middleware is sorted
26
+ * lexicographically by path, so `01.auth.ts` runs before `02.log.ts` and an
27
+ * author controls sequence by naming rather than by a config list. fsx.walk
28
+ * gives no ordering guarantee of its own, so the sort here is what makes the
29
+ * contract real — without it, two agents with identical files could gate
30
+ * requests in different orders on different machines.
31
+ *
32
+ * Module middleware comes from Modules() running this scanner per module
33
+ * root, exactly as it does for routes and plugins.
34
+ *
35
+ * This scanner IMPORTS each file to resolve its handler — the blueprint
36
+ * contract requires resolved values so the runtime mounts as-is and never
37
+ * touches the filesystem. A file that fails to import or lacks a default
38
+ * export is a warning, not middleware.
39
+ */
40
+ export async function Middleware(root: string, opts: { required?: boolean } = {}): Promise<Scanned<AxonMiddleware>> {
41
+ const entries: AxonMiddleware[] = []
42
+ const warnings: Scanned<AxonMiddleware>["warnings"] = []
43
+
44
+ installMiddlewareGlobals()
45
+
46
+ const files = await fsx.walk(join(root, "server", "middleware"))
47
+ // Lexicographic by relative path — the ordering contract above.
48
+ const ordered = [...files].sort((a, b) => a.relPath.localeCompare(b.relPath))
49
+
50
+ for (const { absPath, relPath } of ordered) {
51
+ if (!relPath.endsWith(".ts") || relPath.endsWith(".test.ts")) continue
52
+
53
+ try {
54
+ const mod = (await import(absPath)) as { default?: unknown }
55
+ const entry = mod.default as AxonMiddleware | undefined
56
+
57
+ // A bare defineEventHandler default-export is accepted too: it is
58
+ // the shape an author reaches for out of h3 habit, and refusing it
59
+ // would fail with "no default-export defineMiddleware()" for a file
60
+ // that is otherwise perfectly valid.
61
+ const handler = entry && typeof entry.handler === "function"
62
+ ? entry.handler
63
+ : typeof mod.default === "function"
64
+ ? (mod.default as AxonMiddleware["handler"])
65
+ : undefined
66
+
67
+ if (!handler) {
68
+ warnings.push({ domain: "middleware", error: `${absPath} has no default-export defineMiddleware() — skipped` })
69
+ continue
70
+ }
71
+
72
+ // The filename names what the middleware does ("auth"), which reads
73
+ // better in boot errors than defineMiddleware's generic fallback for
74
+ // an anonymous arrow. Same rule as plugins.
75
+ const named = entry?.name && entry.name !== "middleware" ? entry.name : basename(relPath, ".ts")
76
+ entries.push({ name: named, handler })
77
+ } catch (error) {
78
+ const failure = err("MIDDLEWARE_LOAD_FAILED", {
79
+ detail: `${absPath} — ${error instanceof Error ? error.message : String(error)}`,
80
+ context: { file: absPath },
81
+ cause: error,
82
+ })
83
+
84
+ // Strict for an agent's own middleware, degraded for a module's —
85
+ // but "degraded" here does NOT mean skipped.
86
+ //
87
+ // Middleware commonly carries auth and validation. A skipped one is
88
+ // a request path running without the checks its author wrote: not a
89
+ // missing capability, but a security hole wearing the costume of a
90
+ // working server. So the entry is KEPT, carrying its reason, and
91
+ // the runtime replaces it with a handler that refuses every request
92
+ // — the route stays addressable and answers 503, exactly as a
93
+ // reverse proxy does for a backend it cannot reach.
94
+ //
95
+ // That is also why there is no "allow degraded in dev" switch.
96
+ // There is no environment in which serving unguarded is correct:
97
+ // dev is where the client that assumes auth works gets built, and
98
+ // where a real token gets pasted into a request nothing checks.
99
+ if (opts.required !== false) throw failure
100
+
101
+ // basename, not `named`: that is bound inside the try and the
102
+ // module never loaded, so the filename is the only name there is.
103
+ entries.push({ name: basename(relPath, ".ts"), failed: failure.message })
104
+ warnings.push({ domain: "middleware", error: failure.message, cause: failure })
105
+ continue
106
+ }
107
+ }
108
+
109
+ return { entries, warnings }
110
+ }
@@ -0,0 +1,79 @@
1
+ import { dirname } from "node:path"
2
+ import type TsNamespace from "typescript"
3
+ import {
4
+ collectDefaultImports,
5
+ findConfigProperty,
6
+ parseConfig,
7
+ resolveBinding,
8
+ tsc,
9
+ type ResolvedDeclaration,
10
+ } from "./configImports"
11
+
12
+ /**
13
+ * Static resolution of a config file's `modules: [...]` declaration to the
14
+ * absolute `module.config.ts` path of each SOURCE module.
15
+ *
16
+ * This is how a source module's identity is recovered now that
17
+ * `defineModule()` is pure and stamps nothing — see configImports.ts for the
18
+ * shared machinery and why it resolves statically rather than at runtime.
19
+ *
20
+ * Resolution is POSITIONAL: entry N in the returned array corresponds to entry
21
+ * N in the config's `modules: [...]` array, which is the same order the
22
+ * evaluated config produces. A registry entry (a bare string) resolves to a
23
+ * `registry` result — it has no source path; it is a package name resolved
24
+ * from node_modules elsewhere.
25
+ */
26
+
27
+ /** Module resolution is the shared shape — a module has no extra states. */
28
+ export type ResolvedModulePath = ResolvedDeclaration
29
+
30
+ /** The config filenames a module import may point at. */
31
+ const MODULE_CONFIGS = ["module.config.ts", "module.config.js"] as const
32
+
33
+ /**
34
+ * Resolve every entry in a config's `modules: [...]` array to a path (or a
35
+ * registry name). `configFilePath` is the file whose `defineAgent`/
36
+ * `defineModule` call the array lives in — imports resolve relative to it.
37
+ */
38
+ export async function resolveModulePaths(configFilePath: string): Promise<ResolvedModulePath[]> {
39
+ const src = await parseConfig(configFilePath)
40
+ if (!src) return []
41
+
42
+ const modulesProperty = findConfigProperty(src, "modules")
43
+ if (!modulesProperty || !tsc().isArrayLiteralExpression(modulesProperty)) return []
44
+
45
+ const imports = collectDefaultImports(src)
46
+ const configDir = dirname(configFilePath)
47
+ const resolved: ResolvedModulePath[] = []
48
+
49
+ for (const element of modulesProperty.elements) {
50
+ resolved.push(await resolveEntry(element, imports, configDir, configFilePath))
51
+ }
52
+ return resolved
53
+ }
54
+
55
+ async function resolveEntry(
56
+ element: TsNamespace.Expression,
57
+ imports: Map<string, string>,
58
+ configDir: string,
59
+ configFilePath: string,
60
+ ): Promise<ResolvedModulePath> {
61
+ // ["registry-name", opts] | [Ident, opts] | [defineModule({...}), opts]
62
+ // — the tuple form is module-only, so it stays here rather than in the
63
+ // shared resolver. A cognet is singular and takes no options.
64
+ if (tsc().isArrayLiteralExpression(element)) {
65
+ const head = element.elements[0]
66
+ if (head) return resolveEntry(head, imports, configDir, configFilePath)
67
+ return { kind: "unresolved", detail: "empty module tuple in modules: [...]" }
68
+ }
69
+
70
+ return resolveBinding({
71
+ element,
72
+ imports,
73
+ configDir,
74
+ configFilePath,
75
+ configNames: MODULE_CONFIGS,
76
+ factory: "defineModule",
77
+ label: "module",
78
+ })
79
+ }
@@ -0,0 +1,93 @@
1
+ import { basename, join } from "node:path"
2
+ import { defineAxonPlugin } from "@arcforge/types"
3
+ import type { AxonPlugin } from "@arcforge/types"
4
+ import { err } from "@arcforge/err"
5
+ import { fsx } from "../../../utils/fs"
6
+ import type { Scanned } from "../types"
7
+
8
+ /**
9
+ * Plugin files use the ambient `defineAxonPlugin` global — agent authors never
10
+ * import it, same convention as route files and defineEventHandler. Install
11
+ * the real implementation before importing plugin files (idempotent).
12
+ */
13
+ function installPluginGlobals(): void {
14
+ const g = globalThis as Record<string, unknown>
15
+ g.defineAxonPlugin ??= defineAxonPlugin
16
+ }
17
+
18
+ /**
19
+ * Plugins — server/plugins/ of ONE root. Each file default-exports a
20
+ * defineAxonPlugin() result; the plugin runs once at server boot, after
21
+ * middleware and before routes, and receives the runtime's axon handle to
22
+ * subscribe to hooks and wire behaviour.
23
+ *
24
+ * Module plugins come from Modules() running this scanner per module root,
25
+ * exactly as it does for routes — a module ships its own server/plugins/ and
26
+ * they merge into the same blueprint.server.plugins list, origin-blind.
27
+ *
28
+ * This scanner IMPORTS each plugin file to resolve its fn — the blueprint
29
+ * contract requires resolved values so the runtime boots as-is and never
30
+ * touches the filesystem. A file that fails to import or lacks a default
31
+ * export is a warning, not a plugin.
32
+ */
33
+ /**
34
+ * Whether a file the author wrote that cannot be READ is fatal.
35
+ *
36
+ * True for an agent's own source: the agent is defined by what its author
37
+ * wrote, so silently running a subset of it produces an agent nobody asked
38
+ * for. Invalid state, and invalid states crash.
39
+ *
40
+ * False for a MODULE's, and that is the whole distinction: an agent that
41
+ * installed a broken module is not an invalid agent — it is the agent it was
42
+ * before the install. Crashing the runtime over one dependency leaves the user
43
+ * unable to boot the terminal they need in order to remove it.
44
+ *
45
+ * Degrading was previously rejected because a warning "reached nobody at
46
+ * runtime" — true then, since build:warning classified as debug and was hidden
47
+ * at default verbosity. It is now info-level and renders as its own card, and
48
+ * a module's failure additionally reaches the MODEL through scope.unavailable.
49
+ *
50
+ * Defaults to true: a caller that has not thought about it gets the strict
51
+ * behaviour, and only the module scanner opts out.
52
+ */
53
+ export async function Plugins(root: string, opts: { required?: boolean } = {}): Promise<Scanned<AxonPlugin>> {
54
+ const entries: AxonPlugin[] = []
55
+ const warnings: Scanned<AxonPlugin>["warnings"] = []
56
+
57
+ installPluginGlobals()
58
+
59
+ for (const { absPath, relPath } of await fsx.walk(join(root, "server", "plugins"))) {
60
+ if (!relPath.endsWith(".ts") || relPath.endsWith(".test.ts")) continue
61
+
62
+ try {
63
+ const mod = (await import(absPath)) as { default?: unknown }
64
+ const plugin = mod.default as AxonPlugin | undefined
65
+ if (!plugin || typeof plugin.fn !== "function") {
66
+ warnings.push({ domain: "plugins", error: `${absPath} has no default-export defineAxonPlugin() — skipped` })
67
+ continue
68
+ }
69
+ // The filename names what the plugin wires ("discord"), which reads
70
+ // better in boot errors than defineAxonPlugin's generic "plugin"
71
+ // fallback for an anonymous arrow. Prefer it; keep a named fn's own
72
+ // name only when it's more specific than the fallback.
73
+ const named = plugin.name && plugin.name !== "plugin" ? plugin.name : basename(relPath, ".ts")
74
+ entries.push({ name: named, fn: plugin.fn })
75
+ } catch (error) {
76
+ // Plugins wire server behaviour at boot; one silently missing means
77
+ // the agent runs without behaviour its author declared.
78
+ const failure = err("PLUGIN_LOAD_FAILED", {
79
+ detail: `${absPath} — ${error instanceof Error ? error.message : String(error)}`,
80
+ context: { file: absPath },
81
+ cause: error,
82
+ })
83
+ // Strict for an agent's own files, degraded for a module's.
84
+ // Per FILE: one unreadable script skips that script, never the
85
+ // rest of the directory beside it.
86
+ if (opts.required !== false) throw failure
87
+ warnings.push({ domain: "plugins", error: failure.message, cause: failure })
88
+ continue
89
+ }
90
+ }
91
+
92
+ return { entries, warnings }
93
+ }
@@ -0,0 +1,45 @@
1
+ import { join } from "node:path"
2
+ import type { AxonPrompt } from "@arcforge/types"
3
+ import { fsx } from "../../../utils/fs"
4
+ import { Prompts } from "./prompts"
5
+ import type { Scanned } from "../types"
6
+
7
+ /**
8
+ * Prompt packages — a published prompt artifact, scanned into prompts.
9
+ *
10
+ * A prompt is content, not a capability: it is fetched into the global cache
11
+ * (~/.axon/cache/prompts/...) and rendered on demand, so no agent installs one
12
+ * or depends on it. Each package contributes every top-level .vue/.md it
13
+ * ships, namespaced by the package:
14
+ *
15
+ * @cody/eslint-scout → "@cody/eslint-scout:scout"
16
+ * "@cody/eslint-scout:reconcile"
17
+ *
18
+ * The prefix is what makes a published prompt unable to shadow an agent's own
19
+ * `src/prompts/scout.vue` — they occupy different namespaces by construction
20
+ * rather than by a precedence rule that has to be remembered.
21
+ *
22
+ * A package that declares exactly one prompt named after itself also answers
23
+ * to the bare package name, so `@cody/scout` need not be written
24
+ * `@cody/scout:scout`.
25
+ *
26
+ * Both layouts go through Prompts(): a package authored agent-shaped keeps its
27
+ * src/prompts/, a flat one is scanned with the package root AS the prompts
28
+ * directory. README.md is excluded — it is documentation, not an instruction
29
+ * to run.
30
+ */
31
+ export async function scanPromptPackage(packageRoot: string, name: string): Promise<Scanned<AxonPrompt>> {
32
+ const nested = fsx.exists(join(packageRoot, "src", "prompts"))
33
+ const scanned = await Prompts(packageRoot, { prefix: name, ...(nested ? {} : { dir: "." }) })
34
+
35
+ const entries = scanned.entries.filter(entry => entry.name !== `${name}:README`)
36
+
37
+ // The single-prompt shorthand: @cody/scout shipping scout.vue also
38
+ // answers to the bare package name, so the common case reads as one
39
+ // thing rather than a package with one member.
40
+ const bare = name.split("/").at(-1)
41
+ const self = entries.find(entry => entry.name === `${name}:${bare}`)
42
+ if (self && entries.length === 1) entries.push({ ...self, name })
43
+
44
+ return { entries, warnings: scanned.warnings }
45
+ }
@@ -0,0 +1,164 @@
1
+ import { extname, join, relative } from "node:path"
2
+ import type { vstr as Vstr } from "@arcforge/vstr"
3
+ import type { AxonPrompt } from "@arcforge/types"
4
+ import { err } from "@arcforge/err"
5
+ import { fsx } from "../../../utils/fs"
6
+ import { Components } from "./components"
7
+ import type { Scanned } from "../types"
8
+
9
+ /**
10
+ * `@arcforge/vstr` pulls the whole Vue toolchain behind it — @vue/compiler-sfc,
11
+ * runtime-core, server-renderer, turndown — which is ~280ms of module
12
+ * evaluation, and it was paid at IMPORT time by everything that touched the
13
+ * blueprint. That made it the single largest cost in booting an agent, ahead
14
+ * of the scan itself, and an agent with no .vue prompts at all paid it in full.
15
+ *
16
+ * Loaded on first use instead, and memoised so a directory of .vue prompts
17
+ * still evaluates it once. Static-only and empty prompt directories — every
18
+ * `axon` invocation that never introspects a component — never load Vue.
19
+ */
20
+ let vstrModule: Promise<{ vstr: typeof Vstr }> | null = null
21
+ function loadVstr(): Promise<{ vstr: typeof Vstr }> {
22
+ vstrModule ??= import("@arcforge/vstr")
23
+ return vstrModule
24
+ }
25
+
26
+ /**
27
+ * Prompts — src/prompts/ *.md (static) and *.vue (dynamic, props
28
+ * introspected via vstr). components/ subtrees belong to Components.
29
+ */
30
+ /**
31
+ * Whether a file the author wrote that cannot be READ is fatal.
32
+ *
33
+ * True for an agent's own source: the agent is defined by what its author
34
+ * wrote, so silently running a subset of it produces an agent nobody asked
35
+ * for. Invalid state, and invalid states crash.
36
+ *
37
+ * False for a MODULE's, and that is the whole distinction: an agent that
38
+ * installed a broken module is not an invalid agent — it is the agent it was
39
+ * before the install. Crashing the runtime over one dependency leaves the user
40
+ * unable to boot the terminal they need in order to remove it.
41
+ *
42
+ * Degrading was previously rejected because a warning "reached nobody at
43
+ * runtime" — true then, since build:warning classified as debug and was hidden
44
+ * at default verbosity. It is now info-level and renders as its own card, and
45
+ * a module's failure additionally reaches the MODEL through scope.unavailable.
46
+ *
47
+ * Defaults to true: a caller that has not thought about it gets the strict
48
+ * behaviour, and only the module scanner opts out.
49
+ */
50
+ export async function Prompts(root: string, opts: { prefix?: string; dir?: string; required?: boolean } = {}): Promise<Scanned<AxonPrompt>> {
51
+ // A prompt PACKAGE keeps its prompts at the top level rather than under
52
+ // src/prompts/ — same files, same rules, different depth. `dir` is how
53
+ // that layout reuses this walker instead of duplicating it.
54
+ const promptsDir = opts?.dir ? join(root, opts.dir) : join(root, "src", "prompts")
55
+ const entries: AxonPrompt[] = []
56
+ const warnings: Scanned<AxonPrompt>["warnings"] = []
57
+
58
+ // Scanned once per root and carried on each dynamic entry, so the
59
+ // renderer never re-derives this from a file path. Components sit beside
60
+ // the prompts in both layouts — components/ off whichever directory the
61
+ // prompts themselves live in.
62
+ const components = await Components(root, opts?.dir ? { dir: join(opts.dir, "components") } : undefined)
63
+ const componentPaths = Object.fromEntries(components.entries.map(entry => [entry.name, entry.filePath]))
64
+ const hasComponents = components.entries.length > 0
65
+
66
+ for (const { absPath, relPath } of await fsx.walk(promptsDir, { skipDirs: ["components"] })) {
67
+ const ext = extname(absPath)
68
+ if (ext !== ".md" && ext !== ".vue") continue
69
+
70
+ const name = relative(".", relPath).slice(0, -ext.length).replace(/\\/g, "/")
71
+ const prefixed = opts?.prefix ? `${opts.prefix}:${name}` : name
72
+
73
+ try {
74
+ if (ext === ".md") {
75
+ const content = (await fsx.readText(absPath)) ?? ""
76
+ entries.push({
77
+ name: prefixed,
78
+ kind: "static",
79
+ filePath: absPath,
80
+ ...(firstLine(content) !== undefined ? { description: firstLine(content)! } : {}),
81
+ })
82
+ } else {
83
+ const { vstr } = await loadVstr()
84
+ const props = vstr(absPath).introspect()
85
+
86
+ // A template interpolates VALUES. Anything async has to be
87
+ // awaited in `<script setup>` and interpolated by name — see
88
+ // promptContext, which puts the agent's tools in scope
89
+ // precisely so that is possible.
90
+ for (const call of interpolatedCalls((await fsx.readText(absPath)) ?? "")) {
91
+ warnings.push({
92
+ domain: "prompts",
93
+ error: `${prefixed}: \`{{ ${call} }}\` calls a function in the template.`
94
+ + ` If it returns a promise this renders as "[object Promise]" and the model`
95
+ + ` receives that verbatim — await it in <script setup> and interpolate the result.`,
96
+ })
97
+ }
98
+ entries.push({
99
+ name: prefixed,
100
+ kind: "dynamic",
101
+ filePath: absPath,
102
+ // Static .md has no template, so nothing to compose into.
103
+ ...(hasComponents ? { components: componentPaths } : {}),
104
+ ...(props.length > 0
105
+ ? { props: props.map(p => ({ name: p.name, type: p.type, required: p.required })) }
106
+ : {}),
107
+ })
108
+ }
109
+ } catch (error) {
110
+ // A prompt that cannot be introspected renders without the inputs it
111
+ // declares, or not at all.
112
+ const failure = err("PROMPT_INTROSPECT_FAILED", {
113
+ detail: `${absPath} — ${error instanceof Error ? error.message : String(error)}`,
114
+ context: { file: absPath },
115
+ cause: error,
116
+ })
117
+ // Strict for an agent's own files, degraded for a module's.
118
+ // Per FILE: one unreadable script skips that script, never the
119
+ // rest of the directory beside it.
120
+ if (opts.required !== false) throw failure
121
+ warnings.push({ domain: "prompts", error: failure.message, cause: failure })
122
+ continue
123
+ }
124
+ }
125
+
126
+ return { entries, warnings }
127
+ }
128
+
129
+ /**
130
+ * Calls appearing directly inside a `{{ }}` interpolation.
131
+ *
132
+ * Syntactic on purpose: knowing which names are async would mean carrying the
133
+ * tool scope into the prompt scanner, and the useful signal does not need it.
134
+ * A template can only render a value, so a CALL there is already suspicious —
135
+ * and the async ones are the case that fails silently, reaching the model as
136
+ * "[object Promise]" rather than throwing.
137
+ *
138
+ * Deliberately narrow to avoid crying wolf:
139
+ * - only `name(` and `ns.name(` heads, so `{{ items.length }}` is quiet
140
+ * - `$`-prefixed and capitalised heads are skipped (framework helpers,
141
+ * component references)
142
+ *
143
+ * A warning, never a failure: a synchronous helper called in a template is
144
+ * unusual but legal, and a build that refused it would be wrong.
145
+ */
146
+ function interpolatedCalls(source: string): string[] {
147
+ const found: string[] = []
148
+ for (const match of source.matchAll(/\{\{([^}]*)\}\}/g)) {
149
+ const expression = (match[1] ?? "").trim()
150
+ const call = /^([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\s*\(/.exec(expression)
151
+ if (!call) continue
152
+ const head = call[1]!
153
+ if (head.startsWith("$") || /^[A-Z]/.test(head)) continue
154
+ found.push(expression)
155
+ }
156
+ return found
157
+ }
158
+
159
+ function firstLine(content: string): string | undefined {
160
+ const lines = content.split("\n").map(l => l.trim()).filter(Boolean)
161
+ if (lines.length === 0) return undefined
162
+ const first = lines[0]!
163
+ return first.startsWith("#") ? first.replace(/^#+\s*/, "") : first
164
+ }
@@ -0,0 +1,131 @@
1
+ import { join } from "node:path"
2
+ import { fsx } from "../../../utils/fs"
3
+ import type { DeclaredFile } from "./declare"
4
+
5
+ /**
6
+ * Published — read a module's tools from the manifest it shipped, instead of
7
+ * re-deriving them from its installed source.
8
+ *
9
+ * THE BUG THIS EXISTS FOR. `declareTools()` runs a real `ts.createProgram()`
10
+ * and asks it to emit declarations. TypeScript treats `node_modules` as
11
+ * EXTERNAL LIBRARY CODE and silently skips declaration emit for anything
12
+ * inside it — so a module whose tool file imports a sibling
13
+ * (`../arxiv/client.ts`) got exactly one `.d.ts` where it needed two, and
14
+ * every type declared in that sibling became unresolvable.
15
+ *
16
+ * Proven with byte-identical files: outside node_modules two declarations
17
+ * emit and the scan passes; inside node_modules one emits and the scan throws
18
+ * `type "QueryOptions" is used in an exported signature but has no resolvable
19
+ * definition` — pointing the author at a re-export their source already had.
20
+ *
21
+ * The fix is not to compile harder. It is to stop re-deriving something the
22
+ * publish step ALREADY COMPUTED: a published module ships
23
+ * `.module/build/manifest.json` carrying each tool's `fns`, its
24
+ * `ambientTypes`, and its bundled `source`. Those were emitted in the module's
25
+ * own directory, where the compiler behaves — so they are strictly MORE
26
+ * correct than anything a consumer can derive from the installed copy.
27
+ *
28
+ * It is also faster: the whole `ts.createProgram()` (500ms-1.5s cold) and the
29
+ * bundle step collapse into one file read.
30
+ *
31
+ * This applies ONLY to installed modules. An agent's own `src/tools/` is
32
+ * source under development with no manifest and no publish behind it, and it
33
+ * must keep compiling from source — that is where a type error should surface.
34
+ */
35
+
36
+ /** What a published manifest records for one tool file. */
37
+ type PublishedTool = {
38
+ name: string
39
+ fns: DeclaredFile["fns"]
40
+ ambientTypes?: string[]
41
+ /** Bundled, self-contained source — what the capsule loads. */
42
+ source?: string
43
+ /** Absolute path on the PUBLISHER's machine. Never used to read from. */
44
+ entryPath?: string
45
+ }
46
+
47
+ type PublishedManifest = {
48
+ name?: string
49
+ version?: string
50
+ kind?: string
51
+ tools?: PublishedTool[]
52
+ }
53
+
54
+ /**
55
+ * What a consumer needs from a published module, in the scan's own shapes.
56
+ *
57
+ * Keyed by ABSOLUTE FILE PATH rather than tool name, because that is what the
58
+ * scan's own maps are keyed by and this stands in for them exactly. The paths
59
+ * are rebuilt from the CONSUMER's tools directory — the manifest's `entryPath`
60
+ * is where the file lived on the publisher's machine and means nothing here.
61
+ */
62
+ export type PublishedTools = {
63
+ /** Absolute tool file path → its declarations. */
64
+ declared: Map<string, DeclaredFile>
65
+ /** Absolute tool file path → its bundled source. */
66
+ bundled: Map<string, string>
67
+ }
68
+
69
+ /**
70
+ * Read a published module's tool manifest, or null when there is not a
71
+ * complete one to read.
72
+ *
73
+ * Null is the honest answer for every partial case — no manifest, no tools
74
+ * key, a tool missing its declarations or its bundled source, or a manifest
75
+ * describing a different set of tools than the installed source actually has.
76
+ * The caller falls back to compiling from source, which is what happens today
77
+ * and is never worse than what it replaces. Nothing here guesses: a manifest
78
+ * that cannot answer the whole question does not get to answer part of it.
79
+ *
80
+ * `toolFiles` is the set the scan found on disk. Requiring the manifest to
81
+ * cover exactly that set is what keeps this honest — a manifest listing fewer
82
+ * tools than are installed would silently drop one from the model's scope, and
83
+ * one listing MORE would describe a tool whose source is not there.
84
+ */
85
+ export async function publishedTools(
86
+ root: string,
87
+ toolFiles: string[],
88
+ ): Promise<PublishedTools | null> {
89
+ const manifest = await fsx.readJson<PublishedManifest>(
90
+ join(root, ".module", "build", "manifest.json"),
91
+ )
92
+ if (!manifest?.tools || manifest.tools.length === 0) return null
93
+
94
+ // Tool name → the installed file it corresponds to. A manifest entry is
95
+ // named for its file's basename without the extension, which is the same
96
+ // derivation the scan uses when it builds `entries`.
97
+ const byName = new Map<string, string>()
98
+ for (const filePath of toolFiles) {
99
+ const base = filePath.slice(filePath.lastIndexOf("/") + 1)
100
+ byName.set(base.slice(0, -3), filePath)
101
+ }
102
+
103
+ const declared = new Map<string, DeclaredFile>()
104
+ const bundled = new Map<string, string>()
105
+
106
+ for (const tool of manifest.tools) {
107
+ // Every field the scan would have produced has to be present. A tool
108
+ // with declarations but no bundled source would enter the model's
109
+ // scope as something the capsule cannot load — a tool that is
110
+ // described and uncallable, which is worse than one that is absent.
111
+ if (!tool.name || !Array.isArray(tool.fns) || tool.fns.length === 0) return null
112
+ if (typeof tool.source !== "string" || tool.source.length === 0) return null
113
+
114
+ const filePath = byName.get(tool.name)
115
+ // The manifest names a tool this installation does not have. The two
116
+ // disagree about what is installed, so neither is trustworthy.
117
+ if (!filePath) return null
118
+
119
+ declared.set(filePath, {
120
+ fns: tool.fns,
121
+ ambientTypes: tool.ambientTypes ?? [],
122
+ })
123
+ bundled.set(filePath, tool.source)
124
+ }
125
+
126
+ // Every installed tool file must be covered. A file the manifest does not
127
+ // describe would silently vanish from scope.
128
+ if (declared.size !== toolFiles.length) return null
129
+
130
+ return { declared, bundled }
131
+ }