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

main
ts 263 lines 9.63 KB
Raw
1 import {
2 ORCHESTRATION_V2_WS_METHODS,
3 type TerminalAttachStreamEvent,
4 type TerminalEvent,
5 WS_METHODS,
6 } from "@t3tools/contracts";
7 import type * as Arr from "effect/Array";
8 import * as Cause from "effect/Cause";
9 import * as Clock from "effect/Clock";
10 import * as Duration from "effect/Duration";
11 import * as Effect from "effect/Effect";
12 import * as Latch from "effect/Latch";
13 import * as Stream from "effect/Stream";
14 import type { RpcServer } from "effect/rpc";
15
16 const MAX_PENDING_CHUNKS = 8;
17 const MAX_PENDING_BYTES = 64 * 1024;
18 // Charge an envelope so tiny events cannot bypass the byte budget.
19 const EVENT_OVERHEAD = 128;
20 const isFull = (sizes: number[]) =>
21 sizes.length >= MAX_PENDING_CHUNKS ||
22 sizes.reduce((total, size) => total + size, 0) >= MAX_PENDING_BYTES;
23 // Terminal output is small chunks, so its window also caps bytes. The other streams
24 // window by count only: sizing a multi-MB thread snapshot would serialize it twice.
25 const BYTE_WINDOWED_STREAMS: ReadonlySet<string> = new Set([
26 WS_METHODS.terminalAttach,
27 WS_METHODS.terminalObserve,
28 ]);
29 // One ACK round trip per chunk stalls sync on high-latency links.
30 const COUNT_WINDOWED_STREAMS: ReadonlySet<string> = new Set([
31 WS_METHODS.subscribeServerConfig,
32 ORCHESTRATION_V2_WS_METHODS.subscribeShell,
33 ORCHESTRATION_V2_WS_METHODS.subscribeThread,
34 ]);
35
36 const byteLengthOf = (value: unknown) => (typeof value === "string" ? Buffer.byteLength(value) : 0);
37
38 // Charges every variable-size field a terminal event can carry, so the byte
39 // budgets below cannot be bypassed by a large payload in an uncharged field.
40 const queuedSize = (event: TerminalEvent | TerminalAttachStreamEvent) =>
41 EVENT_OVERHEAD +
42 ("threadId" in event ? byteLengthOf(event.threadId) + byteLengthOf(event.terminalId) : 0) +
43 (event.type === "output"
44 ? byteLengthOf(event.data)
45 : event.type === "error"
46 ? byteLengthOf(event.message)
47 : event.type === "activity"
48 ? byteLengthOf(event.label)
49 : "snapshot" in event
50 ? byteLengthOf(event.snapshot.threadId) +
51 byteLengthOf(event.snapshot.terminalId) +
52 byteLengthOf(event.snapshot.history) +
53 byteLengthOf(event.snapshot.cwd) +
54 byteLengthOf(event.snapshot.worktreePath) +
55 byteLengthOf(event.snapshot.label)
56 : 0);
57
58 // Byte-windowed streams carry TerminalAttachStreamEvent, whose encoded form is the
59 // event itself, so charge it like the output queue does instead of serializing twice.
60 const chunkSize = (values: ReadonlyArray<unknown>) =>
61 values.reduce<number>(
62 (total, value) => total + queuedSize(value as TerminalAttachStreamEvent),
63 EVENT_OVERHEAD,
64 );
65
66 interface Window {
67 readonly bytes: boolean;
68 readonly sizes: number[];
69 }
70
71 export function withOutputWindow(
72 protocol: RpcServer.Protocol["Service"],
73 ): RpcServer.Protocol["Service"] {
74 // RpcServer drops a disconnected client before its streams exit, so their Exit never
75 // reaches send; departed clients are pruned when a window opens instead.
76 const clients = new Map<number, Map<string, Window>>();
77 let receive: Parameters<RpcServer.Protocol["Service"]["run"]>[0];
78 const windowFor = (clientId: number, requestId: string) => clients.get(clientId)?.get(requestId);
79 const openWindow = Effect.fnUntraced(function* (
80 clientId: number,
81 requestId: string,
82 bytes: boolean,
83 ) {
84 const connected = yield* protocol.clientIds;
85 for (const id of clients.keys()) if (!connected.has(id)) clients.delete(id);
86 let windows = clients.get(clientId);
87 if (!windows) clients.set(clientId, (windows = new Map()));
88 if (!windows.has(requestId)) windows.set(requestId, { bytes, sizes: [] });
89 });
90 return {
91 ...protocol,
92 run: (write) => {
93 receive = write;
94 return protocol.run((clientId, message) =>
95 Effect.suspend(() => {
96 if (message._tag === "Request") {
97 const bytes = BYTE_WINDOWED_STREAMS.has(message.tag);
98 if (bytes || COUNT_WINDOWED_STREAMS.has(message.tag)) {
99 return openWindow(clientId, String(message.id), bytes).pipe(
100 Effect.andThen(write(clientId, message)),
101 );
102 }
103 } else if (message._tag === "Ack") {
104 const window = windowFor(clientId, String(message.requestId));
105 if (window) {
106 const wasFull = isFull(window.sizes);
107 window.sizes.shift();
108 if (!wasFull || isFull(window.sizes)) return Effect.void;
109 }
110 }
111 return write(clientId, message);
112 }),
113 );
114 },
115 send: (clientId, response, transferables) =>
116 Effect.suspend(() => {
117 const send = protocol.send(clientId, response, transferables);
118 if (response._tag === "Exit") {
119 clients.get(clientId)?.delete(String(response.requestId));
120 } else if (response._tag === "Chunk") {
121 const window = windowFor(clientId, String(response.requestId));
122 if (window) {
123 window.sizes.push(window.bytes ? chunkSize(response.values) : 0);
124 if (!isFull(window.sizes)) {
125 return send.pipe(
126 Effect.andThen(() =>
127 receive(clientId, {
128 _tag: "Ack",
129 requestId: response.requestId,
130 }),
131 ),
132 );
133 }
134 }
135 }
136 return send;
137 }),
138 };
139 }
140
141 const MAX_QUEUED_OUTPUT = 8 * 1024 * 1024;
142 // Output that follows an emission this closely waits and rides along in one batch,
143 // so a PTY that delivers one line per callback (ConPTY) is not sent one frame per line.
144 const OUTPUT_WINDOW_NANOS = 2_000_000n;
145
146 type Listener<A> = (event: A) => Effect.Effect<void>;
147 // Acquisition must register cleanup synchronously with installing the listener.
148 type Subscribe<A, E> = (
149 listener: Listener<A>,
150 registerCleanup: (stop: () => void) => void,
151 ) => Effect.Effect<() => void, E>;
152
153 export function terminalOutputStream<A extends TerminalEvent | TerminalAttachStreamEvent, E>(
154 subscribe: Subscribe<A, E>,
155 resync?: Subscribe<A, E>,
156 maxQueued = MAX_QUEUED_OUTPUT,
157 ): Stream.Stream<A, E> {
158 return Stream.unwrap(
159 Effect.gen(function* () {
160 const clock = yield* Clock.Clock;
161 const ready = yield* Latch.make();
162 let pending: Array<A | undefined> = [];
163 let sizes: number[] = [];
164 let head = 0;
165 let queued = 0;
166 // Pending events other than output; any of them flushes the window early.
167 let lifecycle = 0;
168 let deadline = 0n;
169 let overflowed = false;
170 let subscription = 0;
171 let unsubscribe: (() => void) | null = null;
172 const release = () => {
173 subscription += 1;
174 unsubscribe?.();
175 unsubscribe = null;
176 pending = [];
177 sizes = [];
178 head = 0;
179 queued = 0;
180 lifecycle = 0;
181 };
182 const urgent = () => lifecycle > 0 || queued >= MAX_PENDING_BYTES;
183 yield* Effect.addFinalizer(() => Effect.sync(release));
184
185 const listen = (from: Subscribe<A, E>) =>
186 Effect.suspend(() => {
187 const id = ++subscription;
188 return from(
189 (event) =>
190 Effect.sync(() => {
191 if (id !== subscription) return;
192 const wasEmpty = head === pending.length;
193 const size = queuedSize(event);
194 pending.push(event);
195 sizes.push(size);
196 queued += size;
197 if (event.type !== "output") lifecycle += 1;
198 // A single snapshot must fit even when history fills the budget.
199 if (queued - sizes[head]! > maxQueued) {
200 release();
201 overflowed = true;
202 }
203 // The current or next pull handles the pending output deadline.
204 if (wasEmpty || overflowed || urgent()) ready.openUnsafe();
205 }),
206 (stop) => {
207 // Overflow or cancellation may invalidate acquisition before registration.
208 if (id === subscription) unsubscribe = stop;
209 else stop();
210 },
211 ).pipe(
212 Effect.asVoid,
213 Effect.onError(() => Effect.sync(release)),
214 );
215 });
216
217 const take = () => {
218 const event = pending[head]!;
219 pending[head] = undefined;
220 head += 1;
221 if (event.type !== "output") lifecycle -= 1;
222 return event;
223 };
224 const takeBatch = (): Arr.NonEmptyReadonlyArray<A> => {
225 let bytes = sizes[head]!;
226 const batch: [A, ...A[]] = [take()];
227 while (head < pending.length && bytes + sizes[head]! <= MAX_PENDING_BYTES) {
228 bytes += sizes[head]!;
229 batch.push(take());
230 }
231 queued -= bytes;
232 if (head * 2 >= pending.length) {
233 pending = pending.slice(head);
234 sizes = sizes.slice(head);
235 head = 0;
236 }
237 return batch;
238 };
239
240 const pull: Effect.Effect<Arr.NonEmptyReadonlyArray<A>, E | Cause.Done> = Effect.suspend(
241 () => {
242 if (overflowed) {
243 overflowed = false;
244 return resync ? listen(resync).pipe(Effect.andThen(pull)) : Cause.done();
245 }
246 ready.closeUnsafe();
247 if (head === pending.length) return ready.await.pipe(Effect.andThen(pull));
248 const now = clock.monotonicTimeNanosUnsafe();
249 if (now >= deadline || urgent()) {
250 deadline = now + OUTPUT_WINDOW_NANOS;
251 return Effect.succeed(takeBatch());
252 }
253 return Effect.raceFirst(ready.await, Effect.sleep(Duration.nanos(deadline - now))).pipe(
254 Effect.andThen(pull),
255 );
256 },
257 );
258
259 yield* listen(subscribe);
260 return Stream.fromPull(Effect.succeed(pull));
261 }),
262 );
263 }