@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,233 @@
1
+ import type { AxonHost, AxonT } from "@arcforge/core"
2
+ import type { AxonBlueprint } from "@arcforge/types"
3
+ import type { AxonSessionT } from "@arcforge/session"
4
+ import type { AxonCloudClient } from "@arcforge/cloud"
5
+ import type { StoreT } from "../../services/store"
6
+ import type { ProjectT, ProjectsT } from "../project"
7
+ import type { AgentT } from "./agent"
8
+ import { type AgentSupervisor, Instances, type InstanceT } from "./instances"
9
+ import { Resolve } from "./resolve"
10
+ import { Requests } from "./requests"
11
+ import { Escalations } from "./escalations"
12
+ import { Sessions } from "./sessions"
13
+ import { Zeno } from "./zeno"
14
+
15
+ type RuntimeOpts = {
16
+ /**
17
+ * Who supervises a spawned agent.
18
+ *
19
+ * Threaded from the top because only the process root knows which daemon
20
+ * it is talking to — a local `Axond()`, or a socket client pointed at one
21
+ * that is already running. Constructing one here would give every
22
+ * Runtime() its own supervisor and defeat the point.
23
+ *
24
+ * Optional: see PlatformOpts.daemon. `spawn` refuses without it.
25
+ */
26
+ daemon?: AgentSupervisor
27
+ store: StoreT
28
+ projects: ProjectsT
29
+ /** Platform invocation directory inherited by every spawned capsule. */
30
+ cwd: string
31
+ /** The platform's authenticated cloud client, handed to every spawned agent. */
32
+ cloud: AxonCloudClient
33
+ /** Fetches and prepares a published artifact — how zeno arrives. */
34
+ clone: (ref: string, cwd: string, options?: { dir?: string }) => Promise<{ root: string }>
35
+ /** This process's control channel, if it serves one — see InstancesOpts.control. */
36
+ control?: () => { port: number; token: string } | null
37
+ }
38
+
39
+ /**
40
+ * Runtime — every agent running on this machine, and what the host addresses.
41
+ *
42
+ * Composition only. The concerns underneath it:
43
+ * instances — the registry: spawn, attach, stop, focus, membership
44
+ * requests — the host surface a running agent calls into, and its limits
45
+ * sessions — the resumable conversations on disk
46
+ * zeno — the default agent, guaranteed to exist
47
+ *
48
+ * The surface below is deliberately flat and unchanged from the Agents() it
49
+ * replaced: consumers (the TUI's composables, the CLI) address instances by
50
+ * sessionId and read focused projections, and none of them should have to learn
51
+ * a new shape because the implementation grew leaves.
52
+ */
53
+ export function Runtime(opts: RuntimeOpts) {
54
+ // instances needs a host to hand every capsule; requests needs the registry
55
+ // to spawn into. The host closes over `requests` rather than being passed a
56
+ // value, so neither has to exist before the other — construction stays pure
57
+ // wiring, and nothing here calls anything.
58
+ // One resolver for every agent reference in this process — a spawn, a
59
+ // script's Axon(), and a fleet member all agree on what a string means.
60
+ const resolve = Resolve({ store: opts.store, cwd: opts.cwd })
61
+
62
+ const escalations = Escalations({ store: opts.store })
63
+
64
+ const instances = Instances({
65
+ ...(opts.daemon ? { daemon: opts.daemon } : {}),
66
+ store: opts.store,
67
+ projects: opts.projects,
68
+ resolve: resolve,
69
+ cwd: opts.cwd,
70
+ cloud: opts.cloud,
71
+ host: { call: input => requests.call(input) },
72
+ escalations: escalations,
73
+ ...(opts.control ? { control: opts.control } : {}),
74
+ })
75
+
76
+ const requests = Requests({ instances: instances })
77
+ const sessions = Sessions({ store: opts.store, isRunning: id => instances.has(id) })
78
+ const zeno = Zeno({ store: opts.store, projects: opts.projects, clone: opts.clone })
79
+
80
+ return {
81
+ /**
82
+ * A target to a project handle: a path, or a bare name under the active
83
+ * profile. Exposed because callers that do not spawn — a headless
84
+ * `axon run` — still need to name an agent rather than infer it from cwd.
85
+ */
86
+ resolve: instances.resolve,
87
+
88
+ /**
89
+ * The host surface a running agent calls into — one agent asking the
90
+ * platform to run work on another. Exposed because it is a real part of
91
+ * what a runtime provides, and because its limits (depth, fan-out,
92
+ * total descendants) are the only guard against an agent spawning
93
+ * without bound: they need to be reachable to be verified.
94
+ */
95
+ host: requests,
96
+
97
+ /**
98
+ * The policy decider — where a surface registers to answer "may I?".
99
+ *
100
+ * Exposed because WHICH surface answers is not this module's business:
101
+ * the TUI attaches when it boots, the CLI may attach for one command,
102
+ * and a headless run attaches nothing at all. Each is a client of the
103
+ * same store, so an escalation approved in one is visible in the rest.
104
+ */
105
+ escalations: escalations,
106
+
107
+
108
+ spawn: instances.spawn,
109
+ attach: instances.attach,
110
+ focus: instances.focus,
111
+ stop: instances.stop,
112
+ shutdown: instances.shutdown,
113
+ children: instances.children,
114
+ onSpawn: instances.onSpawn,
115
+ onStop: instances.onStop,
116
+
117
+ /** Every running instance, spawn order. */
118
+ list: instances.list,
119
+
120
+ /** Every running instance, most recently focused first. */
121
+ recent: instances.recent,
122
+
123
+ get(sessionId: string): InstanceT | null {
124
+ return instances.get(sessionId)
125
+ },
126
+
127
+ /** Every on-disk session across the active profile's agents, newest first. */
128
+ sessions(): ReturnType<typeof sessions.list> {
129
+ return sessions.list()
130
+ },
131
+
132
+ /**
133
+ * The session store itself — fork, rename, list.
134
+ *
135
+ * Exposed alongside `sessions()` rather than replacing it: that method
136
+ * is the hot read every UI does, and dozens of call sites spell it. The
137
+ * handle is for the verbs that act on ONE log, which no caller needed
138
+ * until forking existed.
139
+ */
140
+ get history(): typeof sessions {
141
+ return sessions
142
+ },
143
+
144
+ /**
145
+ * The default agent — always present, so the TUI always has somewhere
146
+ * to send a first message. An ordinary project once scaffolded.
147
+ */
148
+ zeno: zeno,
149
+
150
+ /** The focused instance, or null when nothing is running. */
151
+ get focused(): InstanceT | null {
152
+ return instances.focused()
153
+ },
154
+
155
+ // ── focused projections — what the host's main view addresses ───────
156
+
157
+ /**
158
+ * The focused agent handle, whichever kind it is.
159
+ *
160
+ * `AgentT` is the UNION now, and both variants carry the lifecycle
161
+ * verbs every caller here actually wants — `reload`, `shutdown`,
162
+ * `sessionId`. Returning null for a linked agent was reading the old
163
+ * meaning of the type into the new one: it made `agents.current`
164
+ * null for every agent the platform spawns, since spawning produces
165
+ * linked ones.
166
+ *
167
+ * A caller needing an in-heap ORGAN (`current.axon`, `current.kernel`)
168
+ * narrows on `kind === "process"` and gets a compile error if it
169
+ * forgets — which is the whole reason the union is discriminated.
170
+ * Null still means "nothing focused, or it is a deployment".
171
+ */
172
+ get current(): AgentT | null {
173
+ const instance = instances.focused()
174
+ if (!instance || instance.source.kind === "remote") return null
175
+ return instance.source.agent
176
+ },
177
+
178
+ /**
179
+ * The project backing the focused instance.
180
+ *
181
+ * BOTH local kinds have one: a linked agent runs from source on this
182
+ * machine, it merely runs in its own process. Only a deployment has no
183
+ * project — it has an address instead.
184
+ *
185
+ * This checked `kind === "local"` and so went blank the moment agents
186
+ * became processes, taking the header's `home` row with it. The
187
+ * question a caller is asking here is "is there a directory", not "is
188
+ * the runtime in my heap".
189
+ */
190
+ get project(): ProjectT | null {
191
+ const instance = instances.focused()
192
+ if (!instance || instance.source.kind === "remote") return null
193
+ return instance.source.project
194
+ },
195
+
196
+ get active(): boolean {
197
+ return instances.focused() !== null
198
+ },
199
+
200
+ /**
201
+ * The focused agent's BLUEPRINT — what it is, however it runs.
202
+ *
203
+ * Separate from `runtime` because it is the one thing every surface
204
+ * needs and the boundary does not hide: the supervisor prepares the
205
+ * blueprint and holds it. A header rendering the agent's name, its
206
+ * home and what it is carrying reads this, rather than reaching
207
+ * across the link for facts this side already wrote.
208
+ *
209
+ * Null only for a deployment, which genuinely has no local project.
210
+ */
211
+ get blueprint(): AxonBlueprint | null {
212
+ const instance = instances.focused()
213
+ if (!instance || instance.source.kind === "remote") return null
214
+ return instance.source.agent.blueprint
215
+ },
216
+
217
+ /**
218
+ * The focused agent's SESSION — the durable record, however it runs.
219
+ *
220
+ * Held by the SUPERVISOR — the agent appends through commit and can
221
+ * never rewrite it — so every log projection reads the same record
222
+ * the agent is writing into.
223
+ */
224
+ get session(): AxonSessionT | null {
225
+ const instance = instances.focused()
226
+ if (!instance || instance.source.kind === "remote") return null
227
+ return instance.source.agent.session
228
+ },
229
+
230
+ }
231
+ }
232
+
233
+ export type RuntimeT = ReturnType<typeof Runtime>
@@ -0,0 +1,5 @@
1
+ // sessions — the resumable conversations on disk.
2
+ // Sessions() is the module's single entry point.
3
+
4
+ export { Sessions, type SessionsT } from "./sessions"
5
+ export { sessionHasEntries, sessionHead, isListableSession, type SessionRecord, type SessionHead } from "./record"
@@ -0,0 +1,145 @@
1
+ import { closeSync, openSync, readSync } from "node:fs"
2
+ import { ENTRY_EVENT_PREFIXES } from "@arcforge/types"
3
+
4
+ /** One resumable session on disk — the durable record of a past (or current) conversation. */
5
+ export type SessionRecord = {
6
+ sessionId: string
7
+ /** the agent project's name — where sessions/<id>.jsonl lives */
8
+ agent: string
9
+ /** absolute path to the session's <id>.jsonl — read directly to preview without booting */
10
+ filePath: string
11
+ /** last write to the log — orders "most recent conversation first" */
12
+ modifiedAt: number
13
+ /** size of the log on disk, in bytes — a rough proxy for how much conversation happened */
14
+ sizeBytes: number
15
+ /** a live instance is running over this log right now */
16
+ running: boolean
17
+ /** true when the log contains at least one user/agent/action timeline entry */
18
+ hasEntries: boolean
19
+ /**
20
+ * The name the user gave this conversation, from its header. Null when
21
+ * unnamed, which is almost all of them — a title is opt-in.
22
+ */
23
+ title: string | null
24
+ /**
25
+ * The session this one was forked from, or null for an ordinary session.
26
+ *
27
+ * Written into the header by `fork()` and never by the runtime, so it is
28
+ * recorded lineage rather than an inference. This is what lets `^` render
29
+ * history as a TREE — the parent relation forks branch along, which is a
30
+ * different relation from the one sub-agents nest along in `/`.
31
+ */
32
+ forkedFrom: string | null
33
+ }
34
+
35
+ /** What the listing needs from a session's header line. */
36
+ export type SessionHead = {
37
+ title: string | null
38
+ forkedFrom: string | null
39
+ }
40
+
41
+ /**
42
+ * The listable fields of line 1, without reading the rest of the file.
43
+ *
44
+ * A session log can be megabytes and this runs once per session on every
45
+ * listing, so it reads a small prefix rather than the whole file. The header is
46
+ * always line 1 (see @arcforge/session's home.ts), so a prefix is sufficient by
47
+ * construction rather than by luck.
48
+ *
49
+ * One function for both fields rather than one per field: they come off the
50
+ * same parsed object, and a second reader would open, read and JSON-parse the
51
+ * same bytes again for every session on every listing.
52
+ */
53
+ export function sessionHead(file: string): SessionHead {
54
+ const fd = openSync(file, "r")
55
+ const buffer = Buffer.allocUnsafe(8 * 1024)
56
+ try {
57
+ const bytes = readSync(fd, buffer, 0, buffer.length, 0)
58
+ if (bytes === 0) return NO_HEAD
59
+ const chunk = buffer.toString("utf-8", 0, bytes)
60
+ const newline = chunk.indexOf("\n")
61
+ if (newline < 0) return NO_HEAD
62
+ const head = JSON.parse(chunk.slice(0, newline)) as {
63
+ type?: string
64
+ title?: unknown
65
+ forkedFrom?: { sessionId?: unknown }
66
+ }
67
+ if (head.type !== "session:header") return NO_HEAD
68
+ return {
69
+ title: typeof head.title === "string" && head.title.length > 0 ? head.title : null,
70
+ forkedFrom: typeof head.forkedFrom?.sessionId === "string" ? head.forkedFrom.sessionId : null,
71
+ }
72
+ } catch {
73
+ // A header that is absent, truncated or not JSON is not an error here:
74
+ // the session is still listable and resumable, it simply has no name
75
+ // and no recorded lineage.
76
+ return NO_HEAD
77
+ } finally {
78
+ closeSync(fd)
79
+ }
80
+ }
81
+
82
+ const NO_HEAD: SessionHead = { title: null, forkedFrom: null }
83
+
84
+ /**
85
+ * The byte patterns that prove a log holds a real timeline entry.
86
+ *
87
+ * DERIVED from `ENTRY_EVENT_PREFIXES` rather than written out, because that
88
+ * constant is the single registry of which event families may appear in a
89
+ * session log, and it says so: anything answering "is this a log entry?"
90
+ * derives from it, never from its own prefix sniff.
91
+ *
92
+ * This list WAS written out by hand, and drifted exactly the way that rule
93
+ * predicts. `axon:agent:done` was added to the registry and not here, so a
94
+ * session whose only entries were the agent declaring its turn over reported
95
+ * `hasEntries: false` — it existed, it had run, and it was filtered out of
96
+ * every listing that asks this question. Deriving costs one map() and makes
97
+ * the next family added to the registry impossible to miss.
98
+ */
99
+ const ENTRY_TYPE_MARKERS = ENTRY_EVENT_PREFIXES.map(prefix => `"type":"${prefix}`)
100
+
101
+ /** Session files are compact JSONL authored by core; stop scanning as soon as the first entry appears. */
102
+ export function sessionHasEntries(file: string): boolean {
103
+ const fd = openSync(file, "r")
104
+ const buffer = Buffer.allocUnsafe(64 * 1024)
105
+ const overlap = Math.max(...ENTRY_TYPE_MARKERS.map(marker => marker.length)) - 1
106
+ let carry = ""
107
+ try {
108
+ while (true) {
109
+ const bytes = readSync(fd, buffer, 0, buffer.length, null)
110
+ if (bytes === 0) return false
111
+ const chunk = carry + buffer.toString("utf-8", 0, bytes)
112
+ if (ENTRY_TYPE_MARKERS.some(marker => chunk.includes(marker))) return true
113
+ carry = chunk.slice(-overlap)
114
+ }
115
+ } finally {
116
+ closeSync(fd)
117
+ }
118
+ }
119
+
120
+ /**
121
+ * Is this session worth listing?
122
+ *
123
+ * The predicate every surface listing sessions asks — Fleet's shelf and the
124
+ * TUI's `^` palette both, so it lives beside the record it tests rather than
125
+ * in either one of them.
126
+ *
127
+ * `hasEntries` is the baseline: it hides logs that were opened and never
128
+ * spoken into, so a list is not mostly empty boots. But it is a PROXY for "a
129
+ * person did something here", and it misses two cases where they demonstrably
130
+ * did:
131
+ *
132
+ * - **running** — a session boots with a header and build events but no
133
+ * timeline entry until the first message, so the conversation you are
134
+ * SITTING IN is absent from its own history until you speak. A live
135
+ * instance is proof a person caused this to exist.
136
+ * - **forkedFrom** — a fork is an explicit act. Forking a blank session
137
+ * copies a log with no entries, and `:session fork` deliberately does not
138
+ * switch to it, so it failed both other tests and vanished — the one
139
+ * command whose whole purpose is to leave something behind.
140
+ *
141
+ * The rule is "a person caused this to exist". Entries alone do not express it.
142
+ */
143
+ export function isListableSession(record: Pick<SessionRecord, "hasEntries" | "running" | "forkedFrom">): boolean {
144
+ return record.hasEntries || record.running || record.forkedFrom !== null
145
+ }
@@ -0,0 +1,240 @@
1
+ import { existsSync, readdirSync, statSync } from "node:fs"
2
+ import { readFile, rename, writeFile } from "node:fs/promises"
3
+ import { basename, dirname, join } from "node:path"
4
+ import { err } from "@arcforge/err"
5
+ import type { StoreT } from "../../../services/store"
6
+ import { Frame } from "../../frame"
7
+ import { sessionHasEntries, sessionHead, type SessionRecord } from "./record"
8
+
9
+ type SessionsOpts = {
10
+ store: StoreT
11
+ /** Whether a session is live right now — the registry answers this, not the disk. */
12
+ isRunning: (sessionId: string) => boolean
13
+ }
14
+
15
+ /**
16
+ * Sessions — the resumable conversations on disk.
17
+ *
18
+ * Scans <agent>/.agent/data/sessions/*.jsonl directly: the filesystem is the
19
+ * source of truth for "a session exists" (see core's home.ts), so there is no
20
+ * registry to keep in sync. A session record exists whether or not anything is
21
+ * running, which is why this is its own concern rather than a projection of the
22
+ * instance registry — the registry only supplies the `running` flag.
23
+ *
24
+ * Reads the pre-migration location too. This scanner deliberately does NOT
25
+ * boot a blueprint, so it cannot ask where an agent's data actually lives; it
26
+ * has to know the convention. An agent that has not yet been re-prepared still
27
+ * holds its history at the old path, and listing nothing for it would look
28
+ * exactly like "this agent has never run" — a silent, total loss of visible
29
+ * history rather than an error. Both paths are cheap to stat, so both are read.
30
+ *
31
+ * Still assumes the DEFAULT data path — an agent overriding blueprint
32
+ * paths.data won't be listed; a deliberate cost of not booting a blueprint just
33
+ * to enumerate logs.
34
+ */
35
+ export function Sessions(opts: SessionsOpts) {
36
+ /** Every on-disk session across the active profile's agents, newest first. */
37
+ function list(): SessionRecord[] {
38
+ const profile = opts.store.profiles.active()
39
+ if (!profile) return []
40
+
41
+ const records: SessionRecord[] = []
42
+ const seen = new Set<string>()
43
+
44
+ // locations(), not list(): every agent DIRECTORY in the canonical
45
+ // store and in every settings.paths root, deduped by path. list()
46
+ // dedupes by identity and lets a watched checkout shadow an installed
47
+ // copy of the same name, which silently drops that copy's recorded
48
+ // history — including, when it is the one running, the live session.
49
+ for (const agent of profile.agents.locations()) {
50
+ const agentRoot = agent.root
51
+ const dirs = [
52
+ join(Frame({ root: agentRoot, kind: "agent" }).path("data"), "sessions"),
53
+ // Pre-migration. See this module's header.
54
+ join(agentRoot, "data", "sessions"),
55
+ ]
56
+
57
+ for (const dir of dirs) {
58
+ if (!existsSync(dir)) continue
59
+
60
+ for (const file of readdirSync(dir)) {
61
+ if (!file.endsWith(".jsonl")) continue
62
+ const sessionId = basename(file, ".jsonl")
63
+
64
+ // A half-finished migration can leave the same session
65
+ // under both paths. It is one session either way, and
66
+ // the new location is authoritative because it is read
67
+ // first.
68
+ // Keyed by DIRECTORY, not name: two locations can
69
+ // share an identity (a checkout shadowing an install),
70
+ // and their logs are different conversations.
71
+ const key = `${agentRoot}/${sessionId}`
72
+ if (seen.has(key)) continue
73
+ seen.add(key)
74
+
75
+ const path = join(dir, file)
76
+ // One stat, one header read — both fields of each come
77
+ // off the same syscall rather than repeating it.
78
+ const stat = statSync(path)
79
+ const head = sessionHead(path)
80
+ records.push({
81
+ sessionId: sessionId,
82
+ agent: agent.name,
83
+ filePath: path,
84
+ modifiedAt: stat.mtimeMs,
85
+ sizeBytes: stat.size,
86
+ running: opts.isRunning(sessionId),
87
+ hasEntries: sessionHasEntries(path),
88
+ title: head.title,
89
+ forkedFrom: head.forkedFrom,
90
+ })
91
+ }
92
+ }
93
+ }
94
+ return records.sort((a, b) => b.modifiedAt - a.modifiedAt)
95
+ }
96
+
97
+ return {
98
+ list,
99
+
100
+ /**
101
+ * The most recent conversation worth returning to — what `axon
102
+ * --continue` resumes. Null when there is nothing to continue.
103
+ *
104
+ * ── Why `hasEntries` is the filter ──────────────────────────────────
105
+ *
106
+ * A session file exists from the moment an agent boots, before anyone
107
+ * has said anything. Those empty logs are the MAJORITY of the newest
108
+ * records on a machine where the TUI has been opened and closed a few
109
+ * times, and resuming one restores nothing: the user sees an empty
110
+ * chat, which is indistinguishable from `--continue` having failed
111
+ * while looking exactly like it. "Latest session" and "latest
112
+ * conversation" are different questions, and this answers the second.
113
+ *
114
+ * ── Profile-wide, not per-agent ─────────────────────────────────────
115
+ *
116
+ * "Continue what I was doing" is about the CONVERSATION; which agent
117
+ * held it is a property of that conversation, not a separate choice
118
+ * the user is making. The record carries its own agent, so resuming
119
+ * brings the right one along without the caller selecting first.
120
+ *
121
+ * A running session is a legitimate answer — the caller focuses it
122
+ * rather than double-spawning (see Instances.spawn, which refuses a
123
+ * live sessionId). Excluding it here would skip past the conversation
124
+ * the user most likely means.
125
+ */
126
+ latest(): SessionRecord | null {
127
+ // list() is already newest-first, so the first match IS the latest.
128
+ return list().find(record => record.hasEntries) ?? null
129
+ },
130
+
131
+ /**
132
+ * Copy a session to a new one, and return the copy's id.
133
+ *
134
+ * ── Why a byte copy is the whole implementation ─────────────────────
135
+ *
136
+ * A session log is append-only JSONL and self-contained: every event
137
+ * carries its own context, and nothing outside the file points into
138
+ * it. So a fork is a copy with a rewritten header — no index to
139
+ * update, no backend to tell, works offline, and works on a
140
+ * deployment's local mirror. That is also why it is instant on a log
141
+ * of any size a conversation produces.
142
+ *
143
+ * The events keep their ORIGINAL runIds and spanIds. They are
144
+ * correlation ids within one log, not global identities, and
145
+ * rewriting them would break nothing while making the copy diverge
146
+ * from the record it is a copy of.
147
+ *
148
+ * ── Lineage is recorded now because it cannot be recovered later ────
149
+ *
150
+ * `forkedFrom` goes in the header at the one moment it is free to
151
+ * know. Reconstructing it afterwards from timestamps and content
152
+ * would be guesswork, and a fork with no parent is indistinguishable
153
+ * from an ordinary session.
154
+ */
155
+ async fork(filePath: string, input: { title?: string } = {}): Promise<{ sessionId: string; filePath: string }> {
156
+ if (!existsSync(filePath)) {
157
+ throw err("SESSION_NOT_FOUND", { detail: filePath, context: { filePath } })
158
+ }
159
+
160
+ const source = await readFile(filePath, "utf-8")
161
+ const newline = source.indexOf("\n")
162
+ if (newline < 0) {
163
+ throw err("SESSION_UNREADABLE", {
164
+ detail: `${filePath} has no header line`,
165
+ context: { filePath },
166
+ })
167
+ }
168
+
169
+ let head: Record<string, unknown>
170
+ try {
171
+ head = JSON.parse(source.slice(0, newline)) as Record<string, unknown>
172
+ } catch (cause) {
173
+ throw err("SESSION_UNREADABLE", { detail: filePath, context: { filePath }, cause })
174
+ }
175
+ if (head.type !== "session:header") {
176
+ throw err("SESSION_UNREADABLE", {
177
+ detail: `${filePath} does not start with a session:header`,
178
+ context: { filePath },
179
+ })
180
+ }
181
+
182
+ const sessionId = crypto.randomUUID()
183
+ const forked = {
184
+ ...head,
185
+ sessionId,
186
+ startedAt: new Date().toISOString(),
187
+ ...(input.title ? { title: input.title } : {}),
188
+ forkedFrom: { sessionId: head.sessionId, at: new Date().toISOString() },
189
+ }
190
+
191
+ const target = join(dirname(filePath), `${sessionId}.jsonl`)
192
+ // Written whole rather than appended: the copy has no reader yet,
193
+ // so there is nothing to observe a partial write, and one write is
194
+ // atomic enough for a file nothing is tailing.
195
+ await writeFile(target, JSON.stringify(forked) + source.slice(newline))
196
+ return { sessionId, filePath: target }
197
+ },
198
+
199
+ /**
200
+ * Name a session, by rewriting its header's title.
201
+ *
202
+ * Same temp-then-rename dance `identify()` uses in @arcforge/session:
203
+ * a reader tailing the log must never observe it half-written, and a
204
+ * crash mid-write must not truncate it. Unlike identify(), this may run
205
+ * against a large log — the rewrite is proportional to the file, which
206
+ * is the price of keeping the name IN the log rather than beside it.
207
+ */
208
+ async rename(filePath: string, title: string): Promise<void> {
209
+ if (!existsSync(filePath)) {
210
+ throw err("SESSION_NOT_FOUND", { detail: filePath, context: { filePath } })
211
+ }
212
+
213
+ const current = await readFile(filePath, "utf-8")
214
+ const newline = current.indexOf("\n")
215
+ if (newline < 0) {
216
+ throw err("SESSION_UNREADABLE", { detail: filePath, context: { filePath } })
217
+ }
218
+
219
+ let head: Record<string, unknown>
220
+ try {
221
+ head = JSON.parse(current.slice(0, newline)) as Record<string, unknown>
222
+ } catch (cause) {
223
+ throw err("SESSION_UNREADABLE", { detail: filePath, context: { filePath }, cause })
224
+ }
225
+ if (head.type !== "session:header") {
226
+ throw err("SESSION_UNREADABLE", {
227
+ detail: `${filePath} does not start with a session:header`,
228
+ context: { filePath },
229
+ })
230
+ }
231
+
232
+ const rewritten = JSON.stringify({ ...head, title }) + current.slice(newline)
233
+ const tmp = `${filePath}.${Math.random().toString(36).slice(2, 10)}.tmp`
234
+ await writeFile(tmp, rewritten)
235
+ await rename(tmp, filePath)
236
+ },
237
+ }
238
+ }
239
+
240
+ export type SessionsT = ReturnType<typeof Sessions>