@arcforge/platform 2.0.219 → 2.0.245

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 (127) hide show
  1. package/package.json +27 -19
  2. package/src/build/blueprint/blueprint.ts +48 -64
  3. package/src/build/blueprint/cognet/abi.ts +3 -257
  4. package/src/build/blueprint/cognet/bundle-worker.ts +11 -0
  5. package/src/build/blueprint/cognet/bundle.ts +294 -89
  6. package/src/build/blueprint/cognet/cognet.ts +8 -7
  7. package/src/build/blueprint/cognet/config/config.ts +52 -0
  8. package/src/build/blueprint/cognet/config/index.ts +4 -0
  9. package/src/build/blueprint/cognet/config/literal.ts +83 -0
  10. package/src/build/blueprint/cognet/config/provider.ts +43 -0
  11. package/src/build/blueprint/cognet/config/shape.ts +183 -0
  12. package/src/build/blueprint/cognet/index.ts +4 -2
  13. package/src/build/blueprint/cognet/native/cargo.ts +31 -0
  14. package/src/build/blueprint/cognet/native/crate.ts +126 -0
  15. package/src/build/blueprint/cognet/native/index.ts +2 -0
  16. package/src/build/blueprint/cognet/native/library.ts +125 -0
  17. package/src/build/blueprint/cognet/native/manifest.ts +137 -0
  18. package/src/build/blueprint/cognet/python/index.ts +1 -0
  19. package/src/build/blueprint/cognet/python/project.ts +119 -0
  20. package/src/build/blueprint/cognet/schema/arrays.ts +23 -0
  21. package/src/build/blueprint/cognet/schema/authored.ts +273 -0
  22. package/src/build/blueprint/cognet/schema/compile.ts +78 -0
  23. package/src/build/blueprint/cognet/schema/components/external.ts +15 -0
  24. package/src/build/blueprint/cognet/schema/components/index.ts +3 -0
  25. package/src/build/blueprint/cognet/schema/components/lock.ts +58 -0
  26. package/src/build/blueprint/cognet/schema/components/model.ts +34 -0
  27. package/src/build/blueprint/cognet/schema/components/python.ts +15 -0
  28. package/src/build/blueprint/cognet/schema/components/python_source.py +69 -0
  29. package/src/build/blueprint/cognet/schema/components/rust.ts +33 -0
  30. package/src/build/blueprint/cognet/schema/components/rust_source/Cargo.lock +117 -0
  31. package/src/build/blueprint/cognet/schema/components/rust_source/Cargo.toml +11 -0
  32. package/src/build/blueprint/cognet/schema/components/rust_source/src/main.rs +104 -0
  33. package/src/build/blueprint/cognet/schema/components/source.ts +220 -0
  34. package/src/build/blueprint/cognet/schema/components/tags.ts +66 -0
  35. package/src/build/blueprint/cognet/schema/components/typescript.ts +157 -0
  36. package/src/build/blueprint/cognet/schema/index.ts +5 -0
  37. package/src/build/blueprint/cognet/schema/interfaces/index.ts +3 -0
  38. package/src/build/blueprint/cognet/schema/interfaces/source.ts +218 -0
  39. package/src/build/blueprint/cognet/schema/python.ts +260 -0
  40. package/src/build/blueprint/cognet/schema/rust.ts +316 -0
  41. package/src/build/blueprint/cognet/schema/schema.ts +248 -0
  42. package/src/build/blueprint/cognet/schema/typescript.ts +352 -0
  43. package/src/build/blueprint/index.ts +1 -1
  44. package/src/build/blueprint/modules/index.ts +7 -5
  45. package/src/build/blueprint/modules/meta.ts +47 -3
  46. package/src/build/blueprint/scan/config.ts +22 -16
  47. package/src/build/blueprint/scan/provider-globals.ts +46 -0
  48. package/src/build/blueprint/scan/providers.ts +25 -0
  49. package/src/build/blueprint/scan/tools.ts +21 -15
  50. package/src/build/extensions/edit.ts +66 -2
  51. package/src/build/extensions/extensions.ts +16 -3
  52. package/src/build/extensions/index.ts +1 -1
  53. package/src/build/project/bundle/agent.ts +26 -17
  54. package/src/build/project/bundle/source.ts +2 -2
  55. package/src/build/project/create/cognet.ts +84 -33
  56. package/src/build/project/create/profile.ts +13 -3
  57. package/src/build/project/index.ts +1 -1
  58. package/src/build/project/installer.ts +6 -5
  59. package/src/build/project/kinds.ts +4 -0
  60. package/src/build/project/manifest/env.ts +10 -0
  61. package/src/build/project/models/blobs/blobs.ts +57 -0
  62. package/src/build/project/models/blobs/index.ts +1 -0
  63. package/src/build/project/models/fetch.ts +46 -51
  64. package/src/build/project/models/index.ts +2 -1
  65. package/src/build/project/models/models.ts +12 -38
  66. package/src/build/project/models/onnx.ts +82 -0
  67. package/src/build/project/models/specifier.ts +9 -3
  68. package/src/build/project/models/storage/index-store.ts +27 -0
  69. package/src/build/project/models/storage/index.ts +1 -0
  70. package/src/build/project/models/store.ts +21 -16
  71. package/src/build/project/prepare.ts +82 -27
  72. package/src/build/project/project.ts +8 -14
  73. package/src/build/project/projects.ts +12 -1
  74. package/src/build/project/tree.ts +13 -3
  75. package/src/build/project/treecache.ts +8 -4
  76. package/src/build/project/typegen/axon-dts.ts +18 -0
  77. package/src/build/project/typegen/cognet-dts.ts +248 -59
  78. package/src/build/project/typegen/prompt-dts.ts +2 -3
  79. package/src/build/project/typegen/registry-dts.ts +2 -2
  80. package/src/build/project/typegen/tsconfig.ts +13 -13
  81. package/src/build/project/typegen/tui-dts.ts +3 -4
  82. package/src/build/project/typegen/workspace-scripts.ts +8 -7
  83. package/src/build/project/typegen/write.ts +15 -2
  84. package/src/build/project/watcher.ts +27 -0
  85. package/src/build/runtime/agent.ts +102 -63
  86. package/src/build/runtime/conformance.ts +25 -0
  87. package/src/build/runtime/escalations.ts +3 -8
  88. package/src/build/runtime/index.ts +2 -0
  89. package/src/build/runtime/instances.ts +7 -4
  90. package/src/build/runtime/progress.ts +6 -2
  91. package/src/build/runtime/reload-watch.ts +11 -8
  92. package/src/debug/README.md +398 -0
  93. package/src/debug/debug.ts +101 -0
  94. package/src/debug/events.ts +156 -0
  95. package/src/debug/graph.ts +94 -0
  96. package/src/debug/index.ts +5 -0
  97. package/src/debug/indexer.ts +286 -0
  98. package/src/debug/inference.ts +53 -0
  99. package/src/debug/log.ts +68 -0
  100. package/src/debug/overview.ts +78 -0
  101. package/src/debug/perf.ts +75 -0
  102. package/src/debug/resources.ts +125 -0
  103. package/src/debug/ring.ts +31 -0
  104. package/src/debug/sessions.ts +90 -0
  105. package/src/debug/signs.ts +119 -0
  106. package/src/debug/tally.ts +44 -0
  107. package/src/debug/types.ts +146 -0
  108. package/src/index.ts +9 -0
  109. package/src/link/agent-main.ts +36 -10
  110. package/src/link/index.ts +1 -1
  111. package/src/link/services.ts +88 -57
  112. package/src/platform.ts +17 -25
  113. package/src/services/cloud.ts +1 -4
  114. package/src/services/control/client.ts +1 -1
  115. package/src/services/control/server.ts +1 -1
  116. package/src/services/index.ts +1 -0
  117. package/src/services/ollama/daemon.ts +23 -0
  118. package/src/services/ollama/http.ts +7 -1
  119. package/src/services/ollama/ollama.ts +8 -14
  120. package/src/services/probe/ask.ts +139 -0
  121. package/src/services/probe/index.ts +3 -0
  122. package/src/services/providers.ts +18 -0
  123. package/src/services/resources/hardware.ts +15 -18
  124. package/src/services/resources/resources.ts +4 -5
  125. package/src/services/store/types.ts +3 -0
  126. package/src/services/running/index.ts +0 -1
  127. package/src/services/running/running.ts +0 -216
