@arcforge/platform 2.0.169 → 2.0.171

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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arcforge/platform",
3
- "version": "2.0.169",
3
+ "version": "2.0.171",
4
4
  "description": "The Axon developer platform — headless project discovery, blueprint scanning, typegen, agent lifecycle, registry, benches and tests. Shared by the CLI/TUI and the Fleet extension.",
5
5
  "type": "module",
6
6
  "private": false,
@@ -44,20 +44,20 @@
44
44
  "deploy": "echo \"This package is published ONLY by apps/tui/scripts/release.ts, which pins workspace:* deps to concrete versions first. Publishing it directly ships an unresolvable dependency.\" && exit 1"
45
45
  },
46
46
  "dependencies": {
47
- "@arcforge/session": "2.0.169",
48
- "@arcforge/engines": "2.0.169",
49
- "@arcforge/err": "2.0.169",
50
- "@arcforge/types": "2.0.169",
51
- "@arcforge/cloud": "2.0.169",
52
- "@arcforge/capsule": "2.0.169",
53
- "@arcforge/core": "2.0.169",
54
- "@arcforge/vstr": "2.0.169",
47
+ "@arcforge/session": "2.0.171",
48
+ "@arcforge/engines": "2.0.171",
49
+ "@arcforge/err": "2.0.171",
50
+ "@arcforge/types": "2.0.171",
51
+ "@arcforge/cloud": "2.0.171",
52
+ "@arcforge/capsule": "2.0.171",
53
+ "@arcforge/core": "2.0.171",
54
+ "@arcforge/vstr": "2.0.171",
55
55
  "fft.js": "^4.0.4",
56
56
  "h3": "^1.15.11",
57
57
  "semver": "^7.7.4",
58
58
  "sharp": "^0.35.3",
59
59
  "typescript": "5.9.2",
60
- "@arcforge/link": "2.0.169"
60
+ "@arcforge/link": "2.0.171"
61
61
  },
