@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 04:45 UTC

main
ts 456 lines 17.4 KB
Raw
1 import * as Channel from "effect/Channel";
2 import * as Deferred from "effect/Deferred";
3 import * as Duration from "effect/Duration";
4 import * as Effect from "effect/Effect";
5 import * as Exit from "effect/Exit";
6 import * as Fiber from "effect/Fiber";
7 import * as Scope from "effect/Scope";
8 import * as Semaphore from "effect/Semaphore";
9 import * as Stream from "effect/Stream";
10 import * as ChildProcess from "effect/process/ChildProcess";
11 import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
12 import * as EffectAcpErrors from "effect-acp/errors";
13 import type * as EffectAcpSchema from "effect-acp/compat";
14 import * as NodeBuffer from "node:buffer";
15 import * as HostProcess from "@t3tools/shared/HostProcess";
16
17 const MAX_LIVE_TERMINALS = 16;
18 const MAX_UNRELEASED_TERMINALS = 64;
19 const MAX_RETAINED_TERMINALS = 32;
20 const MAX_RETAINED_OUTPUT_BYTES = 16 * 1024 * 1024;
21 const DEFAULT_OUTPUT_BYTE_LIMIT = 4 * 1024 * 1024;
22 const MAX_OUTPUT_BYTE_LIMIT = 8 * 1024 * 1024;
23 const OUTPUT_DRAIN_GRACE = "1 second";
24
25 const terminalRequestError = (message: string, cause?: unknown) =>
26 EffectAcpErrors.AcpRequestError.internalError(
27 message,
28 undefined,
29 cause === undefined ? {} : { cause },
30 );
31
32 interface OutputBufferState {
33 chunks: Array<Uint8Array>;
34 bytes: number;
35 truncated: boolean;
36 readonly limit: number;
37 }
38
39 function trimOutputStart(state: OutputBufferState, bytes: number): void {
40 let remaining = Math.min(bytes, state.bytes);
41 while (remaining > 0) {
42 const head = state.chunks[0]!;
43 if (head.byteLength <= remaining) {
44 state.chunks.shift();
45 state.bytes -= head.byteLength;
46 remaining -= head.byteLength;
47 } else {
48 state.chunks[0] = head.subarray(remaining);
49 state.bytes -= remaining;
50 remaining = 0;
51 }
52 state.truncated = true;
53 }
54 }
55
56 function appendOutput(state: OutputBufferState, chunk: Uint8Array): void {
57 state.chunks.push(chunk);
58 state.bytes += chunk.byteLength;
59 // The spec requires truncation from the beginning of the output.
60 if (state.bytes > state.limit) trimOutputStart(state, state.bytes - state.limit);
61 }
62
63 function readOutput(state: OutputBufferState): string {
64 let combined: Uint8Array = NodeBuffer.Buffer.concat(state.chunks, state.bytes);
65 if (state.truncated) {
66 // The spec requires truncation at a UTF-8 character boundary.
67 let start = 0;
68 while (start < combined.byteLength && (combined[start]! & 0b1100_0000) === 0b1000_0000) {
69 start += 1;
70 }
71 combined = combined.subarray(start);
72 }
73 return NodeBuffer.Buffer.from(combined).toString("utf8");
74 }
75
76 function terminalExitSignal(error: unknown): string | null {
77 const cause = error instanceof Error ? error.cause : undefined;
78 const message =
79 cause instanceof Error ? cause.message : error instanceof Error ? error.message : "";
80 return message.match(/signal: '([^']+)'/u)?.[1] ?? null;
81 }
82
83 export interface AcpTerminalOutputSnapshot {
84 readonly output: string;
85 readonly truncated: boolean;
86 readonly exitStatus: EffectAcpSchema.TerminalExitStatus | undefined;
87 }
88
89 interface ManagedAcpTerminal {
90 readonly terminalId: string;
91 readonly sessionId: string;
92 readonly commandLine: string;
93 readonly buffer: OutputBufferState;
94 readonly exit: Deferred.Deferred<EffectAcpSchema.WaitForTerminalExitResponse>;
95 readonly kill: Effect.Effect<void>;
96 readonly dispose: Effect.Effect<void>;
97 exitStatus: EffectAcpSchema.TerminalExitStatus | undefined;
98 released: boolean;
99 }
100
101 export interface AcpClientTerminals {
102 readonly create: (
103 request: EffectAcpSchema.CreateTerminalRequest,
104 ) => Effect.Effect<EffectAcpSchema.CreateTerminalResponse, EffectAcpErrors.AcpRequestError>;
105 readonly output: (
106 request: EffectAcpSchema.TerminalOutputRequest,
107 ) => Effect.Effect<EffectAcpSchema.TerminalOutputResponse, EffectAcpErrors.AcpRequestError>;
108 readonly waitForExit: (
109 request: EffectAcpSchema.WaitForTerminalExitRequest,
110 ) => Effect.Effect<EffectAcpSchema.WaitForTerminalExitResponse, EffectAcpErrors.AcpRequestError>;
111 readonly kill: (
112 request: EffectAcpSchema.KillTerminalRequest,
113 ) => Effect.Effect<EffectAcpSchema.KillTerminalResponse, EffectAcpErrors.AcpRequestError>;
114 readonly release: (
115 request: EffectAcpSchema.ReleaseTerminalRequest,
116 ) => Effect.Effect<EffectAcpSchema.ReleaseTerminalResponse, EffectAcpErrors.AcpRequestError>;
117 /** Buffered output for embedded tool-call content; survives release. */
118 readonly readOutputSnapshot: (
119 sessionId: string,
120 terminalId: string,
121 ) => AcpTerminalOutputSnapshot | undefined;
122 readonly readCommandLine: (terminalId: string) => string | undefined;
123 readonly disposeAll: Effect.Effect<void>;
124 }
125
126 export interface AcpClientTerminalsOptions {
127 /** Devin sends shell source in command, rather than an executable plus args. */
128 readonly shellCommands?: boolean | undefined;
129 readonly defaultCwd: string;
130 readonly environment?: NodeJS.ProcessEnv | undefined;
131 readonly environmentForSession?:
132 | ((sessionId: string) => NodeJS.ProcessEnv | undefined)
133 | undefined;
134 readonly forceKillAfter?: Duration.Input | undefined;
135 }
136
137 function acpTerminalCommand(input: {
138 readonly request: EffectAcpSchema.CreateTerminalRequest;
139 readonly shellCommands?: boolean | undefined;
140 readonly defaultCwd: string;
141 readonly environment: NodeJS.ProcessEnv;
142 readonly forceKillAfter: Duration.Input;
143 }) {
144 return ChildProcess.make(input.request.command, input.request.args ?? [], {
145 cwd: input.request.cwd ?? input.defaultCwd,
146 env: input.environment,
147 shell: input.shellCommands === true && (input.request.args?.length ?? 0) === 0,
148 forceKillAfter: input.forceKillAfter,
149 });
150 }
151
152 // Windows variable names are case-insensitive and Node passes only one spelling to the child,
153 // so a later layer's `Path` must replace an earlier `PATH` rather than sit beside it.
154 function mergeEnvironments(
155 isWindows: boolean,
156 layers: ReadonlyArray<Iterable<readonly [string, string | undefined]>>,
157 ) {
158 const variables = new Map<string, readonly [string, string | undefined]>();
159 for (const layer of layers) {
160 for (const [name, value] of layer) {
161 variables.set(isWindows ? name.toUpperCase() : name, [name, value]);
162 }
163 }
164 return Object.fromEntries(variables.values());
165 }
166
167 export const makeAcpClientTerminals = Effect.fn("makeAcpClientTerminals")(function* (
168 options: AcpClientTerminalsOptions,
169 ): Effect.fn.Return<AcpClientTerminals, never, ChildProcessSpawner.ChildProcessSpawner> {
170 const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
171 const forceKillAfter = options.forceKillAfter ?? "5 seconds";
172 const isWindows = yield* HostProcess.isWindows;
173 const creationPermit = yield* Semaphore.make(1);
174 const terminals = new Map<string, ManagedAcpTerminal>();
175 let nextTerminalNumber = 1;
176
177 const enforceTotalOutputLimit = (): void => {
178 let excess =
179 Array.from(terminals.values()).reduce((total, terminal) => total + terminal.buffer.bytes, 0) -
180 MAX_RETAINED_OUTPUT_BYTES;
181 if (excess <= 0) return;
182 for (const terminal of terminals.values()) {
183 const before = terminal.buffer.bytes;
184 trimOutputStart(terminal.buffer, excess);
185 excess -= before - terminal.buffer.bytes;
186 if (excess <= 0) return;
187 }
188 };
189
190 const pruneReleasedSnapshots = (): void => {
191 const released = Array.from(terminals.values()).filter((terminal) => terminal.released);
192 let retainedBytes = released.reduce((total, terminal) => total + terminal.buffer.bytes, 0);
193 while (released.length > MAX_RETAINED_TERMINALS || retainedBytes > MAX_RETAINED_OUTPUT_BYTES) {
194 const terminal = released.shift();
195 if (terminal === undefined) break;
196 retainedBytes -= terminal.buffer.bytes;
197 terminals.delete(terminal.terminalId);
198 }
199 };
200
201 const requireTerminal = (
202 sessionId: string,
203 terminalId: string,
204 operation: string,
205 ): Effect.Effect<ManagedAcpTerminal, EffectAcpErrors.AcpRequestError> => {
206 const terminal = terminals.get(terminalId);
207 if (terminal === undefined || terminal.sessionId !== sessionId || terminal.released) {
208 return Effect.fail(
209 terminalRequestError(`ACP ${operation} received an unknown terminal ID '${terminalId}'.`),
210 );
211 }
212 return Effect.succeed(terminal);
213 };
214
215 const create: AcpClientTerminals["create"] = (request) =>
216 creationPermit.withPermit(
217 Effect.uninterruptibleMask((restore) =>
218 Effect.gen(function* () {
219 const liveCount = Array.from(terminals.values()).filter(
220 (terminal) => !terminal.released && terminal.exitStatus === undefined,
221 ).length;
222 const unreleasedCount = Array.from(terminals.values()).filter(
223 (terminal) => !terminal.released,
224 ).length;
225 if (unreleasedCount >= MAX_UNRELEASED_TERMINALS) {
226 return yield* terminalRequestError(
227 `ACP terminal/create exceeded the limit of ${MAX_UNRELEASED_TERMINALS} unreleased terminals.`,
228 );
229 }
230 if (liveCount >= MAX_LIVE_TERMINALS) {
231 return yield* terminalRequestError(
232 `ACP terminal/create exceeded the limit of ${MAX_LIVE_TERMINALS} concurrent terminals.`,
233 );
234 }
235 // Thread credentials and identity must come from the requesting session.
236 const inheritedEnvironment = Object.fromEntries(
237 Object.entries(options.environment ?? (yield* HostProcess.Environment)).filter(
238 ([name]) =>
239 !name.toUpperCase().startsWith("T3_ACP_MCP_") &&
240 name.toUpperCase() !== "T3CODE_THREAD_ID",
241 ),
242 );
243 const sessionEnvironment = options.environmentForSession?.(request.sessionId);
244 const environment = mergeEnvironments(isWindows, [
245 Object.entries(inheritedEnvironment),
246 Object.entries(sessionEnvironment ?? {}),
247 (request.env ?? []).map((variable) => [variable.name, variable.value] as const),
248 ]);
249 const terminalScope = yield* Scope.make();
250 const child = yield* restore(
251 spawner
252 .spawn(
253 acpTerminalCommand({
254 request,
255 shellCommands: options.shellCommands,
256 defaultCwd: options.defaultCwd,
257 environment,
258 forceKillAfter,
259 }),
260 )
261 .pipe(
262 Effect.provideService(Scope.Scope, terminalScope),
263 Effect.mapError((cause) =>
264 terminalRequestError(
265 `Could not start terminal command '${request.command}'.`,
266 cause,
267 ),
268 ),
269 ),
270 ).pipe(
271 Effect.onExit((exit) =>
272 Exit.isFailure(exit) ? Scope.close(terminalScope, Exit.void) : Effect.void,
273 ),
274 );
275
276 const terminalId = `t3-term-${nextTerminalNumber}`;
277 nextTerminalNumber += 1;
278 const record: ManagedAcpTerminal = {
279 terminalId,
280 sessionId: request.sessionId,
281 commandLine: [request.command, ...(request.args ?? [])].join(" "),
282 buffer: {
283 chunks: [],
284 bytes: 0,
285 truncated: false,
286 limit: Math.min(
287 request.outputByteLimit ?? DEFAULT_OUTPUT_BYTE_LIMIT,
288 MAX_OUTPUT_BYTE_LIMIT,
289 ),
290 },
291 exit: yield* Deferred.make<EffectAcpSchema.WaitForTerminalExitResponse>(),
292 // The spawner only applies the command's forceKillAfter on scope close;
293 // an explicit kill must pass it or a SIGTERM-ignoring command never exits.
294 kill: child.kill({ forceKillAfter }).pipe(Effect.ignore),
295 dispose: Scope.close(terminalScope, Exit.void).pipe(Effect.ignore),
296 exitStatus: undefined,
297 released: false,
298 };
299 terminals.set(terminalId, record);
300
301 const pump = (stream: typeof child.stdout) =>
302 stream.pipe(
303 // Keep each pipe's UTF-8 decoder independent and preserve literal BOMs.
304 Stream.pipeThroughChannel(Channel.decodeText("utf-8", { ignoreBOM: true })),
305 Stream.encodeText,
306 Stream.runForEach((chunk) =>
307 Effect.sync(() => {
308 appendOutput(record.buffer, chunk);
309 enforceTotalOutputLimit();
310 }),
311 ),
312 Effect.ignore,
313 );
314 const stdoutPump = yield* Effect.forkDetach(pump(child.stdout));
315 const stderrPump = yield* Effect.forkDetach(pump(child.stderr));
316 yield* Effect.forkDetach(
317 child.exitCode.pipe(
318 Effect.match({
319 onFailure: (error) => ({ exitCode: null, signal: terminalExitSignal(error) }),
320 onSuccess: (code) => ({ exitCode: Number(code), signal: null }),
321 }),
322 Effect.flatMap((status) =>
323 Effect.all([Fiber.join(stdoutPump), Fiber.join(stderrPump)], {
324 discard: true,
325 }).pipe(
326 // A background child can inherit the pipes and hold them open indefinitely.
327 Effect.timeoutOption(OUTPUT_DRAIN_GRACE),
328 Effect.andThen(
329 Effect.sync(() => {
330 record.exitStatus = status;
331 }),
332 ),
333 Effect.andThen(Deferred.succeed(record.exit, status)),
334 ),
335 ),
336 ),
337 );
338 return { terminalId };
339 }),
340 ),
341 );
342
343 const output: AcpClientTerminals["output"] = (request) =>
344 requireTerminal(request.sessionId, request.terminalId, "terminal/output").pipe(
345 Effect.map((terminal) => ({
346 output: readOutput(terminal.buffer),
347 truncated: terminal.buffer.truncated,
348 ...(terminal.exitStatus === undefined ? {} : { exitStatus: terminal.exitStatus }),
349 })),
350 );
351
352 const waitForExit: AcpClientTerminals["waitForExit"] = (request) =>
353 requireTerminal(request.sessionId, request.terminalId, "terminal/wait_for_exit").pipe(
354 Effect.flatMap((terminal) => Deferred.await(terminal.exit)),
355 );
356
357 const kill: AcpClientTerminals["kill"] = (request) =>
358 requireTerminal(request.sessionId, request.terminalId, "terminal/kill").pipe(
359 Effect.flatMap((terminal) => terminal.kill),
360 Effect.as({}),
361 );
362
363 const release: AcpClientTerminals["release"] = (request) =>
364 Effect.uninterruptible(
365 requireTerminal(request.sessionId, request.terminalId, "terminal/release").pipe(
366 Effect.flatMap((terminal) =>
367 Effect.sync(() => {
368 terminal.released = true;
369 }).pipe(
370 Effect.andThen(terminal.dispose),
371 Effect.andThen(Deferred.await(terminal.exit)),
372 Effect.andThen(Effect.sync(pruneReleasedSnapshots)),
373 ),
374 ),
375 Effect.as({}),
376 ),
377 );
378
379 const readOutputSnapshot: AcpClientTerminals["readOutputSnapshot"] = (sessionId, terminalId) => {
380 const terminal = terminals.get(terminalId);
381 if (terminal === undefined || terminal.sessionId !== sessionId) return undefined;
382 return {
383 output: readOutput(terminal.buffer),
384 truncated: terminal.buffer.truncated,
385 exitStatus: terminal.exitStatus,
386 };
387 };
388
389 const readCommandLine: AcpClientTerminals["readCommandLine"] = (terminalId) =>
390 terminals.get(terminalId)?.commandLine;
391
392 const disposeAll: AcpClientTerminals["disposeAll"] = Effect.uninterruptible(
393 Effect.suspend(() =>
394 Effect.forEach(
395 Array.from(terminals.values()),
396 (terminal) =>
397 Effect.sync(() => {
398 terminal.released = true;
399 }).pipe(Effect.andThen(terminal.dispose), Effect.andThen(Deferred.await(terminal.exit))),
400 { concurrency: "unbounded", discard: true },
401 ).pipe(Effect.andThen(Effect.sync(pruneReleasedSnapshots))),
402 ),
403 );
404
405 const logged =
406 <Request, Response>(
407 operation: string,
408 handler: (request: Request) => Effect.Effect<Response, EffectAcpErrors.AcpRequestError>,
409 ) =>
410 (request: Request) =>
411 handler(request).pipe(
412 Effect.tapError((error) =>
413 Effect.logWarning("ACP client terminal operation failed", {
414 operation,
415 detail: error.message,
416 }),
417 ),
418 );
419
420 return {
421 create: logged("terminal/create", create),
422 output: logged("terminal/output", output),
423 waitForExit: logged("terminal/wait_for_exit", waitForExit),
424 kill: logged("terminal/kill", kill),
425 release: logged("terminal/release", release),
426 readOutputSnapshot,
427 readCommandLine,
428 disposeAll,
429 };
430 });
431
432 export function resolveEmbeddedTerminalContent(
433 notification: EffectAcpSchema.SessionNotification,
434 readOutputSnapshot: AcpClientTerminals["readOutputSnapshot"],
435 ): EffectAcpSchema.SessionNotification {
436 const update = notification.update;
437 if (update.sessionUpdate !== "tool_call" && update.sessionUpdate !== "tool_call_update") {
438 return notification;
439 }
440 const content = update.content;
441 if (!content || !content.some((entry) => entry.type === "terminal")) {
442 return notification;
443 }
444 const mapped = content.map((entry): EffectAcpSchema.ToolCallContent => {
445 if (entry.type !== "terminal") return entry;
446 const snapshot = readOutputSnapshot(notification.sessionId, entry.terminalId);
447 return {
448 type: "content",
449 content: {
450 type: "text",
451 text: snapshot === undefined ? `[terminal ${entry.terminalId}]` : snapshot.output,
452 },
453 };
454 });
455 return { ...notification, update: { ...update, content: mapped } };
456 }