@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,362 @@
1
+ import { writeDts, type TypegenKind } from "./write"
2
+ import { H3_GLOBALS } from "../../blueprint/scan/h3-globals"
3
+
4
+ /**
5
+ * `.agent/axon.d.ts` (config/src scope) and `.agent/axon-test.d.ts` (tests
6
+ * scope) are two DELIBERATELY SEPARATE declaration files, never merged into
7
+ * one ambient scope. Both declare a global named `Axon` — the engine
8
+ * constructor (`Axon({ model })`, used in axon.config.ts) and the test
9
+ * runtime spawner (`await Axon()`, used in tests/*.test.ts) are genuinely
10
+ * different things with the same name in different runtimes. Declaring both
11
+ * in one `declare global` block is a duplicate-identifier error that
12
+ * degrades silently to `any` in some tooling — the actual bug this split
13
+ * exists to prevent. tsconfig.ts gives tests/ its own nested tsconfig that
14
+ * includes axon-test.d.ts INSTEAD of axon.d.ts, so only one `Axon` is ever
15
+ * in scope for a given file.
16
+ *
17
+ * Declares exactly the globals that `inject.ts` puts on globalThis — nothing more.
18
+ * The h3 block is GENERATED from `H3_GLOBALS`, the same list the scanners
19
+ * install at runtime, so the declared surface and the installed surface cannot
20
+ * drift. They previously did: this file declared ~25 helpers while routes.ts
21
+ * installed 6, making `setHeader`/`sendStream`/`getCookie` typecheck and then
22
+ * throw ReferenceError when the route actually ran. Nitro globals are
23
+ * intentionally absent — Axon uses h3 directly, not Nitro.
24
+ *
25
+ * Tool namespace globals are generated separately into `.agent/tool-globals.d.ts`.
26
+ * Prompt/script type overloads are generated into `.agent/prompts.d.ts` / `.agent/scripts.d.ts`.
27
+ */
28
+
29
+ /**
30
+ * Body shared by both scopes — everything except `Axon` itself. No
31
+ * `declare global {`/`}` wrapper and no `export {}` here: each output file
32
+ * below supplies its own so it can insert its own scope-specific `Axon`
33
+ * declaration inside the same block.
34
+ */
35
+ const SHARED_BODY = `\
36
+ namespace NodeJS {
37
+ // ── Axon-injected env vars ────────────────────────────────────────────
38
+ interface ProcessEnv {
39
+ /**
40
+ * Absolute path to the agent's own directory — its PROJECT ROOT,
41
+ * the folder holding axon.config.ts. Injected by the Axon runtime
42
+ * into every capsule — always present, never undefined.
43
+ *
44
+ * Authored content sits directly under it; anything the runtime
45
+ * generated or recorded is under \`.agent/\`:
46
+ * \`\`\`ts
47
+ * const knowledge = \`\${process.env.AXON_HOME}/data/knowledge\`
48
+ * const state = \`\${process.env.AXON_HOME}/.agent/data/state\`
49
+ * \`\`\`
50
+ */
51
+ AXON_HOME: string
52
+ }
53
+
54
+ // ── process.run() / process.spawn() ──────────────────────────────────
55
+ // The capsule extends the global process object with two safe execution APIs.
56
+ // process.exit() is blocked — the capsule manages its own lifecycle.
57
+ interface Process {
58
+ /**
59
+ * Run a shell command and wait for it to complete. Never throws — errors are
60
+ * returned in the result object.
61
+ *
62
+ * \`\`\`ts
63
+ * const { ok, stdout, stderr } = await process.run("git status")
64
+ * if (!ok) console.error(stderr)
65
+ * \`\`\`
66
+ *
67
+ * @see https://axon.arclabs.it/docs/v2/api/proc/run
68
+ */
69
+ run(
70
+ command: string,
71
+ opts?: { cwd?: string; env?: Record<string, string>; input?: string }
72
+ ): Promise<{ ok: boolean; exitCode: number; stdout: string; stderr: string; err?: string }>
73
+
74
+ /**
75
+ * Spawn a long-running process. Returns a handle immediately — the process
76
+ * runs in the background and is visible in the agent's process list.
77
+ *
78
+ * \`\`\`ts
79
+ * const server = process.spawn("bun dev")
80
+ * await server.waitFor("ready", { timeoutMs: 10_000 })
81
+ * const logs = server.stdout()
82
+ * server.kill()
83
+ * \`\`\`
84
+ *
85
+ * @see https://axon.arclabs.it/docs/v2/api/proc/spawn
86
+ */
87
+ spawn(
88
+ command: string,
89
+ opts?: { cwd?: string; env?: Record<string, string> }
90
+ ): LiveProcHandle
91
+ }
92
+ }
93
+
94
+ // ── Axon runtime globals ──────────────────────────────────────────────
95
+
96
+ /**
97
+ * The live Axon runtime handle. Available as a global in tools, scripts,
98
+ * hooks, and server routes — no import needed.
99
+ *
100
+ * Everything the agent can do is accessed through this object: sending
101
+ * requests, calling tools, running scripts, and reacting to lifecycle
102
+ * events.
103
+ *
104
+ * **One-shot request** — waits for the full cognitive loop to complete:
105
+ * \`\`\`ts
106
+ * const result = await axon.request("summarise the project")
107
+ * console.log(result.text)
108
+ * \`\`\`
109
+ *
110
+ * **Streaming** — receive entries as they are produced:
111
+ * \`\`\`ts
112
+ * const { stream } = axon.stream("explain the build system")
113
+ * for await (const entry of stream) {
114
+ * if (entry.type === "engine:text") {
115
+ * process.stdout.write(entry.content)
116
+ * }
117
+ * }
118
+ * \`\`\`
119
+ *
120
+ * **One continuous conversation** — there is no thread/branch concept.
121
+ * One Axon() instance is always exactly one continuous stream, so
122
+ * sequential calls share context automatically:
123
+ * \`\`\`ts
124
+ * await axon.request("hello")
125
+ * await axon.request("what did I just say?")
126
+ * await axon.request("now summarise our conversation")
127
+ * \`\`\`
128
+ *
129
+ * An isolated side task (that should not share context with the main
130
+ * conversation) runs as its own Axon() instance — a host-level (TUI/CLI)
131
+ * concern, not something this handle exposes.
132
+ *
133
+ * @see https://axon.arclabs.it/docs/v2/api
134
+ * @see https://axon.arclabs.it/docs/v2/api/stream
135
+ */
136
+ const axon: AxonHandle
137
+
138
+ /**
139
+ * UI bridge. Post notifications, prompts, and content injections to the
140
+ * connected TUI client. All methods are fire-and-forget in headless mode —
141
+ * they never throw if no client is connected.
142
+ *
143
+ * @see https://axon.arclabs.it/docs/v2/api/ui
144
+ */
145
+ const ui: UiHandle
146
+
147
+ /**
148
+ * Named arguments passed to the current script invocation.
149
+ * Typed via \`defineArgs()\` — use that for full type safety.
150
+ *
151
+ * \`\`\`ts
152
+ * const { date } = defineArgs<{ date: string }>()
153
+ * \`\`\`
154
+ *
155
+ * @see https://axon.arclabs.it/docs/v2/api/scripts
156
+ */
157
+ const args: Record<string, string>
158
+
159
+ // ── Agent / module authoring ──────────────────────────────────────────
160
+
161
+ /**
162
+ * Define this agent's configuration.
163
+ * Used as the default export in \`axon.config.ts\`.
164
+ *
165
+ * @see https://axon.arclabs.it/docs/v2/agent/config
166
+ */
167
+ const defineAgent: typeof import("@arcforge/types").defineAgent
168
+
169
+ /**
170
+ * Define a reusable module. Used as the default export in \`module.config.ts\`.
171
+ *
172
+ * @see https://axon.arclabs.it/docs/v2/modules/config
173
+ */
174
+ const defineModule: typeof import("@arcforge/types").defineModule
175
+
176
+ /**
177
+ * Declare the expected argument shape for this script. Stripped at runtime —
178
+ * type-only. Returns the args object cast to your type.
179
+ *
180
+ * \`\`\`ts
181
+ * const { userId, limit } = defineArgs<{ userId: string; limit?: number }>()
182
+ * \`\`\`
183
+ *
184
+ * @see https://axon.arclabs.it/docs/v2/api/scripts
185
+ */
186
+ function defineArgs<T extends Record<string, unknown>>(): T
187
+
188
+ /**
189
+ * Declare the expected prop shape for this prompt template. Stripped at
190
+ * runtime — type-only. Used in \`src/prompts/\` files.
191
+ *
192
+ * @see https://axon.arclabs.it/docs/v2/api/prompt
193
+ */
194
+ function defineProps<T extends Record<string, unknown>>(): void
195
+
196
+ // ── Server plugin registration ────────────────────────────────────────
197
+
198
+ /**
199
+ * Register a server plugin. Extend the agent's HTTP/WebSocket server with
200
+ * custom routes and handlers.
201
+ *
202
+ * @see https://axon.arclabs.it/docs/v2/agent/server
203
+ */
204
+ const defineAxonPlugin: typeof import("@arcforge/types").defineAxonPlugin
205
+
206
+ /**
207
+ * Register server middleware. Runs on every request, before any route,
208
+ * in filename order. Return nothing to continue; return a value to end
209
+ * the request with it; throw createError(...) to reject.
210
+ *
211
+ * @see https://axon.arclabs.it/docs/v2/agent/server
212
+ */
213
+ const defineMiddleware: typeof import("@arcforge/types").defineMiddleware
214
+
215
+ // ── H3 auto-imports (generated from H3_GLOBALS) ───────────────────────
216
+ ${H3_GLOBALS.map(name => ` const ${name}: typeof import("h3").${name}`).join("\n")}
217
+ `
218
+
219
+ const HEADER = `\
220
+ // generated by axon prepare — do not edit
221
+ // Re-run \`axon prepare\` after upgrading the axon framework.
222
+ import type { AxonHandle, UiHandle, LiveProcHandle } from "@arcforge/types"
223
+
224
+ declare global {
225
+ `
226
+
227
+ /**
228
+ * axon.d.ts — config/src scope. Provider factories are values you call in
229
+ * axon.config.ts (`providers: [Axon()]`) — genuinely different from the test
230
+ * harness in axon-test.d.ts, despite the shared name.
231
+ */
232
+ export const CONFIG_DTS = HEADER + SHARED_BODY + `
233
+ // ── Provider factories ────────────────────────────────────────────────
234
+
235
+ /**
236
+ * Inference sources are declared as a POOL, not as one engine.
237
+ *
238
+ * Most agents declare NOTHING here. A user's providers live on their
239
+ * profile and every agent inherits them, which is what makes installing
240
+ * an agent a download rather than a setup:
241
+ *
242
+ * \`\`\`ts
243
+ * // profile.config.ts — the inference you HAVE
244
+ * export default defineProfile({ providers: [Axon(), Codex()] })
245
+ *
246
+ * // axon.config.ts — usually nothing at all
247
+ * export default defineAgent({})
248
+ * \`\`\`
249
+ *
250
+ * An agent declares \`providers:\` only for a source its user would not
251
+ * otherwise have — a self-hosted endpoint it ships against, a local
252
+ * daemon it assumes. The agent's entries are APPENDED to the profile's,
253
+ * never substituted for them: an installed agent can add a source, but it
254
+ * can never take one away from the person running it.
255
+ *
256
+ * To express a model PREFERENCE, use \`model:\` — a string, not a
257
+ * factory call:
258
+ *
259
+ * \`\`\`ts
260
+ * export default defineAgent({ model: "codex:gpt-5.6-terra" })
261
+ * \`\`\`
262
+ *
263
+ * It is a preference and never a constraint: resolution tries the pin,
264
+ * then falls back to ordinary ranking, so a published agent stays
265
+ * runnable by someone whose providers cannot supply it.
266
+ */
267
+
268
+ /**
269
+ * Axon Cloud inference — the managed route. Needs no connection beyond
270
+ * being signed in, and supplies the full catalogue.
271
+ *
272
+ * \`\`\`ts
273
+ * export default defineAgent({ providers: [Axon()] })
274
+ * \`\`\`
275
+ */
276
+ const Axon: typeof import("@arcforge/engines").Axon
277
+
278
+ /**
279
+ * Ollama local inference.
280
+ *
281
+ * \`\`\`ts
282
+ * export default defineAgent({ providers: [Ollama({ url: "http://box.local:11434" })] })
283
+ * \`\`\`
284
+ */
285
+ const Ollama: typeof import("@arcforge/engines").Ollama
286
+
287
+ /**
288
+ * OpenAI Codex / GPT inference.
289
+ *
290
+ * \`\`\`ts
291
+ * export default defineAgent({ providers: [Codex()] })
292
+ * \`\`\`
293
+ */
294
+ const Codex: typeof import("@arcforge/engines").Codex
295
+
296
+ /**
297
+ * OpenRouter inference. Routes to any provider.
298
+ *
299
+ * \`\`\`ts
300
+ * export default defineAgent({ providers: [OpenRouter()] })
301
+ * \`\`\`
302
+ */
303
+ const OpenRouter: typeof import("@arcforge/engines").OpenRouter
304
+
305
+ /**
306
+ * HuggingFace inference.
307
+ *
308
+ * \`\`\`ts
309
+ * export default defineAgent({ providers: [HuggingFace()] })
310
+ * \`\`\`
311
+ */
312
+ const HuggingFace: typeof import("@arcforge/engines").HuggingFace
313
+
314
+ /**
315
+ * Mock inference — answers from a fixed or handler-driven script, no
316
+ * network and no API key. A provider like any other, so an agent that
317
+ * declares it resolves every role against it.
318
+ *
319
+ * \`\`\`ts
320
+ * export default defineAgent({ providers: [Mock({ hello: "hi there" })] })
321
+ * \`\`\`
322
+ */
323
+ const Mock: typeof import("@arcforge/engines").Mock
324
+ }
325
+
326
+ export {}
327
+ `
328
+
329
+ /**
330
+ * axon-test.d.ts — tests/ scope only. \`Axon()\` here is the test runtime
331
+ * spawner (@arcforge/types' AxonTest), NOT the engine constructor above — the
332
+ * two are declared in separate files/tsconfigs specifically so they never
333
+ * collide in one ambient scope (see the file-level doc comment).
334
+ */
335
+ export const TEST_DTS = HEADER + SHARED_BODY + `
336
+ // ── Test runtime ──────────────────────────────────────────────────────
337
+
338
+ /**
339
+ * Boot a full Axon runtime for integration testing. Global — no import needed.
340
+ *
341
+ * \`\`\`ts
342
+ * const { axon, stop } = await Axon()
343
+ * const result = await axon.request("hello")
344
+ * await stop()
345
+ * \`\`\`
346
+ *
347
+ * @see https://axon.arclabs.it/docs/v2/agent/testing
348
+ */
349
+ const Axon: import("@arcforge/types").AxonTest
350
+ }
351
+
352
+ export {}
353
+ `
354
+
355
+ /** @deprecated Use CONFIG_DTS — kept so any external import of the old name doesn't hard-crash; identical content. */
356
+ export const AXON_DTS = CONFIG_DTS
357
+
358
+ /** Write .agent/axon.d.ts (config/src scope) and .agent/axon-test.d.ts (tests/ scope). */
359
+ export function generateAxonDts(root: string, kind: TypegenKind = "agent"): void {
360
+ writeDts(root, "axon.d.ts", CONFIG_DTS, kind)
361
+ writeDts(root, "axon-test.d.ts", TEST_DTS, kind)
362
+ }
@@ -0,0 +1,91 @@
1
+ import { join } from "node:path"
2
+ import { writeFileSync } from "node:fs"
3
+ import { Frame, type ProjectKind } from "../../frame"
4
+
5
+ /**
6
+ * The ambient authoring surface for cognet source — what the compile step's
7
+ * host installs at runtime (defineCognet, loop, kernel, phase, system), typed
8
+ * here for the editor. Written into the owning project's `types/` area by
9
+ * `axon prepare`: a standalone cognet's own frame, or the AGENT's frame when
10
+ * the brain is inline at `<agent>/cognet/`.
11
+ *
12
+ * Must stay in lockstep with @arcforge/cognet — the host IS this
13
+ * contract's implementation.
14
+ */
15
+ export const COGNET_DTS = `// Generated by axon prepare — do not edit.
16
+ // Ambient globals for cognet source. Implemented by the compile host
17
+ // (@arcforge/cognet); typed here for the editor.
18
+ import type {
19
+ AxonStimulusEntry,
20
+ CognetConfig,
21
+ CognetPlugin,
22
+ KernelAbi,
23
+ } from "@arcforge/types"
24
+
25
+ declare global {
26
+ /** what this brain declares (mode, wakeOn, engines) — cognet.config.ts only.
27
+ * Identity is NOT declared: name and version come from package.json. */
28
+ function defineCognet<T extends CognetConfig>(config: T): T
29
+
30
+ /**
31
+ * A lifecycle plugin — plumbing wired to hooks (boot, wake, tick,
32
+ * shutdown), declared in plugins/*.ts. Registers at import time, before
33
+ * the brain boots. PLUMBING ONLY: load/save derived state, warm caches,
34
+ * devtools. Domain facts are stimuli that fold into the world, never hooks.
35
+ */
36
+ function definePlugin(plugin: CognetPlugin): CognetPlugin
37
+
38
+ /**
39
+ * THE entry point — declare the tick pipeline once, in src/main.ts.
40
+ * The kernel wakes it per stimulus batch; ticks run until stop() or
41
+ * interrupt. Wake-scoped things arrive as args, never as globals.
42
+ */
43
+ function loop(body: (ctx: {
44
+ /** stimuli committed since the last wake, in seq order — stimulus:* only, the cognet's whole input contract */
45
+ stimuli: readonly AxonStimulusEntry[]
46
+ /** kernel interrupt — honor it between units of work */
47
+ signal: AbortSignal
48
+ /** end the wake after this tick — the brain stays warm */
49
+ stop(): void
50
+ }) => Promise<void> | void): void
51
+
52
+ /** the syscall table — live from load() onward; do work inside loop(), not at module top level */
53
+ const kernel: KernelAbi
54
+
55
+
56
+ /** a named stage within a tick — cognet:phase:* telemetry */
57
+ function phase<T>(name: string, fn: () => Promise<T>): Promise<T>
58
+
59
+ /** a unit of work within a phase — timed for the flame graph */
60
+ function system<T>(name: string, fn: () => Promise<T>): Promise<T>
61
+ }
62
+
63
+ export {}
64
+ `
65
+
66
+ /**
67
+ * The cognet authoring surface's filename inside a frame.
68
+ *
69
+ * Named distinctly rather than sharing the generic `globals.d.ts`, because in
70
+ * an agent's frame it sits beside the AGENT's declarations and the two must be
71
+ * separable by glob: the agent's own tsconfig excludes this file, and the
72
+ * inline cognet's tsconfig excludes everything else. Two ambient surfaces in
73
+ * one directory can only coexist if each scope can name the other's files.
74
+ */
75
+ export const COGNET_GLOBALS = "cognet-globals.d.ts"
76
+
77
+ /**
78
+ * Write the cognet authoring surface into a project's frame.
79
+ *
80
+ * `kind` is the OWNING project: a standalone cognet writes into its own
81
+ * `.cognet/types/`, while an agent with an inline `cognet/` writes the same
82
+ * declarations into `.agent/types/` — one brain's authoring surface, reached
83
+ * from whichever frame the source happens to live in.
84
+ */
85
+ export function generateCognetDts(root: string, kind: ProjectKind = "cognet"): void {
86
+ writeFileSync(
87
+ join(Frame({ root: root, kind: kind }).ensure("types"), COGNET_GLOBALS),
88
+ COGNET_DTS,
89
+ "utf-8",
90
+ )
91
+ }
@@ -0,0 +1,45 @@
1
+ import { relative } from "node:path"
2
+ import type { AxonModule } from "@arcforge/types"
3
+ import { Components } from "../../blueprint"
4
+ import { writeDts } from "./write"
5
+
6
+ /**
7
+ * .agent/components.d.ts — Vue GlobalComponents declarations for prompt
8
+ * components, so they auto-import in prompt templates. Agent components
9
+ * win over module components on name collision (same precedence as every
10
+ * other surface).
11
+ */
12
+ export async function generateComponentTypes(root: string, modules: AxonModule[]): Promise<number> {
13
+ const byName = new Map<string, string>() // name → filePath
14
+
15
+ // Module components first — agent overwrites on collision.
16
+ for (const mod of modules) {
17
+ for (const entry of (await Components(mod.root)).entries) {
18
+ byName.set(entry.name, entry.filePath)
19
+ }
20
+ }
21
+ for (const entry of (await Components(root)).entries) {
22
+ byName.set(entry.name, entry.filePath)
23
+ }
24
+
25
+ if (byName.size === 0) return 0
26
+
27
+ const lines: string[] = [
28
+ "// .agent/components.d.ts — generated by axon prepare, do not edit",
29
+ "// Re-run `axon prepare` after adding or removing prompt components.",
30
+ "",
31
+ "declare module 'vue' {",
32
+ " interface GlobalComponents {",
33
+ ]
34
+
35
+ for (const [name, filePath] of byName) {
36
+ // Import path relative to .agent/ where this file lives.
37
+ const rel = relative(root, filePath).replace(/\\/g, "/")
38
+ lines.push(` ${name}: typeof import("../${rel}")["default"]`)
39
+ }
40
+
41
+ lines.push(" }", "}", "", "export {}", "")
42
+
43
+ writeDts(root, "components.d.ts", lines.join("\n"))
44
+ return byName.size
45
+ }
@@ -0,0 +1,59 @@
1
+ import { join } from "node:path"
2
+ import { existsSync, readFileSync } from "node:fs"
3
+ import { writeDts } from "./write"
4
+
5
+ /**
6
+ * Parse keys from a .env file. Handles comments, blank lines, and quoted values.
7
+ * Returns only the key names — values are not extracted (they're secrets).
8
+ */
9
+ function parseEnvKeys(content: string): string[] {
10
+ const keys: string[] = []
11
+ for (const line of content.split("\n")) {
12
+ const trimmed = line.trim()
13
+ if (!trimmed || trimmed.startsWith("#")) continue
14
+ const eq = trimmed.indexOf("=")
15
+ if (eq === -1) continue
16
+ const key = trimmed.slice(0, eq).trim()
17
+ if (/^[A-Z_][A-Z0-9_]*$/i.test(key)) keys.push(key)
18
+ }
19
+ return keys
20
+ }
21
+
22
+ /**
23
+ * Generate .agent/env.d.ts — typed ProcessEnv augmentation.
24
+ *
25
+ * Reads the agent's .env file and produces a NodeJS.ProcessEnv augmentation that
26
+ * makes `process.env.MY_KEY` resolve to `string | undefined` (or `string` for keys
27
+ * the agent explicitly declares as required via env.needs — future enhancement).
28
+ *
29
+ * This makes `process.env` type-safe in tools, scripts, hooks, and server routes:
30
+ * unknown keys are a type error, known keys get correct string types.
31
+ *
32
+ * Returns the number of env keys typed.
33
+ */
34
+ export function generateEnvTypes(agentPath: string): number {
35
+ const envPath = join(agentPath, ".env")
36
+ if (!existsSync(envPath)) return 0
37
+
38
+ const keys = parseEnvKeys(readFileSync(envPath, "utf-8"))
39
+ if (keys.length === 0) return 0
40
+
41
+ const lines: string[] = [
42
+ "// .agent/env.d.ts — generated by axon prepare, do not edit",
43
+ "// Re-run `axon prepare` after adding keys to .env.",
44
+ "",
45
+ "// Augments ProcessEnv so process.env keys declared in .env are typed.",
46
+ "// Values are always string | undefined — the key is present but may be unset.",
47
+ "declare namespace NodeJS {",
48
+ " interface ProcessEnv {",
49
+ ]
50
+
51
+ for (const key of keys) {
52
+ lines.push(` ${key}?: string`)
53
+ }
54
+
55
+ lines.push(" }", "}", "", "export {}", "")
56
+
57
+ writeDts(agentPath, "env.d.ts", lines.join("\n"))
58
+ return keys.length
59
+ }
@@ -0,0 +1,108 @@
1
+ import type { AxonModule, AxonPrompt, AxonScript, AxonTool } from "@arcforge/types"
2
+ import { generateAxonDts } from "./axon-dts"
3
+ import { generateComponentTypes } from "./components"
4
+ import { generateEnvTypes } from "./env"
5
+ import { generateHookTypes } from "./hooks"
6
+ import { generatePromptTypes } from "./prompts"
7
+ import { generateScriptTypes } from "./scripts"
8
+ import { generateToolGlobals } from "./tools"
9
+ import { ensureProjectTsConfig } from "./tsconfig"
10
+ import type { TypegenKind } from "./write"
11
+ import { generateCognetDts } from "./cognet-dts"
12
+ import { generatePromptDts } from "./prompt-dts"
13
+ import { generateTuiDts } from "./tui-dts"
14
+ import { generateRegistryDts, type BuiltinRegistry } from "./registry-dts"
15
+ import { inlineCognetDir } from "../../blueprint/cognet"
16
+ import { KINDS } from "../kinds"
17
+
18
+ type GeneratorsOpts = {
19
+ root: string
20
+ kind: TypegenKind
21
+ }
22
+
23
+ /**
24
+ * Generators — the individual declaration writers, bound to one project.
25
+ * The mechanism layer under Typegen: each verb writes exactly one file and
26
+ * returns its entry count, so watch mode can regenerate a single domain
27
+ * when a single domain changed.
28
+ */
29
+ export function Generators(opts: GeneratorsOpts) {
30
+ const { root, kind } = opts
31
+
32
+ return {
33
+ /** The kind's ambient declaration frame — axon.d.ts, or a cognet's/prompt's globals.d.ts. */
34
+ axon(): void {
35
+ if (KINDS[kind].globals === "cognet") {
36
+ generateCognetDts(root)
37
+ return
38
+ }
39
+ if (KINDS[kind].globals === "prompt") {
40
+ generatePromptDts(root)
41
+ return
42
+ }
43
+ if (KINDS[kind].globals === "tui") {
44
+ generateTuiDts(root, kind)
45
+ return
46
+ }
47
+ generateAxonDts(root, kind)
48
+
49
+ // An agent that writes its own brain gets the cognet authoring
50
+ // surface too — a SECOND ambient scope in the same frame, kept
51
+ // apart from the agent's by the tsconfig pair in tsconfig.ts.
52
+ // Both are written unconditionally here; which files each scope
53
+ // can see is that writer's decision, not this one's.
54
+ if (kind === "agent" && inlineCognetDir(root)) {
55
+ generateCognetDts(root, "agent")
56
+ }
57
+ },
58
+
59
+ /**
60
+ * What a config REGISTERS, as completable names — profile and
61
+ * extension kinds only.
62
+ *
63
+ * `sources` are scanned in load order; `builtins` is Axon's own
64
+ * catalogue, handed in because it lives in the TUI and the platform
65
+ * must not reach into the app it serves.
66
+ */
67
+ registry(sources: readonly string[], builtins?: BuiltinRegistry): void {
68
+ generateRegistryDts(root, kind, sources, builtins)
69
+ },
70
+
71
+ /** The canonical tsconfig for the generated-types dir. */
72
+ tsconfig(): void {
73
+ ensureProjectTsConfig(root, kind)
74
+ },
75
+
76
+ /** tool-globals.d.ts from blueprint tool surfaces. */
77
+ tools(tools: AxonTool[]): number {
78
+ return generateToolGlobals(root, tools, kind)
79
+ },
80
+
81
+ /** prompts.d.ts — AxonPromptMap augmentation. */
82
+ prompts(prompts: AxonPrompt[]): number {
83
+ return generatePromptTypes(root, prompts)
84
+ },
85
+
86
+ /** scripts.d.ts — AxonScriptMap augmentation. */
87
+ scripts(scripts: AxonScript[]): number {
88
+ return generateScriptTypes(root, scripts)
89
+ },
90
+
91
+ /** components.d.ts — Vue GlobalComponents, agent wins over modules. */
92
+ components(modules: AxonModule[]): Promise<number> {
93
+ return generateComponentTypes(root, modules)
94
+ },
95
+
96
+ /** hooks.d.ts — AxonModuleEvents augmentation from installed modules' emits. */
97
+ hooks(modules: AxonModule[]): number {
98
+ return generateHookTypes(root, modules)
99
+ },
100
+
101
+ /** env.d.ts from the project's .env keys. */
102
+ env(): number {
103
+ return generateEnvTypes(root)
104
+ },
105
+ }
106
+ }
107
+
108
+ export type GeneratorsT = ReturnType<typeof Generators>