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

main
ts 533 lines 21.3 KB
Raw
1 import * as NodeServices from "@effect/platform-node/NodeServices";
2 import { describe, expect, it } from "@effect/vitest";
3 import * as Deferred from "effect/Deferred";
4 import * as Effect from "effect/Effect";
5 import * as Fiber from "effect/Fiber";
6 import * as Sink from "effect/Sink";
7 import * as TestClock from "effect/testing/TestClock";
8 import * as Result from "effect/Result";
9 import * as Stream from "effect/Stream";
10 import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
11 import * as HostProcess from "@t3tools/shared/HostProcess";
12
13 import {
14 makeAcpClientTerminals,
15 resolveEmbeddedTerminalContent,
16 type AcpClientTerminals,
17 } from "./clientTerminals.ts";
18
19 const withTerminals = <A, E>(use: (terminals: AcpClientTerminals) => Effect.Effect<A, E>) =>
20 Effect.gen(function* () {
21 const terminals = yield* makeAcpClientTerminals({
22 defaultCwd: process.cwd(),
23 });
24 return yield* use(terminals).pipe(Effect.ensuring(terminals.disposeAll));
25 }).pipe(Effect.provide(NodeServices.layer));
26
27 describe("AcpClientTerminals", () => {
28 it.live("runs a command, buffers output, and reports the exit status", () =>
29 withTerminals((terminals) =>
30 Effect.gen(function* () {
31 const created = yield* terminals.create({
32 sessionId: "session",
33 command: process.execPath,
34 args: ["-e", "console.log('hello from acp'); process.exit(3);"],
35 });
36
37 const exit = yield* terminals.waitForExit({
38 sessionId: "session",
39 terminalId: created.terminalId,
40 });
41 expect(exit.exitCode).toBe(3);
42
43 const output = yield* terminals.output({
44 sessionId: "session",
45 terminalId: created.terminalId,
46 });
47 expect(output.output).toContain("hello from acp");
48 expect(output.truncated).toBe(false);
49 expect(output.exitStatus?.exitCode).toBe(3);
50 }),
51 ),
52 );
53
54 it.effect("preserves UTF-8 when stderr interleaves a split stdout character", () =>
55 Effect.gen(function* () {
56 const stdoutStarted = yield* Deferred.make<void>();
57 const stderrWritten = yield* Deferred.make<void>();
58 const child = ChildProcessSpawner.makeHandle({
59 pid: ChildProcessSpawner.ProcessId(1),
60 exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(0)),
61 isRunning: Effect.succeed(false),
62 kill: () => Effect.void,
63 stdin: Sink.drain,
64 stdout: Stream.make(new Uint8Array([0xe2])).pipe(
65 Stream.concat(Stream.fromEffectDrain(Deferred.succeed(stdoutStarted, undefined))),
66 Stream.concat(Stream.fromEffectDrain(Deferred.await(stderrWritten))),
67 Stream.concat(Stream.make(new Uint8Array([0x82, 0xac]))),
68 ),
69 stderr: Stream.fromEffectDrain(Deferred.await(stdoutStarted)).pipe(
70 Stream.concat(Stream.make(new Uint8Array([0x58]))),
71 Stream.concat(Stream.fromEffectDrain(Deferred.succeed(stderrWritten, undefined))),
72 ),
73 all: Stream.empty,
74 getInputFd: () => Sink.drain,
75 getOutputFd: () => Stream.empty,
76 unref: Effect.succeed(Effect.void),
77 });
78 const terminals = yield* makeAcpClientTerminals({ defaultCwd: process.cwd() }).pipe(
79 Effect.provideService(
80 ChildProcessSpawner.ChildProcessSpawner,
81 ChildProcessSpawner.make(() => Effect.succeed(child)),
82 ),
83 );
84 yield* Effect.addFinalizer(() => terminals.disposeAll);
85 const terminal = yield* terminals.create({ sessionId: "session", command: "fixture" });
86 const request = { sessionId: "session", ...terminal };
87 yield* terminals.waitForExit(request);
88
89 const output = yield* terminals.output(request);
90 expect(output.output).toContain("€");
91 expect(output.output).toContain("X");
92 expect(output.output).not.toContain("\uFFFD");
93 expect(output.truncated).toBe(false);
94 expect(terminals.readOutputSnapshot("session", terminal.terminalId)?.output).toBe(
95 output.output,
96 );
97 }),
98 );
99
100 it.live("resolves terminal environment from the requesting ACP session", () =>
101 Effect.gen(function* () {
102 const inheritedEnvironment = yield* HostProcess.Environment;
103 const terminals = yield* makeAcpClientTerminals({
104 defaultCwd: process.cwd(),
105 environmentForSession: (sessionId) =>
106 sessionId === "unknown"
107 ? undefined
108 : {
109 T3_ACP_MCP_AUTHORIZATION: sessionId === "session-a" ? "token-a" : "token-b",
110 T3CODE_THREAD_ID: sessionId,
111 },
112 });
113 yield* Effect.addFinalizer(() => terminals.disposeAll);
114 inheritedEnvironment.T3_TEST_INHERITED = "refreshed";
115
116 for (const [sessionId, expected] of [
117 ["session-a", "token-a||session-a|refreshed|T3_TEST_OVERRIDE=request"],
118 ["session-b", "token-b||session-b|refreshed|T3_TEST_OVERRIDE=request"],
119 ["unknown", "|||refreshed|T3_TEST_OVERRIDE=inherited"],
120 ] as const) {
121 const created = yield* terminals.create({
122 sessionId,
123 command: process.execPath,
124 args: [
125 "-e",
126 "const env = process.env; process.stdout.write([env.T3_ACP_MCP_AUTHORIZATION ?? '', env.t3_Acp_Mcp_Endpoint ?? '', env.T3CODE_THREAD_ID ?? '', env.T3_TEST_INHERITED, ...Object.keys(env).filter((name) => name.toUpperCase() === 'T3_TEST_OVERRIDE').map((name) => name + '=' + env[name])].join('|'))",
127 ],
128 ...(sessionId === "unknown"
129 ? {}
130 : {
131 env: [
132 { name: "T3_TEST_OVERRIDE", value: "first" },
133 { name: "t3_Test_Override", value: "second" },
134 { name: "T3_TEST_OVERRIDE", value: "request" },
135 ],
136 }),
137 });
138 yield* terminals.waitForExit({ sessionId, terminalId: created.terminalId });
139 const output = yield* terminals.output({ sessionId, terminalId: created.terminalId });
140 expect(output.output).toBe(expected);
141 }
142 }).pipe(
143 Effect.provideService(HostProcess.Environment, {
144 ...process.env,
145 T3_ACP_MCP_AUTHORIZATION: "launching-thread-token",
146 t3_Acp_Mcp_Endpoint: "launching-thread-endpoint",
147 T3CODE_THREAD_ID: "launching-thread",
148 T3_TEST_INHERITED: "kept",
149 T3_TEST_OVERRIDE: "inherited",
150 }),
151 // Exercise Windows' case-insensitive variable names on every OS.
152 Effect.provideService(HostProcess.Platform, "win32"),
153 Effect.provide(NodeServices.layer),
154 ),
155 );
156
157 it.live("runs Devin shell source with arguments, pipes, and session fallback variables", () =>
158 Effect.gen(function* () {
159 const terminals = yield* makeAcpClientTerminals({
160 defaultCwd: process.cwd(),
161 shellCommands: true,
162 environmentForSession: () => ({ T3_ACP_MCP_NODE: "mailbox-probe" }),
163 });
164 yield* Effect.addFinalizer(() => terminals.disposeAll);
165 const terminal = yield* terminals.create({
166 sessionId: "devin",
167 command: 'printf "%s\\n" "$T3_ACP_MCP_NODE" | tr a-z A-Z',
168 });
169 const exit = yield* terminals.waitForExit({ sessionId: "devin", ...terminal });
170 const output = yield* terminals.output({ sessionId: "devin", ...terminal });
171 expect(exit.exitCode).toBe(0);
172 expect(output.output.trim()).toBe("MAILBOX-PROBE");
173 }).pipe(Effect.provide(NodeServices.layer)),
174 );
175
176 it.live.each([
177 { text: "a".repeat(64) + "TAIL", limit: 16 },
178 { text: "€".repeat(16) + "TAIL", limit: 6 },
179 ])("truncates buffered output from the beginning at the $limit byte limit", ({ text, limit }) =>
180 withTerminals((terminals) =>
181 Effect.gen(function* () {
182 const created = yield* terminals.create({
183 sessionId: "session",
184 command: process.execPath,
185 args: ["-e", `process.stdout.write(${JSON.stringify(text)});`],
186 outputByteLimit: limit,
187 });
188 yield* terminals.waitForExit({ sessionId: "session", terminalId: created.terminalId });
189
190 const output = yield* terminals.output({
191 sessionId: "session",
192 terminalId: created.terminalId,
193 });
194 expect(output.truncated).toBe(true);
195 expect(output.output.endsWith("TAIL")).toBe(true);
196 expect(Buffer.byteLength(output.output)).toBeLessThanOrEqual(limit);
197 expect(output.output).not.toContain("\uFFFD");
198 }),
199 ),
200 );
201
202 it.live("kills long-running commands and rejects released terminal handles", () =>
203 withTerminals((terminals) =>
204 Effect.gen(function* () {
205 const created = yield* terminals.create({
206 sessionId: "session",
207 command: process.execPath,
208 args: ["-e", "setInterval(() => {}, 1000);"],
209 });
210 yield* terminals.kill({ sessionId: "session", terminalId: created.terminalId });
211 const exit = yield* terminals.waitForExit({
212 sessionId: "session",
213 terminalId: created.terminalId,
214 });
215 expect(exit.exitCode === 0 ? null : exit.exitCode).not.toBe(0);
216 // Windows has no signals: a killed process only reports an exit code.
217 if (yield* HostProcess.isWindows) {
218 expect(exit.signal).toBeNull();
219 } else {
220 expect(exit.signal).toBe("SIGTERM");
221 }
222
223 yield* terminals.release({ sessionId: "session", terminalId: created.terminalId });
224 const rejected = yield* Effect.flip(
225 terminals.output({ sessionId: "session", terminalId: created.terminalId }),
226 );
227 expect(rejected.message).toContain("unknown terminal ID");
228
229 expect(terminals.readOutputSnapshot("session", created.terminalId)).toBeDefined();
230 }),
231 ),
232 );
233
234 it.effect("answers wait_for_exit when a background child keeps the output pipes open", () =>
235 Effect.gen(function* () {
236 // Models `sh -c "setsid server & echo done"`: sh exits, the orphan inherits stdout/stderr.
237 const orphanExited = yield* Deferred.make<void>();
238 const heldOpen = Stream.fromEffectDrain(Deferred.await(orphanExited));
239 const child = ChildProcessSpawner.makeHandle({
240 pid: ChildProcessSpawner.ProcessId(1),
241 exitCode: Effect.succeed(ChildProcessSpawner.ExitCode(0)),
242 isRunning: Effect.succeed(false),
243 kill: () => Effect.void,
244 stdin: Sink.drain,
245 stdout: Stream.make(new TextEncoder().encode("done\n")).pipe(Stream.concat(heldOpen)),
246 stderr: heldOpen,
247 all: Stream.empty,
248 getInputFd: () => Sink.drain,
249 getOutputFd: () => Stream.empty,
250 unref: Effect.succeed(Effect.void),
251 });
252 const terminals = yield* makeAcpClientTerminals({ defaultCwd: process.cwd() }).pipe(
253 Effect.provideService(
254 ChildProcessSpawner.ChildProcessSpawner,
255 ChildProcessSpawner.make(() => Effect.succeed(child)),
256 ),
257 );
258 yield* Effect.addFinalizer(() =>
259 Deferred.succeed(orphanExited, undefined).pipe(Effect.andThen(terminals.disposeAll)),
260 );
261 const terminal = yield* terminals.create({ sessionId: "session", command: "fixture" });
262 const request = { sessionId: "session", ...terminal };
263 const waiting = yield* terminals.waitForExit(request).pipe(Effect.forkChild);
264
265 yield* TestClock.adjust("5 seconds");
266 expect(waiting.pollUnsafe()).toBeDefined();
267 expect(yield* Fiber.join(waiting)).toEqual({ exitCode: 0, signal: null });
268 const output = yield* terminals.output(request);
269 expect(output.output).toBe("done\n");
270 expect(output.exitStatus).toEqual({ exitCode: 0, signal: null });
271 }),
272 );
273
274 it.effect.each([
275 { deadline: "default", forceKillAfter: undefined, deadlineMillis: 5000 },
276 { deadline: "configured", forceKillAfter: "250 millis" as const, deadlineMillis: 250 },
277 ])(
278 "waits for the $deadline deadline before force-killing a SIGTERM-ignoring terminal",
279 ({ forceKillAfter, deadlineMillis }) =>
280 Effect.gen(function* () {
281 const exited = yield* Deferred.make<ChildProcessSpawner.ExitCode>();
282 const child = ChildProcessSpawner.makeHandle({
283 pid: ChildProcessSpawner.ProcessId(1),
284 exitCode: Deferred.await(exited),
285 isRunning: Deferred.isDone(exited).pipe(Effect.map((done) => !done)),
286 // Model a process that only exits when the spawner escalates after its deadline.
287 kill: (options) =>
288 options?.forceKillAfter === undefined
289 ? Deferred.await(exited).pipe(Effect.asVoid)
290 : Effect.sleep(options.forceKillAfter).pipe(
291 Effect.andThen(Deferred.succeed(exited, ChildProcessSpawner.ExitCode(137))),
292 Effect.asVoid,
293 ),
294 stdin: Sink.drain,
295 stdout: Stream.empty,
296 stderr: Stream.empty,
297 all: Stream.empty,
298 getInputFd: () => Sink.drain,
299 getOutputFd: () => Stream.empty,
300 unref: Effect.succeed(Effect.void),
301 });
302 const terminals = yield* makeAcpClientTerminals({
303 defaultCwd: process.cwd(),
304 ...(forceKillAfter === undefined ? {} : { forceKillAfter }),
305 }).pipe(
306 Effect.provideService(
307 ChildProcessSpawner.ChildProcessSpawner,
308 ChildProcessSpawner.make(() => Effect.succeed(child)),
309 ),
310 );
311 yield* Effect.addFinalizer(() =>
312 Deferred.succeed(exited, ChildProcessSpawner.ExitCode(137)).pipe(
313 Effect.andThen(terminals.disposeAll),
314 ),
315 );
316 const terminal = yield* terminals.create({
317 sessionId: "session",
318 command: "ignores-SIGTERM",
319 });
320 const request = { sessionId: "session", ...terminal };
321 const killing = yield* terminals.kill(request).pipe(Effect.forkChild);
322 const waiting = yield* terminals.waitForExit(request).pipe(Effect.forkChild);
323
324 yield* TestClock.adjust(deadlineMillis - 1);
325 expect(yield* child.isRunning).toBe(true);
326 expect(killing.pollUnsafe()).toBeUndefined();
327 expect(waiting.pollUnsafe()).toBeUndefined();
328 yield* TestClock.adjust("1 millis");
329 expect(yield* child.isRunning).toBe(false);
330 yield* Fiber.join(killing);
331 expect(yield* Fiber.join(waiting)).toEqual({ exitCode: 137, signal: null });
332 }),
333 );
334
335 it.live("force-kills commands that ignore SIGTERM and resolves wait_for_exit", () =>
336 Effect.gen(function* () {
337 const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
338 const ready = yield* Deferred.make<void>();
339 const spawned = yield* Deferred.make<ChildProcessSpawner.ChildProcessHandle>();
340 let stdout = "";
341 const terminals = yield* makeAcpClientTerminals({
342 defaultCwd: process.cwd(),
343 forceKillAfter: "50 millis",
344 }).pipe(
345 Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, {
346 ...spawner,
347 spawn: (command) =>
348 spawner.spawn(command).pipe(
349 Effect.tap((child) => Deferred.succeed(spawned, child)),
350 Effect.map((child) => ({
351 ...child,
352 stdout: child.stdout.pipe(
353 Stream.tap((chunk) => {
354 stdout += Buffer.from(chunk).toString("utf8");
355 return stdout.includes("ready")
356 ? Deferred.succeed(ready, undefined)
357 : Effect.void;
358 }),
359 ),
360 })),
361 ),
362 }),
363 );
364 yield* Effect.addFinalizer(() => terminals.disposeAll);
365 const terminal = yield* terminals.create({
366 sessionId: "session",
367 command: process.execPath,
368 args: [
369 "-e",
370 "process.on('SIGTERM', () => {}); console.log('ready'); setInterval(() => {}, 1000);",
371 ],
372 });
373 const child = yield* Deferred.await(spawned);
374 // Reap only this test's captured child, including when the regression fails.
375 yield* Effect.addFinalizer(() => child.kill({ killSignal: "SIGKILL" }).pipe(Effect.ignore));
376 yield* Deferred.await(ready);
377
378 const request = { sessionId: "session", ...terminal };
379 yield* terminals.kill(request);
380 const exit = yield* terminals.waitForExit(request);
381 // Windows has no signals: the command is terminated without a signal name.
382 if (!(yield* HostProcess.isWindows)) {
383 expect(exit).toEqual({ exitCode: null, signal: "SIGKILL" });
384 }
385 expect(yield* child.isRunning).toBe(false);
386 }).pipe(Effect.provide(NodeServices.layer)),
387 );
388
389 it.live("reserves terminal capacity across concurrent creates", () =>
390 withTerminals((terminals) =>
391 Effect.gen(function* () {
392 const results = yield* Effect.all(
393 Array.from({ length: 17 }, () =>
394 terminals
395 .create({
396 sessionId: "session",
397 command: process.execPath,
398 args: ["-e", "setInterval(() => {}, 1000);"],
399 })
400 .pipe(Effect.result),
401 ),
402 { concurrency: "unbounded" },
403 );
404
405 expect(results.filter(Result.isSuccess)).toHaveLength(16);
406 expect(results.filter(Result.isFailure)).toHaveLength(1);
407 }),
408 ),
409 );
410
411 it.live("bounds unreleased terminal handles without invalidating existing ids", () =>
412 withTerminals((terminals) =>
413 Effect.gen(function* () {
414 const terminalIds: string[] = [];
415 for (let index = 0; index < 64; index += 1) {
416 const created = yield* terminals.create({
417 sessionId: "session",
418 command: process.execPath,
419 args: ["-e", `process.stdout.write('${index}');`],
420 });
421 yield* terminals.waitForExit({
422 sessionId: "session",
423 terminalId: created.terminalId,
424 });
425 terminalIds.push(created.terminalId);
426 }
427
428 const rejected = yield* terminals
429 .create({
430 sessionId: "session",
431 command: process.execPath,
432 args: ["-e", ""],
433 })
434 .pipe(Effect.result);
435 expect(Result.isFailure(rejected)).toBe(true);
436 expect(terminals.readOutputSnapshot("session", terminalIds[0]!)).toBeDefined();
437 expect(terminals.readOutputSnapshot("session", terminalIds.at(-1)!)).toBeDefined();
438 }),
439 ),
440 );
441
442 it.live("bounds aggregate output retained across unreleased terminals", () =>
443 withTerminals((terminals) =>
444 Effect.gen(function* () {
445 const terminalIds: string[] = [];
446 for (let index = 0; index < 3; index += 1) {
447 const created = yield* terminals.create({
448 sessionId: "session",
449 command: process.execPath,
450 args: ["-e", "process.stdout.write('x'.repeat(8 * 1024 * 1024));"],
451 outputByteLimit: 8 * 1024 * 1024,
452 });
453 yield* terminals.waitForExit({
454 sessionId: "session",
455 terminalId: created.terminalId,
456 });
457 terminalIds.push(created.terminalId);
458 }
459
460 const snapshots = terminalIds.map((terminalId) =>
461 terminals.readOutputSnapshot("session", terminalId)!,
462 );
463 const retainedBytes = snapshots.reduce(
464 (total, snapshot) => total + Buffer.byteLength(snapshot.output),
465 0,
466 );
467 expect(retainedBytes).toBeLessThanOrEqual(16 * 1024 * 1024);
468 expect(snapshots.some((snapshot) => snapshot.truncated)).toBe(true);
469 }),
470 ),
471 );
472
473 it.live("rejects terminal handles from a different ACP session", () =>
474 withTerminals((terminals) =>
475 Effect.gen(function* () {
476 const created = yield* terminals.create({
477 sessionId: "owner-session",
478 command: process.execPath,
479 args: ["-e", "process.stdout.write('owned');"],
480 });
481 const foreignRequest = {
482 sessionId: "foreign-session",
483 terminalId: created.terminalId,
484 };
485 const results = yield* Effect.forEach(
486 [
487 terminals.output(foreignRequest),
488 terminals.waitForExit(foreignRequest),
489 terminals.kill(foreignRequest),
490 terminals.release(foreignRequest),
491 ],
492 (effect) => effect.pipe(Effect.result),
493 { concurrency: "unbounded" },
494 );
495
496 expect(results.every(Result.isFailure)).toBe(true);
497 expect(terminals.readOutputSnapshot("foreign-session", created.terminalId)).toBeUndefined();
498 expect(terminals.readOutputSnapshot("owner-session", created.terminalId)).toBeDefined();
499 }),
500 ),
501 );
502 });
503
504 describe("resolveEmbeddedTerminalContent", () => {
505 it("rewrites terminal content into text from the buffered snapshot", () => {
506 const notification = {
507 sessionId: "session",
508 update: {
509 sessionUpdate: "tool_call_update" as const,
510 toolCallId: "call-1",
511 content: [
512 { type: "content" as const, content: { type: "text" as const, text: "before" } },
513 { type: "terminal" as const, terminalId: "t3-term-1" },
514 { type: "terminal" as const, terminalId: "t3-term-unknown" },
515 ],
516 },
517 };
518
519 const resolved = resolveEmbeddedTerminalContent(notification, (sessionId, terminalId) =>
520 sessionId === "session" && terminalId === "t3-term-1"
521 ? { output: "compiled 3 files", truncated: false, exitStatus: undefined }
522 : undefined,
523 );
524
525 expect(resolved.update).toMatchObject({
526 content: [
527 { type: "content", content: { type: "text", text: "before" } },
528 { type: "content", content: { type: "text", text: "compiled 3 files" } },
529 { type: "content", content: { type: "text", text: "[terminal t3-term-unknown]" } },
530 ],
531 });
532 });
533 });