@mostra/runtime 0.0.0-stage → 0.2.0

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 (115) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +39 -2
  3. package/dist/bin.d.ts +1 -0
  4. package/dist/bin.js +236 -0
  5. package/dist/bin.js.map +1 -0
  6. package/dist/builder/child/main.d.ts +1 -0
  7. package/dist/builder/child/main.js +1408 -0
  8. package/dist/builder/child/main.js.map +1 -0
  9. package/dist/child-xrHmytks.js +49 -0
  10. package/dist/child-xrHmytks.js.map +1 -0
  11. package/dist/deps/child/install.d.ts +1 -0
  12. package/dist/deps/child/install.js +33 -0
  13. package/dist/deps/child/install.js.map +1 -0
  14. package/dist/index.d.ts +221 -0
  15. package/dist/index.d.ts.map +1 -0
  16. package/dist/index.js +3 -0
  17. package/dist/instance-CzBkUyHu.js +15920 -0
  18. package/dist/instance-CzBkUyHu.js.map +1 -0
  19. package/dist/types-NjNy7gXX.js +57 -0
  20. package/dist/types-NjNy7gXX.js.map +1 -0
  21. package/package.json +87 -3
  22. package/src/actions/index.ts +622 -0
  23. package/src/addressing/index.ts +281 -0
  24. package/src/bin.ts +240 -0
  25. package/src/builder/child/dev.ts +383 -0
  26. package/src/builder/child/fields.ts +363 -0
  27. package/src/builder/child/main.ts +47 -0
  28. package/src/builder/child/plugins.ts +195 -0
  29. package/src/builder/child/scan.ts +459 -0
  30. package/src/builder/child/spa.ts +348 -0
  31. package/src/builder/coverage.ts +72 -0
  32. package/src/builder/index.ts +406 -0
  33. package/src/builder/types.ts +180 -0
  34. package/src/deps/child/install.ts +30 -0
  35. package/src/deps/index.ts +918 -0
  36. package/src/deps/installer.ts +321 -0
  37. package/src/deps/lock.ts +82 -0
  38. package/src/deps/scan.ts +266 -0
  39. package/src/deps/specifier.ts +64 -0
  40. package/src/deps/warm.ts +57 -0
  41. package/src/dev/index.ts +518 -0
  42. package/src/faults.ts +65 -0
  43. package/src/gate.ts +55 -0
  44. package/src/gateway/actions.ts +268 -0
  45. package/src/gateway/browser.ts +650 -0
  46. package/src/gateway/capabilities.ts +760 -0
  47. package/src/gateway/controls.ts +91 -0
  48. package/src/gateway/dev.ts +119 -0
  49. package/src/gateway/http.ts +229 -0
  50. package/src/gateway/identity.ts +101 -0
  51. package/src/gateway/index.ts +1299 -0
  52. package/src/gateway/integrity.ts +117 -0
  53. package/src/gateway/listener.ts +217 -0
  54. package/src/gateway/routes.ts +197 -0
  55. package/src/gateway/serve.ts +138 -0
  56. package/src/gc/index.ts +451 -0
  57. package/src/home/acquire.ts +276 -0
  58. package/src/home/index.ts +16 -0
  59. package/src/home/paths.ts +192 -0
  60. package/src/home/platform.ts +34 -0
  61. package/src/home/record.ts +76 -0
  62. package/src/home/settings.ts +113 -0
  63. package/src/index.ts +30 -0
  64. package/src/instance/index.ts +979 -0
  65. package/src/interaction/ephemeral.ts +300 -0
  66. package/src/interaction/events.ts +355 -0
  67. package/src/interaction/fields.ts +392 -0
  68. package/src/interaction/index.ts +1013 -0
  69. package/src/interaction/outbox.ts +493 -0
  70. package/src/interaction/policy.ts +26 -0
  71. package/src/interaction/results.ts +341 -0
  72. package/src/interaction/runs.ts +313 -0
  73. package/src/interaction/signals.ts +120 -0
  74. package/src/interaction/submissions.ts +585 -0
  75. package/src/interaction/subscriptions.ts +258 -0
  76. package/src/interaction/viewers.ts +187 -0
  77. package/src/interaction/wait.ts +201 -0
  78. package/src/ledger/index.ts +442 -0
  79. package/src/ledger/migrations.ts +596 -0
  80. package/src/ledger/requests.ts +105 -0
  81. package/src/ledger/types.ts +28 -0
  82. package/src/live/index.ts +573 -0
  83. package/src/log.ts +316 -0
  84. package/src/processes/child.ts +67 -0
  85. package/src/processes/environment.ts +64 -0
  86. package/src/processes/identity.ts +191 -0
  87. package/src/processes/index.ts +19 -0
  88. package/src/processes/manager.ts +543 -0
  89. package/src/protocol-server/client.ts +94 -0
  90. package/src/protocol-server/index.ts +91 -0
  91. package/src/protocol-server/server.ts +518 -0
  92. package/src/protocol-server/streams.ts +81 -0
  93. package/src/publish/checks.ts +92 -0
  94. package/src/publish/digest.ts +87 -0
  95. package/src/publish/index.ts +23 -0
  96. package/src/publish/manifest.ts +409 -0
  97. package/src/publish/methods.ts +96 -0
  98. package/src/publish/publisher.ts +913 -0
  99. package/src/publish/source.ts +272 -0
  100. package/src/publish/tar.ts +110 -0
  101. package/src/registry/index.ts +481 -0
  102. package/src/registry/store.ts +136 -0
  103. package/src/secrets/index.ts +223 -0
  104. package/src/service/idle.ts +64 -0
  105. package/src/service/index.ts +3 -0
  106. package/src/service/unit.ts +250 -0
  107. package/src/verify/fields.ts +125 -0
  108. package/src/verify/index.ts +913 -0
  109. package/src/verify/regression.ts +157 -0
  110. package/src/verify/runner.ts +230 -0
  111. package/src/verify/sandbox.ts +407 -0
  112. package/src/verify/typecheck.ts +371 -0
  113. package/src/workers/index.ts +17 -0
  114. package/src/workers/launcher.ts +260 -0
  115. package/src/workers/pool.ts +708 -0