@@ -24,11 +24,12 @@ import { err } from "@arcforge/err"
24
24
  import { readFileSync } from "node:fs"
25
25
  import { Axon, AxonBus } from "@arcforge/core"
26
26
  import { Routes, Middleware, Plugins } from "../build/blueprint"
27
- import type { AxonCommitContext, AxonMiddleware, AxonPartialBlueprint, AxonPlugin, AxonRoute } from "@arcforge/types"
27
+ import { isEntryEvent, type AxonCommitContext, type AxonMiddleware, type AxonPartialBlueprint, type AxonPlugin, type AxonRoute } from "@arcforge/types"
28
28
  import {
29
29
  AGENT_BLUEPRINT_ENV,
30
30
  AgentRuntime,
31
31
  RemoteDriver,
32
+ RemoteTransform,
32
33
  agentHandlers,
33
34
  connect,
34
35
  readLinkEnv,
@@ -197,7 +198,10 @@ export async function main(): Promise<void> {
197
198
  // remote — inference crosses the link, so no credential is here
198
199
  // (tools then load in this heap, see Axon())
199
200
  // escalate — the DECIDER stays outside; this asks over a verb
200
- remote: role => RemoteDriver({ role, supervisor }),
201
+ remote: {
202
+ generate: role => RemoteDriver({ role: role, supervisor: supervisor }),
203
+ transform: role => RemoteTransform({ role: role, supervisor: supervisor }),
204
+ },
201
205
  /*
202
206
  * Ask the supervisor, which asks the person.
203
207
  *
@@ -268,11 +272,18 @@ export async function main(): Promise<void> {
268
272
  * Returns undefined when neither is present, so an event with no
269
273
  * correlation commits with no context rather than an empty object.
270
274
  */
271
- function contextOf(context: AxonCommitContext | undefined): AxonCommitContext | undefined {
272
- if (!context) return undefined
273
- const { runId, spanId } = context
274
- if (!runId && !spanId) return undefined
275
- return { ...(runId ? { runId } : {}), ...(spanId ? { spanId } : {}) }
275
+ /**
276
+ * What travels with a relayed event: its correlation, and — for an entry —
277
+ * the seq it was stamped with here, which the supervisor's re-stamp would
278
+ * otherwise lose. The mind addresses entries by this seq (a text span
279
+ * names one); `origin` is how it is found in the supervisor's log.
280
+ */
281
+ function contextOf(type: string, context: AxonCommitContext | undefined, seq: number): AxonCommitContext | undefined {
282
+ const runId = context?.runId
283
+ const spanId = context?.spanId
284
+ const origin = isEntryEvent(type) ? seq : undefined
285
+ if (!runId && !spanId && origin === undefined) return undefined
286
+ return { ...(runId ? { runId } : {}), ...(spanId ? { spanId } : {}), ...(origin !== undefined ? { origin: origin } : {}) }
276
287
  }
277
288
 
278
289
  function announce(type: string, payload: unknown): void {
@@ -297,12 +308,12 @@ export async function main(): Promise<void> {
297
308
  * reason about at this seam.
298
309
  */
299
310
  const carrier = payload as {
300
- time?: unknown
311
+ time?: { ms: number; seq: number }
301
312
  data?: unknown
302
313
  type?: unknown
303
314
  context?: AxonCommitContext
304
315
  } | undefined
305
- if (carrier && typeof carrier === "object" && "time" in carrier) {
316
+ if (carrier && typeof carrier === "object" && carrier.time !== undefined) {
306
317
  // The context travels WITH the payload, as its own argument.
307
318
  // Unwrapping the envelope and dropping `context` is what silently
308
319
  // un-correlated every span once agents moved into subprocesses:
@@ -310,7 +321,7 @@ export async function main(): Promise<void> {
310
321
  // complete share it, and nothing else joins them. The supervisor
311
322
  // re-envelopes on the far side, so this is the only place the ids
312
323
  // can be handed over.
313
- forward(type, carrier.data, contextOf(carrier.context))
324
+ forward(type, carrier.data, contextOf(type, carrier.context, carrier.time.seq))
314
325
  return
315
326
  }
316
327
  // A raw event: strip the name it already travels under, keep the rest.
@@ -366,6 +377,21 @@ export async function main(): Promise<void> {
366
377
  // Never hold the process open on our own account.
367
378
  watchdog.unref?.()
368
379
 
380
+ /**
381
+ * The supervisor ends this process, never a signal.
382
+ *
383
+ * Ctrl-C in a terminal signals the whole foreground group, this process
384
+ * included. Left to the default, it died on the spot, before the
385
+ * supervisor's `shutdown` reached it. The brain was never unloaded, no
386
+ * plugin's `shutdown` hook ran, and the session log simply stopped. Held
387
+ * here, the same way the CLI's own supervisor holds them: the supervisor
388
+ * hears the signal and asks for an orderly shutdown, and if it dies
389
+ * instead, the watchdog above ends this process.
390
+ */
391
+ const holdSignal = () => {}
392
+ process.on("SIGINT", holdSignal)
393
+ process.on("SIGTERM", holdSignal)
394
+
369
395
  // Readiness is the SOCKET connecting, which the supervisor already races
370
396
  // against process exit — nothing ever read this line. It stayed harmless
371
397
  // only while the agent's stdout went to an unread pipe; now that stdout
package/src/link/index.ts CHANGED
@@ -26,12 +26,12 @@ export {
26
26
  type SocketPaths,
27
27
  SupervisorLink,
28
28
  supervisorHandlers,
29
- agentServices,
30
29
  VERB,
31
30
  type SupervisorServices,
32
31
  agentHandlers,
33
32
  supervisorProxy,
34
33
  RemoteDriver,
34
+ RemoteTransform,
35
35
  type AgentServices,
36
36
  AgentRuntime,
37
37
  type RuntimeForAgent,
@@ -1,9 +1,10 @@
1
1
  import { err } from "@arcforge/err"
2
2
  import { AxonSession } from "@arcforge/session"
3
3
  import { AxonBus } from "@arcforge/core"
4
- import type { AxonBlueprint, AxonEngineRawEvent, EngineCapability, InferCall } from "@arcforge/types"
4
+ import type { AxonBlueprint, AxonEngineRawEvent, EngineCapability, InferCall, ResolvedEngineFacts, TransformCall } from "@arcforge/types"
5
5
  import type { AxonCloudClient } from "@arcforge/cloud"
6
6
  import { Inference } from "@arcforge/core"
7
+ import type { LocalRuntime, EnginesT } from "@arcforge/engines/catalogue"
7
8
 
8
9
  /**
9
10
  * What the SUPERVISOR holds on a confined agent's behalf.
@@ -27,7 +28,7 @@ type ServicesOpts = {
27
28
  /** Where the log lives. Opened here, on the supervisor's side. */
28
29
  sessionId: string
29
30
  /** The daemon-owned local inference bridge for this machine. */
30
- local?: { catalogue(): Promise<EngineCapability[]>; run(model: string, prompt: string): Promise<string> }
31
+ local?: LocalRuntime
31
32
  }
32
33
 
33
34
  export async function SupervisorSideServices(opts: ServicesOpts) {
@@ -49,75 +50,84 @@ export async function SupervisorSideServices(opts: ServicesOpts) {
49
50
  })
50
51
 
51
52
  /**
52
- * Roles resolved ONCE, on this side.
53
+ * Role resolution belongs to this side of the boundary, but it does NOT
54
+ * belong on the readiness path. A provider catalogue can take a second to
55
+ * answer while routes, tools and the control surface are already usable.
53
56
  *
54
- * The agent never resolves a role: resolution means reaching the user's
55
- * providers over the network and building a driver from a credential,
56
- * which is exactly the work the boundary exists to keep out of the box.
57
+ * One promise coalesces concurrent first requests. A failed resolution is
58
+ * deliberately not retained: the requesting inference receives the error
59
+ * loudly, and a later request may retry after the provider recovers.
57
60
  */
58
- const engines = await Inference({
59
- blueprint: opts.blueprint,
60
- cloud: opts.cloud,
61
- session,
62
- ...(opts.local ? { local: opts.local } : {}),
63
- })
64
-
65
- return {
66
- session,
61
+ let engines: EnginesT | undefined
62
+ let resolving: Promise<EnginesT | undefined> | null = null
67
63
 
68
- /**
69
- * The resolved inference roles — the SUPERVISOR's, because it is the
70
- * side that holds the credential and did the resolving.
71
- *
72
- * Exposed so a model switch can rebind the live binding. `setModel`
73
- * reached for `runtime.kernel.engines`, which exists only for an
74
- * in-heap agent: for a linked one it was null, the rebind silently did
75
- * nothing, and the header had no resolved capability to render.
76
- */
77
- engines,
64
+ async function resolve(): Promise<EnginesT | undefined> {
65
+ if (engines) return engines
66
+ if (!resolving) {
67
+ resolving = Inference({
68
+ blueprint: opts.blueprint,
69
+ cloud: opts.cloud,
70
+ session,
71
+ ...(opts.local ? { local: opts.local } : {}),
72
+ }).then(value => {
73
+ engines = value
74
+ return value
75
+ }).catch(cause => {
76
+ resolving = null
77
+ throw cause
78
+ })
79
+ }
80
+ return resolving
81
+ }
78
82
 
83
+ const selection = {
84
+ get current() { return engines },
85
+ get primary() { return engines?.primary ?? null },
86
+ has: (role: string) => engines?.has(role) ?? false,
87
+ get(role: string) {
88
+ if (!engines) throw err("ENGINE_ROLE_UNBOUND_LINK", { detail: "inference has not been resolved" })
89
+ return engines.get(role)
90
+ },
91
+ async refresh(provider: string): Promise<void> {
92
+ const current = await resolve()
93
+ if (!current) throw err("ENGINE_ROLE_UNBOUND_LINK", { detail: "this agent declares no inference roles" })
94
+ await current.refresh(provider)
95
+ },
96
+ async select(model: string): Promise<EngineCapability | null> {
97
+ const current = await resolve()
98
+ return current ? current.select(model) : null
99
+ },
79
100
  /**
80
- * The primary role's resolved binding, flattened for the wire.
81
- *
82
- * The agent cannot compute this: resolving needs the credential,
83
- * which is the one thing the boundary keeps on this side. So the
84
- * answer is carried on the blueprint (see AxonBlueprint.engine) and
85
- * `/_axon/health` reports it from there rather than from a kernel
86
- * that, for a confined agent, has no engines at all.
87
- *
88
- * Null for a cognet with no roles or no primary — a pure control loop
89
- * genuinely has no model.
101
+ * What each BOUND role got, as the facts a confined agent may know —
102
+ * type, modalities, context, slots; never a provider or a model. What
103
+ * lets `kernel.engine.has()` inside the box tell a filled optional
104
+ * role from an empty one.
90
105
  */
91
- get engine(): { provider: string; model: string | null } | null {
92
- const bound = engines?.resolution.bound
93
- if (!bound?.length) return null
94
-
95
- const primary = bound.find(entry => entry.requirement.primary)
96
- ?? bound.find(entry => entry.role === "main")
97
- if (!primary) return null
98
-
99
- return { provider: primary.capability.provider, model: primary.capability.id }
106
+ async facts(): Promise<Record<string, ResolvedEngineFacts>> {
107
+ const current = await resolve()
108
+ const facts: Record<string, ResolvedEngineFacts> = {}
109
+ for (const binding of current?.resolution.bound ?? []) {
110
+ facts[binding.role] = {
111
+ type: binding.requirement.type,
112
+ ...(binding.capability.context !== undefined ? { context: binding.capability.context } : {}),
113
+ modalities: { in: [...binding.capability.in], out: [...binding.capability.out] },
114
+ slots: binding.slots,
115
+ }
116
+ }
117
+ return facts
100
118
  },
119
+ }
101
120
 
102
- /** Sanitized role facts safe to hand into the confined brain. */
103
- get engineFacts() {
104
- return Object.fromEntries((engines?.resolution.bound ?? []).map(entry => [
105
- entry.role,
106
- {
107
- type: entry.requirement.type,
108
- ...(entry.capability.context !== undefined ? { context: entry.capability.context } : {}),
109
- modalities: { in: entry.capability.in, out: entry.capability.out },
110
- slots: entry.slots,
111
- },
112
- ]))
113
- },
121
+ return {
122
+ engines: selection,
123
+ session,
114
124
 
115
125
  /** Where a surface watches this agent — the linked counterpart of runtime.bus. */
116
126
  bus,
117
127
 
118
128
  /** One inference call, performed here, streamed back as raw deltas. */
119
129
  async *infer(call: InferCall, signal: AbortSignal): AsyncGenerator<AxonEngineRawEvent> {
120
- const bound = engines?.get(call.role)
130
+ const bound = (await resolve())?.get(call.role)
121
131
  if (!bound) {
122
132
  throw err("ENGINE_ROLE_UNBOUND_LINK", { detail: `no engine bound to "${call.role}"`, context: { role: call.role } })
123
133
  }
@@ -131,6 +141,27 @@ export async function SupervisorSideServices(opts: ServicesOpts) {
131
141
  }
132
142
  },
133
143
 
144
+ /**
145
+ * One transform, performed here, its result sent back whole.
146
+ *
147
+ * Traced agent-side, where the kernel brackets every transform; this
148
+ * side only performs it. The wake's signal crossed with the call, so a
149
+ * wake that ends stops the wait — the model's own work cannot be
150
+ * cancelled mid-graph and finishes unobserved.
151
+ */
152
+ async transform(call: TransformCall, signal: AbortSignal): Promise<unknown> {
153
+ const bound = (await resolve())?.get(call.role)
154
+ if (!bound) {
155
+ throw err("ENGINE_ROLE_UNBOUND_LINK", { detail: `no engine bound to "${call.role}"`, context: { role: call.role } })
156
+ }
157
+ const driver = bound.driver
158
+ if (driver.kind !== "transform") {
159
+ throw err("ENGINE_KIND_MISMATCH_LINK", { detail: `role "${call.role}" is bound to a ${driver.kind ?? "generate"} driver, not a transform`, context: { role: call.role, kind: driver.kind ?? "generate" } })
160
+ }
161
+ signal.throwIfAborted()
162
+ return await driver.transform(call.input, { signal: signal })
163
+ },
164
+
134
165
  async close() {
135
166
  await session.end()
136
167
  },
package/src/platform.ts CHANGED
@@ -6,10 +6,11 @@ import { Files } from "./services/files"
6
6
  import { Cloud } from "./services/cloud"
7
7
  import { Deployments } from "./services/deployments"
8
8
  import { Projects } from "./build/project"
9
- import { Profile, Runtime } from "./build/runtime"
9
+ import { Conformance, Profile, Runtime } from "./build/runtime"
10
10
  import type { AgentSupervisor } from "./build/runtime/instances"
11
11
  import { Extensions, ProfileConfigFile, readSettingsSync } from "./build/extensions"
12
12
  import { Resources } from "./services/resources"
13
+ import { Debug } from "./debug"
13
14
 
14
15
  import { TestRunner } from "./services/test"
15
16
  import { Registry, PromptCache } from "./services/registry"
@@ -17,7 +18,7 @@ import { Prompts } from "./services/prompts"
17
18
  import { Updates } from "./services/update"
18
19
  import { join, resolve } from "node:path"
19
20
  import type { Distribution } from "./services/cloud"
20
- import type { ProviderEntry } from "@arcforge/types"
21
+ import { ProfileProviders } from "./services"
21
22
 
22
23
  const BUILD_DISTRIBUTION: Distribution = process.env.NODE_ENV === "production" ? "production" : "development"
23
24
 
@@ -112,28 +113,10 @@ export function Platform(opts: PlatformOpts) {
112
113
  // the registry and project preparation. Both are defined below in terms of
113
114
  // `projects`, so they arrive as thunks rather than values: construction is
114
115
  // wiring, and nothing here calls anything.
115
- /**
116
- * The active profile's declared inference sources.
117
- *
118
- * ASYNC because reading them evaluates the user's own `profile.config.ts`
119
- * — the same single evaluator the extension loader uses, so the two can
120
- * never disagree about what a profile declares. Read per prepare rather
121
- * than cached: a profile switch or a config edit must be visible on the
122
- * next agent boot, and prepare is already doing far more expensive work.
123
- *
124
- * Silent on failure by design. A broken profile config reports through
125
- * the extension loader, which owns telling a user their config is wrong;
126
- * a second message from here would only make the first one ambiguous.
127
- */
128
- async function profileProviders(): Promise<readonly ProviderEntry[] | undefined> {
129
- const root = store.profiles.active()?.root
130
- if (!root) return undefined
131
- const { providers } = await ProfileConfigFile(root)
132
- // Undefined travels: it means "never configured", which the pool
133
- // answers with the default. Returning [] here would tell every
134
- // profile written before this field existed that it has no inference.
135
- return providers
136
- }
116
+ const profileProviders = ProfileProviders({
117
+ root: () => store.profiles.active()?.root,
118
+ read: ProfileConfigFile,
119
+ })
137
120
 
138
121
  /**
139
122
  * This machine's local-inference capacity and what is holding it.
@@ -152,7 +135,7 @@ export function Platform(opts: PlatformOpts) {
152
135
  // Read fresh per call, never captured: the active profile changes
153
136
  // while the process runs, and every agent prepared afterwards must
154
137
  // see the new user's providers rather than the boot-time one's.
155
- profileProviders: () => profileProviders(),
138
+ profileProviders: profileProviders.read,
156
139
  cwd: cwd,
157
140
  frameworkVersion: opts.version,
158
141
  ...(opts.frameworkSource ? { frameworkSource: opts.frameworkSource } : {}),
@@ -241,12 +224,21 @@ export function Platform(opts: PlatformOpts) {
241
224
  latest: async name => (await cloud.client.registry.artifacts.resolve(name)).version,
242
225
  })
243
226
 
227
+ // What an agent uses to see inside a mind — see debug/README.md.
228
+ const debug = Debug()
229
+
230
+ // Whether what fills an agent's uses means what their interfaces say — see `axon conform`.
231
+ const conformance = Conformance({ cloud: cloud.client, profileProviders: profileProviders.read })
232
+
244
233
  return {
245
234
  cloud: cloud,
246
235
  store: store,
247
236
  deployments: deployments,
237
+ debug: debug,
238
+ conformance: conformance,
248
239
  projects: projects,
249
240
  profile: profile,
241
+ providers: profileProviders,
250
242
  extensions: extensions,
251
243
  /**
252
244
  * Re-read `profile.config.ts` settings into the store's cache.
@@ -431,10 +431,7 @@ export function Cloud(opts: CloudOpts) {
431
431
  * or key paste) and uploads the credential; nothing is persisted
432
432
  * on this machine. Pure delegation to AxonCloud's vault surface.
433
433
  */
434
- connections: {
435
- openai: client.user.vault.connections.openai,
436
- openrouter: client.user.vault.connections.openrouter,
437
- },
434
+ connections: client.user.vault.connections,
438
435
  }
439
436
  }
440
437
 
@@ -7,7 +7,7 @@ import { isControlFrame, type TuiSurface } from "./protocol"
7
7
  * ControlClient — the editor end of the control channel.
8
8
  *
9
9
  * Dials a running TUI using the port and token on its instance record.
10
- * There is no discovery here on purpose: `Running()` already answers "what
10
+ * There is no discovery here on purpose: the daemon's registry already answers "what
11
11
  * is running right now", and the extension already watches it. This turns
12
12
  * one record into one connection, nothing more.
13
13
  *
@@ -8,7 +8,7 @@ import { isControlFrame, type ControlHello, type EditorSurface } from "./protoco
8
8
  *
9
9
  * Listens on an ephemeral port and mints a token, both of which the caller
10
10
  * writes into its `AxonInstance` record. That record is the discovery
11
- * mechanism: `Running()` already scans it, pid-checks it, GCs it and
11
+ * mechanism: the daemon's registry already scans it, pid-checks it, GCs it and
12
12
  * watches it, so the channel inherits liveness for free and needs no
13
13
  * announce protocol of its own. The port dies with the process, which is
14
14
  * exactly the fact the pid check already proves — so publishing it does not
@@ -3,3 +3,4 @@ export * from "./deployments"
3
3
  export * from "./mic"
4
4
  export * from "./ollama"
5
5
  export * from "./registry"
6
+ export { ProfileProviders } from "./providers"
@@ -0,0 +1,23 @@
1
+ import { Http } from "./http"
2
+ import { Models } from "./models"
3
+ import type { OllamaStatus } from "./types"
4
+ import { err, isAxonError } from "@arcforge/err"
5
+
6
+ /** One Ollama endpoint's health and installed models. */
7
+ export function Daemon(opts: { host: string }) {
8
+ const http = Http({ host: opts.host })
9
+ const models = Models({ http: http })
10
+ async function status(): Promise<OllamaStatus> {
11
+ try {
12
+ const version = await http.json<unknown>("/api/version")
13
+ if (!version || typeof version !== "object" || !("version" in version) || typeof version.version !== "string") {
14
+ throw err("OLLAMA_REQUEST_FAILED", { detail: "Invalid Ollama version response", context: { host: http.host } })
15
+ }
16
+ return { running: true, version: version.version }
17
+ } catch (cause) {
18
+ if (!isAxonError(cause) || cause.code !== "AX-TUI-037") throw cause
19
+ return { running: false, reason: cause instanceof Error ? cause.message : String(cause) }
20
+ }
21
+ }
22
+ return { host: http.host, models: models, status: status }
23
+ }
@@ -47,7 +47,13 @@ export function Http(opts: HttpOpts) {
47
47
  }
48
48
 
49
49
  if (!response.ok) {
50
- const body = await response.text().catch(() => "")
50
+ const body = await response.text().catch(cause => {
51
+ throw err("OLLAMA_REQUEST_FAILED", {
52
+ detail: `${path}: could not read the daemon's error response`,
53
+ context: { host: host, path: path, status: response.status },
54
+ cause: cause,
55
+ })
56
+ })
51
57
  const message = parseErrorBody(body) ?? `${response.status} ${response.statusText}`
52
58
  throw err("OLLAMA_REQUEST_FAILED", {
53
59
  detail: `${path}: ${message}`,
@@ -1,7 +1,6 @@
1
- import { Http } from "./http"
2
- import { Models } from "./models"
1
+ import { Daemon } from "./daemon"
3
2
  import { Registry } from "./registry"
4
- import type { CatalogModel, OllamaStatus } from "./types"
3
+ import type { CatalogModel } from "./types"
5
4
 
6
5
  /** Ollama's own default. Overridable for a daemon on another host or port. */
7
6
  const DEFAULT_HOST = "http://localhost:11434"
@@ -34,12 +33,12 @@ type OllamaOpts = {
34
33
  export function Ollama(opts: OllamaOpts = {}) {
35
34
  const host = opts.host ?? process.env.OLLAMA_HOST ?? DEFAULT_HOST
36
35
 
37
- const http = Http({ host: host })
38
- const models = Models({ http: http })
36
+ const daemon = Daemon({ host: host })
37
+ const models = daemon.models
39
38
  const registry = Registry(opts.registryUrl !== undefined ? { baseUrl: opts.registryUrl } : {})
40
39
 
41
40
  return {
42
- host: http.host,
41
+ host: daemon.host,
43
42
  models: models,
44
43
  registry: registry,
45
44
 
@@ -51,14 +50,9 @@ export function Ollama(opts: OllamaOpts = {}) {
51
50
  * unreachable daemon is the expected answer half the time rather than a
52
51
  * fault. Every other verb throws.
53
52
  */
54
- async status(): Promise<OllamaStatus> {
55
- try {
56
- const { version } = await http.json<{ version: string }>("/api/version")
57
- return { running: true, version: version }
58
- } catch (cause) {
59
- return { running: false, reason: cause instanceof Error ? cause.message : String(cause) }
60
- }
61
- },
53
+ status: daemon.status,
54
+ /** Machine policy may point at a different daemon. No network at construction. */
55
+ at(host: string) { return Daemon({ host: host }) },
62
56
 
63
57
  /**
64
58
  * The catalog, marked up with what is already installed and what each
@@ -0,0 +1,139 @@
1
+ /**
2
+ * Ask an external binary a question, and never block this thread for the answer.
3
+ *
4
+ * ── Why this exists ─────────────────────────────────────────────────────────
5
+ *
6
+ * Every machine probe here — GPU memory, GPU utilisation, the macOS platform
7
+ * UUID — works the same way: run a vendor tool, parse a line, tolerate its
8
+ * absence. All of them originally used a bare `Bun.spawnSync(...)`, which makes
9
+ * the calling thread hostage to a third-party binary.
10
+ *
11
+ * ── Why a timeout was NOT the whole fix ─────────────────────────────────────
12
+ *
13
+ * The first version of this file bounded `Bun.spawnSync` at two seconds and
14
+ * treated the problem as solved. It was not. Caught in the act on 2026-09-08:
15
+ * a `bun test --test-worker --isolate` process alive for 4h57m with
16
+ * `nvidia-smi <defunct>` as its child — and the worker in state R, spinning on
17
+ * CPU rather than blocked. The child had exited and was never reaped; the
18
+ * parent never resumed. `spawnSync`'s `timeout` does not bound that.
19
+ *
20
+ * The damage was not confined to the wedged suite. That one process pushed the
21
+ * machine's load average past 12, and every other suite then failed at its
22
+ * exact declared ceiling — store tests at 5000ms, blueprint loads at 60000ms,
23
+ * a tui install at 30000ms, staging tests mid-release. They read as unrelated
24
+ * flakes and blocked several attempts to ship.
25
+ *
26
+ * ── The fix: nothing waits ──────────────────────────────────────────────────
27
+ *
28
+ * `ask` never spawns synchronously. It answers from a cache and refreshes that
29
+ * cache in the BACKGROUND with `Bun.spawn`, whose exit is awaited against an
30
+ * AbortSignal. A hung vendor tool now costs one stale metric and one abandoned
31
+ * subprocess — never a stalled thread.
32
+ *
33
+ * The first call for a command reports "unknown", which is a shape every caller
34
+ * already handles: they all read `exitCode !== 0` as "we do not know", the same
35
+ * answer they give for a missing binary. So a metric appears one tick late
36
+ * rather than wrongly, and `read()` stays synchronous and safe to call from a
37
+ * timer — which is what kept this fix from cascading into the admission path
38
+ * that has to answer at an instant.
39
+ */
40
+
41
+ /** A healthy vendor probe answers in tens of milliseconds; this is a hang bound, not a budget. */
42
+ export const PROBE_TIMEOUT_MS = 2_000
43
+
44
+ export type Probe = { exitCode: number | null; stdout: Buffer; stderr: Buffer }
45
+
46
+ /** What a caller gets before the first refresh lands, and after a failed one. */
47
+ function unknown(detail: string): Probe {
48
+ return { exitCode: null, stdout: Buffer.alloc(0), stderr: Buffer.from(detail) }
49
+ }
50
+
51
+ const NOT_YET = "probe has not answered yet"
52
+
53
+ /**
54
+ * Has this question simply not come back yet, as opposed to failing?
55
+ *
56
+ * Both are `exitCode !== 0` and most callers are right not to care — "we do not
57
+ * know" covers both. It matters only to a caller that CACHES the answer:
58
+ * latching "no GPU" because the first background refresh had not landed yet
59
+ * would be permanently wrong on a machine that has one.
60
+ */
61
+ export function pending(probe: Probe): boolean {
62
+ return probe.exitCode === null && probe.stderr.toString() === NOT_YET
63
+ }
64
+
65
+ /** Last known answer per command, plus whether a refresh is already in flight. */
66
+ const answers = new Map<string, Probe>()
67
+ const inFlight = new Set<string>()
68
+
69
+ /**
70
+ * Run the tool and record its answer. Never throws, never rejects — a probe
71
+ * cannot answer wrongly, only absently.
72
+ *
73
+ * A MISSING binary is the ordinary case (most machines have no `nvidia-smi`,
74
+ * no Linux machine has `ioreg`), and `Bun.spawn` raises on it. That failure and
75
+ * a timeout collapse into the same `exitCode: null` shape, so no call site
76
+ * needs its own try/catch to express "no GPU".
77
+ */
78
+ async function refresh(key: string, cmd: string[]): Promise<void> {
79
+ try {
80
+ const child = Bun.spawn({
81
+ cmd: cmd,
82
+ stdout: "pipe",
83
+ stderr: "pipe",
84
+ // Abandoned rather than awaited if it wedges: the point of this
85
+ // whole file is that a stuck vendor tool never holds anything up.
86
+ signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
87
+ })
88
+ const [stdout, stderr] = await Promise.all([
89
+ new Response(child.stdout).arrayBuffer(),
90
+ new Response(child.stderr).arrayBuffer(),
91
+ ])
92
+ const exitCode = await child.exited
93
+ answers.set(key, {
94
+ exitCode: exitCode,
95
+ stdout: Buffer.from(stdout),
96
+ stderr: Buffer.from(stderr),
97
+ })
98
+ } catch (cause) {
99
+ // The reason travels back in `stderr`, so a caller that reports probe
100
+ // failures (Hardware does) still has something to say.
101
+ answers.set(key, unknown(cause instanceof Error ? cause.message : String(cause)))
102
+ } finally {
103
+ inFlight.delete(key)
104
+ }
105
+ }
106
+
107
+ /**
108
+ * The last answer to this question, and a refresh started if none is running.
109
+ *
110
+ * Named `ask` because that is the whole contract: pose a question, take the
111
+ * most recent answer, and carry on without waiting for a new one.
112
+ */
113
+ export function ask(cmd: string[]): Probe {
114
+ const key = cmd.join(" ")
115
+
116
+ if (!inFlight.has(key)) {
117
+ inFlight.add(key)
118
+ // Deliberately unawaited — this is the entire mechanism. `refresh`
119
+ // cannot reject, so there is no rejection to handle.
120
+ void refresh(key, cmd)
121
+ }
122
+
123
+ return answers.get(key) ?? unknown(NOT_YET)
124
+ }
125
+
126
+ /**
127
+ * Await any refresh currently in flight.
128
+ *
129
+ * For tests and for a caller that genuinely needs a reading before continuing
130
+ * (`axon machine` printing a one-shot report, where "unknown" on a healthy box
131
+ * would be a wrong answer rather than a late one). Bounded by the same ceiling
132
+ * as the probe itself, so waiting here cannot reintroduce the hang.
133
+ */
134
+ export async function settled(): Promise<void> {
135
+ const deadline = Date.now() + PROBE_TIMEOUT_MS * 2
136
+ while (inFlight.size > 0 && Date.now() < deadline) {
137
+ await Bun.sleep(10)
138
+ }
139
+ }
@@ -0,0 +1,3 @@
1
+ // probe — ask a vendor binary a question without ever waiting on it.
2
+
3
+ export { ask, pending, settled, PROBE_TIMEOUT_MS, type Probe } from "./ask"