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