@@ -0,0 +1,543 @@
1
+ /**
2
+ * The process manager (RT-09, ARCHITECTURE §4, FAILURE_MODEL §2). Every child runs as the leader
3
+ * of its own process group and is recorded in the ledger's `child` table with its PID and start
4
+ * time before anyone relies on it. A child's group dies with it, and a supervisor that starts
5
+ * after a crash reaps every recorded group that is still running.
6
+ */
7
+ import { type ChildProcess, spawn } from "node:child_process";
8
+ import { createInterface } from "node:readline";
9
+ import type { Duplex, Writable } from "node:stream";
10
+ import { type JsonRpcParams, RpcPeer } from "@mostra/protocol";
11
+ import * as z from "zod";
12
+ import { type Faults, noFaults } from "../faults.ts";
13
+ import type { Ledger } from "../ledger/index.ts";
14
+ import type { Environment, Log, Redactor } from "../log.ts";
15
+ import {
16
+ listProcesses,
17
+ type ProcessInfo,
18
+ readProcess,
19
+ sameBoot,
20
+ startedNoEarlier,
21
+ } from "./identity.ts";
22
+
23
+ /** How long a stopping child gets between SIGTERM and SIGKILL, by default. */
24
+ const DEFAULT_GRACE_MS = 5000;
25
+ /** How long reaping waits between SIGTERM and SIGKILL. */
26
+ const REAP_GRACE_MS = 2000;
27
+ /** How long to wait for SIGKILLed processes to disappear before reporting them. */
28
+ const KILL_WAIT_MS = 5000;
29
+ /** How many stderr lines a child's exit report keeps. */
30
+ const STDERR_TAIL = 50;
31
+
32
+ /**
33
+ * The gate every child starts behind (issue #7): `/bin/sh` waits for "go" on file descriptor 3 and
34
+ * only then replaces itself with the real command, keeping its PID, process group and start time.
35
+ * The supervisor writes "go" after it has recorded the child, so a supervisor killed in between
36
+ * leaves a gate that reads end-of-file and exits 125 without running anything.
37
+ */
38
+ const GATE_SCRIPT = 'IFS= read -r go <&3 && [ "$go" = go ] || exit 125; exec 3<&-; exec "$@"';
39
+
40
+ /** How a child ended. */
41
+ export interface ChildExit {
42
+ /** The exit code, or `null` when a signal ended it. */
43
+ readonly code: number | null;
44
+ /** The signal that ended it, if any. */
45
+ readonly signal: string | null;
46
+ /** Its last stderr lines, for diagnostics such as `MOSTRA_BUILD_CRASHED`. */
47
+ readonly stderrTail: readonly string[];
48
+ }
49
+
50
+ /** What to start. */
51
+ export interface SpawnSpec {
52
+ /** What the child is: `builder`, `verify`, `worker`, `pty-host`, `demo`, `install` … */
53
+ readonly kind: string;
54
+ /** What it serves, such as an artifact or version ID. */
55
+ readonly ownerRef: string;
56
+ /** The executable. */
57
+ readonly command: string;
58
+ /** Its arguments. */
59
+ readonly args?: readonly string[];
60
+ /** Its working directory. Default: the supervisor's. */
61
+ readonly cwd?: string;
62
+ /** The child's whole environment. Default: the supervisor's. */
63
+ readonly env?: Environment;
64
+ /**
65
+ * Values the child receives that must never appear in logs or reports, such as secrets.
66
+ * Variables whose names look like secrets (`*_TOKEN`, `*_SECRET` …) are redacted as well.
67
+ */
68
+ readonly redact?: readonly string[];
69
+ /**
70
+ * Receives each line the child writes to stdout, redacted, instead of the log: for children
71
+ * whose output is data, such as the installer's NDJSON report. Every line has arrived before
72
+ * `exited` resolves.
73
+ */
74
+ readonly onStdout?: (line: string) => void;
75
+ /**
76
+ * Opens a JSON-RPC channel over Node IPC; the command must then be a Node.js executable. The
77
+ * handlers answer the child's requests besides the built-in `child/adopt` and `child/release`.
78
+ */
79
+ readonly ipc?: {
80
+ readonly onRequest?: (method: string, params: unknown) => unknown;
81
+ readonly onNotification?: (method: string, params: unknown) => void;
82
+ };
83
+ /**
84
+ * Opens a plain byte channel as the child's fd 4 (an artifact's worker, D124): a pipe the child
85
+ * reads and writes as it likes, unlike `ipc`, which is Node's own channel on the main thread.
86
+ * The two exclude each other.
87
+ */
88
+ readonly channel?: true;
89
+ }
90
+
91
+ /** A running child. */
92
+ export interface ChildHandle {
93
+ /** Its process ID, which is also its process group ID. */
94
+ readonly pid: number;
95
+ /** What it is (`SpawnSpec.kind`). */
96
+ readonly kind: string;
97
+ /** What it serves (`SpawnSpec.ownerRef`). */
98
+ readonly ownerRef: string;
99
+ /** When it was started (RFC 3339). */
100
+ readonly startedAt: string;
101
+ /** Sends requests to the child, when it was started with `ipc`. */
102
+ request(
103
+ method: string,
104
+ params?: JsonRpcParams,
105
+ options?: { timeoutMs?: number },
106
+ ): Promise<unknown>;
107
+ /** The child's fd 4, when it was started with `channel`. */
108
+ readonly channel?: Duplex;
109
+ /** Resolves when the child has exited and its process groups are gone. */
110
+ readonly exited: Promise<ChildExit>;
111
+ /** Stops the child: SIGTERM to its group, SIGKILL after `graceMs`. */
112
+ stop(graceMs?: number): Promise<ChildExit>;
113
+ }
114
+
115
+ /** What reaping found for one recorded child. */
116
+ export interface ReapedChild {
117
+ /** The recorded process ID. */
118
+ readonly pid: number;
119
+ /** The recorded kind; a program a child adopted has its parent's kind plus "/adopted". */
120
+ readonly kind: string;
121
+ /** What it served. */
122
+ readonly ownerRef: string;
123
+ /** The processes that were signalled: the leader if it still ran, and its group's members. */
124
+ readonly signalled: readonly number[];
125
+ /** Why nothing was signalled, when nothing was. */
126
+ readonly skipped?: "gone" | "pid reused" | "other boot";
127
+ }
128
+
129
+ interface ChildRow {
130
+ pid: number;
131
+ start_time: string;
132
+ kind: string;
133
+ owner_ref: string;
134
+ pgid: number;
135
+ started_at: string;
136
+ parent_pid: number | null;
137
+ }
138
+
139
+ const AdoptParams = z.object({ pid: z.int().min(2) });
140
+
141
+ /** The process manager of one supervisor. */
142
+ export interface ProcessManager {
143
+ /** Starts a child in its own process group and records it. */
144
+ spawn(spec: SpawnSpec): Promise<ChildHandle>;
145
+ /** The children running now, for `instance/status`. */
146
+ list(): readonly { pid: number; kind: string; ownerRef: string; startedAt: string }[];
147
+ /** Stops every child; used when the supervisor stops. */
148
+ stopAll(graceMs?: number): Promise<void>;
149
+ }
150
+
151
+ /** Options for {@link openProcessManager}. */
152
+ export interface ProcessManagerOptions {
153
+ readonly ledger: Ledger;
154
+ readonly log: Log;
155
+ /** Learns the secrets children receive, so their output is redacted wherever it goes. */
156
+ readonly redactor: Redactor;
157
+ /** Test fault points (`spawn:before-record`). Default: none. */
158
+ readonly faults?: Faults;
159
+ }
160
+
161
+ /**
162
+ * Opens the process manager: first reaps every child a previous supervisor of this home left
163
+ * running (FAILURE_MODEL §2), then accepts new children. Call it only while holding the home's
164
+ * ledger lock, so no live supervisor's children are touched.
165
+ */
166
+ export async function openProcessManager(
167
+ options: ProcessManagerOptions,
168
+ ): Promise<{ manager: ProcessManager; reaped: readonly ReapedChild[] }> {
169
+ const reaped = await reapRecorded(options.ledger, options.log);
170
+ return { manager: createManager(options), reaped };
171
+ }
172
+
173
+ /** Signals `pids`, ignoring ones already gone. */
174
+ function signalAll(pids: readonly number[], signal: NodeJS.Signals): void {
175
+ for (const pid of pids) {
176
+ try {
177
+ process.kill(pid, signal);
178
+ } catch {
179
+ // Already gone.
180
+ }
181
+ }
182
+ }
183
+
184
+ function signalGroup(pgid: number, signal: NodeJS.Signals): boolean {
185
+ try {
186
+ process.kill(-pgid, signal);
187
+ return true;
188
+ } catch {
189
+ return false;
190
+ }
191
+ }
192
+
193
+ const groupAlive = (pgid: number): boolean => signalGroup(pgid, 0 as unknown as NodeJS.Signals);
194
+
195
+ const delay = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
196
+
197
+ /** Waits for `promise` to settle, or `ms` at most, leaving no timer behind. */
198
+ async function settleWithin(promise: Promise<unknown>, ms: number): Promise<void> {
199
+ let timer: ReturnType<typeof setTimeout> | undefined;
200
+ try {
201
+ await Promise.race([
202
+ promise.then(
203
+ () => undefined,
204
+ () => undefined,
205
+ ),
206
+ new Promise<void>((resolve) => {
207
+ timer = setTimeout(resolve, ms);
208
+ }),
209
+ ]);
210
+ } finally {
211
+ clearTimeout(timer);
212
+ }
213
+ }
214
+
215
+ /** The processes of a recorded group that are provably the recorded child's: see FAILURE_MODEL §2. */
216
+ function targetsFor(
217
+ row: ChildRow,
218
+ processes: readonly ProcessInfo[],
219
+ ): number[] | NonNullable<ReapedChild["skipped"]> {
220
+ const leader = processes.find((info) => info.pid === row.pid);
221
+ if (leader && leader.startTime !== row.start_time) return "pid reused";
222
+ if (!leader) {
223
+ const boot = processes.find((info) => info.pid === process.pid)?.startTime;
224
+ if (boot === undefined || !sameBoot(boot, row.start_time)) return "other boot";
225
+ }
226
+ const members = processes
227
+ .filter((info) => info.pgid === row.pgid && info.pid !== process.pid)
228
+ .filter((info) => startedNoEarlier(info.startTime, row.start_time))
229
+ .map((info) => info.pid);
230
+ return members.length > 0 ? members : "gone";
231
+ }
232
+
233
+ async function reapRecorded(ledger: Ledger, log: Log): Promise<ReapedChild[]> {
234
+ const rows = ledger.read((db) => db.all<ChildRow>("SELECT * FROM child ORDER BY started_at"));
235
+ if (rows.length === 0) return [];
236
+ const before = await listProcesses();
237
+ const plan = rows.map((row) => ({ row, targets: targetsFor(row, before) }));
238
+ // Only groups proven to be the recorded children's are signalled, then watched until they are
239
+ // empty: a member may start more processes in the group while it handles SIGTERM, so every
240
+ // round re-lists the groups instead of trusting the first snapshot (RT-09).
241
+ const owned = plan.filter((entry) => Array.isArray(entry.targets)).map((entry) => entry.row);
242
+ const members = (processes: readonly ProcessInfo[]): number[] => [
243
+ ...new Set(
244
+ owned.flatMap((row) => {
245
+ const targets = targetsFor(row, processes);
246
+ return Array.isArray(targets) ? targets : [];
247
+ }),
248
+ ),
249
+ ];
250
+ // A listing is a series of reads, so a process that starts while another exits can slip
251
+ // between them; the groups count as gone only when the kernel has no member left either.
252
+ const groupsLeft = (): boolean => owned.some((row) => groupAlive(row.pgid));
253
+ signalAll(members(before), "SIGTERM");
254
+ const deadline = Date.now() + REAP_GRACE_MS;
255
+ let remaining = members(await listProcesses());
256
+ while ((remaining.length > 0 || groupsLeft()) && Date.now() < deadline) {
257
+ await delay(100);
258
+ remaining = members(await listProcesses());
259
+ }
260
+ const killDeadline = Date.now() + KILL_WAIT_MS;
261
+ while ((remaining.length > 0 || groupsLeft()) && Date.now() < killDeadline) {
262
+ signalAll(remaining, "SIGKILL");
263
+ await delay(50);
264
+ remaining = members(await listProcesses());
265
+ }
266
+ if (remaining.length > 0 || groupsLeft()) {
267
+ log.warn("process.reap_incomplete", { pids: remaining, pgids: owned.map((row) => row.pgid) });
268
+ }
269
+ ledger.write((db) => {
270
+ for (const { row } of plan) {
271
+ db.run("DELETE FROM child WHERE pid = ? AND start_time = ?", row.pid, row.start_time);
272
+ }
273
+ });
274
+ const report = plan.map(({ row, targets }): ReapedChild => {
275
+ const base = { pid: row.pid, kind: row.kind, ownerRef: row.owner_ref };
276
+ return Array.isArray(targets)
277
+ ? { ...base, signalled: targets }
278
+ : { ...base, signalled: [], skipped: targets };
279
+ });
280
+ for (const entry of report) log.info("process.reaped", { ...entry });
281
+ return report;
282
+ }
283
+
284
+ function createManager({
285
+ ledger,
286
+ log,
287
+ redactor,
288
+ faults = noFaults,
289
+ }: ProcessManagerOptions): ProcessManager {
290
+ const running = new Map<number, ChildHandle>();
291
+ let stopping = false;
292
+
293
+ const record = (row: ChildRow): void => {
294
+ ledger.write((db) =>
295
+ db.run(
296
+ "INSERT OR REPLACE INTO child (pid, start_time, kind, owner_ref, pgid, started_at, parent_pid) VALUES (?, ?, ?, ?, ?, ?, ?)",
297
+ row.pid,
298
+ row.start_time,
299
+ row.kind,
300
+ row.owner_ref,
301
+ row.pgid,
302
+ row.started_at,
303
+ row.parent_pid,
304
+ ),
305
+ );
306
+ };
307
+ const forget = (pid: number): void => {
308
+ ledger.write((db) => db.run("DELETE FROM child WHERE pid = ? OR parent_pid = ?", pid, pid));
309
+ };
310
+
311
+ /**
312
+ * Terminates groups: SIGTERM, then SIGKILL after `graceMs` to those still present, then waits
313
+ * (boundedly) until they are gone.
314
+ */
315
+ const endGroups = async (pgids: readonly number[], graceMs: number): Promise<void> => {
316
+ for (const pgid of pgids) signalGroup(pgid, "SIGTERM");
317
+ const deadline = Date.now() + graceMs;
318
+ while (Date.now() < deadline && pgids.some(groupAlive)) await delay(25);
319
+ for (const pgid of pgids) if (groupAlive(pgid)) signalGroup(pgid, "SIGKILL");
320
+ const killDeadline = Date.now() + KILL_WAIT_MS;
321
+ while (Date.now() < killDeadline && pgids.some(groupAlive)) await delay(10);
322
+ const left = pgids.filter(groupAlive);
323
+ if (left.length > 0) log.warn("process.group_survived_sigkill", { pgids: left });
324
+ };
325
+
326
+ const spawnChild = async (spec: SpawnSpec): Promise<ChildHandle> => {
327
+ if (stopping) throw new Error("The process manager is stopping.");
328
+ if (spec.ipc && spec.channel) throw new Error("A child takes ipc or a channel, not both.");
329
+ for (const value of spec.redact ?? []) redactor.protect(value);
330
+ redactor.protectEnvironment(spec.env ?? process.env);
331
+ // fd 3 is the gate; the IPC channel, when there is one, is fd 4 (NODE_CHANNEL_FD survives
332
+ // the gate replacing itself with the command).
333
+ const child: ChildProcess = spawn(
334
+ "/bin/sh",
335
+ ["-c", GATE_SCRIPT, `mostra-${spec.kind}`, spec.command, ...(spec.args ?? [])],
336
+ {
337
+ cwd: spec.cwd,
338
+ env: spec.env ?? process.env,
339
+ detached: true,
340
+ stdio: spec.ipc
341
+ ? ["ignore", "pipe", "pipe", "pipe", "ipc"]
342
+ : spec.channel
343
+ ? ["ignore", "pipe", "pipe", "pipe", "pipe"]
344
+ : ["ignore", "pipe", "pipe", "pipe"],
345
+ serialization: "json",
346
+ },
347
+ );
348
+ const gate = child.stdio[3] as Writable | null;
349
+ gate?.on("error", () => {
350
+ // The child exited before reading "go"; its exit is reported through `exited`.
351
+ });
352
+ const startedAt = new Date().toISOString();
353
+ const pid = await new Promise<number>((resolve, reject) => {
354
+ child.once("spawn", () => resolve(child.pid ?? 0));
355
+ child.once("error", reject);
356
+ });
357
+ // After the spawn, errors (a failed signal or IPC send) are reported, never thrown: an
358
+ // unhandled 'error' event would take the supervisor down.
359
+ child.on("error", (error) => log.warn("process.error", { kind: spec.kind, pid, error }));
360
+ const adopted = new Map<number, number>(); // adopted pid → its pgid
361
+ const stderrTail: string[] = [];
362
+ const exit = new Promise<{ code: number | null; signal: string | null }>((resolve) => {
363
+ child.once("exit", (code, signal) => resolve({ code, signal }));
364
+ });
365
+ // Output can still be in the pipes when the process exits; `exited` waits for it.
366
+ const drained: Promise<unknown>[] = [];
367
+
368
+ if (child.stdout) {
369
+ const lines = createInterface({ input: child.stdout });
370
+ drained.push(new Promise((resolve) => lines.once("close", resolve)));
371
+ lines.on("line", (line) => {
372
+ if (spec.onStdout) spec.onStdout(redactor.redact(line));
373
+ else log.info("process.stdout", { kind: spec.kind, pid, line });
374
+ });
375
+ }
376
+ if (child.stderr) {
377
+ const lines = createInterface({ input: child.stderr });
378
+ drained.push(new Promise((resolve) => lines.once("close", resolve)));
379
+ lines.on("line", (line) => {
380
+ // The log redacts what it writes; the tail feeds diagnostics, so it is redacted here.
381
+ stderrTail.push(redactor.redact(line));
382
+ if (stderrTail.length > STDERR_TAIL) stderrTail.shift();
383
+ log.info("process.stderr", { kind: spec.kind, pid, line });
384
+ });
385
+ }
386
+
387
+ let peer: RpcPeer | undefined;
388
+ if (spec.ipc) {
389
+ const ipc = spec.ipc;
390
+ peer = new RpcPeer({
391
+ send: (message) => {
392
+ if (!child.connected) throw new Error("The IPC channel is closed.");
393
+ child.send(message);
394
+ },
395
+ onRequest: async (method, params) => {
396
+ if (method === "child/adopt" || method === "child/release") {
397
+ const parsed = AdoptParams.safeParse(params);
398
+ if (!parsed.success) throw new Error(`Invalid params for ${method}.`);
399
+ if (method === "child/release") {
400
+ adopted.delete(parsed.data.pid);
401
+ ledger.write((db) =>
402
+ db.run("DELETE FROM child WHERE pid = ? AND parent_pid = ?", parsed.data.pid, pid),
403
+ );
404
+ return {};
405
+ }
406
+ const info = await readProcess(parsed.data.pid);
407
+ // Only a group leader (a program in its own session, such as a PTY program) can be
408
+ // adopted: its whole group is then signalled, and no foreign group ever is.
409
+ if (!info || info.pgid !== info.pid) return { adopted: false };
410
+ adopted.set(info.pid, info.pgid);
411
+ record({
412
+ pid: info.pid,
413
+ start_time: info.startTime,
414
+ kind: `${spec.kind}/adopted`,
415
+ owner_ref: spec.ownerRef,
416
+ pgid: info.pgid,
417
+ started_at: new Date().toISOString(),
418
+ parent_pid: pid,
419
+ });
420
+ return { adopted: true };
421
+ }
422
+ if (!ipc.onRequest) throw new Error(`No handler for ${method}.`);
423
+ return ipc.onRequest(method, params);
424
+ },
425
+ ...(ipc.onNotification ? { onNotification: ipc.onNotification } : {}),
426
+ onInternalError: (error, method) =>
427
+ log.error("process.ipc_error", { kind: spec.kind, pid, method, error }),
428
+ });
429
+ const connected = peer;
430
+ child.on("message", (message) => connected.receive(message));
431
+ child.on("disconnect", () => connected.close());
432
+ }
433
+
434
+ // Record the child before it may run its command (RT-09, issue #7), then open its gate. If it
435
+ // already exited, nothing is left to reap.
436
+ const registered = (async () => {
437
+ const info = await readProcess(pid);
438
+ faults.at("spawn:before-record");
439
+ if (!info) {
440
+ // Gone already: nothing is left to record or reap.
441
+ if (child.exitCode !== null || child.signalCode !== null) return;
442
+ // Still waiting at its gate, so it can't have exited by itself: its identity just
443
+ // couldn't be read. Without a row it couldn't be reaped, so it never runs (D80 Claude
444
+ // review finding 8); the caller stops it and fails the spawn.
445
+ throw new Error(`Couldn't read the process identity of ${spec.kind} ${pid}.`);
446
+ }
447
+ record({
448
+ pid,
449
+ start_time: info.startTime,
450
+ kind: spec.kind,
451
+ owner_ref: spec.ownerRef,
452
+ pgid: pid,
453
+ started_at: startedAt,
454
+ parent_pid: null,
455
+ });
456
+ gate?.end("go\n");
457
+ })();
458
+
459
+ // From here on, the child's group ends with it, whatever happens to its registration.
460
+ const exited = exit.then(async ({ code, signal }) => {
461
+ // The child's lifetime bounds its group and the groups it adopted.
462
+ await endGroups([pid, ...adopted.values()], 2000);
463
+ // The group is gone, so nothing holds the pipes open any more; the bound covers a
464
+ // descendant that left the group with them.
465
+ await settleWithin(Promise.all(drained), 2000);
466
+ await registered.catch(() => {});
467
+ running.delete(pid);
468
+ try {
469
+ forget(pid);
470
+ } catch (error) {
471
+ log.warn("process.forget_failed", { pid, error });
472
+ }
473
+ log.info("process.exited", { kind: spec.kind, pid, code, signal });
474
+ return { code, signal, stderrTail: [...stderrTail] };
475
+ });
476
+
477
+ const channel = spec.channel ? (child.stdio[4] as Duplex | null) : null;
478
+ channel?.on("error", (error) =>
479
+ log.warn("process.channel_error", { kind: spec.kind, pid, error }),
480
+ );
481
+ const handle: ChildHandle = {
482
+ pid,
483
+ kind: spec.kind,
484
+ ownerRef: spec.ownerRef,
485
+ startedAt,
486
+ ...(channel ? { channel } : {}),
487
+ exited,
488
+ request(method, params, options) {
489
+ if (!peer) return Promise.reject(new Error(`${spec.kind} was started without IPC.`));
490
+ return peer.request(method, params, options);
491
+ },
492
+ async stop(graceMs = DEFAULT_GRACE_MS) {
493
+ if (child.exitCode === null && child.signalCode === null) {
494
+ await endGroups([pid, ...adopted.values()], graceMs);
495
+ }
496
+ return exited;
497
+ },
498
+ };
499
+ // Tracked from the spawn on, so stopAll reaches a child whose registration is still running.
500
+ running.set(pid, handle);
501
+
502
+ try {
503
+ await registered;
504
+ } catch (error) {
505
+ // A child that can't be recorded can't be reaped after a crash: don't keep it.
506
+ log.error("process.record_failed", { kind: spec.kind, pid, error });
507
+ await handle.stop(500);
508
+ throw error;
509
+ }
510
+ log.info("process.started", { kind: spec.kind, ownerRef: spec.ownerRef, pid });
511
+ return handle;
512
+ };
513
+
514
+ /** Spawns in progress, so stopAll waits for them before it stops the children. */
515
+ const inflight = new Set<Promise<unknown>>();
516
+ const trackedSpawn = (spec: SpawnSpec): Promise<ChildHandle> => {
517
+ const spawning = spawnChild(spec);
518
+ const settled = spawning.then(
519
+ () => undefined,
520
+ () => undefined,
521
+ );
522
+ inflight.add(settled);
523
+ void settled.then(() => inflight.delete(settled));
524
+ return spawning;
525
+ };
526
+
527
+ return {
528
+ spawn: trackedSpawn,
529
+ list: () =>
530
+ [...running.values()].map((child) => ({
531
+ pid: child.pid,
532
+ kind: child.kind,
533
+ ownerRef: child.ownerRef,
534
+ startedAt: child.startedAt,
535
+ })),
536
+ async stopAll(graceMs = DEFAULT_GRACE_MS) {
537
+ stopping = true;
538
+ // Spawns already under way finish first, so their children are tracked and stopped too.
539
+ await Promise.all(inflight);
540
+ await Promise.all([...running.values()].map((child) => child.stop(graceMs)));
541
+ },
542
+ };
543
+ }
@@ -0,0 +1,94 @@
1
+ /**
2
+ * The client end of the home socket, used by a starter that finds another supervisor holding the
3
+ * home (D81) and by tests. SDKs and the CLI implement the same few steps in their own packages.
4
+ */
5
+ import { createConnection, type Socket } from "node:net";
6
+ import {
7
+ type ClientInfo,
8
+ createDiagnostic,
9
+ HOST_PROTOCOL_REVISIONS,
10
+ type MostraInitializeResult,
11
+ mostraInitializeMethod,
12
+ RpcError,
13
+ RpcPeer,
14
+ } from "@mostra/protocol";
15
+ import { pump, writeLine } from "./streams.ts";
16
+
17
+ /** An open client connection to an instance's socket. */
18
+ export interface SocketClient {
19
+ readonly peer: RpcPeer;
20
+ /** Resolves when the connection has closed. */
21
+ readonly closed: Promise<void>;
22
+ close(): void;
23
+ }
24
+
25
+ /**
26
+ * Connects to a control socket. Rejects with `MOSTRA_HOST_CONNECTION_CLOSED` when nothing
27
+ * listens there (the file is missing or stale) or the connection doesn't open within `timeoutMs`.
28
+ */
29
+ export function connectSocket(path: string, timeoutMs = 5000): Promise<SocketClient> {
30
+ return new Promise((resolve, reject) => {
31
+ const socket: Socket = createConnection(path);
32
+ const timer = setTimeout(() => {
33
+ socket.destroy();
34
+ reject(refused(path, "timed out"));
35
+ }, timeoutMs);
36
+ socket.once("error", (error: NodeJS.ErrnoException) => {
37
+ clearTimeout(timer);
38
+ reject(refused(path, error.code ?? "failed"));
39
+ });
40
+ socket.once("connect", () => {
41
+ clearTimeout(timer);
42
+ const peer = new RpcPeer({ send: (message) => void writeLine(socket, message) });
43
+ let markClosed: () => void = () => {};
44
+ const closed = new Promise<void>((done) => {
45
+ markClosed = done;
46
+ });
47
+ socket.on("error", () => socket.destroy());
48
+ pump(
49
+ { input: socket, output: socket },
50
+ () => peer,
51
+ () => {
52
+ peer.close();
53
+ markClosed();
54
+ },
55
+ );
56
+ resolve({
57
+ peer,
58
+ closed,
59
+ close: () => {
60
+ peer.close();
61
+ socket.end();
62
+ },
63
+ });
64
+ });
65
+ });
66
+ }
67
+
68
+ function refused(path: string, why: string): RpcError {
69
+ return new RpcError(
70
+ createDiagnostic("MOSTRA_HOST_CONNECTION_CLOSED", {
71
+ message: `Couldn't connect to the instance socket ${path} (${why}).`,
72
+ }),
73
+ );
74
+ }
75
+
76
+ /** Connects to a socket and opens a session. The caller closes the returned client. */
77
+ export async function attach(
78
+ path: string,
79
+ client: ClientInfo,
80
+ timeoutMs = 5000,
81
+ ): Promise<{ client: SocketClient; result: MostraInitializeResult }> {
82
+ const connection = await connectSocket(path, timeoutMs);
83
+ try {
84
+ const result = await connection.peer.call(
85
+ mostraInitializeMethod,
86
+ { client, revisions: [...HOST_PROTOCOL_REVISIONS], capabilities: {}, ports: [] },
87
+ { timeoutMs },
88
+ );
89
+ return { client: connection, result };
90
+ } catch (error) {
91
+ connection.close();
92
+ throw error;
93
+ }
94
+ }