@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,604 @@
1
+ import { join } from "node:path"
2
+ import { err } from "@arcforge/err"
3
+ import type { AxonCloudClient, RemoteAgentHandle } from "@arcforge/cloud"
4
+ import type { AxonHost } from "@arcforge/core"
5
+ import type { ConnectableDeployment } from "../../services/deployments"
6
+ import type { StoreT } from "../../services/store"
7
+ import type { ProjectT, ProjectsT } from "../project"
8
+ import { Agent, type AgentT, type LinkedRuntime } from "./agent"
9
+ import type { BootProgress, UnitTiming } from "./progress"
10
+ import type { ResolveT } from "./resolve"
11
+ import type { EscalationsT } from "./escalations"
12
+ import type { EscalationCall, SupervisorToAgent } from "@arcforge/types"
13
+ import type { AxonSessionT } from "@arcforge/session"
14
+
15
+ /**
16
+ * Where an instance's runtime lives.
17
+ *
18
+ * A local instance owns an Axon() runtime in this process, with a project on
19
+ * disk it can reload and a bus to subscribe to. A remote instance is a deployed
20
+ * agent reached over `/_axon/*`: no project, no reload, no bus — its events
21
+ * arrive on the mirrored session's event stream instead.
22
+ *
23
+ * A discriminated union rather than an optional-field widening: the verbs that
24
+ * only make sense locally (reload, serve, watcher) are ABSENT from the remote
25
+ * branch, so nothing downstream can reach for them and find undefined.
26
+ */
27
+ /**
28
+ * A remote agent to bind to — the input side of attach().
29
+ *
30
+ * ONE shape for a deployment and a bare URL, because the difference between
31
+ * them is not a difference in what attaching means: both are an agent already
32
+ * running that this process does not own, reached over `/_axon/*`. What
33
+ * actually differs is whether a capability token has to be minted, and that is
34
+ * one optional field rather than a second code path.
35
+ *
36
+ * `url` is the identity here, not `deploymentId` — a URL is the one thing both
37
+ * kinds always have, and it is what makes two attaches to the same agent
38
+ * detectable as the same binding.
39
+ */
40
+ export type RemoteTarget = {
41
+ /** Base URL of the running agent — `http://localhost:3010`, or a deployment's URL. */
42
+ url: string
43
+ /** What to call it in a UI. Resolved from the health handshake when a caller has no name. */
44
+ name: string
45
+ /**
46
+ * The registry agent id, when this is a deployment. Drives connect-token
47
+ * minting: the capability presented is scoped to this agent alone, and the
48
+ * user's own credential never leaves the control plane. Absent for a local
49
+ * dev server, where the agent is inside its owner's trust boundary and the
50
+ * connect gate is open.
51
+ */
52
+ agentId?: string
53
+ /** Present only for a deployment — what the control plane knows it as. */
54
+ deploymentId?: string
55
+ tier?: string
56
+ /**
57
+ * What the agent reports it is carrying, resolved from the handshake.
58
+ * Null when it did not say — an older agent, distinct from zero.
59
+ */
60
+ loaded?: { modules: number; tools: number } | null
61
+ /**
62
+ * The engine the agent declares, as it reported it. Null when it declares
63
+ * none or did not say — the caller renders an empty row rather than
64
+ * inventing one.
65
+ */
66
+ engine?: { provider: string; model: string | null } | null
67
+ }
68
+
69
+ /**
70
+ * What a spawned agent's supervisor gives back.
71
+ *
72
+ * Named here rather than imported, because the platform declares what it needs
73
+ * and the daemon satisfies it — the dependency points that way, and typing
74
+ * this against the daemon's own return would invert it.
75
+ */
76
+ export type AgentSupervisor = {
77
+ supervise(input: {
78
+ sessionId: string
79
+ blueprint: unknown
80
+ agent: string
81
+ projectRoot: string
82
+ dataRoot: string
83
+ /**
84
+ * The ownership graph — who spawned this, what tree it belongs to, how
85
+ * deep. Carried across because the DAEMON writes the liveness record
86
+ * now, and a record without these loses the subagent tree every reader
87
+ * nests on.
88
+ */
89
+ parentSessionId?: string | null
90
+ rootSessionId?: string
91
+ depth?: number
92
+ job?: string
93
+ /** A control channel this process serves, published for readers. */
94
+ control?: { port: number; token: string }
95
+ }): Promise<{
96
+ link: SupervisorToAgent & { close(): void }
97
+ session: AxonSessionT
98
+ bus: { onAny(handler: (type: string, data: unknown) => void): () => void }
99
+ engines?: unknown
100
+ blueprint: unknown
101
+ tier: "none" | "auto" | "container" | "hardened"
102
+ pid: number
103
+ stop(): Promise<void>
104
+ }>
105
+ }
106
+
107
+ export type InstanceSource =
108
+ /**
109
+ * An agent reached over a LINK — a real process, addressed by the six
110
+ * verbs and never by a handle.
111
+ *
112
+ * Named for HOW it is reached rather than who spawned it. An agent this
113
+ * process asked for and one adopted from a daemon are the same thing to
114
+ * every consumer: the link is the whole surface either way.
115
+ *
116
+ * This was one of THREE kinds. `local` meant an Axon() runtime sharing
117
+ * the caller's heap — no box around it, no policy enforceable against it —
118
+ * and it became unreachable when every spawn started taking the confined
119
+ * path. Deleting it took `isLocal` and `hasProject`'s two-kind widening
120
+ * with it: a union of one is a type, and three guards over it were three
121
+ * ways to ask a question with one answer.
122
+ */
123
+ | { kind: "linked"; project: ProjectT; agent: LinkedRuntime }
124
+ /**
125
+ * A deployment reached over `/_axon/*` — no project, no reload, no bus.
126
+ * Its events arrive on the mirrored session's stream.
127
+ */
128
+ | { kind: "remote"; target: RemoteTarget; agent: RemoteAgentHandle }
129
+
130
+ export type InstanceT = {
131
+ sessionId: string
132
+ parentSessionId: string | null
133
+ rootSessionId: string
134
+ depth: number
135
+ source: InstanceSource
136
+ }
137
+
138
+
139
+ /** Narrow to a linked instance — an agent in its own process on this machine. */
140
+ export function isLinked(instance: InstanceT): instance is InstanceT & { source: Extract<InstanceSource, { kind: "linked" }> } {
141
+ return instance.source.kind === "linked"
142
+ }
143
+
144
+
145
+ /** Narrow to an attached deployment. */
146
+ export function isRemote(instance: InstanceT): instance is InstanceT & { source: Extract<InstanceSource, { kind: "remote" }> } {
147
+ return instance.source.kind === "remote"
148
+ }
149
+
150
+ export type SpawnOpts = {
151
+ session?: string
152
+ /** Job directory this run answers, for correlation — see AgentOpts.job. */
153
+ job?: string
154
+ /** A local control channel the caller is listening on, published on the running record — see AgentOpts.control. */
155
+ control?: { port: number; token: string }
156
+ parentSessionId?: string
157
+ /** User spawns take attention; an agent-initiated spawn deliberately does not. */
158
+ focus?: boolean
159
+ /**
160
+ * Live boot progress, for a caller that shows one (the TUI's status line).
161
+ * A cold boot is seconds of `bun install` and looks hung without it.
162
+ * Observational only — see AgentOpts.onProgress.
163
+ */
164
+ onProgress?: (progress: BootProgress) => void
165
+ /** What each timed unit of the build cost — see AgentOpts.onTiming. */
166
+ onTiming?: (timing: UnitTiming) => void
167
+ }
168
+
169
+ type InstancesOpts = {
170
+ /**
171
+ * Who supervises a spawned agent.
172
+ *
173
+ * A SEAM, not the daemon package: the platform must not depend on the
174
+ * daemon (the daemon depends on the platform, and a cycle between them is
175
+ * the boundary being wrong). The caller supplies something that can boot a
176
+ * blueprint and hold the credential — `Axond().agents` today, and a socket
177
+ * client once the TUI stops hosting one.
178
+ *
179
+ * Optional: a Platform that never spawns needs none, and `spawn` is what
180
+ * refuses when it is absent — at the call that needs it, naming the fix.
181
+ */
182
+ daemon?: AgentSupervisor
183
+ store: StoreT
184
+ projects: ProjectsT
185
+ /** Owns every agent-reference form — path, profile name, registry package. */
186
+ resolve: ResolveT
187
+ cwd: string
188
+ cloud: AxonCloudClient
189
+ /** The host surface handed to every spawned capsule — supplied by Runtime(). */
190
+ host: AxonHost
191
+ /**
192
+ * The platform's policy decider. Bound per agent here, since a grant is
193
+ * written against an agent NAME and the capsule reports only the fn and
194
+ * its arguments. Absent = no decider, which the capsule treats as deny.
195
+ */
196
+ escalations?: EscalationsT
197
+ /**
198
+ * The control channel this PROCESS is serving, if it serves one.
199
+ *
200
+ * A thunk, not a value: the server binds a port, and construction here is
201
+ * wiring only — the surface that owns the channel (the TUI) starts it when
202
+ * it is ready and this reads whatever is live at spawn time. Headless
203
+ * callers (`axon run`) pass nothing and their records carry no port.
204
+ *
205
+ * Stamped onto EVERY instance this process spawns, deliberately: one
206
+ * process serves one channel, and every conversation inside it is
207
+ * reachable on that one port. Two records naming the same port is not
208
+ * duplication — `TuiSurface.focus(sessionId)` is precisely how a caller
209
+ * picks between the conversations behind it.
210
+ */
211
+ control?: () => { port: number; token: string } | null
212
+ }
213
+
214
+ /**
215
+ * Instances — the registry of running agents.
216
+ *
217
+ * Keyed by sessionId because the session IS the conversation's durable identity
218
+ * (the same project can run twice as two independent conversations). No shared
219
+ * state between instances: the whole point of the multi-instance model is that
220
+ * there is nothing to couple.
221
+ *
222
+ * Owns membership and focus, nothing else. What an agent may spawn (requests.ts)
223
+ * and what sessions exist on disk (sessions/) are separate concerns that read
224
+ * this registry rather than living inside it.
225
+ */
226
+ export function Instances(opts: InstancesOpts) {
227
+ const instances = new Map<string, InstanceT>()
228
+ const spawnListeners = new Set<(instance: InstanceT) => void>()
229
+ const stopListeners = new Set<(sessionId: string) => void>()
230
+ let focusedId: string | null = null
231
+
232
+ /**
233
+ * sessionId → a monotonic tick stamped every time an instance is focused.
234
+ *
235
+ * Registry state, not a property of an instance: "which of these did I look
236
+ * at last" is a fact about the set, and an instance handed to a caller has
237
+ * no business carrying it. Lets the agent list order by last-used — the
238
+ * behavior you want when ping-ponging between two conversations, where
239
+ * spawn order is the wrong answer after the first switch.
240
+ *
241
+ * A counter rather than Date.now(): two focuses inside the same millisecond
242
+ * must still order, and nothing here needs wall-clock meaning.
243
+ */
244
+ const focusOrder = new Map<string, number>()
245
+ let tick = 0
246
+
247
+ function stampFocus(sessionId: string): void {
248
+ focusedId = sessionId
249
+ focusOrder.set(sessionId, ++tick)
250
+ }
251
+
252
+ /**
253
+ * Resolve a target to a project.
254
+ *
255
+ * Delegates the string case to Resolve(), which owns every reference
256
+ * form — path, bare name under the active profile, and registry
257
+ * package (fetched and installed on a miss). One resolver, so a
258
+ * spawn and a script's Axon() agree on what "@axon/zeno" means.
259
+ */
260
+ async function resolve(target: ProjectT | string): Promise<ProjectT> {
261
+ if (typeof target !== "string") return target
262
+ const resolved = await opts.resolve.one(target)
263
+ return opts.projects.open(resolved.root)
264
+ }
265
+
266
+ /**
267
+ * Boot a project (or a named agent under the active profile) as a new
268
+ * instance and focus it. `session` resumes an existing on-disk session —
269
+ * spawning an already-running sessionId is refused: that conversation is
270
+ * live, focus it instead.
271
+ */
272
+ async function spawn(target: ProjectT | string, spawnOpts: SpawnOpts = {}): Promise<InstanceT> {
273
+ if (spawnOpts?.session && instances.has(spawnOpts.session)) {
274
+ throw err("SESSION_ALREADY_RUNNING", { context: { sessionId: spawnOpts.session } })
275
+ }
276
+
277
+ const parent = spawnOpts.parentSessionId ? instances.get(spawnOpts.parentSessionId) : undefined
278
+ if (spawnOpts.parentSessionId && !parent) {
279
+ throw err("PARENT_INSTANCE_NOT_RUNNING", { context: { sessionId: spawnOpts.parentSessionId } })
280
+ }
281
+
282
+ const project = await resolve(target)
283
+ // Read at spawn time, not at construction: the TUI starts serving after
284
+ // Platform() exists, so an instance booted later must still get the port.
285
+ const control = opts.control?.() ?? null
286
+ // No prepare() here: Agent() owns the whole pre-runtime sequence
287
+ // now, so it happens inside the build span that reports it. Three
288
+ // call sites used to run it by hand and a caller that forgot got
289
+ // NO_COGNET on first boot.
290
+ const agent = await Agent({
291
+ project: project,
292
+ ...(spawnOpts.job ? { job: spawnOpts.job } : {}),
293
+ ...(spawnOpts.control ? { control: spawnOpts.control } : {}),
294
+ /**
295
+ * AGENTS ARE PROCESSES.
296
+ *
297
+ * Every spawn takes the confined path: `Agent()` builds the
298
+ * blueprint and hands it here, and this boots a real process
299
+ * behind the link. There is no in-heap variant left to choose:
300
+ * `confined` is required, because a runtime in the caller's own
301
+ * heap has no box around it and no policy that can be enforced
302
+ * against it.
303
+ *
304
+ * The TIER still comes from policy: `isolation: "none"` spawns an
305
+ * unboxed process, `"auto"` builds a bwrap box. What changed is
306
+ * that "no box" no longer means "no boundary" — it is still a
307
+ * separate process reached by the six verbs, so the credential and
308
+ * the log stay on this side either way.
309
+ */
310
+ /**
311
+ * SUPERVISION IS THE DAEMON'S.
312
+ *
313
+ * This callback used to assemble the supervisor's services and
314
+ * spawn the box inline — the credential, the session log and the
315
+ * escalation decider all held in whichever process called `spawn`.
316
+ * That made an agent's lifetime and its controllability both
317
+ * properties of its launcher: close the terminal and the agent
318
+ * went with it, and one started headlessly could never be spoken
319
+ * to again.
320
+ *
321
+ * The daemon outlives terminals, so it holds them now. Everything
322
+ * ABOVE this line still happens here — resolve, prepare,
323
+ * blueprint.load(), the build spans — because that is the
324
+ * platform's work and needs the whole project stack. The platform
325
+ * builds; the daemon runs.
326
+ */
327
+ confined: async ({ blueprint, sessionId, rescan }) => {
328
+ if (!opts.daemon) {
329
+ throw err("AGENT_NO_SUPERVISOR", {
330
+ detail: "this platform was built without a supervisor, so it cannot boot an agent — construct it with `daemon`",
331
+ context: { agent: blueprint.agent?.name ?? project.name },
332
+ })
333
+ }
334
+
335
+ const live = await opts.daemon.supervise({
336
+ sessionId: sessionId,
337
+ blueprint: blueprint as never,
338
+ agent: blueprint.agent?.name ?? project.name,
339
+ projectRoot: project.root,
340
+ dataRoot: join(project.root, ".agent/data"),
341
+ // The ownership graph travels with the spawn: the daemon
342
+ // writes the record, so it needs what the record says.
343
+ parentSessionId: parent?.sessionId ?? null,
344
+ rootSessionId: parent?.rootSessionId ?? sessionId,
345
+ depth: parent ? parent.depth + 1 : 0,
346
+ ...(spawnOpts.job ? { job: spawnOpts.job } : {}),
347
+ ...(control ? { control: control } : {}),
348
+ })
349
+
350
+ /** The blueprint currently live — replaced by reload(). */
351
+ let current = blueprint
352
+
353
+ return {
354
+ kind: "linked",
355
+ sessionId: sessionId,
356
+ link: live.link,
357
+ session: live.session,
358
+ bus: live.bus,
359
+ ...(live.engines ? { engines: live.engines as never } : {}),
360
+ get blueprint() {
361
+ return current as never
362
+ },
363
+ tier: live.tier,
364
+ pid: live.pid,
365
+ /**
366
+ * A REAL reload: rescan HERE, then send the blueprint
367
+ * across. The daemon does not scan projects — it has no
368
+ * project stack and should not grow one — so the platform
369
+ * pushes the new blueprint rather than the daemon pulling
370
+ * it.
371
+ */
372
+ async reload(): Promise<void> {
373
+ current = await rescan()
374
+ await live.link.update(current as never)
375
+ },
376
+ async shutdown(): Promise<void> {
377
+ await live.stop()
378
+ },
379
+ } as never
380
+ },
381
+ cloud: opts.cloud,
382
+ store: opts.store,
383
+ cwd: opts.cwd,
384
+ host: opts.host,
385
+ // Bound to THIS agent's name, because a grant is written against
386
+ // one and the capsule only ever reports the fn and its arguments —
387
+ // it has no idea which agent it belongs to. Closed over here,
388
+ // where both the project and the decider are in scope.
389
+ ...(opts.escalations
390
+ ? {
391
+ // The session id is read at CALL time, not closed over:
392
+ // the agent that owns it does not exist yet at this point
393
+ // in construction, and a reload can replace the runtime
394
+ // underneath. Reading through the handle is what keeps a
395
+ // request naming the session it was actually raised in.
396
+ escalate: (call: EscalationCall) => opts.escalations!.decide(
397
+ { agent: project.name, sessionId: agent.sessionId },
398
+ call,
399
+ ),
400
+ }
401
+ : {}),
402
+ parentSessionId: parent?.sessionId ?? null,
403
+ ...(parent ? { rootSessionId: parent.rootSessionId } : {}),
404
+ depth: parent ? parent.depth + 1 : 0,
405
+ ...(spawnOpts?.session ? { session: spawnOpts.session } : {}),
406
+ ...(spawnOpts?.onProgress ? { onProgress: spawnOpts.onProgress } : {}),
407
+ ...(spawnOpts?.onTiming ? { onTiming: spawnOpts.onTiming } : {}),
408
+ ...(control ? { control } : {}),
409
+ })
410
+
411
+ const sessionId = agent.sessionId
412
+ const instance: InstanceT = {
413
+ sessionId: sessionId,
414
+ parentSessionId: parent?.sessionId ?? null,
415
+ rootSessionId: parent?.rootSessionId ?? sessionId,
416
+ depth: parent ? parent.depth + 1 : 0,
417
+ // Every spawn takes the confined path — `Agent()` calls
418
+ // bootLinked unconditionally — so there is one kind. The "local"
419
+ // branch was for an embedder building Agent() without a `confined`
420
+ // builder, which cannot exist now that one is required.
421
+ source: { kind: "linked" as const, project: project, agent: agent },
422
+ }
423
+ instances.set(instance.sessionId, instance)
424
+ if (spawnOpts.focus !== false) stampFocus(instance.sessionId)
425
+ for (const listener of spawnListeners) listener(instance)
426
+ return instance
427
+ }
428
+
429
+ /**
430
+ * Attach to a deployed agent as an instance and focus it.
431
+ *
432
+ * The remote counterpart of spawn(): the deployment is already running, so
433
+ * this binds to it rather than booting anything. attach() hydrates the
434
+ * session, so the returned instance has the agent's real history — a caller
435
+ * renders it exactly as it renders a local one.
436
+ *
437
+ * Re-attaching to a deployment already in the registry focuses the existing
438
+ * instance instead of opening a second binding to the same session. Two
439
+ * handles onto one remote session would both write to it, which breaks the
440
+ * one-session-one-writer rule the remote handle exists to hold.
441
+ */
442
+ async function attach(target: RemoteTarget): Promise<InstanceT> {
443
+ // Keyed on the URL, not the deploymentId: a dev server has no
444
+ // deploymentId, and the URL is what both kinds always have. Normalized
445
+ // so a trailing slash cannot open a second writer onto one session —
446
+ // the rule this guard exists to hold.
447
+ const url = normalizeUrl(target.url)
448
+ const existing = [...instances.values()].find(
449
+ item => item.source.kind === "remote" && normalizeUrl(item.source.target.url) === url,
450
+ )
451
+ if (existing) {
452
+ stampFocus(existing.sessionId)
453
+ return existing
454
+ }
455
+
456
+ // agentId drives connect-token minting, and is absent for a local dev
457
+ // server — where the connect gate is open because the agent is already
458
+ // inside its owner's trust boundary. Passing it through conditionally
459
+ // rather than branching: attaching is one operation either way.
460
+ const { axon, sessionId, agent, loaded, engine } = await opts.cloud.attach(url, {
461
+ ...(target.agentId ? { agentId: target.agentId } : {}),
462
+ })
463
+
464
+ const instance: InstanceT = {
465
+ sessionId: sessionId,
466
+ // A remote agent is always a root conversation: any agents it runs
467
+ // are its own concern, inside its own capsule.
468
+ parentSessionId: null,
469
+ rootSessionId: sessionId,
470
+ depth: 0,
471
+ source: {
472
+ kind: "remote",
473
+ // The handshake is the only thing that knows what a bare URL is
474
+ // running, so a caller that had no name gets one here rather
475
+ // than rendering a hostname where an identity belongs.
476
+ target: { ...target, url, name: target.name || agent || url, loaded, engine },
477
+ agent: axon,
478
+ },
479
+ }
480
+ instances.set(sessionId, instance)
481
+ stampFocus(sessionId)
482
+ for (const listener of spawnListeners) listener(instance)
483
+ return instance
484
+ }
485
+
486
+ /** Shut down one instance. Focus falls to the most recently USED survivor, or null. */
487
+ async function stop(sessionId: string): Promise<void> {
488
+ const owned = children(sessionId)
489
+ await Promise.allSettled(owned.map(child => stop(child.sessionId)))
490
+
491
+ const instance = instances.get(sessionId)
492
+ if (!instance) return
493
+ instances.delete(sessionId) // remove first — a failing shutdown() must not leave a caller thinking it's still safely running
494
+ focusOrder.delete(sessionId)
495
+ for (const listener of stopListeners) listener(sessionId)
496
+ if (focusedId === sessionId) {
497
+ // Where you were before this one, not whatever spawned last — after
498
+ // any switching at all those differ, and the spawn-order answer
499
+ // drops you somewhere you never asked for.
500
+ focusedId = byRecency()[0]?.sessionId ?? null
501
+ }
502
+ // A remote instance owns no runtime here — detaching is dropping the
503
+ // handle. The deployed agent keeps running; that is the point of a
504
+ // deployment, and stopping it is a control-plane action, not a close.
505
+ //
506
+ // Everything else DOES get shut down, linked included: it is a real
507
+ // process this supervisor started, and skipping it leaked an agent per
508
+ // stop — the exact orphan the exit handler exists to catch, arriving
509
+ // through the front door.
510
+ if (instance.source.kind !== "remote") await instance.source.agent.shutdown()
511
+ }
512
+
513
+ /**
514
+ * One canonical spelling per agent, so the attach guard cannot be defeated
515
+ * by a trailing slash or a capitalized host. Only the parts that are
516
+ * genuinely case-insensitive are lowered — a path can be case-sensitive,
517
+ * and folding it would merge two different agents behind one proxy.
518
+ */
519
+ function normalizeUrl(raw: string): string {
520
+ const trimmed = raw.trim().replace(/\/+$/, "")
521
+ try {
522
+ const parsed = new URL(trimmed)
523
+ const path = parsed.pathname.replace(/\/+$/, "")
524
+ return `${parsed.protocol.toLowerCase()}//${parsed.host.toLowerCase()}${path}`
525
+ } catch {
526
+ // Not parseable as a URL — attach will fail on it with a real
527
+ // network error naming the address, which beats this inventing a
528
+ // complaint about a string it does not understand.
529
+ return trimmed
530
+ }
531
+ }
532
+
533
+ function children(parentSessionId: string): InstanceT[] {
534
+ return [...instances.values()].filter(instance => instance.parentSessionId === parentSessionId)
535
+ }
536
+
537
+ /**
538
+ * Every instance, most recently focused first. An instance spawned with
539
+ * `focus: false` (an agent-initiated subagent) has never been stamped, so it
540
+ * sorts last — correct: the user has never looked at it.
541
+ */
542
+ function byRecency(): InstanceT[] {
543
+ return [...instances.values()].sort(
544
+ (a, b) => (focusOrder.get(b.sessionId) ?? 0) - (focusOrder.get(a.sessionId) ?? 0),
545
+ )
546
+ }
547
+
548
+ function descendants(rootSessionId: string): InstanceT[] {
549
+ return [...instances.values()]
550
+ .filter(instance => instance.rootSessionId === rootSessionId && instance.sessionId !== rootSessionId)
551
+ }
552
+
553
+ function focused(): InstanceT | null {
554
+ return focusedId ? instances.get(focusedId) ?? null : null
555
+ }
556
+
557
+ return {
558
+ resolve: resolve,
559
+ spawn: spawn,
560
+ attach: attach,
561
+ stop: stop,
562
+ children: children,
563
+ descendants: descendants,
564
+ focused: focused,
565
+
566
+ list(): InstanceT[] {
567
+ return [...instances.values()]
568
+ },
569
+
570
+ /** Every instance, most recently focused first — what an agent list orders by. */
571
+ recent: byRecency,
572
+
573
+ get(sessionId: string): InstanceT | null {
574
+ return instances.get(sessionId) ?? null
575
+ },
576
+
577
+ has(sessionId: string): boolean {
578
+ return instances.has(sessionId)
579
+ },
580
+
581
+ /** Point the host's main view at a running instance. Pure selection — touches no runtime. */
582
+ focus(sessionId: string): void {
583
+ if (!instances.has(sessionId)) throw err("SESSION_NOT_RUNNING", { context: { sessionId } })
584
+ stampFocus(sessionId)
585
+ },
586
+
587
+ /** Shut down every instance — the exit path. Failures don't stop the sweep. */
588
+ async shutdown(): Promise<void> {
589
+ await Promise.allSettled([...instances.keys()].map(id => stop(id)))
590
+ },
591
+
592
+ onSpawn(listener: (instance: InstanceT) => void): () => void {
593
+ spawnListeners.add(listener)
594
+ return () => spawnListeners.delete(listener)
595
+ },
596
+
597
+ onStop(listener: (sessionId: string) => void): () => void {
598
+ stopListeners.add(listener)
599
+ return () => stopListeners.delete(listener)
600
+ },
601
+ }
602
+ }
603
+
604
+ export type InstancesT = ReturnType<typeof Instances>