Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
perf(client): stop replaying terminal buffers on rollover (#242)
Leo1d98fd0a2439
diff --git a/apps/mobile/src/features/terminal/terminalMenu.test.ts b/apps/mobile/src/features/terminal/terminalMenu.test.tsindex 966312270..3e09dc872 100644--- a/apps/mobile/src/features/terminal/terminalMenu.test.ts+++ b/apps/mobile/src/features/terminal/terminalMenu.test.ts@@ -1,6 +1,9 @@import { describe, expect, it } from "vite-plus/test";-import { type KnownTerminalSession } from "@t3tools/client-runtime/state/terminal";+import {+ EMPTY_TERMINAL_BUFFER_STATE,+ type KnownTerminalSession,+} from "@t3tools/client-runtime/state/terminal";import { DEFAULT_TERMINAL_ID, EnvironmentId, ThreadId } from "@t3tools/contracts";import { getTerminalLabel } from "@t3tools/shared/terminalLabels";@@ -55,7 +58,7 @@ function makeKnownSession(input: {updatedAt: input.updatedAt ?? "2026-04-15T20:00:00.000Z",}: null,- buffer: "",+ output: EMPTY_TERMINAL_BUFFER_STATE.output,status: input.status,error: null,hasRunningSubprocess: false,diff --git a/apps/mobile/src/state/use-terminal-session.ts b/apps/mobile/src/state/use-terminal-session.tsindex 328557a20..6be57007a 100644--- a/apps/mobile/src/state/use-terminal-session.ts+++ b/apps/mobile/src/state/use-terminal-session.ts@@ -2,6 +2,7 @@ import {combineTerminalSessionState,EMPTY_TERMINAL_BUFFER_STATE,EMPTY_TERMINAL_SESSION_STATE,+ terminalOutputText,type KnownTerminalSession,type TerminalSessionState,} from "@t3tools/client-runtime/state/terminal";@@ -11,10 +12,16 @@ import { useMemo } from "react";import { useEnvironmentQuery } from "./query";import { terminalEnvironment } from "./terminal";+type LegacyTerminalSessionState = TerminalSessionState & { readonly buffer: string };+const EMPTY_LEGACY_TERMINAL_SESSION_STATE: LegacyTerminalSessionState = {+ ...EMPTY_TERMINAL_SESSION_STATE,+ buffer: "",+};+export function useAttachedTerminalSession(input: {readonly environmentId: EnvironmentId | null;readonly terminal: TerminalAttachInput | null;-}): TerminalSessionState {+}): LegacyTerminalSessionState {const attach = useEnvironmentQuery(input.environmentId !== null && input.terminal !== null? terminalEnvironment.attach({@@ -31,10 +38,14 @@ export function useAttachedTerminalSession(input: {input: null,}),);+ const output = attach.data?.output ?? EMPTY_TERMINAL_BUFFER_STATE.output;+ // Installed native binaries still accept initialBuffer. Keep materialization+ // at this mobile boundary until the native streaming API is released.+ const buffer = useMemo(() => terminalOutputText(output), [output]);return useMemo(() => {if (input.environmentId === null || input.terminal === null) {- return EMPTY_TERMINAL_SESSION_STATE;+ return EMPTY_LEGACY_TERMINAL_SESSION_STATE;}const summary =metadata.data?.find(@@ -42,9 +53,12 @@ export function useAttachedTerminalSession(input: {terminal.threadId === input.terminal?.threadId &&terminal.terminalId === input.terminal?.terminalId,) ?? null;- const state = combineTerminalSessionState(summary, attach.data ?? EMPTY_TERMINAL_BUFFER_STATE);+ const state = {+ ...combineTerminalSessionState(summary, attach.data ?? EMPTY_TERMINAL_BUFFER_STATE),+ buffer,+ };return attach.error === null ? state : { ...state, error: attach.error, status: "error" };- }, [attach.data, attach.error, input.environmentId, input.terminal, metadata.data]);+ }, [attach.data, attach.error, buffer, input.environmentId, input.terminal, metadata.data]);}export function useKnownTerminalSessions(input: {diff --git a/apps/web/src/components/ThreadTerminalDrawer.tsx b/apps/web/src/components/ThreadTerminalDrawer.tsxindex 9d4902332..7440893e1 100644--- a/apps/web/src/components/ThreadTerminalDrawer.tsx+++ b/apps/web/src/components/ThreadTerminalDrawer.tsx@@ -3,7 +3,13 @@ import {isAtomCommandInterrupted,squashAtomCommandFailure,} from "@t3tools/client-runtime/state/runtime";-import { type TerminalSessionState } from "@t3tools/client-runtime/state/terminal";+import {+ INITIAL_TERMINAL_OUTPUT_CURSOR,+ readTerminalOutputUpdate,+ type TerminalOutputCursor,+ type TerminalOutputUpdate,+ type TerminalSessionState,+} from "@t3tools/client-runtime/state/terminal";import {Plus,Square,@@ -96,8 +102,15 @@ function writeSystemMessage(terminal: GhosttyTerminalSurface, message: string):terminal.write(`\r\n[terminal] ${message}\r\n`);}-function writeTerminalBuffer(terminal: GhosttyTerminalSurface, buffer: string): void {- terminal.resetAndWrite(buffer);+export function writeTerminalOutputUpdate(+ terminal: Pick<GhosttyTerminalSurface, "resetAndWrite" | "write">,+ update: TerminalOutputUpdate,+): void {+ if (update.type === "reset") {+ terminal.resetAndWrite(update.data);+ } else if (update.type === "append") {+ terminal.write(update.data);+ }}function parseTerminalColor(value: string, fallback: GhosttyColor): GhosttyColor {@@ -429,9 +442,10 @@ export function TerminalViewport({input: { threadId, terminalId, cols, rows },}),);- const terminalBuffer = terminalSession.buffer;+ const terminalOutput = terminalSession.output;const terminalError = terminalSession.error;const terminalStatus = terminalSession.status;+ const outputCursorRef = useRef<TerminalOutputCursor>(INITIAL_TERMINAL_OUTPUT_CURSOR);const synchronizedStatusRef = useRef<TerminalSessionState["status"]>("closed");const synchronizeTerminalStatus = useEffectEvent((terminal: GhosttyTerminalSurface, status: TerminalSessionState["status"]) => {@@ -452,14 +466,14 @@ export function TerminalViewport({);const terminalVersion = terminalSession.version;const previousSessionRef = useRef({- buffer: terminalBuffer,+ output: terminalOutput,error: terminalError,status: terminalStatus,version: terminalVersion,});const latestSessionRef = useRef(previousSessionRef.current);latestSessionRef.current = {- buffer: terminalBuffer,+ output: terminalOutput,error: terminalError,status: terminalStatus,version: terminalVersion,@@ -531,7 +545,14 @@ export function TerminalViewport({}const latestSession = latestSessionRef.current;previousSessionRef.current = latestSession;- if (latestSession.buffer.length > 0) terminal.resetAndWrite(latestSession.buffer);+ const initialOutput = readTerminalOutputUpdate(+ latestSession.output,+ INITIAL_TERMINAL_OUTPUT_CURSOR,+ );+ if (initialOutput.type === "reset" && initialOutput.data.length > 0) {+ writeTerminalOutputUpdate(terminal, initialOutput);+ }+ outputCursorRef.current = initialOutput.cursor;if (latestSession.error !== null) writeSystemMessage(terminal, latestSession.error);// Attaching to a session that already exited must still run exit handling// once, so mount synchronization starts from the empty "closed" state.@@ -923,7 +944,7 @@ export function TerminalViewport({useEffect(() => {const terminal = terminalRef.current;const current = {- buffer: terminalBuffer,+ output: terminalOutput,error: terminalError,status: terminalStatus,version: terminalVersion,@@ -935,18 +956,13 @@ export function TerminalViewport({const previous = previousSessionRef.current;synchronizeTerminalStatus(terminal, current.status);- if (current.version === previous.version) {+ if (current.version === previous.version && current.output === previous.output) {return;}- if (- current.buffer.length >= previous.buffer.length &&- current.buffer.startsWith(previous.buffer)- ) {- terminal.write(current.buffer.slice(previous.buffer.length));- } else {- writeTerminalBuffer(terminal, current.buffer);- }+ const outputUpdate = readTerminalOutputUpdate(current.output, outputCursorRef.current);+ writeTerminalOutputUpdate(terminal, outputUpdate);+ outputCursorRef.current = outputUpdate.cursor;terminal.clearSelection();if (current.error !== null && current.error !== previous.error) {@@ -959,7 +975,7 @@ export function TerminalViewport({});}previousSessionRef.current = current;- }, [autoFocus, terminalBuffer, terminalError, terminalStatus, terminalVersion]);+ }, [autoFocus, terminalOutput, terminalError, terminalStatus, terminalVersion]);useEffect(() => {if (!autoFocus || !visible) return;diff --git a/packages/client-runtime/src/state/terminal.ts b/packages/client-runtime/src/state/terminal.tsindex 028f7a8c6..cc96dbe4b 100644--- a/packages/client-runtime/src/state/terminal.ts+++ b/packages/client-runtime/src/state/terminal.ts@@ -13,7 +13,23 @@ import { subscribe, type EnvironmentRpcInput } from "../rpc/client.ts";import {applyTerminalAttachStreamEvent,applyTerminalMetadataStreamEvent,+ nextTerminalAttachSeedState,+} from "./terminalSession.ts";++export {+ applyTerminalAttachStreamEvent,+ combineTerminalSessionState,+ DEFAULT_MAX_TERMINAL_BUFFER_BYTES,EMPTY_TERMINAL_BUFFER_STATE,+ EMPTY_TERMINAL_SESSION_STATE,+ INITIAL_TERMINAL_OUTPUT_CURSOR,+ nextTerminalAttachSeedState,+ readTerminalOutputUpdate,+ selectRunningSubprocessTerminalIds,+ terminalOutputText,+ type KnownTerminalSession,+ type TerminalBufferState,+ type TerminalSessionState,} from "./terminalSession.ts";export function createTerminalEnvironmentAtoms<R, E>(@@ -40,8 +56,10 @@ export function createTerminalEnvironmentAtoms<R, E>(attach: createEnvironmentSubscriptionAtomFamily(runtime, {label: "environment-data:terminal:attach",subscribe: (input: EnvironmentRpcInput<typeof WS_METHODS.terminalAttach>) =>- subscribe(WS_METHODS.terminalAttach, input).pipe(- Stream.scan(EMPTY_TERMINAL_BUFFER_STATE, applyTerminalAttachStreamEvent),+ Stream.suspend(() =>+ subscribe(WS_METHODS.terminalAttach, input).pipe(+ Stream.scan(nextTerminalAttachSeedState(), applyTerminalAttachStreamEvent),+ ),),}),events: createEnvironmentRpcSubscriptionAtomFamily(runtime, {diff --git a/packages/client-runtime/src/state/terminalOutput.ts b/packages/client-runtime/src/state/terminalOutput.tsnew file mode 100644index 000000000..3da12ecd7--- /dev/null+++ b/packages/client-runtime/src/state/terminalOutput.ts@@ -0,0 +1,325 @@+export interface TerminalOutputChunk {+ /** UTF-16 string offset within this generation and reset. */+ readonly startOffset: number;+ readonly data: string;+ readonly byteLength: number;+}++export interface TerminalOutputState {+ readonly generation: number;+ readonly chunks: ReadonlyArray<TerminalOutputChunk>;+ readonly retainedBytes: number;+ readonly resetVersion: number;+ readonly nextOffset: number;+}++export interface TerminalOutputCursor {+ readonly generation: number;+ readonly resetVersion: number;+ /** Start of the retained output already rendered into the viewport. */+ readonly retainedStartOffset: number;+ readonly offset: number;+}++/** Forces the first `readTerminalOutputUpdate` to resynchronize from a reset. */+export const INITIAL_TERMINAL_OUTPUT_CURSOR = Object.freeze<TerminalOutputCursor>({+ generation: -1,+ resetVersion: -1,+ retainedStartOffset: 0,+ offset: 0,+});++export type TerminalOutputUpdate =+ | {+ readonly type: "none";+ readonly cursor: TerminalOutputCursor;+ }+ | {+ readonly type: "reset";+ readonly data: string;+ readonly cursor: TerminalOutputCursor;+ }+ | {+ readonly type: "append";+ readonly cursor: TerminalOutputCursor;+ readonly data: string;+ };++export const DEFAULT_MAX_TERMINAL_BUFFER_BYTES = 512 * 1024;+const DEFAULT_TERMINAL_CHUNK_BYTES = 16 * 1024;+const MAX_TERMINAL_OUTPUT_CHUNKS = 1_024;+const textEncoder = new TextEncoder();+// A BOM at a retained chunk boundary is terminal data, not an encoding marker.+const textDecoder = new TextDecoder("utf-8", { ignoreBOM: true });++export const EMPTY_TERMINAL_OUTPUT_STATE = Object.freeze<TerminalOutputState>({+ generation: 0,+ chunks: Object.freeze([]),+ retainedBytes: 0,+ resetVersion: 0,+ nextOffset: 0,+});++interface Utf8Chunk {+ readonly data: string;+ readonly byteLength: number;+}++/**+ * Split a string into chunks of at most `maxBytes` UTF-8 bytes without cutting+ * a code point in half. The retained-output budget always supplies a positive+ * size. Only new output is encoded on live updates.+ *+ * A chunk that fits whole is returned as the original string, so the common+ * small-write path pays one encode and no decode.+ */+function splitStringByUtf8Bytes(data: string, maxBytes: number): ReadonlyArray<Utf8Chunk> {+ if (data.length === 0) return [];++ const encoded = textEncoder.encode(data);+ if (encoded.byteLength <= maxBytes) {+ return [{ data, byteLength: encoded.byteLength }];+ }++ const chunks: Utf8Chunk[] = [];+ let offset = 0;+ while (offset < encoded.byteLength) {+ let end = Math.min(offset + maxBytes, encoded.byteLength);+ while (end < encoded.byteLength && ((encoded[end] ?? 0) & 0xc0) === 0x80) {+ end -= 1;+ }+ // A degenerate budget smaller than one code point still has to advance:+ // include the whole code point rather than looping forever.+ if (end === offset) {+ end = Math.min(offset + maxBytes, encoded.byteLength);+ while (end < encoded.byteLength && ((encoded[end] ?? 0) & 0xc0) === 0x80) {+ end += 1;+ }+ }+ const bytes = encoded.subarray(offset, end);+ chunks.push({ data: textDecoder.decode(bytes), byteLength: bytes.byteLength });+ offset = end;+ }++ return chunks;+}++function trimBufferToBytes(buffer: string, maxBufferBytes: number): string {+ if (maxBufferBytes <= 0) {+ return "";+ }++ const encoded = textEncoder.encode(buffer);+ if (encoded.byteLength <= maxBufferBytes) {+ return buffer;+ }++ let start = encoded.byteLength - maxBufferBytes;+ while (start < encoded.length) {+ const byte = encoded[start];+ if (byte === undefined || (byte & 0b1100_0000) !== 0b1000_0000) {+ break;+ }+ start += 1;+ }++ return textDecoder.decode(encoded.subarray(start));+}++function splitOutputChunks(+ data: string,+ firstOffset: number,+ maxChunkBytes = DEFAULT_TERMINAL_CHUNK_BYTES,+): {+ readonly chunks: ReadonlyArray<TerminalOutputChunk>;+ readonly nextOffset: number;+ readonly byteLength: number;+} {+ const split = splitStringByUtf8Bytes(data, maxChunkBytes);+ let byteLength = 0;+ let nextOffset = firstOffset;+ const chunks = split.map((chunk) => {+ byteLength += chunk.byteLength;+ const startOffset = nextOffset;+ nextOffset += chunk.data.length;+ return {+ startOffset,+ data: chunk.data,+ byteLength: chunk.byteLength,+ };+ });++ return {+ chunks,+ nextOffset,+ byteLength,+ };+}++/**+ * Merge adjacent chunks without changing their string positions. A reader can+ * still append the unread suffix when its cursor falls inside a merged chunk.+ */+function compactRetainedChunks(chunks: ReadonlyArray<TerminalOutputChunk>) {+ const compacted: TerminalOutputChunk[] = [];+ for (const chunk of chunks) {+ const previous = compacted.at(-1);+ if (+ previous !== undefined &&+ previous.startOffset + previous.data.length === chunk.startOffset &&+ previous.byteLength + chunk.byteLength <= DEFAULT_TERMINAL_CHUNK_BYTES+ ) {+ compacted[compacted.length - 1] = {+ startOffset: previous.startOffset,+ data: `${previous.data}${chunk.data}`,+ byteLength: previous.byteLength + chunk.byteLength,+ };+ } else {+ compacted.push(chunk);+ }+ }+ return compacted;+}++// Scan only the removed prefix instead of encoding retained output again.+function trimOutputChunkStart(+ chunk: TerminalOutputChunk,+ bytesToDrop: number,+): TerminalOutputChunk {+ let offset = 0;+ let droppedBytes = 0;+ while (droppedBytes < bytesToDrop && offset < chunk.data.length) {+ const codepoint = chunk.data.codePointAt(offset)!;+ droppedBytes += codepoint <= 0x7f ? 1 : codepoint <= 0x7ff ? 2 : codepoint <= 0xffff ? 3 : 4;+ offset += codepoint <= 0xffff ? 1 : 2;+ }+ return {+ ...chunk,+ startOffset: chunk.startOffset + offset,+ data: chunk.data.slice(offset),+ byteLength: chunk.byteLength - droppedBytes,+ };+}++function appendOutput(+ current: TerminalOutputState,+ data: string,+ maxBufferBytes: number,+): TerminalOutputState {+ if (data.length === 0) return current;+ if (maxBufferBytes <= 0) {+ return {+ generation: current.generation,+ chunks: [],+ retainedBytes: 0,+ resetVersion: current.resetVersion + 1,+ nextOffset: current.nextOffset + data.length,+ };+ }+ const appended = splitOutputChunks(+ data,+ current.nextOffset,+ Math.min(DEFAULT_TERMINAL_CHUNK_BYTES, Math.max(1, maxBufferBytes)),+ );++ const chunks = [...current.chunks, ...appended.chunks];+ let retainedBytes = current.retainedBytes + appended.byteLength;+ let firstRetainedIndex = 0;+ while (retainedBytes > maxBufferBytes && firstRetainedIndex < chunks.length) {+ const first = chunks[firstRetainedIndex]!;+ const bytesToDrop = retainedBytes - maxBufferBytes;+ if (bytesToDrop < first.byteLength) {+ const trimmed = trimOutputChunkStart(first, bytesToDrop);+ retainedBytes -= first.byteLength - trimmed.byteLength;+ if (trimmed.byteLength > 0) {+ chunks[firstRetainedIndex] = trimmed;+ } else {+ firstRetainedIndex += 1;+ }+ break;+ }+ retainedBytes -= first.byteLength;+ firstRetainedIndex += 1;+ }++ let retainedChunks = firstRetainedIndex === 0 ? chunks : chunks.slice(firstRetainedIndex);+ if (retainedChunks.length > MAX_TERMINAL_OUTPUT_CHUNKS) {+ retainedChunks = compactRetainedChunks(retainedChunks);+ const excessChunks = retainedChunks.length - MAX_TERMINAL_OUTPUT_CHUNKS;+ if (excessChunks > 0) {+ for (const chunk of retainedChunks.slice(0, excessChunks)) {+ retainedBytes -= chunk.byteLength;+ }+ retainedChunks = retainedChunks.slice(excessChunks);+ }+ }++ return {+ generation: current.generation,+ chunks: retainedChunks,+ retainedBytes,+ resetVersion: current.resetVersion,+ nextOffset: appended.nextOffset,+ };+}++function resetOutput(+ current: TerminalOutputState,+ data: string,+ maxBufferBytes: number,+): TerminalOutputState {+ const retained = trimBufferToBytes(data, maxBufferBytes);+ const reset = splitOutputChunks(+ retained,+ 0,+ Math.min(DEFAULT_TERMINAL_CHUNK_BYTES, Math.max(1, maxBufferBytes)),+ );+ return {+ generation: current.generation,+ chunks: reset.chunks,+ retainedBytes: reset.byteLength,+ resetVersion: current.resetVersion + 1,+ nextOffset: reset.nextOffset,+ };+}++export function terminalOutputText(output: TerminalOutputState): string {+ return output.chunks.map((chunk) => chunk.data).join("");+}++export function readTerminalOutputUpdate(+ output: TerminalOutputState,+ cursor: TerminalOutputCursor,+): TerminalOutputUpdate {+ const retainedStartOffset = output.chunks[0]?.startOffset ?? output.nextOffset;+ const nextCursor = {+ generation: output.generation,+ resetVersion: output.resetVersion,+ retainedStartOffset,+ offset: output.nextOffset,+ };+ if (+ cursor.generation !== output.generation ||+ cursor.resetVersion !== output.resetVersion ||+ cursor.retainedStartOffset !== retainedStartOffset ||+ cursor.offset < retainedStartOffset+ ) {+ return { type: "reset", data: terminalOutputText(output), cursor: nextCursor };+ }++ const appended = output.chunks.filter(+ (chunk) => chunk.startOffset + chunk.data.length > cursor.offset,+ );+ if (appended.length === 0) {+ return { type: "none", cursor: nextCursor };+ }+ return {+ type: "append",+ data: appended+ .map((chunk) => chunk.data.slice(Math.max(0, cursor.offset - chunk.startOffset)))+ .join(""),+ cursor: nextCursor,+ };+}++export { appendOutput, resetOutput };diff --git a/packages/client-runtime/src/state/terminalSession.test.ts b/packages/client-runtime/src/state/terminalSession.test.tsindex 85c57592d..055a999a9 100644--- a/packages/client-runtime/src/state/terminalSession.test.ts+++ b/packages/client-runtime/src/state/terminalSession.test.ts@@ -1,4 +1,4 @@-import { describe, expect, it } from "vite-plus/test";+import { describe, expect, it, vi } from "vite-plus/test";import { EnvironmentId, TerminalSessionSnapshot, ThreadId } from "@t3tools/contracts";@@ -6,8 +6,13 @@ import {applyTerminalAttachStreamEvent,applyTerminalMetadataStreamEvent,combineTerminalSessionState,+ DEFAULT_MAX_TERMINAL_BUFFER_BYTES,EMPTY_TERMINAL_BUFFER_STATE,+ INITIAL_TERMINAL_OUTPUT_CURSOR,+ nextTerminalAttachSeedState,+ readTerminalOutputUpdate,selectRunningSubprocessTerminalIds,+ terminalOutputText,} from "./terminalSession.ts";const TARGET = {@@ -126,11 +131,11 @@ describe("terminal session reducers", () => {);expect(output).toMatchObject({- buffer: "lo world",status: "running",error: null,version: 2,});+ expect(terminalOutputText(output.output)).toBe("lo world");});it("reduces terminal metadata snapshots, upserts, and removals", () => {@@ -182,6 +187,268 @@ describe("terminal session reducers", () => {4,);- expect(state.buffer).toBe("🙂");+ expect(terminalOutputText(state.output)).toBe("🙂");+ });++ it("preserves a BOM code point at a new output chunk boundary", () => {+ const initial = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {+ type: "snapshot",+ snapshot: { ...BASE_SNAPSHOT, history: "" },+ });+ const cursor = readTerminalOutputUpdate(initial.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;+ const data = `${"x".repeat(16_384)}\uFEFF${"y".repeat(20)}`;+ const state = applyTerminalAttachStreamEvent(initial, {+ type: "output",+ threadId: TARGET.threadId,+ terminalId: TARGET.terminalId,+ data,+ });++ expect(terminalOutputText(state.output)).toBe(data);+ expect(readTerminalOutputUpdate(state.output, cursor)).toMatchObject({ type: "append", data });+ expect(state.output.retainedBytes).toBe(new TextEncoder().encode(data).byteLength);+ });++ it("preserves a leading BOM in the retained snapshot tail", () => {+ const state = applyTerminalAttachStreamEvent(+ EMPTY_TERMINAL_BUFFER_STATE,+ { type: "snapshot", snapshot: { ...BASE_SNAPSHOT, history: "discard\uFEFFtail" } },+ 7,+ );++ expect(terminalOutputText(state.output)).toBe("\uFEFFtail");+ expect(state.output.retainedBytes).toBe(7);+ });++ it("trims whole Unicode code points from a partially retained chunk", () => {+ let state = applyTerminalAttachStreamEvent(+ EMPTY_TERMINAL_BUFFER_STATE,+ { type: "snapshot", snapshot: { ...BASE_SNAPSHOT, history: "é界🙂end" } },+ 12,+ );+ let cursor = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;+ for (const [data, expected, retainedBytes] of [+ ["x", "界🙂endx", 11],+ ["yz", "🙂endxyz", 10],+ ["abc", "endxyzabc", 9],+ ] as const) {+ state = applyTerminalAttachStreamEvent(+ state,+ { type: "output", threadId: TARGET.threadId, terminalId: TARGET.terminalId, data },+ 12,+ );+ const update = readTerminalOutputUpdate(state.output, cursor);+ expect(update).toMatchObject({ type: "reset", data: expected });+ expect(terminalOutputText(state.output)).toBe(expected);+ expect(state.output.retainedBytes).toBe(retainedBytes);+ cursor = update.cursor;+ }+ });++ it("delivers all output when several events arrive before a renderer reads", () => {+ const initial = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {+ type: "snapshot",+ snapshot: BASE_SNAPSHOT,+ });+ const cursor = readTerminalOutputUpdate(initial.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;+ let state = initial;+ for (const data of [" one", " two", " three"]) {+ state = applyTerminalAttachStreamEvent(state, {+ type: "output",+ threadId: TARGET.threadId,+ terminalId: TARGET.terminalId,+ data,+ });+ }+ const update = readTerminalOutputUpdate(state.output, cursor);+ expect(update).toMatchObject({ type: "append", data: " one two three" });+ expect(readTerminalOutputUpdate(state.output, update.cursor).type).toBe("none");+ });++ it("preserves the byte-limited tail and resets every viewport after rollover", () => {+ const initial = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {+ type: "snapshot",+ snapshot: { ...BASE_SNAPSHOT, history: "" },+ });+ const staleCursor = readTerminalOutputUpdate(+ initial.output,+ INITIAL_TERMINAL_OUTPUT_CURSOR,+ ).cursor;+ const first = applyTerminalAttachStreamEvent(initial, {+ type: "output",+ threadId: TARGET.threadId,+ terminalId: TARGET.terminalId,+ data: "hello",+ });+ const caughtUpCursor = readTerminalOutputUpdate(first.output, staleCursor).cursor;+ const state = applyTerminalAttachStreamEvent(+ first,+ { type: "output", threadId: TARGET.threadId, terminalId: TARGET.terminalId, data: " world" },+ 8,+ );++ expect(readTerminalOutputUpdate(state.output, caughtUpCursor)).toMatchObject({+ type: "reset",+ data: "lo world",+ });+ expect(readTerminalOutputUpdate(state.output, staleCursor)).toMatchObject({+ type: "reset",+ data: "lo world",+ });+ expect(state.output.retainedBytes).toBe(8);+ });++ it("does not encode retained history again when appending at the byte limit", () => {+ let state = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {+ type: "snapshot",+ snapshot: { ...BASE_SNAPSHOT, history: "x".repeat(DEFAULT_MAX_TERMINAL_BUFFER_BYTES) },+ });+ const data = "y".repeat(8192);+ const encode = vi.spyOn(TextEncoder.prototype, "encode");+ try {+ for (let index = 0; index < 100; index += 1) {+ state = applyTerminalAttachStreamEvent(state, {+ type: "output",+ threadId: TARGET.threadId,+ terminalId: TARGET.terminalId,+ data,+ });+ }+ expect(encode.mock.calls.reduce((total, [text]) => total + (text?.length ?? 0), 0)).toBe(+ data.length * 100,+ );+ expect(state.output.retainedBytes).toBe(DEFAULT_MAX_TERMINAL_BUFFER_BYTES);+ } finally {+ encode.mockRestore();+ }+ });++ it.each([0, -1])("discards output without encoding when the byte budget is %s", (maxBytes) => {+ const initial = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {+ type: "snapshot",+ snapshot: BASE_SNAPSHOT,+ });+ const cursor = readTerminalOutputUpdate(initial.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;+ const data = "x".repeat(65_536);+ const encode = vi.spyOn(TextEncoder.prototype, "encode");+ try {+ const discarded = applyTerminalAttachStreamEvent(+ initial,+ { type: "output", threadId: TARGET.threadId, terminalId: TARGET.terminalId, data },+ maxBytes,+ );+ expect(encode).not.toHaveBeenCalled();+ expect(discarded.output.nextOffset).toBe(initial.output.nextOffset + data.length);+ expect(discarded.output.retainedBytes).toBe(0);+ expect(readTerminalOutputUpdate(discarded.output, cursor)).toMatchObject({+ type: "reset",+ data: "",+ });++ const empty = applyTerminalAttachStreamEvent(+ initial,+ { type: "output", threadId: TARGET.threadId, terminalId: TARGET.terminalId, data: "" },+ maxBytes,+ );+ expect(empty.output).toBe(initial.output);+ expect(encode).not.toHaveBeenCalled();+ } finally {+ encode.mockRestore();+ }+ });++ it("resets for repeated snapshots, clear, and restart even when output text repeats", () => {+ let state = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {+ type: "snapshot",+ snapshot: BASE_SNAPSHOT,+ });+ let cursor = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;+ state = applyTerminalAttachStreamEvent(state, { type: "snapshot", snapshot: BASE_SNAPSHOT });+ const repeated = readTerminalOutputUpdate(state.output, cursor);+ expect(repeated).toMatchObject({ type: "reset", data: "hello" });+ expect(state.version).toBe(2);+ cursor = repeated.cursor;++ state = applyTerminalAttachStreamEvent(state, {+ type: "cleared",+ threadId: TARGET.threadId,+ terminalId: TARGET.terminalId,+ });+ const cleared = readTerminalOutputUpdate(state.output, cursor);+ expect(cleared).toMatchObject({ type: "reset", data: "" });+ state = applyTerminalAttachStreamEvent(state, {+ type: "restarted",+ threadId: TARGET.threadId,+ terminalId: TARGET.terminalId,+ snapshot: BASE_SNAPSHOT,+ });+ expect(readTerminalOutputUpdate(state.output, cleared.cursor)).toMatchObject({+ type: "reset",+ data: "hello",+ });+ });++ it("does not reuse a renderer cursor when a fresh attach has matching counters", () => {+ const first = applyTerminalAttachStreamEvent(nextTerminalAttachSeedState(), {+ type: "snapshot",+ snapshot: BASE_SNAPSHOT,+ });+ const cursor = readTerminalOutputUpdate(first.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;+ const next = applyTerminalAttachStreamEvent(nextTerminalAttachSeedState(), {+ type: "snapshot",+ snapshot: { ...BASE_SNAPSHOT, history: "other" },+ });+ expect(next.output.resetVersion).toBe(first.output.resetVersion);+ expect(next.output.nextOffset).toBe(first.output.nextOffset);+ expect(readTerminalOutputUpdate(next.output, cursor)).toMatchObject({+ type: "reset",+ data: "other",+ });+ });++ it("keeps appending while compacting metadata for many small writes", () => {+ let state = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {+ type: "snapshot",+ snapshot: { ...BASE_SNAPSHOT, history: "" },+ });+ let cursor = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;+ let received = "";+ for (let index = 0; index < 2500; index += 1) {+ state = applyTerminalAttachStreamEvent(state, {+ type: "output",+ threadId: TARGET.threadId,+ terminalId: TARGET.terminalId,+ data: "x",+ });+ const update = readTerminalOutputUpdate(state.output, cursor);+ if (update.type !== "append") throw new Error(`Expected append, received ${update.type}`);+ received += update.data;+ cursor = update.cursor;+ }+ expect(received).toBe("x".repeat(2500));+ expect(state.output.chunks.length).toBeLessThan(1024);+ expect(terminalOutputText(state.output)).toBe(received);+ });++ it("appends every unread character across a compaction boundary", () => {+ let state = applyTerminalAttachStreamEvent(EMPTY_TERMINAL_BUFFER_STATE, {+ type: "snapshot",+ snapshot: { ...BASE_SNAPSHOT, history: "" },+ });+ let cursor = readTerminalOutputUpdate(state.output, INITIAL_TERMINAL_OUTPUT_CURSOR).cursor;+ const writes = Array.from({ length: 1200 }, (_, index) => ["x", "é", "界", "🙂"][index % 4]!);+ for (const [index, data] of writes.entries()) {+ state = applyTerminalAttachStreamEvent(state, {+ type: "output",+ threadId: TARGET.threadId,+ terminalId: TARGET.terminalId,+ data,+ });+ if (index === 99) cursor = readTerminalOutputUpdate(state.output, cursor).cursor;+ }+ expect(readTerminalOutputUpdate(state.output, cursor)).toMatchObject({+ type: "append",+ data: writes.slice(100).join(""),+ });});});diff --git a/packages/client-runtime/src/state/terminalSession.ts b/packages/client-runtime/src/state/terminalSession.tsindex ee444e36d..70a7ea2bc 100644--- a/packages/client-runtime/src/state/terminalSession.ts+++ b/packages/client-runtime/src/state/terminalSession.ts@@ -6,10 +6,27 @@ import type {TerminalSummary,ThreadId,} from "@t3tools/contracts";+import {+ appendOutput,+ DEFAULT_MAX_TERMINAL_BUFFER_BYTES,+ EMPTY_TERMINAL_OUTPUT_STATE,+ resetOutput,+ type TerminalOutputState,+} from "./terminalOutput.ts";++export {+ DEFAULT_MAX_TERMINAL_BUFFER_BYTES,+ INITIAL_TERMINAL_OUTPUT_CURSOR,+ readTerminalOutputUpdate,+ terminalOutputText,+ type TerminalOutputCursor,+ type TerminalOutputState,+ type TerminalOutputUpdate,+} from "./terminalOutput.ts";export interface TerminalSessionState {readonly summary: TerminalSummary | null;- readonly buffer: string;+ readonly output: TerminalOutputState;readonly status: TerminalSessionSnapshot["status"] | "closed";readonly error: string | null;readonly hasRunningSubprocess: boolean;@@ -18,7 +35,7 @@ export interface TerminalSessionState {}export interface TerminalBufferState {- readonly buffer: string;+ readonly output: TerminalOutputState;readonly status: TerminalSessionSnapshot["status"] | "closed";readonly error: string | null;readonly updatedAt: string | null;@@ -45,7 +62,7 @@ export function selectRunningSubprocessTerminalIds(}export const EMPTY_TERMINAL_BUFFER_STATE = Object.freeze<TerminalBufferState>({- buffer: "",+ output: EMPTY_TERMINAL_OUTPUT_STATE,status: "closed",error: null,updatedAt: null,@@ -54,7 +71,7 @@ export const EMPTY_TERMINAL_BUFFER_STATE = Object.freeze<TerminalBufferState>({export const EMPTY_TERMINAL_SESSION_STATE = Object.freeze<TerminalSessionState>({summary: null,- buffer: "",+ output: EMPTY_TERMINAL_OUTPUT_STATE,status: "closed",error: null,hasRunningSubprocess: false,@@ -62,42 +79,30 @@ export const EMPTY_TERMINAL_SESSION_STATE = Object.freeze<TerminalSessionState>(version: 0,});-export const DEFAULT_MAX_TERMINAL_BUFFER_BYTES = 512 * 1024;-const textEncoder = new TextEncoder();-const textDecoder = new TextDecoder();+let terminalAttachGeneration = 0;-function trimBufferToBytes(buffer: string, maxBufferBytes: number): string {- if (maxBufferBytes <= 0) {- return "";- }-- const encoded = textEncoder.encode(buffer);- if (encoded.byteLength <= maxBufferBytes) {- return buffer;- }-- let start = encoded.byteLength - maxBufferBytes;- while (start < encoded.length) {- const byte = encoded[start];- if (byte === undefined || (byte & 0b1100_0000) !== 0b1000_0000) {- break;- }- start += 1;- }-- return textDecoder.decode(encoded.subarray(start));+/** A reinstalled attach stream must not reuse an old renderer's output cursor. */+export function nextTerminalAttachSeedState(): TerminalBufferState {+ return {+ ...EMPTY_TERMINAL_BUFFER_STATE,+ output: {+ ...EMPTY_TERMINAL_OUTPUT_STATE,+ generation: ++terminalAttachGeneration,+ },+ };}export function terminalBufferStateFromSnapshot(snapshot: TerminalSessionSnapshot,maxBufferBytes: number,+ current: TerminalBufferState = EMPTY_TERMINAL_BUFFER_STATE,): TerminalBufferState {return {- buffer: trimBufferToBytes(snapshot.history, maxBufferBytes),+ output: resetOutput(current.output, snapshot.history, maxBufferBytes),status: snapshot.status,error: null,updatedAt: snapshot.updatedAt,- version: 1,+ version: current.version + 1,};}@@ -113,7 +118,7 @@ export function combineTerminalSessionState(): TerminalSessionState {return {summary,- buffer: buffer.buffer,+ output: buffer.output,status: buffer.version > 0 ? buffer.status : (summary?.status ?? buffer.status),error: buffer.error,hasRunningSubprocess: summary?.hasRunningSubprocess ?? false,@@ -130,11 +135,11 @@ export function applyTerminalAttachStreamEvent(switch (event.type) {case "snapshot":case "restarted":- return terminalBufferStateFromSnapshot(event.snapshot, maxBufferBytes);+ return terminalBufferStateFromSnapshot(event.snapshot, maxBufferBytes, current);case "output":return {...current,- buffer: trimBufferToBytes(`${current.buffer}${event.data}`, maxBufferBytes),+ output: appendOutput(current.output, event.data, maxBufferBytes),status: current.status === "closed" ? "running" : current.status,error: null,version: current.version + 1,@@ -142,7 +147,7 @@ export function applyTerminalAttachStreamEvent(case "cleared":return {...current,- buffer: "",+ output: resetOutput(current.output, "", maxBufferBytes),error: null,version: current.version + 1,};