@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,303 @@
1
+ /** Record shapes as they exist on disk under ~/.axon. */
2
+
3
+ export type EnvTarget = "local" | "cloud"
4
+
5
+ export type UpdateRecord = {
6
+ status: "pending" | "running" | "complete" | "failed" | "rolled-back"
7
+ from: string
8
+ to: string
9
+ updatedAt: string
10
+ error?: string
11
+ }
12
+
13
+ /** profiles/index.json — which profile is active. */
14
+ export type ActiveProfile = {
15
+ userId: string
16
+ }
17
+
18
+ /** profiles/<id>/store/profile.json — identity + credentials. */
19
+ export type ProfileRecord = {
20
+ user: {
21
+ id: string
22
+ email: string
23
+ name?: string
24
+ memberSince?: string
25
+ }
26
+ auth: {
27
+ accessToken?: string
28
+ expiresAt?: number
29
+ apiKey?: string
30
+ }
31
+ }
32
+
33
+ /** profiles/<id>/store/settings.json — user preferences, TUI + CLI. */
34
+ /**
35
+ * Verbosity profile — per-channel control over what the thread timeline
36
+ * renders. The debugging dial: all defaults are the everyday view; turning
37
+ * channels on interleaves the machinery's own records into the timeline.
38
+ */
39
+ /**
40
+ * Re-exported, not redefined.
41
+ *
42
+ * These are the EXTENSION CONTRACT — a user's `profile.config.ts` is typed
43
+ * against the copy in `@arcforge/types/tui.ts` that `axon prepare` writes into
44
+ * their frame. A second definition here would be the same shape twice, and the
45
+ * day they disagreed a setting would typecheck in the user's editor and be
46
+ * rejected by the terminal reading it.
47
+ */
48
+ export type { VerbosityProfile, ProfileSettings } from "@arcforge/types"
49
+
50
+ /** profiles/<id>/store/history.jsonl — one line per sent message, oldest first on disk. */
51
+ /**
52
+ * A standing policy approval — what "allow always" writes.
53
+ *
54
+ * ── Why a store rather than a config edit ───────────────────────────────────
55
+ *
56
+ * The alternative was writing the grant into the agent's own `axon.config.ts`
57
+ * or the profile's. Both are worse: editing a user's authored config from a
58
+ * palette keypress is invasive, and under the ceiling an agent-level grant
59
+ * cannot widen a profile that escalated anyway — so "always" would fail
60
+ * confusingly in exactly the case that produced the prompt.
61
+ *
62
+ * A separate store also makes grants inspectable and revocable as a LIST,
63
+ * which neither config can be: a config says what is permitted, not what was
64
+ * decided, when, or by whom.
65
+ *
66
+ * ── What a grant can and cannot do ──────────────────────────────────────────
67
+ *
68
+ * A grant only ever satisfies an ESCALATION. It can never overturn a `deny`
69
+ * from either layer — "stop asking me this" is a different act from "override
70
+ * the ceiling", and collapsing them would let one keypress undo a machine-wide
71
+ * rule the user set deliberately.
72
+ *
73
+ * ── Keyed by agent NAME ─────────────────────────────────────────────────────
74
+ *
75
+ * Two agents of the same name in different directories share a grant. That is
76
+ * a known simplification: the alternative keys on the project path, which is
77
+ * more correct and less legible in a file a person is meant to read. Revisit
78
+ * when someone actually runs two same-named agents.
79
+ */
80
+ export type PolicyGrant = {
81
+ /** Grant id — what a revocation names. */
82
+ id: string
83
+ /** The agent this was granted to, by name. `"*"` grants to every agent on this profile. */
84
+ agent: string
85
+ /** Fully qualified function, e.g. `"process.run"` or `"github.issues"`. */
86
+ fn: string
87
+ /**
88
+ * The subject this covers, as a glob — the command, host, or namespace the
89
+ * escalation was raised for. Matched with the same matcher policy uses, so
90
+ * a grant reads exactly like the rule it satisfies.
91
+ */
92
+ subject: string
93
+ /** When it was granted. */
94
+ grantedAt: number
95
+ /**
96
+ * Set when this entry REVOKES an earlier grant, naming it. Revocation is
97
+ * an append rather than a rewrite: the log is an audit trail, and a
98
+ * decision that was made and later withdrawn is two facts, not zero.
99
+ */
100
+ revokes?: string
101
+ }
102
+
103
+ /**
104
+ * An escalation that was raised — the audit trail, and the queue a surface
105
+ * answers from.
106
+ *
107
+ * Written for EVERY escalation, including ones a human answers immediately.
108
+ * The record is what makes "3 escalations this session, 2 approved" answerable
109
+ * and what lets a request be approved long after the call that raised it gave
110
+ * up — the grant it produces is what the next attempt reads.
111
+ *
112
+ * `outcome` is absent while a request is open. A request with no outcome and
113
+ * no live process behind it is stale rather than pending; a surface listing
114
+ * them should say so rather than offering to answer a call nobody is waiting
115
+ * on.
116
+ */
117
+ export type PolicyRequest = {
118
+ /** Request id — what an answer names. Distinct from the capsule's escalation id. */
119
+ id: string
120
+ /** The agent that raised it, by name. */
121
+ agent: string
122
+ /** The session it was raised in — how a surface finds the conversation. */
123
+ sessionId: string
124
+ /** Fully qualified function, e.g. `"process.run"`. */
125
+ fn: string
126
+ /** What was being asked for — the command, host, or namespace. */
127
+ subject: string
128
+ /** When it was raised. */
129
+ raisedAt: number
130
+ /**
131
+ * How it settled, and by what.
132
+ *
133
+ * "grant" means a standing approval covered it and no human was asked.
134
+ * "expired" means nothing was listening — the call already failed, and
135
+ * answering now writes a grant for next time rather than unblocking it.
136
+ */
137
+ outcome?: {
138
+ decision: "allow" | "deny"
139
+ by: "user" | "grant" | "expired"
140
+ at: number
141
+ /** The grant this produced, when the user chose "always". */
142
+ grantId?: string
143
+ }
144
+ }
145
+
146
+ export type HistoryEntry = {
147
+ id: string
148
+ content: string
149
+ /** Name of the agent the message was sent to — null if none was running. */
150
+ agentName: string | null
151
+ createdAt: string
152
+ }
153
+
154
+
155
+ /**
156
+ * One agent's last-known shape — what a status line can show before the agent
157
+ * is up.
158
+ *
159
+ * Every field is optional: an agent that has never booted has no manifest, and
160
+ * a manifest written by an older version may be missing whatever was added
161
+ * since. A reader treats absence as "not known yet", which is the same state a
162
+ * cold boot is in anyway.
163
+ */
164
+ export type AgentManifest = {
165
+ /** The model it ran on — what the header's "model:" row shows. */
166
+ model?: string
167
+ /** How many modules it loaded. */
168
+ modules?: number
169
+ /** How many tools those modules registered. */
170
+ tools?: number
171
+ /** The session it was last on, so `^` and the session name have something to show. */
172
+ sessionId?: string
173
+ /** Context used at shutdown, in tokens. */
174
+ context?: number
175
+ }
176
+
177
+ /**
178
+ * profiles/<id>/store/state.json — app-remembered continuity data, distinct from
179
+ * settings.json (user-configured preferences). Nothing here is something
180
+ * the user directly edits; it's what the app itself writes to resume
181
+ * where it left off (last agent today, potentially last thread/session
182
+ * later).
183
+ */
184
+ /**
185
+ * What the TUI should open on its next boot, written by a CLI command.
186
+ *
187
+ * `axon attach <url>` and `axon open <session>` do not do their work in the
188
+ * CLI process — there is no terminal UI there to attach TO. They record an
189
+ * intent and return, which makes vterm boot the app, and the app performs it
190
+ * on mount exactly as if the user had typed the command inside.
191
+ *
192
+ * ONE-SHOT, and that is the whole difference from `AppState`. State is
193
+ * continuity — the agent you were last on, re-selected every launch forever.
194
+ * An intent is an instruction that has been carried out: left in place it
195
+ * would re-attach to a URL on every subsequent start, long after the user
196
+ * moved on. It is cleared as it is read.
197
+ *
198
+ * A discriminated union rather than a bag of optional fields: two intents can
199
+ * never be pending at once, and a reader switches on `kind` rather than
200
+ * guessing which combination of fields it was handed.
201
+ */
202
+ export type AppIntent =
203
+ /**
204
+ * Open the terminal on an agent — what `-a` records.
205
+ *
206
+ * `ref` is the SAME reference form the CLI accepts everywhere: a path, a
207
+ * package, or a URL. The reader decides what that means, because the two
208
+ * cases genuinely differ — a URL is an agent already running, so it is
209
+ * bound to; a path or package names one that has to be spawned first.
210
+ *
211
+ * It was `url` only, when attaching was its own command and only a running
212
+ * address could be named. Widening it is what lets `axon @cody/zeno -a`
213
+ * and `axon ./zeno -p "hi" -a` land in the same place as an attach: the
214
+ * user asked for the same thing — a terminal on this agent — and the
215
+ * transport is an implementation detail of which reference they used.
216
+ */
217
+ | {
218
+ kind: "attach"
219
+ ref: string
220
+ /**
221
+ * Messages to deliver once the terminal is up — what
222
+ * `axon <ref> -p "…" -a` records.
223
+ *
224
+ * An ARRAY, because each `-p` is its own message: they land in the
225
+ * TUI's queue in order and are sent as the agent becomes free,
226
+ * exactly as if the user had typed them one after another. Joining
227
+ * them into one instruction (which is what `-p` does WITHOUT `-a`,
228
+ * where there is one turn to run) would collapse a conversation
229
+ * into a single prompt.
230
+ *
231
+ * Carried rather than run CLI-side: `-a` says the conversation
232
+ * continues in the terminal, so running the turn first meant
233
+ * watching it complete in one place and then opening a second to
234
+ * see it again.
235
+ */
236
+ send?: string[]
237
+ }
238
+ /**
239
+ * Reopen a session — focus it if live, otherwise boot its agent onto it.
240
+ *
241
+ * Carries the agent's ADDRESS as well as the id, because resuming boots
242
+ * the agent the session belongs to and a log id does not name one. The
243
+ * command that records this already knows both (it resolved the session
244
+ * to show it), so making the reader search every agent's logs for an id
245
+ * would be re-deriving what the writer had.
246
+ */
247
+ | { kind: "session"; sessionId: string; agent: string }
248
+
249
+ export type AppState = {
250
+ /**
251
+ * ADDRESS (directory name) of the last agent selected — the TUI auto-boots
252
+ * this on startup, if present. An address, not an identity: it is fed back
253
+ * to resolve(), and a package name ("@axon/zeno") contains a "/" that
254
+ * resolve() reads as a path.
255
+ */
256
+ lastAgent?: string
257
+
258
+ /**
259
+ * Last known model per agent, keyed by ADDRESS.
260
+ *
261
+ * Purely a render cache for the header's "model:" row. That value is read
262
+ * off the agent's live blueprint, which does not exist until boot
263
+ * completes, so a cold start showed a spinner for the whole boot even
264
+ * though the answer had not changed since last run. Written on every
265
+ * successful boot, read only while booting, and always superseded by the
266
+ * live blueprint the moment it lands — a stale entry is visible for one
267
+ * boot at most, and never overrides truth.
268
+ */
269
+ agentModels?: Record<string, string>
270
+
271
+ /**
272
+ * What each agent looked like when it last shut down, keyed by ADDRESS.
273
+ *
274
+ * The generalisation of `agentModels`, and the same reasoning: every value
275
+ * a status line shows is read off a live blueprint or session, none of
276
+ * which exist until boot completes. A cold start therefore rendered a bar
277
+ * of empty sections for the second or so the agent took to come up, and
278
+ * the row visibly filled in piece by piece — which reads as a broken
279
+ * layout rather than as loading.
280
+ *
281
+ * Written on shutdown and on every successful boot, read only while
282
+ * booting, and superseded by live values the moment they land. A stale
283
+ * entry is visible for one boot at most and never overrides truth — the
284
+ * same contract `agentModels` states, widened to the rest of the row.
285
+ *
286
+ * Deliberately NOT a general component cache. Only values that are
287
+ * expensive to learn and stable across a restart belong here; a clock or a
288
+ * process id is cheaper to compute than to remember.
289
+ */
290
+ agentManifests?: Record<string, AgentManifest>
291
+
292
+ /**
293
+ * Model picks, most recent first — canonical `route:model/id` strings
294
+ * ("codex:openai/gpt-5.5", "axon:auto").
295
+ *
296
+ * The model palette is one flat list of every (route, model) pair, which is
297
+ * ~800 rows. Recency is what makes that navigable without typing: the
298
+ * handful anyone actually uses sit at the top, and everything else is a few
299
+ * keystrokes of search away. Capped — this is a convenience ordering, not a
300
+ * usage log, and an unbounded list would just be a slower one.
301
+ */
302
+ recentModels?: string[]
303
+ }
@@ -0,0 +1,150 @@
1
+ import { err } from "@arcforge/err"
2
+ import type { AxonTestEventFrame } from "@arcforge/types"
3
+ import { isFrame, isTestChannel } from "./frames"
4
+
5
+ /** How long a SIGTERM is given to land before SIGKILL. */
6
+ const KILL_GRACE_MS = 1_000
7
+
8
+ /** How long to wait for the child's IPC channel to close after it exits. */
9
+ const DISCONNECT_GRACE_MS = 100
10
+
11
+ /**
12
+ * The instrumented preload, resolved to an absolute path.
13
+ *
14
+ * Lives in bin/ because it is loaded into a DIFFERENT process — `bun test
15
+ * --preload` — and is never imported by this one. Packaged builds ship it as a
16
+ * sibling .js (see the TUI's vterm.config.ts); a source checkout runs the .ts.
17
+ */
18
+ const PRELOAD = new URL("../../bin/test-preload.ts", import.meta.url).pathname
19
+
20
+ export type ChildOutcome = {
21
+ exitCode: number
22
+ stdout: string
23
+ stderr: string
24
+ /** True when the run was aborted rather than finishing on its own. */
25
+ cancelled: boolean
26
+ }
27
+
28
+ type ChildOpts = {
29
+ cwd: string
30
+ env?: Record<string, string | undefined>
31
+ timeoutMs?: number
32
+ /** Extra preloads the child loads AFTER instrumentation. */
33
+ preloads?: string[]
34
+ /** A well-formed test frame arrived. */
35
+ onFrame: (frame: AxonTestEventFrame) => void
36
+ /** A message on the test channel that is not a valid frame — a protocol fault. */
37
+ onInvalid: () => void
38
+ /** Every IPC message, valid or not. Domain extensions read their own channels. */
39
+ onMessage?: (message: unknown) => void
40
+ }
41
+
42
+ /**
43
+ * Child — one `bun test` subprocess, watched.
44
+ *
45
+ * Owns the process boundary completely: argument construction, environment,
46
+ * IPC decoding, and the SIGTERM→SIGKILL escalation an abort needs. The runner
47
+ * above it never touches Bun.spawn.
48
+ *
49
+ * One file per child, `--max-concurrency 1`. Test files mutate global state
50
+ * (the instrumented bun:test API is installed per-process), so a shared child
51
+ * would interleave two files' events into one ambiguous stream.
52
+ */
53
+ export function Child(opts: ChildOpts) {
54
+ /**
55
+ * `bun test foo.bench.ts` treats a non-.test/.spec name as a FILTER rather
56
+ * than a path. An explicit relative prefix opts into arbitrary filenames,
57
+ * which benchmark suites deliberately use.
58
+ */
59
+ function argsFor(file: string): string[] {
60
+ const args = ["bun", "test", "--preload", PRELOAD, "--max-concurrency", "1"]
61
+ if (opts.timeoutMs !== undefined) args.push("--timeout", String(opts.timeoutMs))
62
+ args.push(file.startsWith(".") || file.startsWith("/") ? file : `./${file}`)
63
+ return args
64
+ }
65
+
66
+ /** process.env with overrides applied, minus anything explicitly unset. */
67
+ function envFor(file: string): Record<string, string> {
68
+ const merged: Record<string, string> = {}
69
+ const source = {
70
+ ...process.env,
71
+ ...opts.env,
72
+ AXON_TEST_FILE: file,
73
+ AXON_TEST_EXTENSION_PRELOADS: JSON.stringify(opts.preloads ?? []),
74
+ }
75
+ for (const [key, value] of Object.entries(source)) {
76
+ if (value !== undefined) merged[key] = value
77
+ }
78
+ return merged
79
+ }
80
+
81
+ return {
82
+ /** Run one file to completion. Resolves once the process has exited and its output is drained. */
83
+ async run(file: string, signal?: AbortSignal): Promise<ChildOutcome> {
84
+ let cancelled = signal?.aborted ?? false
85
+
86
+ let disconnect!: () => void
87
+ const disconnected = new Promise<void>(resolve => { disconnect = resolve })
88
+
89
+ const child = Bun.spawn(argsFor(file), {
90
+ cwd: opts.cwd,
91
+ env: envFor(file),
92
+ stdin: "ignore",
93
+ stdout: "pipe",
94
+ stderr: "pipe",
95
+ ipc(message) {
96
+ opts.onMessage?.(message)
97
+
98
+ if (isFrame(message)) {
99
+ opts.onFrame(message.frame)
100
+ return
101
+ }
102
+ // Only a malformed message ON OUR CHANNEL is a fault. An
103
+ // extension's own traffic is none of this runner's business.
104
+ if (isTestChannel(message)) opts.onInvalid()
105
+ },
106
+ onDisconnect: disconnect,
107
+ })
108
+
109
+ let force: ReturnType<typeof setTimeout> | undefined
110
+ const abort = () => {
111
+ cancelled = true
112
+ child.kill("SIGTERM")
113
+ // A test blocked in native code will not answer SIGTERM. Escalate
114
+ // rather than leaving an orphan holding the terminal.
115
+ force = setTimeout(() => child.kill("SIGKILL"), KILL_GRACE_MS)
116
+ }
117
+ signal?.addEventListener("abort", abort, { once: true })
118
+
119
+ // Start draining BEFORE awaiting exit: a child that fills the pipe
120
+ // buffer blocks on write and never exits.
121
+ const stdout = new Response(child.stdout).text()
122
+ const stderr = new Response(child.stderr).text()
123
+
124
+ try {
125
+ const exitCode = await child.exited
126
+ // IPC frames can still be in flight when the process exits —
127
+ // wait briefly for the channel to close so the last events are
128
+ // not dropped, but never hang on a child that already died.
129
+ await Promise.race([disconnected, Bun.sleep(DISCONNECT_GRACE_MS)])
130
+
131
+ return {
132
+ exitCode: exitCode,
133
+ stdout: await stdout,
134
+ stderr: await stderr,
135
+ cancelled: cancelled,
136
+ }
137
+ } finally {
138
+ if (force) clearTimeout(force)
139
+ signal?.removeEventListener("abort", abort)
140
+ }
141
+ },
142
+ }
143
+ }
144
+
145
+ export type ChildT = ReturnType<typeof Child>
146
+
147
+ /** The protocol fault a malformed frame produces — one shape, one place. */
148
+ export function invalidFrameError() {
149
+ return err("UNKNOWN", { detail: "test child sent an invalid IPC frame" })
150
+ }
@@ -0,0 +1,102 @@
1
+ import type { AxonTestEvent, AxonTestEventContext, AxonTestEventMap } from "@arcforge/types"
2
+
3
+ type EventsOpts = {
4
+ /** Correlates every event in one run. */
5
+ runId: string
6
+ /**
7
+ * Called in authoritative order, one at a time. A consumer that awaits is
8
+ * awaited before the next event is delivered — the stream is a sequence,
9
+ * and a subscriber must never see it interleaved.
10
+ */
11
+ onEvent?: (event: AxonTestEvent) => void | Promise<void>
12
+ }
13
+
14
+ /**
15
+ * Events — the authoritative lifecycle stream of one test run.
16
+ *
17
+ * Owns three things a caller must never have to think about:
18
+ *
19
+ * ordering a monotonic sequence number, so events sort identically no
20
+ * matter how the transport reordered them
21
+ * liveness which cases have started and not yet reported a terminal
22
+ * result, so a child that dies mid-test can be reconciled
23
+ * delivery subscriber calls chained rather than fired in parallel
24
+ *
25
+ * Recording is synchronous and always succeeds. Delivery is deferred: a slow
26
+ * subscriber must not stall the child process being watched, so `settle()` is
27
+ * what a caller awaits once at the end.
28
+ */
29
+ export function Events(opts: EventsOpts) {
30
+ const collected: AxonTestEvent[] = []
31
+ /** Cases that started and have not reported a terminal result, keyed by test + attempt. */
32
+ const live = new Map<string, AxonTestEventContext>()
33
+
34
+ let sequence = 0
35
+ let delivery = Promise.resolve()
36
+
37
+ function key(context: AxonTestEventContext): string {
38
+ return `${context.testId}:${context.attempt ?? 0}`
39
+ }
40
+
41
+ return {
42
+ /** Everything recorded so far, in authoritative order. */
43
+ get all(): AxonTestEvent[] {
44
+ return collected
45
+ },
46
+
47
+ record<K extends keyof AxonTestEventMap>(
48
+ type: K,
49
+ data: AxonTestEventMap[K],
50
+ context: Omit<AxonTestEventContext, "testRunId"> = {},
51
+ ): AxonTestEvent {
52
+ const event = {
53
+ id: Bun.randomUUIDv7(),
54
+ type,
55
+ time: { ms: Date.now(), seq: sequence++ },
56
+ context: { testRunId: opts.runId, ...context },
57
+ data,
58
+ } as AxonTestEvent
59
+
60
+ collected.push(event)
61
+
62
+ if (event.context.testId) {
63
+ if (type === "test:case:start") live.set(key(event.context), event.context)
64
+ if (type === "test:case:pass" || type === "test:case:fail") live.delete(key(event.context))
65
+ }
66
+
67
+ if (opts.onEvent) {
68
+ delivery = delivery.then(() => opts.onEvent!(event)).then(() => undefined)
69
+ }
70
+ return event
71
+ },
72
+
73
+ /** Cases from one file still awaiting a terminal result — the child died owing them an answer. */
74
+ orphaned(file: string): AxonTestEventContext[] {
75
+ return [...live.values()].filter(context => context.file === file)
76
+ },
77
+
78
+ /** How many cases reached each terminal state. */
79
+ tally(): { passed: number; failed: number; skipped: number; todo: number } {
80
+ const count = (type: string) => collected.filter(event => event.type === type).length
81
+ return {
82
+ passed: count("test:case:pass"),
83
+ failed: count("test:case:fail"),
84
+ skipped: count("test:case:skip"),
85
+ todo: count("test:case:todo"),
86
+ }
87
+ },
88
+
89
+ /** Whether a file reported any failure — a case or a hook. */
90
+ failed(file: string): boolean {
91
+ return collected.some(event => event.context.file === file
92
+ && (event.type === "test:case:fail" || event.type === "test:hook:fail"))
93
+ },
94
+
95
+ /** Wait for every queued subscriber call to finish. Awaited once, at the end of a run. */
96
+ async settle(): Promise<void> {
97
+ await delivery
98
+ },
99
+ }
100
+ }
101
+
102
+ export type EventsT = ReturnType<typeof Events>
@@ -0,0 +1,26 @@
1
+ import { isAbsolute, relative, resolve } from "node:path"
2
+
3
+ function isGlob(value: string): boolean {
4
+ return /[*?[]/.test(value)
5
+ }
6
+
7
+ /** Resolve direct paths and Bun globs into stable, cwd-relative test paths. */
8
+ export async function resolveTestFiles(patterns: string | string[], cwd: string): Promise<string[]> {
9
+ const requested = Array.isArray(patterns) ? patterns : [patterns]
10
+ const found = new Set<string>()
11
+
12
+ for (const pattern of requested) {
13
+ if (!isGlob(pattern)) {
14
+ const absolute = isAbsolute(pattern) ? pattern : resolve(cwd, pattern)
15
+ if (await Bun.file(absolute).exists()) found.add(relative(cwd, absolute))
16
+ continue
17
+ }
18
+
19
+ const glob = new Bun.Glob(pattern)
20
+ for await (const match of glob.scan({ cwd, onlyFiles: true, dot: false })) {
21
+ found.add(match)
22
+ }
23
+ }
24
+
25
+ return [...found].sort()
26
+ }
@@ -0,0 +1,39 @@
1
+ import type { AxonTestEventFrame } from "@arcforge/types"
2
+
3
+ /** The IPC channel test frames arrive on. Anything else is a domain extension's own traffic. */
4
+ export const CHANNEL = "axon:test"
5
+
6
+ /**
7
+ * Every event type a test child may report.
8
+ *
9
+ * An allowlist rather than a shape check: the child is a subprocess running
10
+ * user code, so a frame is untrusted input. Accepting an unknown `type` would
11
+ * put an event into the authoritative stream that no consumer knows how to
12
+ * read.
13
+ */
14
+ const EVENT_TYPES = new Set<string>([
15
+ "test:suite:declare", "test:suite:start", "test:suite:complete",
16
+ "test:case:declare", "test:case:start", "test:case:pass", "test:case:fail",
17
+ "test:case:skip", "test:case:todo",
18
+ "test:hook:start", "test:hook:complete", "test:hook:fail",
19
+ "test:console", "test:process:fault",
20
+ ])
21
+
22
+ export type ChildMessage = { channel: typeof CHANNEL; frame: AxonTestEventFrame }
23
+
24
+ /** Whether a message is addressed to the test channel at all — extensions use their own. */
25
+ export function isTestChannel(value: unknown): boolean {
26
+ return Boolean(value) && typeof value === "object"
27
+ && (value as { channel?: unknown }).channel === CHANNEL
28
+ }
29
+
30
+ /** Whether a message is a well-formed test frame this runner can record. */
31
+ export function isFrame(value: unknown): value is ChildMessage {
32
+ if (!isTestChannel(value)) return false
33
+
34
+ const frame = (value as { frame?: { type?: unknown; context?: unknown; data?: unknown } }).frame
35
+ return typeof frame?.type === "string"
36
+ && EVENT_TYPES.has(frame.type)
37
+ && typeof frame.context === "object"
38
+ && typeof frame.data === "object"
39
+ }
@@ -0,0 +1,7 @@
1
+ // test — native Bun test execution, projected into a structured event stream.
2
+ // TestRunner() is the module's single entry point.
3
+
4
+ export { TestRunner, type TestRunnerT } from "./runner"
5
+ export { Events, type EventsT } from "./events"
6
+ export { resolveTestFiles } from "./files"
7
+ export type { TestRunOptions, TestRunResult } from "./types"