62
62
  "devDependencies": {
63
63
  "@arcforge/air": "2.0.167",
@@ -74,6 +74,22 @@ export type RemoteTarget = {
74
74
  * this against the daemon's own return would invert it.
75
75
  */
76
76
  export type AgentSupervisor = {
77
+ /**
78
+ * What the supervisor knows about an agent it did not necessarily spawn
79
+ * for THIS process — its place in the ownership graph.
80
+ *
81
+ * Needed because a parent is not always a local instance. Agent code that
82
+ * shells out (`axon @x -p "…" --parent <id>`) runs in its own process, so
83
+ * the CLI serving that spawn has an empty registry and cannot see the
84
+ * agent that asked for it. The daemon can: it is the only thing that sees
85
+ * every spawn, which is exactly why it writes the records.
86
+ *
87
+ * Null for an id the supervisor has never heard of — a caller passing a
88
+ * stale or invented parent gets a refusal rather than a silently rooted
89
+ * child.
90
+ */
91
+ lineage?(sessionId: string): { rootSessionId: string; depth: number } | null
92
+
77
93
  supervise(input: {
78
94
  sessionId: string
79
95
  blueprint: unknown
@@ -274,11 +290,36 @@ export function Instances(opts: InstancesOpts) {
274
290
  throw err("SESSION_ALREADY_RUNNING", { context: { sessionId: spawnOpts.session } })
275
291
  }
276
292
 
277
- const parent = spawnOpts.parentSessionId ? instances.get(spawnOpts.parentSessionId) : undefined
278
- if (spawnOpts.parentSessionId && !parent) {
293
+ /**
294
+ * The parent, which may not be an instance THIS process holds.
295
+ *
296
+ * A subagent spawned in-heap has its parent right here. One spawned by
297
+ * agent code shelling out to the CLI does not: that runs in its own
298
+ * process, whose registry is empty, and the parent is alive in a
299
+ * different one entirely.
300
+ *
301
+ * So the local registry is asked first and the SUPERVISOR second. The
302
+ * daemon sees every spawn — it is what writes the records the tree is
303
+ * read from — and can answer for an agent this process never met.
304
+ * Without the fallback, `--parent` could only ever name something in
305
+ * the same heap, which is precisely the case that never happens.
306
+ */
307
+ const local = spawnOpts.parentSessionId ? instances.get(spawnOpts.parentSessionId) : undefined
308
+ const remote = !local && spawnOpts.parentSessionId
309
+ ? opts.daemon?.lineage?.(spawnOpts.parentSessionId) ?? null
310
+ : null
311
+
312
+ if (spawnOpts.parentSessionId && !local && !remote) {
279
313
  throw err("PARENT_INSTANCE_NOT_RUNNING", { context: { sessionId: spawnOpts.parentSessionId } })
280
314
  }
281
315
 
316
+ /** The parentage this spawn inherits, from whichever source knew it. */
317
+ const lineage = local
318
+ ? { parentSessionId: local.sessionId, rootSessionId: local.rootSessionId, depth: local.depth + 1 }
319
+ : remote
320
+ ? { parentSessionId: spawnOpts.parentSessionId!, rootSessionId: remote.rootSessionId, depth: remote.depth + 1 }
321
+ : null
322
+
282
323
  const project = await resolve(target)
283
324
  // Read at spawn time, not at construction: the TUI starts serving after
284
325
  // Platform() exists, so an instance booted later must still get the port.
@@ -340,9 +381,9 @@ export function Instances(opts: InstancesOpts) {
340
381
  dataRoot: join(project.root, ".agent/data"),
341
382
  // The ownership graph travels with the spawn: the daemon
342
383
  // 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,
384
+ parentSessionId: lineage?.parentSessionId ?? null,
385
+ rootSessionId: lineage?.rootSessionId ?? sessionId,
386
+ depth: lineage?.depth ?? 0,
346
387
  ...(spawnOpts.job ? { job: spawnOpts.job } : {}),
347
388
  ...(control ? { control: control } : {}),
348
389
  })
@@ -436,9 +477,9 @@ export function Instances(opts: InstancesOpts) {
436
477
  ),
437
478
  }
438
479
  : {}),
439
- parentSessionId: parent?.sessionId ?? null,
440
- ...(parent ? { rootSessionId: parent.rootSessionId } : {}),
441
- depth: parent ? parent.depth + 1 : 0,
480
+ parentSessionId: lineage?.parentSessionId ?? null,
481
+ ...(lineage ? { rootSessionId: lineage.rootSessionId } : {}),
482
+ depth: lineage?.depth ?? 0,
442
483
  ...(spawnOpts?.session ? { session: spawnOpts.session } : {}),
443
484
  ...(spawnOpts?.onProgress ? { onProgress: spawnOpts.onProgress } : {}),
444
485
  ...(spawnOpts?.onTiming ? { onTiming: spawnOpts.onTiming } : {}),
@@ -448,9 +489,9 @@ export function Instances(opts: InstancesOpts) {
448
489
  const sessionId = agent.sessionId
449
490
  const instance: InstanceT = {
450
491
  sessionId: sessionId,
451
- parentSessionId: parent?.sessionId ?? null,
452
- rootSessionId: parent?.rootSessionId ?? sessionId,
453
- depth: parent ? parent.depth + 1 : 0,
492
+ parentSessionId: lineage?.parentSessionId ?? null,
493
+ rootSessionId: lineage?.rootSessionId ?? sessionId,
494
+ depth: lineage?.depth ?? 0,
454
495
  // Every spawn takes the confined path — `Agent()` calls
455
496
  // bootLinked unconditionally — so there is one kind. The "local"
456
497
  // branch was for an embedder building Agent() without a `confined`
package/src/index.ts CHANGED
@@ -6,6 +6,11 @@ export type { FileEntry, FilesT } from "./services/files"
6
6
  // The process tree every surface renders — folded from the session log, so a
7
7
  // local runtime and an attached deployment read identically.
8
8
  export { procTree, appendOutput, type ProcNode } from "./procs"
9
+ // The live instance forest — agents, their subagents, and each one's procs as
10
+ // one tree. The TUI's `/` palette and the Fleet extension's Instances view
11
+ // both render it; the ordering rules are subtle enough that a second
12
+ // implementation would drift rather than differ.
13
+ export { forest, childrenOf, flatten, type ForestAgent, type ForestNode, type Indented } from "./procs"
9
14
  // The supervisor ↔ agent transport. Moves bytes; the verbs it carries are
10
15
  // SupervisorToAgent / AgentToSupervisor in @arcforge/types.
11
16
  export { serve, connect, Channel, type LinkChannels, type SocketPaths, type ChannelT } from "./link"
@@ -0,0 +1,187 @@
1
+ import type { ProcNode } from "./tree"
2
+
3
+ /**
4
+ * The live process forest — agents, the subagents they spawned, and the
5
+ * processes each of those is running, as one tree.
6
+ *
7
+ * ── Why this is shared ──────────────────────────────────────────────────────
8
+ *
9
+ * A subagent is spawned by shelling out to `axon run --parent <sessionId>`, so
10
+ * one spawn produces two rows at two layers: a proc on the parent's log (the
11
+ * `axon` command itself) and an independent agent instance carrying
12
+ * `parentSessionId`. Joining those two structures back into one tree is the
13
+ * same problem for every surface that draws it — the TUI's `/` palette and the
14
+ * Fleet extension's Instances view — and the ordering rules below are subtle
15
+ * enough that a second implementation would drift rather than merely differ.
16
+ *
17
+ * ── Why it is generic ───────────────────────────────────────────────────────
18
+ *
19
+ * Surfaces disagree about what an agent IS. The TUI's InstanceView carries
20
+ * focus and tombstones; the extension's AxonInstance carries a pid and a
21
+ * project root. Neither is wrong, and widening one to cover both would put
22
+ * `focused` on a record that cannot be focused. The forest needs exactly three
23
+ * facts from an agent — its id, its parent, and its procs — so it asks for
24
+ * those and stays ignorant of the rest.
25
+ *
26
+ * ── Why the forest, not the flattened list ──────────────────────────────────
27
+ *
28
+ * A terminal draws an indented list; VS Code's TreeDataProvider asks for one
29
+ * node's children at a time and owns expansion itself. Sharing the flattened
30
+ * list would force the extension to flatten and then re-derive parentage from
31
+ * indent, which is the same information twice with a chance to disagree.
32
+ * `forest()` returns the structure; `flatten()` is for surfaces that draw
33
+ * indentation themselves.
34
+ */
35
+
36
+ /** The three facts the forest needs from an agent. Anything else is the surface's business. */
37
+ export type ForestAgent = {
38
+ sessionId: string
39
+ /** Null or absent for a user-owned root; a spawning agent's id otherwise. */
40
+ parentSessionId?: string | null
41
+ /** What this agent has spawned, as `procTree()` folded it from its own log. */
42
+ processes?: readonly ProcNode[]
43
+ }
44
+
45
+ /**
46
+ * One agent and everything hanging under it.
47
+ *
48
+ * `subagents` and `procs` stay separate rather than being concatenated into
49
+ * one `children` array: they are different kinds of thing with different
50
+ * affordances (a conversation can be focused, a `sleep 3600` cannot), and a
51
+ * surface that had to re-split them would be discriminating on a union we
52
+ * already knew the answer to. Rendering order across the two is fixed —
53
+ * subagents first, see `childrenOf` — so the split costs nothing.
54
+ */
55
+ export type ForestNode<Agent extends ForestAgent> = {
56
+ agent: Agent
57
+ /** Instances this one spawned, each with its own subtree. */
58
+ subagents: ForestNode<Agent>[]
59
+ /** Processes this agent spawned directly, in spawn order. */
60
+ procs: readonly ProcNode[]
61
+ }
62
+
63
+ /**
64
+ * Build the forest from a flat list of live agents.
65
+ *
66
+ * Roots are returned in the order given, except as reordered by `pinned` —
67
+ * a list navigated with a cursor must not reorder under the hand mid-preview,
68
+ * so a surface that previews captures an order once and passes it here.
69
+ *
70
+ * Only ROOTS are pinned. A child always sits under its parent, so pinning a
71
+ * focused subagent to the top would have to tear it out of the tree it belongs
72
+ * to; its root rises instead, which brings it along and keeps the shape.
73
+ */
74
+ export function forest<Agent extends ForestAgent>(
75
+ agents: readonly Agent[],
76
+ opts?: {
77
+ /** Session ids in preferred root order. Ids not listed keep list order, after those that are. */
78
+ pinned?: readonly string[]
79
+ },
80
+ ): ForestNode<Agent>[] {
81
+ const byId = new Map(agents.map(agent => [agent.sessionId, agent]))
82
+
83
+ const childrenOf = new Map<string, Agent[]>()
84
+ const roots: Agent[] = []
85
+ for (const agent of agents) {
86
+ // A parent that is gone (exited and pruned) makes this a root: it has
87
+ // to render somewhere, and hanging it off a row that does not exist is
88
+ // the one option that cannot work.
89
+ const parentId = agent.parentSessionId
90
+ const parent = parentId ? byId.get(parentId) : undefined
91
+ if (!parent) {
92
+ roots.push(agent)
93
+ continue
94
+ }
95
+ const siblings = childrenOf.get(parent.sessionId)
96
+ if (siblings) siblings.push(agent)
97
+ else childrenOf.set(parent.sessionId, [agent])
98
+ }
99
+
100
+ const order = new Map((opts?.pinned ?? []).map((id, index) => [id, index]))
101
+ const rank = (agent: Agent): number => order.get(agent.sessionId) ?? Number.MAX_SAFE_INTEGER
102
+ roots.sort((left, right) => rank(left) - rank(right))
103
+
104
+ // Cycle guard. Parentage is stamped at spawn and never rewritten, so a
105
+ // cycle should be impossible — but if one existed, every agent in it would
106
+ // have a visible parent, none would become a root, and they would vanish
107
+ // from the view while still running. An unreachable running agent is
108
+ // strictly worse than an oddly-drawn one.
109
+ const seen = new Set<string>()
110
+ const build = (agent: Agent): ForestNode<Agent> | null => {
111
+ if (seen.has(agent.sessionId)) return null
112
+ seen.add(agent.sessionId)
113
+ return {
114
+ agent,
115
+ subagents: (childrenOf.get(agent.sessionId) ?? [])
116
+ .map(build)
117
+ .filter((node): node is ForestNode<Agent> => node !== null),
118
+ procs: agent.processes ?? [],
119
+ }
120
+ }
121
+
122
+ const built = roots.map(build).filter((node): node is ForestNode<Agent> => node !== null)
123
+
124
+ // Anything the walk never reached — only possible inside a cycle — renders
125
+ // flat at the root rather than not at all.
126
+ for (const agent of agents) {
127
+ if (seen.has(agent.sessionId)) continue
128
+ seen.add(agent.sessionId)
129
+ built.push({ agent, subagents: [], procs: agent.processes ?? [] })
130
+ }
131
+ return built
132
+ }
133
+
134
+ /**
135
+ * A node's children in render order: subagents, then its own processes.
136
+ *
137
+ * A conversation is a bigger thing than a shell command, and a burst of
138
+ * short-lived `run` rows must not push a subagent off the visible window.
139
+ *
140
+ * This is the one place the two child kinds are interleaved, so a surface that
141
+ * asks for children lazily (VS Code) and one that flattens (a terminal) cannot
142
+ * disagree about the order.
143
+ */
144
+ export function childrenOf<Agent extends ForestAgent>(
145
+ node: ForestNode<Agent>,
146
+ ): ({ kind: "agent"; node: ForestNode<Agent> } | { kind: "proc"; proc: ProcNode })[] {
147
+ return [
148
+ ...node.subagents.map(child => ({ kind: "agent" as const, node: child })),
149
+ ...node.procs.map(proc => ({ kind: "proc" as const, proc })),
150
+ ]
151
+ }
152
+
153
+ /** Where a row sits in the drawn tree — for surfaces that render indentation themselves. */
154
+ export type Indented = { indent: number; last: boolean }
155
+
156
+ /**
157
+ * Flatten the forest into display order, stamping indent and last-child.
158
+ *
159
+ * `indent` is computed HERE rather than read off the record. An agent's
160
+ * `depth` is its true depth in the runtime forest, which is not the same as
161
+ * its indent: a subagent whose parent has already exited and been pruned would
162
+ * render indented under nothing. Deriving it from the rendered ancestry keeps
163
+ * the drawing honest about what is actually on screen.
164
+ */
165
+ export function flatten<Agent extends ForestAgent>(
166
+ nodes: readonly ForestNode<Agent>[],
167
+ ): ({ kind: "agent"; agent: Agent } & Indented | { kind: "proc"; proc: ProcNode; ownerSessionId: string } & Indented)[] {
168
+ const rows: ReturnType<typeof flatten<Agent>> = []
169
+
170
+ const walk = (node: ForestNode<Agent>, indent: number, last: boolean): void => {
171
+ rows.push({ kind: "agent", agent: node.agent, indent, last })
172
+ const children = childrenOf(node)
173
+ children.forEach((child, index) => {
174
+ const isLast = index === children.length - 1
175
+ if (child.kind === "agent") walk(child.node, indent + 1, isLast)
176
+ else rows.push({
177
+ kind: "proc",
178
+ proc: child.proc,
179
+ ownerSessionId: node.agent.sessionId,
180
+ indent: indent + 1,
181
+ last: isLast,
182
+ })
183
+ })
184
+ }
185
+ nodes.forEach((node, index) => walk(node, 0, index === nodes.length - 1))
186
+ return rows
187
+ }
@@ -13,3 +13,8 @@
13
13
  * agent boundary moves out to the whole process.
14
14
  */
15
15
  export { procTree, appendOutput, type ProcNode, type ProcLogEvent } from "./tree"
16
+ // The forest those trees hang in: agents, their subagents, and each one's
17
+ // procs as a single structure. Shared because a subagent spawn produces a row
18
+ // on two layers at once (a proc on the parent's log, an instance on the
19
+ // daemon) and rejoining them is the same problem for every surface.
20
+ export { forest, childrenOf, flatten, type ForestAgent, type ForestNode, type Indented } from "./forest"