@devries-cameron20 / t3code Mirror · read-only / commits / c9f0caca1b
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, 18:30 UTC

perf(server,client): attaching to a terminal with a large history over a slow link drops from 5,555 ms to 751 ms median (7.4x) (#33942)

Co-authored-by: Julius Marminge <julius0216@outlook.com>

Andrei committed Nov 13, 2026 at 05:10 UTC c9f0caca1b2cdc1ce77154f092ea5ef03c6f5f0d
7 files changed +137 -34
apps/server/src/terminal/Manager.test.ts
+52
@@ -10,6 +10,7 @@ import {
10 ProviderDriverKind,
11 ProviderInstanceId,
12 ProjectId,
13 + retainedTerminalHistory,
14 TerminalProviderInstanceNotFoundError,
15 } from "@t3tools/contracts";
16 import * as HostProcess from "@t3tools/shared/HostProcess";
@@ -2325,6 +2326,57 @@ it.layer(
2326 }).pipe(Effect.scoped),
2327 );
2328
2329 + it.effect("sends bounded attach streams only the history the client retains", () =>
2330 + Effect.gen(function* () {
2331 + const { manager, ptyAdapter } = yield* createManager();
2332 + const maxHistoryBytes = 9;
2333 + yield* manager.open(openInput());
2334 + const process = ptyAdapter.processes[0]!;
2335 + const published = yield* Deferred.make<void>();
2336 + const unsubscribe = yield* manager.subscribe((event) =>
2337 + event.type === "output" && event.data === "yz\n"
2338 + ? Deferred.succeed(published, undefined).pipe(Effect.asVoid)
2339 + : Effect.void,
2340 + );
2341 + process.emitData("aaaa\nx名😀");
2342 + process.emitData("yz\n");
2343 + yield* Deferred.await(published);
2344 + unsubscribe();
2345 +
2346 + const full = yield* Stream.toPull(manager.attachOutputStream(openInput(), "full"));
2347 + const bounded = yield* Stream.toPull(
2348 + manager.attachOutputStream({ ...openInput(), maxHistoryBytes }, "bounded"),
2349 + );
2350 + const expectRetained = Effect.fnUntraced(function* () {
2351 + const [fullEvents, boundedEvents] = [yield* full, yield* bounded];
2352 + const fullSnapshot = fullEvents.at(-1);
2353 + if (fullSnapshot?.type !== "snapshot") throw new Error("Expected a full snapshot");
2354 + expect(boundedEvents.at(-1)).toEqual({
2355 + ...fullSnapshot,
2356 + snapshot: {
2357 + ...fullSnapshot.snapshot,
2358 + history: retainedTerminalHistory(fullSnapshot.snapshot.history, maxHistoryBytes),
2359 + },
2360 + });
2361 + return fullSnapshot.snapshot.history;
2362 + });
2363 +
2364 + expect(yield* expectRetained()).toBe("aaaa\nx名😀yz\n");
2365 + // The cap starts inside 名, so the tail begins at the next code point.
2366 + expect(retainedTerminalHistory("aaaa\nx名😀yz\n", maxHistoryBytes)).toBe("😀yz\n");
2367 + process.emitData("after\n");
2368 + expect(yield* full).toEqual(yield* bounded);
2369 +
2370 + yield* publishPastOutputBudget(manager, process);
2371 + expect(yield* expectRetained()).toMatch(/last\n$/);
2372 +
2373 + process.emitExit({ exitCode: 0, signal: 0 });
2374 + expect(yield* full).toEqual(yield* bounded);
2375 + yield* manager.attachStream({ ...openInput(), restartIfNotRunning: true }, () => Effect.void);
2376 + yield* expectRetained();
2377 + }).pipe(Effect.scoped),
2378 + );
2379 +
2380 it.effect("does not replay in-flight output already included in an observer snapshot", () =>
2381 Effect.gen(function* () {
2382 const { manager, ptyAdapter } = yield* createManager();
apps/server/src/terminal/Manager.ts
+26 -4
@@ -5,6 +5,7 @@ import { withWorkspaceLease } from "../workspace/workspaceLease.ts";
5 import {
6 DEFAULT_TERMINAL_ID,
7 DEFAULT_MAX_TERMINAL_BUFFER_BYTES,
8 + retainedTerminalHistory,
9 TerminalCwdError,
10 TerminalCwdNotDirectoryError,
11 TerminalCwdNotFoundError,
@@ -3240,20 +3241,41 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
3241 registerCleanup,
3242 );
3243
3243 - const attachOutputStream: TerminalManager["Service"]["attachOutputStream"] = (input, viewerId) =>
3244 - Stream.unwrap(
3244 + const attachOutputStream: TerminalManager["Service"]["attachOutputStream"] = (
3245 + input,
3246 + viewerId,
3247 + ) => {
3248 + const { maxHistoryBytes } = input;
3249 + const retained = (listener: (event: TerminalAttachStreamEvent) => Effect.Effect<void>) =>
3250 + maxHistoryBytes === undefined
3251 + ? listener
3252 + : (event: TerminalAttachStreamEvent) =>
3253 + listener(
3254 + "snapshot" in event
3255 + ? {
3256 + ...event,
3257 + snapshot: {
3258 + ...event.snapshot,
3259 + history: retainedTerminalHistory(event.snapshot.history, maxHistoryBytes),
3260 + },
3261 + }
3262 + : event,
3263 + );
3264 + return Stream.unwrap(
3265 Effect.acquireRelease(
3266 Effect.sync(() => retainViewerOnce(input, viewerId, null)),
3267 (release) => Effect.sync(release),
3268 ).pipe(
3269 Effect.as(
3270 terminalOutputStream(
3251 - (listener, registerCleanup) => attachStream(input, listener, registerCleanup, viewerId),
3252 - (listener, registerCleanup) => resyncStream(input, listener, registerCleanup),
3271 + (listener, registerCleanup) =>
3272 + attachStream(input, retained(listener), registerCleanup, viewerId),
3273 + (listener, registerCleanup) => resyncStream(input, retained(listener), registerCleanup),
3274 ),
3275 ),
3276 ),
3277 );
3278 + };
3279
3280 const metadataEventFromTerminalEvent = (
3281 event: TerminalEvent,
packages/client-runtime/src/state/runtime.test.ts
+7 -5
@@ -1,5 +1,6 @@
1 import { describe, expect, it } from "@effect/vitest";
2 import {
3 + DEFAULT_MAX_TERMINAL_BUFFER_BYTES,
4 EnvironmentId,
5 type FilesystemBrowseEntry,
6 ORCHESTRATION_V2_WS_METHODS,
@@ -552,6 +553,7 @@ describe("environment query lifecycle", () => {
553 cwd: "/tmp/project",
554 restartIfNotRunning: true,
555 };
556 + const sent = { ...input, maxHistoryBytes: DEFAULT_MAX_TERMINAL_BUFFER_BYTES };
557 const atoms = createTerminalEnvironmentAtoms(harness.runtime);
558 const registry = AtomRegistry.make();
559 const atom = atoms.attach({ environmentId: QUERY_ENVIRONMENT.environmentId, input });
@@ -571,9 +573,9 @@ describe("environment query lifecycle", () => {
573 }),
574 );
575
574 - expect(yield* Queue.take(inputs)).toEqual(input);
576 + expect(yield* Queue.take(inputs)).toEqual(sent);
577 yield* SubscriptionRef.set(harness.supervisorSession, Option.some({ ...firstSession }));
576 - expect(yield* Queue.take(inputs)).toEqual(input);
578 + expect(yield* Queue.take(inputs)).toEqual(sent);
579 yield* Queue.offer(events, {
580 type: "closed",
581 threadId: input.threadId,
@@ -582,10 +584,10 @@ describe("environment query lifecycle", () => {
584 yield* Deferred.await(received);
585
586 yield* SubscriptionRef.set(harness.supervisorSession, Option.some({ ...firstSession }));
585 - expect(yield* Queue.take(inputs)).toEqual({ ...input, resume: true });
587 + expect(yield* Queue.take(inputs)).toEqual({ ...sent, resume: true });
588 // Catalog replacements rerun the same stream through followStream's switchMap.
589 yield* SubscriptionRef.update(harness.streamGeneration, (generation) => generation + 1);
588 - expect(yield* Queue.take(inputs)).toEqual({ ...input, resume: true });
590 + expect(yield* Queue.take(inputs)).toEqual({ ...sent, resume: true });
591
592 unmount();
593 registry.dispose();
@@ -597,7 +599,7 @@ describe("environment query lifecycle", () => {
599 remountedRegistry.dispose();
600 }),
601 );
600 - expect(yield* Queue.take(inputs)).toEqual(input);
602 + expect(yield* Queue.take(inputs)).toEqual(sent);
603 }),
604 );
605
packages/client-runtime/src/state/terminal.ts
+6 -1
@@ -1,4 +1,5 @@
1 import {
2 + DEFAULT_MAX_TERMINAL_BUFFER_BYTES,
3 type EnvironmentId,
4 type TerminalAttachInput,
5 type TerminalCloseInput,
@@ -67,7 +68,11 @@ export function createTerminalEnvironmentAtoms<R, E>(
68 // Retry an unanswered first attach unchanged so it can still open the shell.
69 let replied = false;
70 return subscribeDynamic(WS_METHODS.terminalAttach, () =>
70 - Effect.sync(() => (replied ? { ...input, resume: true } : input)),
71 + Effect.sync(() => ({
72 + ...input,
73 + ...(replied ? { resume: true } : {}),
74 + maxHistoryBytes: DEFAULT_MAX_TERMINAL_BUFFER_BYTES,
75 + })),
76 ).pipe(
77 Stream.onFirst(() =>
78 Effect.sync(() => {
packages/client-runtime/src/state/terminalOutput.ts
+3 -23
@@ -1,3 +1,5 @@
1 +import { retainedTerminalHistory } from "@t3tools/contracts";
2 +
3 export interface TerminalOutputChunk {
4 readonly startOffset: number;
5 readonly data: string;
@@ -90,28 +92,6 @@ function splitStringByUtf8Bytes(data: string, maxBytes: number): ReadonlyArray<U
92 return chunks;
93 }
94
93 -function trimBufferToBytes(buffer: string, maxBufferBytes: number): string {
94 - if (maxBufferBytes <= 0) {
95 - return "";
96 - }
97 -
98 - const encoded = textEncoder.encode(buffer);
99 - if (encoded.byteLength <= maxBufferBytes) {
100 - return buffer;
101 - }
102 -
103 - let start = encoded.byteLength - maxBufferBytes;
104 - while (start < encoded.length) {
105 - const byte = encoded[start];
106 - if (byte === undefined || (byte & 0b1100_0000) !== 0b1000_0000) {
107 - break;
108 - }
109 - start += 1;
110 - }
111 -
112 - return textDecoder.decode(encoded.subarray(start));
113 -}
114 -
95 function splitOutputChunks(
96 data: string,
97 firstOffset: number,
@@ -249,7 +229,7 @@ function resetOutput(
229 data: string,
230 maxBufferBytes: number,
231 ): TerminalOutputState {
252 - const retained = trimBufferToBytes(data, maxBufferBytes);
232 + const retained = retainedTerminalHistory(data, maxBufferBytes);
233 const reset = splitOutputChunks(
234 retained,
235 0,
packages/client-runtime/src/state/terminalSession.test.ts
+14 -1
@@ -1,6 +1,11 @@
1 import { describe, expect, it } from "vite-plus/test";
2
3 -import { EnvironmentId, TerminalSessionSnapshot, ThreadId } from "@t3tools/contracts";
3 +import {
4 + EnvironmentId,
5 + retainedTerminalHistory,
6 + TerminalSessionSnapshot,
7 + ThreadId,
8 +} from "@t3tools/contracts";
9
10 import {
11 applyTerminalAttachStreamEvent,
@@ -119,6 +124,14 @@ describe("terminal session reducers", () => {
124
125 expect(terminalOutputText(state.output)).toBe("\uFEFFtail");
126 expect(state.output.retainedBytes).toBe(7);
127 + const serverTail = retainedTerminalHistory("discardtail", 7);
128 + expect(
129 + applyTerminalAttachStreamEvent(
130 + EMPTY_TERMINAL_BUFFER_STATE,
131 + { type: "snapshot", snapshot: { ...BASE_SNAPSHOT, history: serverTail } },
132 + 7,
133 + ),
134 + ).toEqual(state);
135 });
136
137 it("trims whole Unicode code points from a partially retained chunk", () => {
packages/contracts/src/terminal.ts
+29
@@ -5,6 +5,33 @@ import { ProviderInstanceId } from "./providerInstance.ts";
5 export const DEFAULT_TERMINAL_ID = "term-1";
6 export const DEFAULT_MAX_TERMINAL_BUFFER_BYTES = 512 * 1024;
7
8 +const historyEncoder = new TextEncoder();
9 +// A BOM at a retained chunk boundary is terminal data, not an encoding marker.
10 +const historyDecoder = new TextDecoder("utf-8", { ignoreBOM: true });
11 +
12 +/** The final `maxBytes` of UTF-8 a client retains, starting at a code point boundary. */
13 +export function retainedTerminalHistory(history: string, maxBytes: number): string {
14 + if (maxBytes <= 0) {
15 + return "";
16 + }
17 +
18 + const encoded = historyEncoder.encode(history);
19 + if (encoded.byteLength <= maxBytes) {
20 + return history;
21 + }
22 +
23 + let start = encoded.byteLength - maxBytes;
24 + while (start < encoded.length) {
25 + const byte = encoded[start];
26 + if (byte === undefined || (byte & 0b1100_0000) !== 0b1000_0000) {
27 + break;
28 + }
29 + start += 1;
30 + }
31 +
32 + return historyDecoder.decode(encoded.subarray(start));
33 +}
34 +
35 const TrimmedNonEmptyStringSchema = TrimmedNonEmptyString;
36 const TerminalColsSchema = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1)).check(
37 Schema.isLessThanOrEqualTo(1000),
@@ -57,6 +84,8 @@ export const TerminalAttachInput = Schema.Struct({
84 restartIfNotRunning: Schema.optional(Schema.Boolean),
85 // Resubscriptions preserve stopped terminals; unknown IDs recover after a server restart.
86 resume: Schema.optional(Schema.Boolean),
87 + // Snapshots carry only the history a client this bounded keeps; older servers ignore it.
88 + maxHistoryBytes: Schema.optional(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))),
89 });
90 export type TerminalAttachInput = typeof TerminalAttachInput.Type;
91