@arcforge/platform 2.0.219 → 2.0.244

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
@@ -2,13 +2,13 @@ import { randomUUID } from "node:crypto"
2
2
  import { join, resolve } from "node:path"
3
3
  import { Axon } from "@arcforge/core"
4
4
  import type { AxonHost, AxonT } from "@arcforge/core"
5
- import type { AxonBlueprint, AxonPartialBlueprint, SupervisorToAgent } from "@arcforge/types"
5
+ import type { AxonBlueprint, AxonPartialBlueprint, SupervisorToAgent, EngineSelection } from "@arcforge/types"
6
6
  import type { AxonSessionT } from "@arcforge/session"
7
7
  import { err } from "@arcforge/err"
8
8
  import type { AxonCloudClient } from "@arcforge/cloud"
9
9
  import { BuildRecorder, span } from "@arcforge/session"
10
10
  import { Blueprint } from "../blueprint"
11
- import { readPolicy, ProfileConfigFile } from "../extensions"
11
+ import { readPermissions, readPolicy, ProfileConfigFile } from "../extensions"
12
12
  import { advances, stageFor, unitFor } from "./progress"
13
13
  import type { BootProgress, BootStage, UnitTiming } from "./progress"
14
14
  import { Frame } from "../frame"
@@ -33,6 +33,14 @@ type AgentOpts = {
33
33
  depth?: number
34
34
  /** Job directory this run answers, for correlation — see RunningRecord.job. */
35
35
  job?: string
36
+ /**
37
+ * What THIS invocation says, laid over the agent's own `.env`.
38
+ *
39
+ * The world address `-c` resolved rides here: one run's facts, so the
40
+ * same agent can be sent somewhere new without editing a file. The
41
+ * agent's `.env` is still what answers for everything this does not name.
42
+ */
43
+ env?: Readonly<Record<string, string>>
36
44
  /**
37
45
  * A local control channel this instance is listening on, published on
38
46
  * the running record so an editor can find and dial it.
@@ -140,21 +148,24 @@ export async function Agent(opts: AgentOpts) {
140
148
  * applies from the next boot or reload — not retroactively to a call
141
149
  * already in flight.
142
150
  *
143
- * Never throws. An unreadable or absent profile means no ceiling, which is
144
- * the correct state for `axon run` outside one and for a deployment. A
145
- * ceiling that failed CLOSED here would make a broken config unbootable;
146
- * one that fails open is the same posture the rest of the profile takes,
147
- * and the config's own loader is what reports the breakage.
151
+ * No active profile means no ceiling, which is correct for `axon run`
152
+ * outside one and for a deployment. An active profile that cannot be read
153
+ * is invalid configuration and must fail this boot loudly; silently
154
+ * dropping its ceiling would run the agent with broader policy than the
155
+ * user configured.
148
156
  */
149
157
  async function profileCeiling(): Promise<AxonPartialBlueprint["profilePolicy"]> {
150
- try {
151
- const active = opts.store.profiles.active()
152
- if (!active) return undefined
153
- const policy = await readPolicy(active.root)
154
- return Object.keys(policy).length > 0 ? (policy as AxonPartialBlueprint["profilePolicy"]) : undefined
155
- } catch {
156
- return undefined
157
- }
158
+ const active = opts.store.profiles.active()
159
+ if (!active) return undefined
160
+ const policy = await readPolicy(active.root)
161
+ const permissions = await readPermissions(active.root)
162
+ const mediation = permissions === "allow"
163
+ ? { shell: { allow: ["*"], raw: true, spawn: true }, tools: true }
164
+ : permissions === "ask"
165
+ ? { shell: { spawn: "escalate" }, tools: "escalate" }
166
+ : {}
167
+ const ceiling = { ...policy, ...mediation }
168
+ return Object.keys(ceiling).length > 0 ? (ceiling as AxonPartialBlueprint["profilePolicy"]) : undefined
158
169
  }
159
170
 
160
171
  /**
@@ -168,24 +179,21 @@ export async function Agent(opts: AgentOpts) {
168
179
  * Re-read per load so a provider added or a key connected takes effect on
169
180
  * the next boot or reload, rather than only after restarting the terminal.
170
181
  *
171
- * Never throws. An unreadable profile means no providers, which is the
172
- * correct state for `axon run` outside one and for a deployment — and a
173
- * throw here would make a broken profile config unbootable, when the
174
- * config's own loader is what reports the breakage.
182
+ * No active profile means no providers, which is correct for `axon run`
183
+ * outside one and for a deployment. An active profile that cannot be read
184
+ * is a broken credential/config boundary, not permission to silently fall
185
+ * back to a different provider pool.
175
186
  */
176
187
  async function profileProviders(): Promise<AxonPartialBlueprint["profileProviders"]> {
177
- try {
178
- const active = opts.store.profiles.active()
179
- if (!active) return undefined
180
- const { providers } = await ProfileConfigFile(active.root)
181
- // Carried VERBATIM, including an empty array. `[]` is a user who
182
- // declared no providers and absent is one who was never asked —
183
- // collapsing the first into the second would silently hand them
184
- // the default pool they had deliberately cleared.
185
- return providers ? [...providers] : undefined
186
- } catch {
187
- return undefined
188
- }
188
+ const active = opts.store.profiles.active()
189
+ if (!active) return undefined
190
+ const { providers, error } = await ProfileConfigFile(active.root)
191
+ if (error) throw error
192
+ // Carried VERBATIM, including an empty array. `[]` is a user who
193
+ // declared no providers and absent is one who was never asked —
194
+ // collapsing the first into the second would silently hand them
195
+ // the default pool they had deliberately cleared.
196
+ return providers ? [...providers] : undefined
189
197
  }
190
198
 
191
199
  /**
@@ -231,6 +239,16 @@ export async function Agent(opts: AgentOpts) {
231
239
  }
232
240
 
233
241
  function reportProgress(type: string, data: unknown): void {
242
+ if (type === "build:progress") {
243
+ const progress = data as { stage: string; message: string }
244
+ const stage = stageFor(`build:${progress.stage}:start`)
245
+ if (!stage) return
246
+ if (stage !== reported && !advances(reported, stage)) return
247
+ reported = stage
248
+ opts.onProgress?.({ stage: stage, detail: progress.message })
249
+ return
250
+ }
251
+
234
252
  // A closing span carries what it cost. Reported alongside progress so
235
253
  // a surface can show "4 mods, 15 tools (42ms)" without timing the
236
254
  // build itself — the span already measured it.
@@ -360,7 +378,14 @@ export async function Agent(opts: AgentOpts) {
360
378
  // framework, modules, cognet, tree and typegen each report
361
379
  // themselves through it, so a five-second build decomposes
362
380
  // instead of being one opaque bar.
363
- () => project.prepare({ report: (type, data) => recorder.emit(type as never, data as never) }),
381
+ () => project.prepare({
382
+ report: (type, data) => recorder.emit(type as never, data as never),
383
+ // A prepared result is reusable only while Project's
384
+ // watcher has continuously observed the root. The next
385
+ // blueprint load still runs below, so profile policy and
386
+ // providers are never taken from a stale cache.
387
+ reuse: true,
388
+ }),
364
389
  result => ({ warnings: result.warnings.length }),
365
390
  )
366
391
 
@@ -368,7 +393,7 @@ export async function Agent(opts: AgentOpts) {
368
393
  recorder,
369
394
  "build:load",
370
395
  { root: project.root },
371
- async () => blueprint.load({ profilePolicy: await profileCeiling(), profileProviders: await profileProviders() }),
396
+ async () => blueprint.load({ profilePolicy: await profileCeiling(), profileProviders: await profileProviders(), ...(opts.env ? { env: opts.env } : {}) }),
372
397
  result => ({
373
398
  // A scan that produced no agent identity is a scan that
374
399
  // failed to find one — recorded as the empty string
@@ -440,25 +465,31 @@ export async function Agent(opts: AgentOpts) {
440
465
  */
441
466
  raise({ stage: "booting" })
442
467
 
443
- const linked = await confined({
444
- blueprint: { ...loaded, session: { id: sessionId } },
445
- sessionId,
446
- /**
447
- * A REAL reload: rescan the project, then hand the agent the
448
- * blueprint that produced.
449
- *
450
- * The first cut re-sent the blueprint captured at boot, which
451
- * is a reload that cannot observe an edit — a tool the author
452
- * had just added never appeared, and the call reported success.
453
- * `build()` is the same scan+compile+load the boot path runs,
454
- * so a reload and a fresh boot see the project identically.
455
- *
456
- * The session id is preserved: a reload is the same
457
- * conversation with new code, and minting a new one would
458
- * split the log at every edit.
459
- */
460
- rescan: () => build().then(next => ({ ...next, session: { id: sessionId } })),
461
- })
468
+ const linked = await span(
469
+ recorder,
470
+ "build:supervise",
471
+ { agent: loaded.agent?.name ?? project.name },
472
+ () => confined({
473
+ blueprint: { ...loaded, session: { id: sessionId } },
474
+ sessionId,
475
+ /**
476
+ * A REAL reload: rescan the project, then hand the agent the
477
+ * blueprint that produced.
478
+ *
479
+ * The first cut re-sent the blueprint captured at boot, which
480
+ * is a reload that cannot observe an edit — a tool the author
481
+ * had just added never appeared, and the call reported success.
482
+ * `build()` is the same scan+compile+load the boot path runs,
483
+ * so a reload and a fresh boot see the project identically.
484
+ *
485
+ * The session id is preserved: a reload is the same
486
+ * conversation with new code, and minting a new one would
487
+ * split the log at every edit.
488
+ */
489
+ rescan: () => build().then(next => ({ ...next, session: { id: sessionId } })),
490
+ }),
491
+ runtime => ({ pid: runtime.pid }),
492
+ )
462
493
  // The supervisor-held session owns this log from here, so build
463
494
  // events commit through the same writer the agent's own will —
464
495
  // one serialized writer per file, which the envelope depends on.
@@ -492,21 +523,30 @@ export async function Agent(opts: AgentOpts) {
492
523
  * writes the reload's own business rather than the next reload's
493
524
  * trigger.
494
525
  */
495
- if (true) return linked // MUTANT
496
-
497
- const stopWatching = ReloadWatch({
498
- watcher: project.watcher,
499
- reload: () => project.watcher.during(
500
- () => linked.reload(),
501
- { selfReloads: true },
502
- ),
503
- })
526
+ if (opts.watch === false) return linked
527
+
528
+ let stopWatching: () => void
529
+ try {
530
+ stopWatching = await ReloadWatch({
531
+ watcher: project.watcher,
532
+ reload: () => project.watcher.during(
533
+ () => linked.reload(),
534
+ { selfReloads: true },
535
+ ),
536
+ })
537
+ } catch (cause) {
538
+ try { await linked.shutdown() } catch (shutdown) {
539
+ throw new AggregateError([cause, shutdown], "Watcher startup and agent shutdown failed")
540
+ }
541
+ throw cause
542
+ }
504
543
 
505
544
  // Stop watching when the agent stops. A watcher outliving its
506
545
  // agent holds an fs handle open and reloads a runtime that is
507
546
  // gone - and every boot would add another.
508
547
  return {
509
548
  ...linked,
549
+ get blueprint() { return linked.blueprint },
510
550
  async shutdown() {
511
551
  stopWatching()
512
552
  await linked.shutdown()
@@ -567,7 +607,7 @@ export type LinkedRuntime = {
567
607
  * where a model picker rebinds and where a header reads what actually
568
608
  * answered. Undefined for a cognet that declared no roles.
569
609
  */
570
- engines?: { select(model: string): unknown; readonly primary?: string; has(role: string): boolean; get(role: string): { binding: { capability: { provider: string; id: string } } } }
610
+ engines?: EngineSelection
571
611
  /** Which containment tier actually built the box. Reported, never assumed. */
572
612
  tier: "none" | "auto" | "container" | "hardened"
573
613
  /**
@@ -589,4 +629,3 @@ export type LinkedRuntime = {
589
629
  * one kind now, so consumers reach the link directly instead of narrowing.
590
630
  */
591
631
  export type AgentT = Awaited<ReturnType<typeof Agent>>
592
-
@@ -0,0 +1,25 @@
1
+ import { AxonBlueprint, Conform, type Conformed } from "@arcforge/core"
2
+ import type { AxonCloudClient } from "@arcforge/cloud"
3
+ import type { ProviderEntry } from "@arcforge/types"
4
+ import { Blueprint } from "../blueprint"
5
+
6
+ /**
7
+ * Conformance — an agent's uses, each filled as its boot would fill it and
8
+ * held to its interface's cases. What `axon conform` asks.
9
+ *
10
+ * Read from the agent as prepared: its compiled brain says what it uses and
11
+ * where each interface's cases are, its config what it grants. Run in this
12
+ * process, never inside the agent's box — it calls providers, it does not run
13
+ * the agent.
14
+ */
15
+ export function Conformance(opts: { cloud: AxonCloudClient; profileProviders(): Promise<readonly ProviderEntry[] | undefined> }) {
16
+ return {
17
+ async check(root: string): Promise<Conformed[]> {
18
+ const profileProviders = await opts.profileProviders()
19
+ const { blueprint } = await Blueprint({ root: root }).load({ ...(profileProviders ? { profileProviders: [...profileProviders] } : {}) })
20
+ return Conform({ blueprint: AxonBlueprint(blueprint), cloud: opts.cloud }).run()
21
+ },
22
+ }
23
+ }
24
+
25
+ export type ConformanceT = ReturnType<typeof Conformance>
@@ -38,14 +38,9 @@ export type EscalationsT = ReturnType<typeof Escalations>
38
38
  * 2. A SURFACE is attached → prompt, and wait for the answer.
39
39
  * 3. NOTHING is attached → deny immediately.
40
40
  *
41
- * (3) is the one worth stating. The capsule's own fallback is a 30-second
42
- * timeout, which turns every escalation in a headless run — CI, a cron, a
43
- * deployment — into a 30-second stall before the same denial. Failing fast is
44
- * both quicker and more honest: the request is recorded, the call gets a
45
- * denial naming it, and approving it later writes a grant the NEXT attempt
46
- * reads. "Answer later" cannot mean "the call waits" — the wake is blocked
47
- * inside a tool call, and parking that for hours would freeze the agent
48
- * mid-turn holding a capsule and a run.
41
+ * Without a surface, deny immediately and record the request. Approving it
42
+ * later writes a grant for the next attempt. With a surface attached, wait
43
+ * indefinitely for its answer, including time spent queued behind other asks.
49
44
  *
50
45
  * ── Every request is recorded, answered or not ──────────────────────────────
51
46
  *
@@ -13,3 +13,5 @@ export { Profile, type ProfileT } from "./profile"
13
13
  // Sessions() acts on ONE log by path (fork, rename) as well as listing them,
14
14
  // so it is reachable on its own rather than only through Runtime().
15
15
  export { Sessions, type SessionsT } from "./sessions"
16
+ // An agent's uses held to their interfaces' conformance cases — what `axon conform` asks.
17
+ export { Conformance, type ConformanceT } from "./conformance"
@@ -9,7 +9,7 @@ import { Agent, type AgentT, type LinkedRuntime } from "./agent"
9
9
  import type { BootProgress, UnitTiming } from "./progress"
10
10
  import type { ResolveT } from "./resolve"
11
11
  import type { EscalationsT } from "./escalations"
12
- import type { EscalationCall, SupervisorToAgent } from "@arcforge/types"
12
+ import type { EscalationCall, SupervisorToAgent, EngineSelection, EngineEffort } from "@arcforge/types"
13
13
  import type { AxonSessionT } from "@arcforge/session"
14
14
 
15
15
  /**
@@ -63,7 +63,7 @@ export type RemoteTarget = {
63
63
  * none or did not say — the caller renders an empty row rather than
64
64
  * inventing one.
65
65
  */
66
- engine?: { provider: string; model: string | null } | null
66
+ engine?: { provider: string; model: string | null; effort?: EngineEffort } | null
67
67
  }
68
68
 
69
69
  /**
@@ -112,7 +112,7 @@ export type AgentSupervisor = {
112
112
  link: SupervisorToAgent & { close(): void }
113
113
  session: AxonSessionT
114
114
  bus: { onAny(handler: (type: string, data: unknown) => void): () => void }
115
- engines?: unknown
115
+ engines?: EngineSelection
116
116
  blueprint: unknown
117
117
  tier: "none" | "auto" | "container" | "hardened"
118
118
  pid: number
@@ -167,6 +167,8 @@ export type SpawnOpts = {
167
167
  session?: string
168
168
  /** Job directory this run answers, for correlation — see AgentOpts.job. */
169
169
  job?: string
170
+ /** What this invocation says, over the agent's own `.env` — see AgentOpts.env. */
171
+ env?: Readonly<Record<string, string>>
170
172
  /** A local control channel the caller is listening on, published on the running record — see AgentOpts.control. */
171
173
  control?: { port: number; token: string }
172
174
  parentSessionId?: string
@@ -331,6 +333,7 @@ export function Instances(opts: InstancesOpts) {
331
333
  const agent = await Agent({
332
334
  project: project,
333
335
  ...(spawnOpts.job ? { job: spawnOpts.job } : {}),
336
+ ...(spawnOpts.env ? { env: spawnOpts.env } : {}),
334
337
  ...(spawnOpts.control ? { control: spawnOpts.control } : {}),
335
338
  /**
336
339
  * AGENTS ARE PROCESSES.
@@ -397,7 +400,7 @@ export function Instances(opts: InstancesOpts) {
397
400
  link: live.link,
398
401
  session: live.session,
399
402
  bus: live.bus,
400
- ...(live.engines ? { engines: live.engines as never } : {}),
403
+ ...(live.engines ? { engines: live.engines } : {}),
401
404
  get blueprint() {
402
405
  return current as never
403
406
  },
@@ -103,7 +103,7 @@ export function unitFor(type: BuildEventName | string): BuildUnit | null {
103
103
  switch (type) {
104
104
  case "build:modules:complete": return "modules"
105
105
  case "build:tree:complete": return "dependencies"
106
- case "build:cognet:complete": return "cognet"
106
+ case "build:compile:complete": return "cognet"
107
107
  default: return null
108
108
  }
109
109
  }
@@ -130,7 +130,11 @@ export function stageFor(type: BuildEventName | string): BootStage | null {
130
130
  case "build:typegen:start":
131
131
  return "preparing"
132
132
  case "build:tree:start": return "dependencies"
133
- case "build:cognet:start": return "compiling"
133
+ // ABI/model checks can be slow (a model store may inspect local
134
+ // weights) but do not bundle source. Keep them under preparation so
135
+ // the visible compile phase names the actual bundle/cache operation.
136
+ case "build:cognet:start": return "preparing"
137
+ case "build:compile:start": return "compiling"
134
138
  // Scan is fast and unactionable — it holds whatever came before rather
135
139
  // than earning a name (see the note above).
136
140
  //
@@ -66,11 +66,10 @@ export type ReloadWatchOpts = {
66
66
  /**
67
67
  * Start watching. Returns the stop function.
68
68
  *
69
- * Never throws and never rejects into the caller: a watcher is an accelerant,
70
- * and an agent whose boot failed because a file could not be watched would be
71
- * strictly worse than one that simply needs `:reload`.
69
+ * Starting the watcher is part of starting a watched agent. Failure must reach
70
+ * the caller rather than leaving an agent that silently never reloads.
72
71
  */
73
- export function ReloadWatch(opts: ReloadWatchOpts): () => void {
72
+ export async function ReloadWatch(opts: ReloadWatchOpts): Promise<() => void> {
74
73
  let running = false
75
74
  let deafUntil = 0
76
75
 
@@ -96,13 +95,17 @@ export function ReloadWatch(opts: ReloadWatchOpts): () => void {
96
95
  })()
97
96
  })
98
97
 
99
- // Fire-and-forget: start() walks the tree, and a slow walk must not hold
100
- // up the agent that is already running.
101
- void opts.watcher.start()
98
+ let release: () => void
99
+ try {
100
+ release = await opts.watcher.retain()
101
+ } catch (cause) {
102
+ stop()
103
+ throw cause
104
+ }
102
105
 
103
106
  return () => {
104
107
  stop()
105
- opts.watcher.stop()
108
+ release()
106
109
  }
107
110
  }
108
111