Skip to content

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(server): bound terminal history incrementally (#206)

Leo8f3211a544cb
diff --git a/apps/server/src/terminal/Manager.test.ts b/apps/server/src/terminal/Manager.test.ts
index fc9e69fda..5f4c1fb2e 100644
--- a/apps/server/src/terminal/Manager.test.ts
+++ b/apps/server/src/terminal/Manager.test.ts
@@ -218,6 +218,7 @@ interface CreateManagerOptions {
subprocessPollIntervalMs?: number;
processKillGraceMs?: number;
maxRetainedInactiveSessions?: number;
+ historyByteLimit?: number;
ptyAdapter?: FakePtyAdapter;
}
@@ -248,6 +249,9 @@ const createManager = (
logsDir,
historyLineLimit,
ptyAdapter,
+ ...(options.historyByteLimit !== undefined
+ ? { historyByteLimit: options.historyByteLimit }
+ : {}),
...(options.shellResolver !== undefined ? { shellResolver: options.shellResolver } : {}),
...(options.env !== undefined ? { env: options.env } : {}),
...(options.subprocessInspector !== undefined
@@ -282,6 +286,105 @@ const createManager = (
const withHostPlatform = (platform: NodeJS.Platform) =>
Layer.succeed(HostProcessPlatform, platform);
+// Apply the existing line policy, then find the longest code-point-aligned byte tail.
+function retainedHistory(text: string, maxLines: number, maxBytes = Infinity): string {
+ const terminated = text.endsWith("\n");
+ const lines = text.split("\n");
+ if (terminated) lines.pop();
+ const retained = lines.slice(Math.max(0, lines.length - maxLines)).join("\n");
+ const capped = terminated ? `${retained}\n` : retained;
+ if (Buffer.byteLength(capped) <= maxBytes) return capped;
+ const points = Array.from(capped);
+ let start = points.length;
+ let bytes = 0;
+ while (start > 0) {
+ const next = Buffer.byteLength(points[start - 1]!);
+ if (bytes + next > maxBytes) break;
+ bytes += next;
+ start -= 1;
+ }
+ return points.slice(start).join("");
+}
+
+it("preserves line and byte limits across arbitrary chunks, Unicode, ANSI sequences, and clear", () => {
+ let randomSeed = 0x20260904;
+ const fragments = [
+ "",
+ "a",
+ "\n",
+ "\n\n",
+ "\r",
+ "\r\n",
+ "café",
+ "名",
+ "🚀",
+ "\u001b[31m",
+ "\u001b[0m",
+ "\u001b]8;;url\u0007",
+ "\ud83d",
+ "\ude80",
+ ];
+ const nextFragment = () => {
+ randomSeed = (Math.imul(randomSeed, 1_664_525) + 1_013_904_223) >>> 0;
+ return fragments[randomSeed % fragments.length]!;
+ };
+
+ for (const maxBytes of [0, 3, 8, 64, Infinity]) {
+ for (const maxLines of [0, 1, 3, 5, 5_000]) {
+ let expected = retainedHistory("before\ninitial\n", maxLines, maxBytes);
+ const history = new TerminalManager.BoundedTerminalHistory(
+ maxLines,
+ "before\ninitial\n",
+ maxBytes,
+ );
+ expect(history.value()).toBe(expected);
+
+ for (let step = 0; step < 300; step += 1) {
+ if (step % 73 === 0) {
+ history.clear();
+ expected = "";
+ expect(history.value()).toBe(expected);
+ }
+ const chunk = nextFragment() + nextFragment();
+ history.append(chunk);
+ expected = retainedHistory(expected + chunk, maxLines, maxBytes);
+ expect(history.value()).toBe(expected);
+ }
+ }
+ }
+});
+
+it("bounds long partial lines and joins surrogate pairs across chunk boundaries", () => {
+ const maxBytes = 65_539;
+ let expected = "";
+ const history = new TerminalManager.BoundedTerminalHistory(5_000, "", maxBytes);
+ const writes = [
+ "a".repeat(16_383) + "😀" + "b".repeat(70_000),
+ "\r" + "c".repeat(70_000) + "\ud83d",
+ "\ude80" + "d".repeat(100),
+ "\uFEFF" + "名".repeat(30_000),
+ ];
+ for (const text of writes) {
+ history.append(text);
+ expected = retainedHistory(expected + text, 5_000, maxBytes);
+ expect(history.value()).toBe(expected);
+ expect(Buffer.byteLength(history.value())).toBeLessThanOrEqual(maxBytes);
+ }
+});
+
+it("preserves retained lines as older storage is compacted", () => {
+ for (const maxLines of [3, 5_000]) {
+ let expected = "";
+ const history = new TerminalManager.BoundedTerminalHistory(maxLines, expected);
+ for (let batch = 0; batch < 40; batch += 1) {
+ const chunk = Array.from({ length: 300 }, (_, line) => `${batch}:${line}\n`).join("");
+ history.append(chunk);
+ expected = retainedHistory(expected + chunk, maxLines);
+ expect(history.value()).toBe(expected);
+ }
+ }
+});
+
it.layer(
Layer.merge(NodeServices.layer, ProcessRunner.layer.pipe(Layer.provide(NodeServices.layer))),
{ excludeTestServices: true },
@@ -1182,6 +1285,105 @@ it.layer(
}),
);
+ it.effect("caps incrementally appended history without losing partial or empty lines", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter } = yield* createManager(3);
+ yield* manager.open(openInput());
+ const process = ptyAdapter.processes[0];
+ expect(process).toBeDefined();
+ if (!process) return;
+
+ process.emitData("line1\n");
+ process.emitData("\n");
+ process.emitData("line3");
+ process.emitData("-continued\nline4");
+ yield* manager.close({ threadId: "thread-1" });
+
+ const reopened = yield* manager.open(openInput());
+ expect(reopened.history).toBe("\nline3-continued\nline4");
+ }),
+ );
+
+ it.effect("bounds persisted and attached history without truncating live output", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter, logsDir } = yield* createManager(5, { historyByteLimit: 10 });
+ const attachEvents = yield* Ref.make<ReadonlyArray<TerminalAttachStreamEvent>>([]);
+ const unsubscribe = yield* manager.attachStream(openInput(), (event) =>
+ Ref.update(attachEvents, (events) => [...events, event]),
+ );
+ yield* Effect.addFinalizer(() => Effect.sync(unsubscribe));
+ const writes = ["a".repeat(32), "😀\rEND"];
+ const process = ptyAdapter.processes[0]!;
+ for (const text of writes) process.emitData(text);
+ yield* manager.close({ threadId: "thread-1" });
+ expect(yield* readFileString(yield* historyLogPath(logsDir))).toBe("aa😀\rEND");
+
+ const reopened = yield* manager.open(openInput());
+ const events = yield* Ref.get(attachEvents);
+ expect(events.filter((event) => event.type === "output").map((event) => event.data)).toEqual(
+ writes,
+ );
+ const snapshot = events.findLast((event) => event.type === "snapshot")?.snapshot;
+ expect(snapshot?.history).toBe("aa😀\rEND");
+ expect(snapshot?.sequence).toBe(reopened.sequence);
+ }),
+ );
+
+ for (const source of ["current", "legacy"] as const) {
+ it.effect(`reads only a Unicode-safe tail from oversized ${source} history`, () =>
+ Effect.gen(function* () {
+ const fs = yield* FileSystem.FileSystem;
+ const path = yield* Path.Path;
+ let sourcePath: string | undefined;
+ let closedReads = 0;
+ const readRequests: number[] = [];
+ const trackedFileSystem = FileSystem.FileSystem.of({
+ ...fs,
+ readFileString: (candidate, encoding) =>
+ candidate === sourcePath
+ ? Effect.die("History restoration must not read the whole file")
+ : fs.readFileString(candidate, encoding),
+ open: (candidate, options) =>
+ Effect.gen(function* () {
+ if (candidate !== sourcePath) return yield* fs.open(candidate, options);
+ yield* Effect.addFinalizer(() =>
+ Effect.sync(() => {
+ closedReads += 1;
+ }),
+ );
+ const file = yield* fs.open(candidate, options);
+ return new Proxy(file, {
+ get(target, key) {
+ if (key === "read") {
+ return (buffer: Uint8Array) => {
+ readRequests.push(buffer.byteLength);
+ return target.read(buffer.subarray(0, 5));
+ };
+ }
+ return Reflect.get(target, key, target);
+ },
+ });
+ }),
+ });
+ const { manager, logsDir } = yield* createManager(5, { historyByteLimit: 15 }).pipe(
+ Effect.provideService(FileSystem.FileSystem, trackedFileSystem),
+ );
+ const nextPath = yield* historyLogPath(logsDir);
+ sourcePath = source === "current" ? nextPath : path.join(logsDir, "thread-1.log");
+ yield* fs.writeFileString(sourcePath, "old".repeat(32_768) + "😀\uFEFFnewest\ré");
+
+ const snapshot = yield* manager.open(openInput());
+ expect(snapshot.history).toBe("\uFEFFnewest\ré");
+ expect(readRequests).toEqual([15, 10, 5]);
+ expect(closedReads).toBe(1);
+ expect(Buffer.from(yield* fs.readFile(nextPath)).toString()).toBe("\uFEFFnewest\ré");
+ if (source === "legacy") expect(yield* fs.exists(sourcePath)).toBe(false);
+ yield* manager.close({ threadId: "thread-1" });
+ expect((yield* manager.open(openInput())).history).toBe("\uFEFFnewest\ré");
+ }),
+ );
+ }
+
it.effect("strips replay-unsafe terminal query and reply sequences from persisted history", () =>
Effect.gen(function* () {
const { manager, ptyAdapter } = yield* createManager();
diff --git a/apps/server/src/terminal/Manager.ts b/apps/server/src/terminal/Manager.ts
index ee3e9d7e1..9047c457a 100644
--- a/apps/server/src/terminal/Manager.ts
+++ b/apps/server/src/terminal/Manager.ts
@@ -77,6 +77,8 @@ export {
};
const DEFAULT_HISTORY_LINE_LIMIT = 5_000;
+const DEFAULT_HISTORY_BYTE_LIMIT = 8 * 1024 * 1024;
+const MAX_HISTORY_CHUNK_LENGTH = 16 * 1024;
const DEFAULT_PERSIST_DEBOUNCE_MS = 40;
const DEFAULT_SUBPROCESS_POLL_INTERVAL_MS = 1_000;
const MAX_SUBPROCESS_POLL_INTERVAL_MS = 60_000;
@@ -248,7 +250,7 @@ export interface TerminalSessionState {
worktreePath: string | null;
status: TerminalSessionStatus;
pid: number | null;
- history: string;
+ history: BoundedTerminalHistory;
pendingHistoryControlSequence: string;
pendingProcessEvents: Array<PendingProcessEvent>;
pendingProcessEventIndex: number;
@@ -269,7 +271,7 @@ export interface TerminalSessionState {
}
interface PersistHistoryRequest {
- history: string;
+ history: BoundedTerminalHistory;
immediate: boolean;
}
@@ -284,7 +286,7 @@ type DrainProcessEventAction =
threadId: string;
terminalId: string;
sequence: number;
- history: string | null;
+ history: BoundedTerminalHistory | null;
data: string;
}
| {
@@ -343,7 +345,7 @@ function snapshot(session: TerminalSessionState): TerminalSessionSnapshot {
worktreePath: session.worktreePath,
status: session.status,
pid: session.pid,
- history: session.history,
+ history: session.history.value(),
exitCode: session.exitCode,
exitSignal: session.exitSignal,
label: terminalWireLabel(session),
@@ -793,16 +795,188 @@ const windowsProcessTableSnapshot = Effect.fn("terminal.windowsProcessTableSnaps
},
);
-function capHistory(history: string, maxLines: number): string {
- if (history.length === 0) return history;
- const hasTrailingNewline = history.endsWith("\n");
- const lines = history.split("\n");
- if (hasTrailingNewline) {
- lines.pop();
+interface TerminalHistoryChunk {
+ data: string;
+ byteLength: number;
+ lineBreaks: number;
+}
+
+export class BoundedTerminalHistory {
+ private readonly maxLines: number;
+ private readonly maxBytes: number;
+ private chunks: Array<TerminalHistoryChunk | undefined> = [];
+ private start = 0;
+ private byteLength = 0;
+ private lineBreaks = 0;
+ // Reading the old string's tail on each append can force chunk concatenation.
+ private lastCodeUnit: number | undefined;
+ private cachedValue: string | null = "";
+
+ constructor(maxLines: number, initial: string, maxBytes = DEFAULT_HISTORY_BYTE_LIMIT) {
+ this.maxLines = maxLines;
+ this.maxBytes = maxBytes;
+ this.append(initial);
+ }
+
+ append(text: string): void {
+ if (text.length === 0) return;
+ this.cachedValue = null;
+ if (this.maxBytes <= 0 || this.maxLines <= 0) {
+ this.clear();
+ // Preserve the existing zero-line limit's trailing newline behavior.
+ if (this.maxBytes > 0 && text.endsWith("\n")) this.appendChunk("\n");
+ return;
+ }
+
+ let offset = 0;
+ const previous = this.chunks.at(-1);
+ const lastCode = this.lastCodeUnit;
+ const firstCode = text.charCodeAt(0);
+ if (
+ previous &&
+ lastCode !== undefined &&
+ lastCode >= 0xd800 &&
+ lastCode <= 0xdbff &&
+ firstCode >= 0xdc00 &&
+ firstCode <= 0xdfff
+ ) {
+ // Joining a split surrogate changes its UTF-8 size from 3 to 4 bytes.
+ previous.data += text[0];
+ previous.byteLength += 1;
+ this.byteLength += 1;
+ this.lastCodeUnit = firstCode;
+ offset = 1;
+ this.trim();
+ }
+
+ while (offset < text.length) {
+ let end = Math.min(offset + MAX_HISTORY_CHUNK_LENGTH, text.length);
+ const before = text.charCodeAt(end - 1);
+ const after = text.charCodeAt(end);
+ if (before >= 0xd800 && before <= 0xdbff && after >= 0xdc00 && after <= 0xdfff) {
+ end -= 1;
+ }
+ const data = text.slice(offset, end);
+ // Detach small chunks from large input strings so evicted prefixes can be collected.
+ this.appendChunk(
+ text.length > MAX_HISTORY_CHUNK_LENGTH
+ ? Buffer.from(data, "utf16le").toString("utf16le")
+ : data,
+ );
+ this.trim();
+ offset = end;
+ }
+ }
+
+ private appendChunk(data: string): void {
+ const byteLength = Buffer.byteLength(data);
+ let lineBreaks = 0;
+ for (let index = data.indexOf("\n"); index !== -1; index = data.indexOf("\n", index + 1)) {
+ lineBreaks += 1;
+ }
+ const previous = this.chunks.at(-1);
+ if (previous && previous.data.length + data.length <= MAX_HISTORY_CHUNK_LENGTH) {
+ previous.data += data;
+ previous.byteLength += byteLength;
+ previous.lineBreaks += lineBreaks;
+ } else {
+ this.chunks.push({ data, byteLength, lineBreaks });
+ }
+ this.byteLength += byteLength;
+ this.lineBreaks += lineBreaks;
+ this.lastCodeUnit = data.charCodeAt(data.length - 1);
+ this.cachedValue = null;
+ }
+
+ private discardChunk(): void {
+ const first = this.chunks[this.start]!;
+ this.byteLength -= first.byteLength;
+ this.lineBreaks -= first.lineBreaks;
+ this.chunks[this.start++] = undefined;
+ }
+
+ private trimChunk(offset: number, byteLength: number, lineBreaks: number): void {
+ const first = this.chunks[this.start]!;
+ if (offset === first.data.length) {
+ this.discardChunk();
+ return;
+ }
+ first.data = first.data.slice(offset);
+ first.byteLength -= byteLength;
+ first.lineBreaks -= lineBreaks;
+ this.byteLength -= byteLength;
+ this.lineBreaks -= lineBreaks;
+ }
+
+ private trim(): void {
+ const trailingNewline = this.lastCodeUnit === 10;
+ let linesToDrop = this.lineBreaks + (trailingNewline ? 0 : 1) - this.maxLines;
+ while (linesToDrop > 0) {
+ const first = this.chunks[this.start]!;
+ if (first.lineBreaks < linesToDrop) {
+ linesToDrop -= first.lineBreaks;
+ this.discardChunk();
+ continue;
+ }
+ let offset = 0;
+ for (let line = 0; line < linesToDrop; line += 1) {
+ offset = first.data.indexOf("\n", offset) + 1;
+ }
+ this.trimChunk(offset, Buffer.byteLength(first.data.slice(0, offset)), linesToDrop);
+ linesToDrop = 0;
+ }
+
+ while (this.byteLength > this.maxBytes) {
+ const first = this.chunks[this.start]!;
+ const bytesToDrop = this.byteLength - this.maxBytes;
+ if (first.byteLength <= bytesToDrop) {
+ this.discardChunk();
+ continue;
+ }
+ if (first.byteLength === first.data.length && first.lineBreaks === 0) {
+ // ASCII without newlines needs no scan to find the byte cutoff.
+ this.trimChunk(bytesToDrop, bytesToDrop, 0);
+ continue;
+ }
+ let offset = 0;
+ let bytes = 0;
+ let lineBreaks = 0;
+ // Scan only the discarded prefix of one small chunk, never all history.
+ while (bytes < bytesToDrop) {
+ const codePoint = first.data.codePointAt(offset)!;
+ bytes += codePoint <= 0x7f ? 1 : codePoint <= 0x7ff ? 2 : codePoint <= 0xffff ? 3 : 4;
+ offset += codePoint <= 0xffff ? 1 : 2;
+ if (codePoint === 10) lineBreaks += 1;
+ }
+ this.trimChunk(offset, bytes, lineBreaks);
+ }
+ if (
+ this.start === this.chunks.length ||
+ (this.start > 2_048 && this.start * 2 >= this.chunks.length)
+ ) {
+ this.chunks = this.chunks.slice(this.start);
+ this.start = 0;
+ if (this.chunks.length === 0) this.lastCodeUnit = undefined;
+ }
+ }
+
+ clear(): void {
+ this.chunks = [];
+ this.start = 0;
+ this.byteLength = 0;
+ this.lineBreaks = 0;
+ this.lastCodeUnit = undefined;
+ this.cachedValue = "";
+ }
+
+ value(): string {
+ if (this.cachedValue !== null) return this.cachedValue;
+ this.cachedValue = this.chunks
+ .slice(this.start)
+ .map((chunk) => chunk!.data)
+ .join("");
+ return this.cachedValue;
}
- if (lines.length <= maxLines) return history;
- const capped = lines.slice(lines.length - maxLines).join("\n");
- return hasTrailingNewline ? `${capped}\n` : capped;
}
function isCsiFinalByte(codePoint: number): boolean {
@@ -1120,6 +1294,7 @@ function normalizedRuntimeEnv(
interface TerminalManagerOptions {
logsDir: string;
historyLineLimit?: number;
+ historyByteLimit?: number;
ptyAdapter: PtyAdapter.PtyAdapter["Service"];
shellResolver?: () => string;
env?: NodeJS.ProcessEnv;
@@ -1170,6 +1345,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
const logsDir = options.logsDir;
const historyLineLimit = options.historyLineLimit ?? DEFAULT_HISTORY_LINE_LIMIT;
+ const historyByteLimit = options.historyByteLimit ?? DEFAULT_HISTORY_BYTE_LIMIT;
const platform = yield* HostProcessPlatform;
// Terminals must inherit the user's full environment (minus the blocklist
// applied in createTerminalSpawnEnv) — an allowlist here silently strips
@@ -1428,22 +1604,24 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
return;
}
- yield* fileSystem.writeFileString(historyPath(threadId, terminalId), request.history).pipe(
- Effect.catch((error) =>
- Effect.logWarning("failed to persist terminal history", {
- threadId,
- terminalId,
- error,
- }),
- ),
- );
+ yield* fileSystem
+ .writeFileString(historyPath(threadId, terminalId), request.history.value())
+ .pipe(
+ Effect.catch((error) =>
+ Effect.logWarning("failed to persist terminal history", {
+ threadId,
+ terminalId,
+ error,
+ }),
+ ),
+ );
}),
});
const queuePersist = Effect.fn("terminal.queuePersist")(function* (
threadId: string,
terminalId: string,
- history: string,
+ history: BoundedTerminalHistory,
) {
yield* persistWorker.enqueue(toSessionKey(threadId, terminalId), {
history,
@@ -1461,7 +1639,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
const persistHistory = Effect.fn("terminal.persistHistory")(function* (
threadId: string,
terminalId: string,
- history: string,
+ history: BoundedTerminalHistory,
) {
yield* persistWorker.enqueue(toSessionKey(threadId, terminalId), {
history,
@@ -1470,6 +1648,30 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
yield* flushPersist(threadId, terminalId);
});
+ const readHistoryTail = Effect.fn("terminal.readHistoryTail")(function* (filePath: string) {
+ const file = yield* fileSystem.open(filePath, { flag: "r" });
+ const info = yield* file.stat;
+ const limit = BigInt(historyByteLimit);
+ const offset = info.size > limit ? info.size - limit : 0n;
+ yield* file.seek(offset, "start");
+ const bytes = new Uint8Array(Number(info.size - offset));
+ let length = 0;
+ while (length < bytes.length) {
+ const read = Number(yield* file.read(bytes.subarray(length)));
+ if (read === 0) break;
+ length += read;
+ }
+ let start = 0;
+ if (offset > 0n) {
+ // A tail read can start inside a UTF-8 code point. Skip its remaining bytes.
+ while (start < length && ((bytes[start] ?? 0) & 0xc0) === 0x80) start += 1;
+ }
+ return {
+ history: new TextDecoder("utf-8", { ignoreBOM: true }).decode(bytes.subarray(start, length)),
+ truncated: offset > 0n,
+ };
+ });
+
const readHistory = Effect.fn("terminal.readHistory")(function* (
threadId: string,
terminalId: string,
@@ -1484,15 +1686,15 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
),
)
) {
- const raw = yield* fileSystem
- .readFileString(nextPath)
- .pipe(
- Effect.mapError(
- (cause) => new TerminalHistoryError({ operation: "read", threadId, terminalId, cause }),
- ),
- );
- const capped = capHistory(raw, historyLineLimit);
- if (capped !== raw) {
+ const { history: raw, truncated } = yield* readHistoryTail(nextPath).pipe(
+ Effect.scoped,
+ Effect.mapError(
+ (cause) => new TerminalHistoryError({ operation: "read", threadId, terminalId, cause }),
+ ),
+ );
+ const history = new BoundedTerminalHistory(historyLineLimit, raw, historyByteLimit);
+ const capped = history.value();
+ if (truncated || capped !== raw) {
yield* fileSystem
.writeFileString(nextPath, capped)
.pipe(
@@ -1502,11 +1704,11 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
),
);
}
- return capped;
+ return history;
}
if (terminalId !== DEFAULT_TERMINAL_ID) {
- return "";
+ return new BoundedTerminalHistory(historyLineLimit, "", historyByteLimit);
}
const legacyPath = legacyHistoryPath(threadId);
@@ -1520,18 +1722,17 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
),
))
) {
- return "";
+ return new BoundedTerminalHistory(historyLineLimit, "", historyByteLimit);
}
- const raw = yield* fileSystem
- .readFileString(legacyPath)
- .pipe(
- Effect.mapError(
- (cause) =>
- new TerminalHistoryError({ operation: "migrate", threadId, terminalId, cause }),
- ),
- );
- const capped = capHistory(raw, historyLineLimit);
+ const { history: raw } = yield* readHistoryTail(legacyPath).pipe(
+ Effect.scoped,
+ Effect.mapError(
+ (cause) => new TerminalHistoryError({ operation: "migrate", threadId, terminalId, cause }),
+ ),
+ );
+ const history = new BoundedTerminalHistory(historyLineLimit, raw, historyByteLimit);
+ const capped = history.value();
yield* fileSystem
.writeFileString(nextPath, capped)
.pipe(
@@ -1548,7 +1749,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
}),
),
);
- return capped;
+ return history;
});
const deleteHistory = Effect.fn("terminal.deleteHistory")(function* (
@@ -1717,10 +1918,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
);
session.pendingHistoryControlSequence = sanitized.pendingControlSequence;
if (sanitized.visibleText.length > 0) {
- session.history = capHistory(
- `${session.history}${sanitized.visibleText}`,
- historyLineLimit,
- );
+ session.history.append(sanitized.visibleText);
}
const eventStamp = advanceEventSequence(session);
@@ -2297,7 +2495,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
liveSession.cwd = input.cwd;
liveSession.worktreePath = nextWorktreePath;
liveSession.runtimeEnv = nextRuntimeEnv;
- liveSession.history = "";
+ liveSession.history.clear();
liveSession.pendingHistoryControlSequence = "";
liveSession.pendingProcessEvents = [];
liveSession.pendingProcessEventIndex = 0;
@@ -2306,7 +2504,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
} else if (liveSession.status === "exited" || liveSession.status === "error") {
liveSession.runtimeEnv = nextRuntimeEnv;
liveSession.worktreePath = nextWorktreePath;
- liveSession.history = "";
+ liveSession.history.clear();
liveSession.pendingHistoryControlSequence = "";
liveSession.pendingProcessEvents = [];
liveSession.pendingProcessEventIndex = 0;
@@ -2611,7 +2809,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
Effect.gen(function* () {
const terminalId = input.terminalId;
const session = yield* requireSession(input.threadId, terminalId);
- session.history = "";
+ session.history.clear();
session.pendingHistoryControlSequence = "";
session.pendingProcessEvents = [];
session.pendingProcessEventIndex = 0;
@@ -2648,7 +2846,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
worktreePath: input.worktreePath ?? null,
status: "starting",
pid: null,
- history: "",
+ history: new BoundedTerminalHistory(historyLineLimit, "", historyByteLimit),
pendingHistoryControlSequence: "",
pendingProcessEvents: [],
pendingProcessEventIndex: 0,
@@ -2684,7 +2882,7 @@ export const makeWithOptions = Effect.fn("TerminalManager.makeWithOptions")(func
const cols = input.cols ?? session.cols;
const rows = input.rows ?? session.rows;
- session.history = "";
+ session.history.clear();
session.pendingHistoryControlSequence = "";
session.pendingProcessEvents = [];
session.pendingProcessEventIndex = 0;
diff --git a/docs/README.md b/docs/README.md
index ef1ed2fcc..860e31819 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -9,6 +9,7 @@
- [Permission modes](./user/permission-modes.md)
- [Configure sandboxes](./user/sandboxes.md)
- [Keyboard shortcuts](./user/keybindings.md)
+- [Terminal history](./user/terminal.md)
- [Organizing chats](./user/chats.md)
- [Sending product feedback](./user/product-feedback.md)
- [Plugins](./user/plugins.md)
@@ -42,6 +43,7 @@ policy in [CONTRIBUTING.md](../CONTRIBUTING.md); agent rules in [AGENTS.md](../A
- [Plugin lifecycle verification](./internals/plugin-lifecycle-verification.md)
- [Remote environments](./internals/remote.md)
- [Server updates](./internals/server-updates.md)
+- [Terminal runtime](./internals/terminal-runtime.md)
- [Resource telemetry](./internals/resource-telemetry.md)
- [Usage analytics](./internals/usage-analytics.md)
- [Environment auth](./internals/environment-auth.md)
diff --git a/docs/internals/terminal-runtime.md b/docs/internals/terminal-runtime.md
new file mode 100644
index 000000000..5c6251656
--- /dev/null
+++ b/docs/internals/terminal-runtime.md
@@ -0,0 +1,54 @@
+# Terminal runtime
+
+> For maintainers. Using Akeru Bot? See [docs/user/terminal.md](../user/terminal.md).
+
+The environment server owns terminal processes, retained output history, and
+session lifecycle. Web, desktop, and mobile clients attach to the same
+server-owned session over the environment RPC connection. The desktop renderer
+does not own a separate PTY. Clients can reconnect to a running PTY or share
+it with another client.
+
+## Output path
+
+PTY output follows this path:
+
+```text
+PTY callback
+ -> ordered process-event drain
+ -> bounded retained-history append
+ -> live terminal output event
+ -> coalesced history persistence
+```
+
+Live output events contain only the new PTY data. Full retained history is
+materialized only when the server returns a snapshot or when the coalescing
+persistence worker writes the latest state.
+
+Retained history is limited to 5,000 lines and 8 MiB of UTF-8 text per terminal.
+The server discards the oldest output when either limit is reached. A byte
+cutoff can shorten the oldest retained line, but does not split a Unicode code
+point. Live output is not truncated.
+
+History uses small chunks with byte and newline counts. Appending output scans
+the new text and any removed chunk prefix, not the full retained history.
+Empty lines, incomplete final lines, and trailing newlines remain unchanged
+within the limits. Split surrogate pairs are joined before byte eviction.
+
+Discard each chunk's string reference as soon as it leaves retained history.
+Array compaction can run later. Shared web and mobile client state retains at
+most 512 KiB, so each client can display less scrollback than the server keeps.
+
+Measure sustained-output changes against a full retained history so terminal
+throughput does not regress unnoticed.
+
+## Persistence
+
+History persistence is keyed by terminal session and coalesces pending writes.
+The worker reads the newest bounded-history state after its debounce instead
+of receiving a newly materialized full string for every PTY callback. Clear,
+restart, close, and final flush operations still force the latest state to
+disk before their lifecycle boundary completes.
+
+Restoration reads at most the last 8 MiB from current and legacy history files.
+It skips an incomplete UTF-8 code point at the start and applies the line limit
+before rewriting oversized files. File handles close before that rewrite.
diff --git a/docs/user/terminal.md b/docs/user/terminal.md
new file mode 100644
index 000000000..5751a01b1
--- /dev/null
+++ b/docs/user/terminal.md
@@ -0,0 +1,8 @@
+# Terminal history
+
+Each terminal keeps up to 5,000 lines and 8 MiB of scrollback on its environment
+server. Akeru removes the oldest output when either limit is reached. A long
+line can be shortened at the start. New terminal output is not truncated.
+
+These limits apply when you reconnect and when Akeru restores saved terminal
+history. A client can show less scrollback than the server keeps.