The best way to control Claude Code, Codex and more from any computer or phone

main
ts 569 lines 19.2 KB
Raw
1 // @effect-diagnostics nodeBuiltinImport:off - worker threads and Node streams implement the platform spawner boundary.
2 import * as NodeEvents from "node:events";
3 import type * as NodeChildProcess from "node:child_process";
4 import * as NodeStream from "node:stream";
5 import * as NodeWorkerThreads from "node:worker_threads";
6 import * as NodeChildProcessSpawner from "@effect/platform-node-shared/NodeChildProcessSpawner";
7 import * as Effect from "effect/Effect";
8 import * as Layer from "effect/Layer";
9 import { supportsEnvChdir } from "@t3tools/shared/envTrampoline";
10 import * as HostProcess from "@t3tools/shared/HostProcess";
11
12 // Windows runs CreateProcess synchronously on the calling thread, and antivirus or a busy disk can
13 // hold it for seconds; Linux's spawn waits for chdir and the PATH search, which a hung mount
14 // stalls. Workers own the children, so only the worker waits.
15 const MAX_WORKERS = 4;
16 const MAX_IDLE_WORKERS = 1;
17
18 type ToWorker =
19 | {
20 readonly type: "spawn";
21 readonly id: number;
22 readonly command: string;
23 readonly args: ReadonlyArray<string>;
24 readonly options: NodeChildProcess.SpawnOptions;
25 }
26 | { readonly type: "write"; readonly id: number; readonly fd: number; readonly data: Uint8Array }
27 | { readonly type: "end"; readonly id: number; readonly fd: number }
28 | { readonly type: "flow"; readonly id: number; readonly fd: number; readonly paused: boolean }
29 | { readonly type: "destroy"; readonly id: number; readonly fd: number }
30 | { readonly type: "kill"; readonly id: number; readonly signal: NodeJS.Signals | number };
31
32 interface SerializedError {
33 readonly message: string;
34 readonly [key: string]: unknown;
35 }
36
37 type FromWorker =
38 | { readonly type: "spawn"; readonly id: number; readonly pid: number | undefined }
39 | { readonly type: "error"; readonly id: number; readonly error: SerializedError }
40 | { readonly type: "data"; readonly id: number; readonly fd: number; readonly data: Uint8Array }
41 | {
42 readonly type: "written";
43 readonly id: number;
44 readonly fd: number;
45 readonly error?: SerializedError;
46 }
47 | { readonly type: "eof"; readonly id: number; readonly fd: number }
48 | { readonly type: "finished"; readonly id: number; readonly fd: number }
49 | {
50 readonly type: "stream-error";
51 readonly id: number;
52 readonly fd: number;
53 readonly error: SerializedError;
54 }
55 | {
56 readonly type: "exit";
57 readonly id: number;
58 readonly code: number | null;
59 readonly signal: NodeJS.Signals | null;
60 }
61 | { readonly type: "close"; readonly id: number };
62
63 // Windows makes a child's stdio pipes inheritable for the length of its CreateProcess, so a child
64 // another worker launches meanwhile inherits them and holds the first child's output open. Every
65 // pool's workers take this lock around spawn(); it holds the owning worker's threadId.
66 const windowsSpawnLock = new Int32Array(new SharedArrayBuffer(4));
67
68 // Inline source runs from bundles, asar archives and single-executable builds without module files.
69 const workerSource = `
70 const { parentPort, threadId, workerData } = require("node:worker_threads");
71 const { spawn } = require("node:child_process");
72 const { lock } = workerData;
73 const locked = (launch) => {
74 if (lock === undefined) return launch();
75 // Wait on the owner compareExchange saw: an unlock after it changes the value, so no wakeup is lost.
76 for (let owner; (owner = Atomics.compareExchange(lock, 0, 0, threadId)) !== 0; ) Atomics.wait(lock, 0, owner);
77 try {
78 return launch();
79 } finally {
80 Atomics.store(lock, 0, 0);
81 Atomics.notify(lock, 0, 1);
82 }
83 };
84 const children = new Map();
85 const post = (message, transfer) => parentPort.postMessage(message, transfer);
86 const serialize = (error) => {
87 const out = { message: String(error && error.message) };
88 for (const key of ["code", "errno", "syscall", "path", "spawnargs"]) {
89 if (error && error[key] !== undefined) out[key] = error[key];
90 }
91 return out;
92 };
93 parentPort.on("message", (request) => {
94 const { id } = request;
95 if (request.type === "spawn") {
96 let child;
97 try {
98 child = locked(() => spawn(request.command, request.args, request.options));
99 } catch (error) {
100 post({ type: "error", id, error: serialize(error) });
101 return;
102 }
103 children.set(id, child);
104 child.on("spawn", () => post({ type: "spawn", id, pid: child.pid }));
105 child.on("error", (error) => post({ type: "error", id, error: serialize(error) }));
106 child.on("exit", (code, signal) => post({ type: "exit", id, code, signal }));
107 // Output can still arrive after exit; close follows the last of it.
108 child.on("close", () => {
109 children.delete(id);
110 post({ type: "close", id });
111 });
112 child.stdio?.forEach((stream, fd) => {
113 if (!stream) return;
114 stream.on("error", (error) => post({ type: "stream-error", id, fd, error: serialize(error) }));
115 if (fd === 0) return;
116 // Cloning a Buffer copies its whole backing store; copy the bytes once and transfer them.
117 stream.on("data", (chunk) => {
118 const data = new Uint8Array(chunk);
119 post({ type: "data", id, fd, data }, [data.buffer]);
120 });
121 stream.on("end", () => post({ type: "eof", id, fd }));
122 });
123 return;
124 }
125 const child = children.get(id);
126 if (child === undefined) {
127 if (request.type === "write") post({ type: "written", id, fd: request.fd, error: { message: "write after exit", code: "EPIPE" } });
128 if (request.type === "end") post({ type: "finished", id, fd: request.fd });
129 return;
130 }
131 const stream = child.stdio?.[request.fd];
132 switch (request.type) {
133 case "write":
134 if (!stream || stream.destroyed) {
135 post({ type: "written", id, fd: request.fd, error: { message: "write after end", code: "EPIPE" } });
136 return;
137 }
138 try {
139 stream.write(request.data, (error) => post({ type: "written", id, fd: request.fd, error: error ? serialize(error) : undefined }));
140 } catch (error) {
141 post({ type: "written", id, fd: request.fd, error: serialize(error) });
142 }
143 return;
144 case "end":
145 if (!stream || stream.destroyed || stream.writableFinished) post({ type: "finished", id, fd: request.fd });
146 else stream.end(() => post({ type: "finished", id, fd: request.fd }));
147 return;
148 case "flow":
149 if (request.paused) stream?.pause();
150 else stream?.resume();
151 return;
152 case "destroy":
153 stream?.destroy();
154 return;
155 case "kill":
156 try {
157 child.kill(request.signal);
158 } catch {}
159 return;
160 }
161 });
162 `;
163
164 const toError = (serialized: SerializedError) =>
165 Object.assign(new Error(serialized.message), serialized);
166
167 const toBuffer = (data: Uint8Array) => Buffer.from(data.buffer, data.byteOffset, data.byteLength);
168
169 class WorkerChild
170 extends NodeEvents.EventEmitter
171 implements NodeChildProcessSpawner.SpawnedChildProcess
172 {
173 pid: number | undefined;
174 exitCode: number | null = null;
175 signalCode: NodeJS.Signals | null = null;
176 stdin: NodeStream.Writable | null = null;
177 stdout: NodeStream.Readable | null = null;
178 stderr: NodeStream.Readable | null = null;
179 readonly stdio: Array<NodeStream.Readable | NodeStream.Writable | null | undefined> = [];
180 referenced = true;
181 killed = false;
182 spawned = false;
183 exited = false;
184 readonly #writes = new Map<number, Array<(error?: Error | null) => void>>();
185 readonly #finals = new Map<number, (error?: Error | null) => void>();
186 readonly #paused = new Set<number>();
187
188 readonly worker: SpawnWorker;
189 readonly id: number;
190
191 constructor(worker: SpawnWorker, id: number, stdio: ReadonlyArray<unknown>) {
192 super();
193 this.worker = worker;
194 this.id = id;
195 stdio.forEach((option, fd) => {
196 if (option !== "pipe" && option !== "overlapped") return;
197 const stream = this.#relay(fd);
198 this.stdio[fd] = stream;
199 if (fd === 0) this.stdin = stream as NodeStream.Writable;
200 else if (fd === 1) this.stdout = stream as NodeStream.Readable;
201 else if (fd === 2) this.stderr = stream as NodeStream.Readable;
202 });
203 }
204
205 #relay(fd: number): NodeStream.Readable | NodeStream.Writable {
206 const read = () => {
207 if (this.#paused.delete(fd))
208 this.worker.post({ type: "flow", id: this.id, fd, paused: false });
209 };
210 const write = (
211 chunk: Buffer,
212 _encoding: BufferEncoding,
213 callback: (error?: Error | null) => void,
214 ) => {
215 if (this.worker.closed) {
216 callback(Object.assign(new Error("write EPIPE"), { code: "EPIPE" }));
217 return;
218 }
219 const pending = this.#writes.get(fd) ?? [];
220 pending.push(callback);
221 this.#writes.set(fd, pending);
222 const data = new Uint8Array(chunk);
223 this.worker.post({ type: "write", id: this.id, fd, data }, [data.buffer]);
224 };
225 const final = (callback: (error?: Error | null) => void) => {
226 this.#finals.set(fd, callback);
227 this.worker.post({ type: "end", id: this.id, fd });
228 };
229 // A caller that destroys its end closes the child pipe, as it would with a real pipe.
230 const destroy = (error: Error | null, callback: (error?: Error | null) => void) => {
231 if (!this.exited) this.worker.post({ type: "destroy", id: this.id, fd });
232 callback(error);
233 };
234 if (fd === 0) return new NodeStream.Writable({ write, final, destroy });
235 if (fd <= 2) return new NodeStream.Readable({ read, destroy });
236 return new NodeStream.Duplex({ read, write, final, destroy, allowHalfOpen: true });
237 }
238
239 onData(fd: number, data: Uint8Array): void {
240 const stream = this.stdio[fd];
241 if (!stream || !("push" in stream)) return;
242 if (!stream.push(toBuffer(data)) && !this.#paused.has(fd)) {
243 this.#paused.add(fd);
244 this.worker.post({ type: "flow", id: this.id, fd, paused: true });
245 }
246 }
247
248 onEof(fd: number): void {
249 const stream = this.stdio[fd];
250 if (stream && "push" in stream) stream.push(null);
251 }
252
253 onFinished(fd: number): void {
254 const callback = this.#finals.get(fd);
255 this.#finals.delete(fd);
256 callback?.();
257 }
258
259 onWritten(fd: number, error: SerializedError | undefined): void {
260 const callback = this.#writes.get(fd)?.shift();
261 callback?.(error === undefined ? null : toError(error));
262 }
263
264 onStreamError(fd: number, error: SerializedError): void {
265 this.stdio[fd]?.destroy(toError(error));
266 }
267
268 kill(signal: NodeJS.Signals | number = "SIGTERM"): boolean {
269 if (this.exited) return false;
270 this.killed = true;
271 this.worker.post({ type: "kill", id: this.id, signal });
272 return true;
273 }
274
275 ref(): void {
276 this.referenced = true;
277 this.worker.syncRef();
278 }
279
280 unref(): void {
281 this.referenced = false;
282 this.worker.syncRef();
283 }
284
285 exit(code: number | null, signal: NodeJS.Signals | null): void {
286 if (this.exited) return;
287 this.exited = true;
288 this.exitCode = code;
289 this.signalCode = signal;
290 // Node destroys stdin on exit; the Effect sink may already have removed its error listener.
291 this.stdin?.on("error", () => {});
292 this.stdin?.destroy();
293 this.emit("exit", code, signal);
294 }
295
296 /** The worker is gone: end output so readers finish, and let the exit report the kill. */
297 abandon(): void {
298 // Not destroy(error): Effect leaves an unread stderr's pipe without an error listener.
299 for (const stream of this.stdio) {
300 if (stream && "push" in stream && !stream.readableEnded) stream.push(null);
301 else if (stream && !("push" in stream)) stream.destroy();
302 }
303 }
304 }
305
306 class SpawnWorker {
307 readonly worker: NodeWorkerThreads.Worker;
308 readonly children = new Map<number, WorkerChild>();
309 readonly pool: SpawnWorkerPool;
310 /** Node sets `worker.threadId` to -1 once the thread exits, so keep the id the lock holds. */
311 readonly threadId: number;
312 /** Launches sent but not yet answered; the worker is inside CreateProcess for one of them. */
313 launching = 0;
314 closed = false;
315
316 constructor(pool: SpawnWorkerPool) {
317 this.pool = pool;
318 this.worker = new NodeWorkerThreads.Worker(workerSource, {
319 eval: true,
320 workerData: { lock: pool.platform === "win32" ? windowsSpawnLock : undefined },
321 });
322 this.threadId = this.worker.threadId;
323 this.worker.on("message", (message: FromWorker) => this.onMessage(message));
324 this.worker.on("error", (error) => this.fail(error));
325 this.worker.on("exit", () => this.fail(new Error("The process launcher thread exited.")));
326 this.worker.unref();
327 }
328
329 post(message: ToWorker, transfer?: ReadonlyArray<ArrayBuffer>): void {
330 if (!this.closed) this.worker.postMessage(message, transfer);
331 }
332
333 spawn(
334 id: number,
335 command: string,
336 args: ReadonlyArray<string>,
337 options: NodeChildProcess.SpawnOptions,
338 ): WorkerChild {
339 const io = options.stdio;
340 const stdio =
341 typeof io === "string" || io === undefined ? [io ?? "pipe", io ?? "pipe", io ?? "pipe"] : io;
342 const child = new WorkerChild(this, id, stdio);
343 // An AbortSignal cannot cross to the worker, so this thread kills on abort as Node would.
344 const { signal, ...rest } = options;
345 if (signal !== undefined) {
346 const abort = () => child.kill();
347 if (signal.aborted) queueMicrotask(abort);
348 else {
349 signal.addEventListener("abort", abort, { once: true });
350 child.once("exit", () => signal.removeEventListener("abort", abort));
351 }
352 }
353 this.children.set(id, child);
354 this.launching++;
355 this.syncRef();
356 this.post({
357 type: "spawn",
358 id,
359 command,
360 args: [...args],
361 // A worker's process.env is a copy from when it started; children get the server's current one.
362 options: { ...rest, stdio, env: rest.env ?? { ...process.env } },
363 });
364 return child;
365 }
366
367 syncRef(): void {
368 if (this.closed) return;
369 const referenced =
370 this.launching > 0 || [...this.children.values()].some((child) => child.referenced);
371 if (referenced) this.worker.ref();
372 else this.worker.unref();
373 }
374
375 onMessage(message: FromWorker): void {
376 const child = this.children.get(message.id);
377 if (child === undefined) return;
378 switch (message.type) {
379 case "spawn":
380 this.launching--;
381 child.spawned = true;
382 child.pid = message.pid;
383 child.emit("spawn");
384 break;
385 case "error":
386 if (!child.spawned) {
387 this.launching--;
388 child.exited = true;
389 this.release(child);
390 }
391 child.emit("error", toError(message.error));
392 break;
393 case "data":
394 child.onData(message.fd, message.data);
395 break;
396 case "written":
397 child.onWritten(message.fd, message.error);
398 break;
399 case "eof":
400 child.onEof(message.fd);
401 break;
402 case "finished":
403 child.onFinished(message.fd);
404 break;
405 case "stream-error":
406 child.onStreamError(message.fd, message.error);
407 break;
408 case "exit":
409 child.exit(message.code, message.signal);
410 break;
411 case "close":
412 child.emit("close", child.exitCode, child.signalCode);
413 this.release(child);
414 break;
415 }
416 }
417
418 release(child: WorkerChild): void {
419 this.children.delete(child.id);
420 this.syncRef();
421 this.pool.release(this);
422 }
423
424 fail(error: Error): void {
425 if (this.closed) return;
426 this.close();
427 for (const child of this.children.values()) {
428 if (child.exited) {
429 child.abandon();
430 continue;
431 }
432 if (!child.spawned) {
433 child.exited = true;
434 child.emit("error", error);
435 continue;
436 }
437 // The worker owned the only handle, so try to end the whole tree before reporting the exit.
438 const finish = () => {
439 child.exit(null, "SIGKILL");
440 child.abandon();
441 };
442 if (child.pid === undefined) finish();
443 else this.pool.killTree(child.pid, finish);
444 }
445 this.children.clear();
446 }
447
448 close(): void {
449 if (this.closed) return;
450 this.closed = true;
451 this.pool.workers.delete(this);
452 void this.worker.terminate().then(() => {
453 // The thread may have died holding the lock, or between its unlock and notify, or after
454 // a notify woke it: free the lock and wake every waiter so none sleeps on a free lock.
455 Atomics.compareExchange(windowsSpawnLock, 0, this.threadId, 0);
456 Atomics.notify(windowsSpawnLock, 0);
457 });
458 }
459 }
460
461 class SpawnWorkerPool {
462 readonly workers = new Set<SpawnWorker>();
463 readonly platform: NodeJS.Platform;
464 #nextId = 0;
465
466 constructor(platform: NodeJS.Platform) {
467 this.platform = platform;
468 }
469
470 readonly spawn = (
471 command: string,
472 args: ReadonlyArray<string>,
473 options: NodeChildProcess.SpawnOptions,
474 ) => {
475 const workers = [...this.workers];
476 // A worker inside CreateProcess cannot start another launch until it returns.
477 const worker =
478 workers.find((candidate) => candidate.launching === 0) ??
479 (workers.length < MAX_WORKERS
480 ? this.#add()
481 : workers.reduce((best, candidate) =>
482 candidate.launching < best.launching ? candidate : best,
483 ));
484 return worker.spawn(++this.#nextId, command, args, options);
485 };
486
487 killTree(pid: number, done: () => void): void {
488 const killPid = () => {
489 try {
490 process.kill(pid, "SIGKILL");
491 } catch {}
492 };
493 if (this.platform !== "win32") {
494 killPid();
495 done();
496 return;
497 }
498 let settled = false;
499 const finish = (killed: boolean) => {
500 if (settled) return;
501 settled = true;
502 // As Effect's own kill does when taskkill fails, end at least the direct child.
503 if (!killed) killPid();
504 done();
505 };
506 this.spawn("taskkill", ["/pid", String(pid), "/T", "/F"], {
507 stdio: "ignore",
508 windowsHide: true,
509 })
510 .on("error", () => finish(false))
511 .on("exit", (code) => finish(code === 0));
512 }
513
514 #add(): SpawnWorker {
515 const worker = new SpawnWorker(this);
516 this.workers.add(worker);
517 return worker;
518 }
519
520 release(worker: SpawnWorker): void {
521 if (worker.children.size > 0 || worker.launching > 0) return;
522 const idle = [...this.workers].filter(
523 (candidate) => candidate.children.size === 0 && candidate.launching === 0,
524 );
525 if (idle.length > MAX_IDLE_WORKERS) worker.close();
526 }
527
528 close(): void {
529 for (const worker of this.workers) worker.close();
530 }
531 }
532
533 let sharedPool: SpawnWorkerPool | undefined;
534
535 /** A piped `child_process.spawn` for Windows launches outside Effect's spawner. */
536 export const spawnPiped = (
537 command: string,
538 args: ReadonlyArray<string>,
539 options: Omit<NodeChildProcess.SpawnOptions, "stdio">,
540 ) =>
541 (sharedPool ??= new SpawnWorkerPool("win32")).spawn(command, args, {
542 ...options,
543 stdio: ["pipe", "pipe", "pipe"],
544 }) as WorkerChild & {
545 readonly stdin: NodeStream.Writable;
546 readonly stdout: NodeStream.Readable;
547 readonly stderr: NodeStream.Readable;
548 };
549
550 export const layer = Layer.unwrap(
551 Effect.gen(function* () {
552 const platform = yield* HostProcess.Platform;
553 const pool = yield* Effect.acquireRelease(
554 Effect.sync(() => new SpawnWorkerPool(platform)),
555 (pool) => Effect.sync(() => pool.close()),
556 );
557 return NodeChildProcessSpawner.layerWithSpawn(pool.spawn);
558 }),
559 );
560
561 /** Workers on Windows, and on Linux where `NonBlockingSpawner` has no GNU `env -C` to use. */
562 export const layerServer = Layer.unwrap(
563 Effect.gen(function* () {
564 const platform = yield* HostProcess.Platform;
565 if (platform === "win32") return layer;
566 if (platform === "linux" && !(yield* Effect.promise(supportsEnvChdir))) return layer;
567 return NodeChildProcessSpawner.layer;
568 }),
569 );