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.

Refactor terminal manager onto Effect runtime (#1525)

Julius Marminge8622b952cae4
diff --git a/apps/server/src/terminal/Layers/Manager.test.ts b/apps/server/src/terminal/Layers/Manager.test.ts
index 5717fda39..ccdd47717 100644
--- a/apps/server/src/terminal/Layers/Manager.test.ts
+++ b/apps/server/src/terminal/Layers/Manager.test.ts
@@ -1,24 +1,38 @@
-import fs from "node:fs";
-import os from "node:os";
import path from "node:path";
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, it } from "@effect/vitest";
import {
DEFAULT_TERMINAL_ID,
type TerminalEvent,
type TerminalOpenInput,
type TerminalRestartInput,
} from "@t3tools/contracts";
-import { afterEach, describe, expect, it } from "vitest";
-
import {
- PtySpawnError,
+ Duration,
+ Effect,
+ Encoding,
+ Exit,
+ Fiber,
+ FileSystem,
+ Option,
+ PlatformError,
+ Ref,
+ Schedule,
+ Scope,
+} from "effect";
+import { TestClock } from "effect/testing";
+import { expect } from "vitest";
+
+import type { TerminalManagerShape } from "../Services/Manager";
+import {
type PtyAdapterShape,
type PtyExitEvent,
type PtyProcess,
type PtySpawnInput,
+ PtySpawnError,
} from "../Services/PTY";
-import { TerminalManagerRuntime } from "./Manager";
-import { Effect, Encoding } from "effect";
+import { makeTerminalManagerWithOptions } from "./Manager";
class FakePtyProcess implements PtyProcess {
readonly writes: string[] = [];
@@ -107,27 +121,29 @@ class FakePtyAdapter implements PtyAdapterShape {
}
}
-function waitFor(predicate: () => boolean, timeoutMs = 800): Promise<void> {
- const started = Date.now();
- return new Promise((resolve, reject) => {
- const poll = () => {
- if (predicate()) {
- resolve();
- return;
- }
- if (Date.now() - started > timeoutMs) {
- reject(new Error("Timed out waiting for condition"));
- return;
- }
- setTimeout(poll, 15);
- };
- poll();
- });
-}
+const waitFor = <E, R>(
+ predicate: Effect.Effect<boolean, E, R>,
+ timeout: Duration.Input = 800,
+): Effect.Effect<void, Error | E, R> =>
+ predicate.pipe(
+ Effect.filterOrFail(
+ (done) => done,
+ () => new Error("Condition not met"),
+ ),
+ Effect.retry(Schedule.spaced("15 millis")),
+ Effect.timeoutOption(timeout),
+ Effect.flatMap((result) =>
+ Option.match(result, {
+ onNone: () => Effect.fail(new Error("Timed out waiting for condition")),
+ onSome: () => Effect.void,
+ }),
+ ),
+ );
function openInput(overrides: Partial<TerminalOpenInput> = {}): TerminalOpenInput {
return {
threadId: "thread-1",
+ terminalId: DEFAULT_TERMINAL_ID,
cwd: process.cwd(),
cols: 100,
rows: 24,
@@ -138,6 +154,7 @@ function openInput(overrides: Partial<TerminalOpenInput> = {}): TerminalOpenInpu
function restartInput(overrides: Partial<TerminalRestartInput> = {}): TerminalRestartInput {
return {
threadId: "thread-1",
+ terminalId: DEFAULT_TERMINAL_ID,
cwd: process.cwd(),
cols: 100,
rows: 24,
@@ -169,598 +186,777 @@ function multiTerminalHistoryLogPath(
return path.join(logsDir, multiTerminalHistoryLogName(threadId, terminalId));
}
-describe("TerminalManager", () => {
- const tempDirs: string[] = [];
-
- afterEach(() => {
- for (const dir of tempDirs.splice(0, tempDirs.length)) {
- fs.rmSync(dir, { recursive: true, force: true });
- }
- });
-
- function makeManager(
- historyLineLimit = 5,
- options: {
- shellResolver?: () => string;
- subprocessChecker?: (terminalPid: number) => Promise<boolean>;
- subprocessPollIntervalMs?: number;
- processKillGraceMs?: number;
- maxRetainedInactiveSessions?: number;
- ptyAdapter?: FakePtyAdapter;
- } = {},
- ) {
- const logsDir = fs.mkdtempSync(path.join(os.tmpdir(), "t3code-terminal-"));
- tempDirs.push(logsDir);
- const ptyAdapter = options.ptyAdapter ?? new FakePtyAdapter();
- const manager = new TerminalManagerRuntime({
- logsDir,
- ptyAdapter,
- historyLineLimit,
- shellResolver: options.shellResolver ?? (() => "/bin/bash"),
- ...(options.subprocessChecker ? { subprocessChecker: options.subprocessChecker } : {}),
- ...(options.subprocessPollIntervalMs
- ? { subprocessPollIntervalMs: options.subprocessPollIntervalMs }
- : {}),
- ...(options.processKillGraceMs ? { processKillGraceMs: options.processKillGraceMs } : {}),
- ...(options.maxRetainedInactiveSessions
- ? { maxRetainedInactiveSessions: options.maxRetainedInactiveSessions }
- : {}),
- });
- return { logsDir, ptyAdapter, manager };
- }
+interface CreateManagerOptions {
+ shellResolver?: () => string;
+ subprocessChecker?: (terminalPid: number) => Effect.Effect<boolean>;
+ subprocessPollIntervalMs?: number;
+ processKillGraceMs?: number;
+ maxRetainedInactiveSessions?: number;
+ ptyAdapter?: FakePtyAdapter;
+}
- it("spawns lazily and reuses running terminal per thread", async () => {
- const { manager, ptyAdapter } = makeManager();
- const [first, second] = await Promise.all([
- manager.open(openInput()),
- manager.open(openInput()),
- ]);
- const third = await manager.open(openInput());
-
- expect(first.threadId).toBe("thread-1");
- expect(first.terminalId).toBe("default");
- expect(second.threadId).toBe("thread-1");
- expect(third.threadId).toBe("thread-1");
- expect(ptyAdapter.spawnInputs).toHaveLength(1);
-
- manager.dispose();
- });
-
- it("supports asynchronous PTY spawn effects", async () => {
- const { manager, ptyAdapter } = makeManager(5, { ptyAdapter: new FakePtyAdapter("async") });
-
- const snapshot = await manager.open(openInput());
-
- expect(snapshot.status).toBe("running");
- expect(ptyAdapter.spawnInputs).toHaveLength(1);
- expect(ptyAdapter.processes).toHaveLength(1);
-
- manager.dispose();
- });
-
- it("forwards write and resize to active pty process", async () => {
- const { manager, ptyAdapter } = makeManager();
- await manager.open(openInput());
- const process = ptyAdapter.processes[0];
- expect(process).toBeDefined();
- if (!process) return;
-
- await manager.write({ threadId: "thread-1", data: "ls\n" });
- await manager.resize({ threadId: "thread-1", cols: 120, rows: 30 });
-
- expect(process.writes).toEqual(["ls\n"]);
- expect(process.resizeCalls).toEqual([{ cols: 120, rows: 30 }]);
-
- manager.dispose();
- });
-
- it("resizes running terminal on open when a different size is requested", async () => {
- const { manager, ptyAdapter } = makeManager();
- await manager.open(openInput({ cols: 100, rows: 24 }));
- const process = ptyAdapter.processes[0];
- expect(process).toBeDefined();
- if (!process) return;
-
- await manager.open(openInput({ cols: 140, rows: 40 }));
-
- expect(process.resizeCalls).toEqual([{ cols: 140, rows: 40 }]);
-
- manager.dispose();
- });
-
- it("preserves existing terminal size on open when size is omitted", async () => {
- const { manager, ptyAdapter } = makeManager();
- await manager.open(openInput({ cols: 100, rows: 24 }));
- const ptyProcess = ptyAdapter.processes[0];
- expect(ptyProcess).toBeDefined();
- if (!ptyProcess) return;
-
- await manager.open({
- threadId: "thread-1",
- cwd: globalThis.process.cwd(),
- });
-
- expect(ptyProcess.resizeCalls).toEqual([]);
-
- ptyProcess.emitExit({ exitCode: 0, signal: 0 });
- await manager.open({
- threadId: "thread-1",
- cwd: globalThis.process.cwd(),
- });
-
- const resumedSpawn = ptyAdapter.spawnInputs[1];
- expect(resumedSpawn).toBeDefined();
- if (!resumedSpawn) return;
- expect(resumedSpawn.cols).toBe(100);
- expect(resumedSpawn.rows).toBe(24);
-
- manager.dispose();
- });
-
- it("uses default dimensions when opening a new terminal without size hints", async () => {
- const { manager, ptyAdapter } = makeManager();
- await manager.open({
- threadId: "thread-1",
- cwd: process.cwd(),
- });
-
- const spawned = ptyAdapter.spawnInputs[0];
- expect(spawned).toBeDefined();
- if (!spawned) return;
- expect(spawned.cols).toBe(120);
- expect(spawned.rows).toBe(30);
-
- manager.dispose();
- });
-
- it("supports multiple terminals per thread with isolated sessions", async () => {
- const { manager, ptyAdapter } = makeManager();
- await manager.open(openInput({ terminalId: "default" }));
- await manager.open(openInput({ terminalId: "term-2" }));
-
- const first = ptyAdapter.processes[0];
- const second = ptyAdapter.processes[1];
- expect(first).toBeDefined();
- expect(second).toBeDefined();
- if (!first || !second) return;
-
- await manager.write({ threadId: "thread-1", terminalId: "default", data: "pwd\n" });
- await manager.write({ threadId: "thread-1", terminalId: "term-2", data: "ls\n" });
-
- expect(first.writes).toEqual(["pwd\n"]);
- expect(second.writes).toEqual(["ls\n"]);
- expect(ptyAdapter.spawnInputs).toHaveLength(2);
-
- manager.dispose();
- });
-
- it("clears transcript and emits cleared event", async () => {
- const { manager, ptyAdapter, logsDir } = makeManager();
- const events: TerminalEvent[] = [];
- manager.on("event", (event) => {
- events.push(event);
- });
- await manager.open(openInput());
- const process = ptyAdapter.processes[0];
- expect(process).toBeDefined();
- if (!process) return;
-
- process.emitData("hello\n");
- await waitFor(() => fs.existsSync(historyLogPath(logsDir)));
- await manager.clear({ threadId: "thread-1" });
- await waitFor(() => fs.readFileSync(historyLogPath(logsDir), "utf8") === "");
-
- expect(events.some((event) => event.type === "cleared")).toBe(true);
- expect(
- events.some(
- (event) =>
- event.type === "cleared" &&
- event.threadId === "thread-1" &&
- event.terminalId === "default",
- ),
- ).toBe(true);
-
- manager.dispose();
- });
-
- it("restarts terminal with empty transcript and respawns pty", async () => {
- const { manager, ptyAdapter, logsDir } = makeManager();
- await manager.open(openInput());
- const firstProcess = ptyAdapter.processes[0];
- expect(firstProcess).toBeDefined();
- if (!firstProcess) return;
- firstProcess.emitData("before restart\n");
- await waitFor(() => fs.existsSync(historyLogPath(logsDir)));
-
- const snapshot = await manager.restart(restartInput());
- expect(snapshot.history).toBe("");
- expect(snapshot.status).toBe("running");
- expect(ptyAdapter.spawnInputs).toHaveLength(2);
- await waitFor(() => fs.readFileSync(historyLogPath(logsDir), "utf8") === "");
-
- manager.dispose();
- });
-
- it("emits exited event and reopens with clean transcript after exit", async () => {
- const { manager, ptyAdapter, logsDir } = makeManager();
- const events: TerminalEvent[] = [];
- manager.on("event", (event) => {
- events.push(event);
- });
- await manager.open(openInput());
- const process = ptyAdapter.processes[0];
- expect(process).toBeDefined();
- if (!process) return;
- process.emitData("old data\n");
- await waitFor(() => fs.existsSync(historyLogPath(logsDir)));
- process.emitExit({ exitCode: 0, signal: 0 });
-
- await waitFor(() => events.some((event) => event.type === "exited"));
- const reopened = await manager.open(openInput());
-
- expect(reopened.history).toBe("");
- expect(ptyAdapter.spawnInputs).toHaveLength(2);
- expect(fs.readFileSync(historyLogPath(logsDir), "utf8")).toBe("");
-
- manager.dispose();
- });
-
- it("ignores trailing writes after terminal exit", async () => {
- const { manager, ptyAdapter } = makeManager();
- await manager.open(openInput());
- const process = ptyAdapter.processes[0];
- expect(process).toBeDefined();
- if (!process) return;
-
- process.emitExit({ exitCode: 0, signal: 0 });
-
- await expect(manager.write({ threadId: "thread-1", data: "\r" })).resolves.toBeUndefined();
- expect(process.writes).toEqual([]);
-
- manager.dispose();
- });
-
- it("emits subprocess activity events when child-process state changes", async () => {
- let hasRunningSubprocess = false;
- const { manager } = makeManager(5, {
- subprocessChecker: async () => hasRunningSubprocess,
- subprocessPollIntervalMs: 20,
- });
- const events: TerminalEvent[] = [];
- manager.on("event", (event) => {
- events.push(event);
- });
-
- await manager.open(openInput());
- await waitFor(() => events.some((event) => event.type === "started"));
- expect(events.some((event) => event.type === "activity")).toBe(false);
-
- hasRunningSubprocess = true;
- await waitFor(
- () =>
- events.some((event) => event.type === "activity" && event.hasRunningSubprocess === true),
- 1_200,
- );
+interface ManagerFixture {
+ readonly baseDir: string;
+ readonly logsDir: string;
+ readonly ptyAdapter: FakePtyAdapter;
+ readonly manager: TerminalManagerShape;
+ readonly getEvents: Effect.Effect<ReadonlyArray<TerminalEvent>>;
+}
- hasRunningSubprocess = false;
- await waitFor(
- () =>
- events.some((event) => event.type === "activity" && event.hasRunningSubprocess === false),
- 1_200,
+const createManager = (
+ historyLineLimit = 5,
+ options: CreateManagerOptions = {},
+): Effect.Effect<
+ ManagerFixture,
+ PlatformError.PlatformError,
+ FileSystem.FileSystem | Scope.Scope
+> =>
+ Effect.flatMap(Effect.service(FileSystem.FileSystem), (fs) =>
+ Effect.gen(function* () {
+ const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3code-terminal-" });
+ const logsDir = path.join(baseDir, "userdata", "logs", "terminals");
+ const ptyAdapter = options.ptyAdapter ?? new FakePtyAdapter();
+
+ const manager = yield* makeTerminalManagerWithOptions({
+ logsDir,
+ historyLineLimit,
+ ptyAdapter,
+ ...(options.shellResolver !== undefined ? { shellResolver: options.shellResolver } : {}),
+ ...(options.subprocessChecker !== undefined
+ ? { subprocessChecker: options.subprocessChecker }
+ : {}),
+ ...(options.subprocessPollIntervalMs !== undefined
+ ? { subprocessPollIntervalMs: options.subprocessPollIntervalMs }
+ : {}),
+ ...(options.processKillGraceMs !== undefined
+ ? { processKillGraceMs: options.processKillGraceMs }
+ : {}),
+ ...(options.maxRetainedInactiveSessions !== undefined
+ ? { maxRetainedInactiveSessions: options.maxRetainedInactiveSessions }
+ : {}),
+ });
+ const eventsRef = yield* Ref.make<ReadonlyArray<TerminalEvent>>([]);
+ const scope = yield* Effect.scope;
+ const unsubscribe = yield* manager.subscribe((event) =>
+ Ref.update(eventsRef, (events) => [...events, event]),
+ );
+ yield* Scope.addFinalizer(scope, Effect.sync(unsubscribe));
+
+ return {
+ baseDir,
+ logsDir,
+ ptyAdapter,
+ manager,
+ getEvents: Ref.get(eventsRef),
+ };
+ }),
+ );
+
+it.layer(NodeServices.layer, { excludeTestServices: true })("TerminalManager", (it) => {
+ it.effect("spawns lazily and reuses running terminal per thread", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter } = yield* createManager();
+ const [first, second] = yield* Effect.all(
+ [manager.open(openInput()), manager.open(openInput())],
+ { concurrency: "unbounded" },
+ );
+ const third = yield* manager.open(openInput());
+
+ assert.equal(first.threadId, "thread-1");
+ assert.equal(first.terminalId, "default");
+ assert.equal(second.threadId, "thread-1");
+ assert.equal(third.threadId, "thread-1");
+ expect(ptyAdapter.spawnInputs).toHaveLength(1);
+ }),
+ );
+
+ const makeDirectory = (filePath: string) =>
+ Effect.flatMap(Effect.service(FileSystem.FileSystem), (fs) =>
+ fs.makeDirectory(filePath, { recursive: true }),
);
- manager.dispose();
- });
-
- it("caps persisted history to configured line limit", async () => {
- const { manager, ptyAdapter } = makeManager(3);
- await manager.open(openInput());
- const process = ptyAdapter.processes[0];
- expect(process).toBeDefined();
- if (!process) return;
-
- process.emitData("line1\nline2\nline3\nline4\n");
- await manager.close({ threadId: "thread-1" });
-
- const reopened = await manager.open(openInput());
- const nonEmptyLines = reopened.history.split("\n").filter((line) => line.length > 0);
- expect(nonEmptyLines).toEqual(["line2", "line3", "line4"]);
-
- manager.dispose();
- });
-
- it("strips replay-unsafe terminal query and reply sequences from persisted history", async () => {
- const { manager, ptyAdapter } = makeManager();
- await manager.open(openInput());
- const process = ptyAdapter.processes[0];
- expect(process).toBeDefined();
- if (!process) return;
-
- process.emitData("prompt ");
- process.emitData("\u001b[32mok\u001b[0m ");
- process.emitData("\u001b]11;rgb:ffff/ffff/ffff\u0007");
- process.emitData("\u001b[1;1R");
- process.emitData("done\n");
-
- await manager.close({ threadId: "thread-1" });
-
- const reopened = await manager.open(openInput());
- expect(reopened.history).toBe("prompt \u001b[32mok\u001b[0m done\n");
-
- manager.dispose();
- });
-
- it("preserves clear and style control sequences while dropping chunk-split query traffic", async () => {
- const { manager, ptyAdapter } = makeManager();
- await manager.open(openInput());
- const process = ptyAdapter.processes[0];
- expect(process).toBeDefined();
- if (!process) return;
-
- process.emitData("before clear\n");
- process.emitData("\u001b[H\u001b[2J");
- process.emitData("prompt ");
- process.emitData("\u001b]11;");
- process.emitData("rgb:ffff/ffff/ffff\u0007\u001b[1;1");
- process.emitData("R\u001b[36mdone\u001b[0m\n");
-
- await manager.close({ threadId: "thread-1" });
-
- const reopened = await manager.open(openInput());
- expect(reopened.history).toBe(
- "before clear\n\u001b[H\u001b[2Jprompt \u001b[36mdone\u001b[0m\n",
- );
+ const chmod = (filePath: string, mode: number) =>
+ Effect.flatMap(Effect.service(FileSystem.FileSystem), (fs) => fs.chmod(filePath, mode));
- manager.dispose();
- });
+ const pathExists = (filePath: string) =>
+ Effect.flatMap(Effect.service(FileSystem.FileSystem), (fs) => fs.exists(filePath));
- it("does not leak final bytes from ESC sequences with intermediate bytes", async () => {
- const { manager, ptyAdapter } = makeManager();
- await manager.open(openInput());
- const process = ptyAdapter.processes[0];
- expect(process).toBeDefined();
- if (!process) return;
+ const readFileString = (filePath: string) =>
+ Effect.flatMap(Effect.service(FileSystem.FileSystem), (fs) => fs.readFileString(filePath));
- process.emitData("before ");
- process.emitData("\u001b(B");
- process.emitData("after\n");
+ const writeFileString = (filePath: string, contents: string) =>
+ Effect.flatMap(Effect.service(FileSystem.FileSystem), (fs) =>
+ fs.writeFileString(filePath, contents),
+ );
- await manager.close({ threadId: "thread-1" });
-
- const reopened = await manager.open(openInput());
- expect(reopened.history).toBe("before \u001b(Bafter\n");
-
- manager.dispose();
- });
+ it.effect("preserves non-notFound cwd stat failures", () =>
+ Effect.gen(function* () {
+ const { manager, baseDir } = yield* createManager();
+ const blockedRoot = path.join(baseDir, "blocked-root");
+ const blockedCwd = path.join(blockedRoot, "cwd");
+ yield* makeDirectory(blockedCwd);
+ yield* chmod(blockedRoot, 0o000);
- it("preserves chunk-split ESC sequences with intermediate bytes without leaking final bytes", async () => {
- const { manager, ptyAdapter } = makeManager();
- await manager.open(openInput());
- const process = ptyAdapter.processes[0];
- expect(process).toBeDefined();
- if (!process) return;
-
- process.emitData("before ");
- process.emitData("\u001b(");
- process.emitData("Bafter\n");
+ const error = yield* Effect.flip(manager.open(openInput({ cwd: blockedCwd }))).pipe(
+ Effect.ensuring(chmod(blockedRoot, 0o755).pipe(Effect.ignore)),
+ );
- await manager.close({ threadId: "thread-1" });
-
- const reopened = await manager.open(openInput());
- expect(reopened.history).toBe("before \u001b(Bafter\n");
+ expect(error).toMatchObject({
+ _tag: "TerminalCwdError",
+ cwd: blockedCwd,
+ reason: "statFailed",
+ });
+ }),
+ );
- manager.dispose();
- });
+ it.effect("supports asynchronous PTY spawn effects", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter } = yield* createManager(5, {
+ ptyAdapter: new FakePtyAdapter("async"),
+ });
- it("deletes history file when close(deleteHistory=true)", async () => {
- const { manager, ptyAdapter, logsDir } = makeManager();
- await manager.open(openInput());
- const process = ptyAdapter.processes[0];
- expect(process).toBeDefined();
- if (!process) return;
- process.emitData("bye\n");
- await waitFor(() => fs.existsSync(historyLogPath(logsDir)));
+ const snapshot = yield* manager.open(openInput());
+
+ assert.equal(snapshot.status, "running");
+ expect(ptyAdapter.spawnInputs).toHaveLength(1);
+ expect(ptyAdapter.processes).toHaveLength(1);
+ }),
+ );
+
+ it.effect("forwards write and resize to active pty process", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter } = yield* createManager();
+ yield* manager.open(openInput());
+ const process = ptyAdapter.processes[0];
+ expect(process).toBeDefined();
+ if (!process) return;
+
+ yield* manager.write({
+ threadId: "thread-1",
+ terminalId: DEFAULT_TERMINAL_ID,
+ data: "ls\n",
+ });
+ yield* manager.resize({
+ threadId: "thread-1",
+ terminalId: DEFAULT_TERMINAL_ID,
+ cols: 120,
+ rows: 30,
+ });
- await manager.close({ threadId: "thread-1", deleteHistory: true });
- expect(fs.existsSync(historyLogPath(logsDir))).toBe(false);
+ expect(process.writes).toEqual(["ls\n"]);
+ expect(process.resizeCalls).toEqual([{ cols: 120, rows: 30 }]);
+ }),
+ );
+
+ it.effect("resizes running terminal on open when a different size is requested", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter } = yield* createManager();
+ yield* manager.open(openInput({ cols: 100, rows: 24 }));
+ const process = ptyAdapter.processes[0];
+ expect(process).toBeDefined();
+ if (!process) return;
+
+ const reopened = yield* manager.open(openInput({ cols: 120, rows: 30 }));
+
+ assert.equal(reopened.status, "running");
+ expect(process.resizeCalls).toEqual([{ cols: 120, rows: 30 }]);
+ }),
+ );
+
+ it.effect("supports multiple terminals per thread independently", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter } = yield* createManager();
+ yield* manager.open(openInput({ terminalId: "default" }));
+ yield* manager.open(openInput({ terminalId: "term-2" }));
+
+ const first = ptyAdapter.processes[0];
+ const second = ptyAdapter.processes[1];
+ expect(first).toBeDefined();
+ expect(second).toBeDefined();
+ if (!first || !second) return;
+
+ yield* manager.write({ threadId: "thread-1", terminalId: "default", data: "pwd\n" });
+ yield* manager.write({ threadId: "thread-1", terminalId: "term-2", data: "ls\n" });
+
+ expect(first.writes).toEqual(["pwd\n"]);
+ expect(second.writes).toEqual(["ls\n"]);
+ expect(ptyAdapter.spawnInputs).toHaveLength(2);
+ }),
+ );
+
+ it.effect("clears transcript and emits cleared event", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter, logsDir, getEvents } = yield* createManager();
+ yield* manager.open(openInput());
+ const process = ptyAdapter.processes[0];
+ expect(process).toBeDefined();
+ if (!process) return;
+
+ process.emitData("hello\n");
+ yield* waitFor(pathExists(historyLogPath(logsDir)));
+ yield* manager.clear({ threadId: "thread-1", terminalId: DEFAULT_TERMINAL_ID });
+ yield* waitFor(Effect.map(readFileString(historyLogPath(logsDir)), (text) => text === ""));
+
+ const events = yield* getEvents;
+ expect(events.some((event) => event.type === "cleared")).toBe(true);
+ expect(
+ events.some(
+ (event) =>
+ event.type === "cleared" &&
+ event.threadId === "thread-1" &&
+ event.terminalId === "default",
+ ),
+ ).toBe(true);
+ }),
+ );
+
+ it.effect("restarts terminal with empty transcript and respawns pty", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter, logsDir } = yield* createManager();
+ yield* manager.open(openInput());
+ const firstProcess = ptyAdapter.processes[0];
+ expect(firstProcess).toBeDefined();
+ if (!firstProcess) return;
+ firstProcess.emitData("before restart\n");
+ yield* waitFor(pathExists(historyLogPath(logsDir)));
+
+ const snapshot = yield* manager.restart(restartInput());
+ assert.equal(snapshot.history, "");
+ assert.equal(snapshot.status, "running");
+ expect(ptyAdapter.spawnInputs).toHaveLength(2);
+ yield* waitFor(Effect.map(readFileString(historyLogPath(logsDir)), (text) => text === ""));
+ }),
+ );
+
+ it.effect("emits exited event and reopens with clean transcript after exit", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter, logsDir, getEvents } = yield* createManager();
+ yield* manager.open(openInput());
+ const process = ptyAdapter.processes[0];
+ expect(process).toBeDefined();
+ if (!process) return;
+ process.emitData("old data\n");
+ yield* waitFor(pathExists(historyLogPath(logsDir)));
+ process.emitExit({ exitCode: 0, signal: 0 });
+
+ yield* waitFor(
+ Effect.map(getEvents, (events) => events.some((event) => event.type === "exited")),
+ );
+ const reopened = yield* manager.open(openInput());
+
+ assert.equal(reopened.history, "");
+ expect(ptyAdapter.spawnInputs).toHaveLength(2);
+ expect(yield* readFileString(historyLogPath(logsDir))).toBe("");
+ }),
+ );
+
+ it.effect("ignores trailing writes after terminal exit", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter } = yield* createManager();
+ yield* manager.open(openInput());
+ const process = ptyAdapter.processes[0];
+ expect(process).toBeDefined();
+ if (!process) return;
+
+ process.emitExit({ exitCode: 0, signal: 0 });
+
+ yield* manager.write({
+ threadId: "thread-1",
+ terminalId: DEFAULT_TERMINAL_ID,
+ data: "\r",
+ });
+ expect(process.writes).toEqual([]);
+ }),
+ );
+
+ it.effect("emits subprocess activity events when child-process state changes", () =>
+ Effect.gen(function* () {
+ let hasRunningSubprocess = false;
+ const { manager, getEvents } = yield* createManager(5, {
+ subprocessChecker: () => Effect.succeed(hasRunningSubprocess),
+ subprocessPollIntervalMs: 20,
+ });
- manager.dispose();
- });
+ yield* manager.open(openInput());
+ expect((yield* getEvents).some((event) => event.type === "activity")).toBe(false);
- it("closes all terminals for a thread when close omits terminalId", async () => {
- const { manager, ptyAdapter, logsDir } = makeManager();
- await manager.open(openInput({ terminalId: "default" }));
- await manager.open(openInput({ terminalId: "sidecar" }));
- const defaultProcess = ptyAdapter.processes[0];
- const sidecarProcess = ptyAdapter.processes[1];
- expect(defaultProcess).toBeDefined();
- expect(sidecarProcess).toBeDefined();
- if (!defaultProcess || !sidecarProcess) return;
+ hasRunningSubprocess = true;
+ yield* waitFor(
+ Effect.map(getEvents, (events) =>
+ events.some((event) => event.type === "activity" && event.hasRunningSubprocess === true),
+ ),
+ "1200 millis",
+ );
- defaultProcess.emitData("default\n");
- sidecarProcess.emitData("sidecar\n");
- await waitFor(() => fs.existsSync(multiTerminalHistoryLogPath(logsDir, "thread-1", "default")));
- await waitFor(() => fs.existsSync(multiTerminalHistoryLogPath(logsDir, "thread-1", "sidecar")));
+ hasRunningSubprocess = false;
+ yield* waitFor(
+ Effect.map(getEvents, (events) =>
+ events.some((event) => event.type === "activity" && event.hasRunningSubprocess === false),
+ ),
+ "1200 millis",
+ );
+ }),
+ );
+
+ it.effect("does not invoke subprocess polling until a terminal session is running", () =>
+ Effect.gen(function* () {
+ let checks = 0;
+ const { manager } = yield* createManager(5, {
+ subprocessChecker: () => {
+ checks += 1;
+ return Effect.succeed(false);
+ },
+ subprocessPollIntervalMs: 20,
+ });
- await manager.close({ threadId: "thread-1", deleteHistory: true });
+ yield* Effect.sleep("80 millis");
+ assert.equal(checks, 0);
- expect(defaultProcess.killed).toBe(true);
- expect(sidecarProcess.killed).toBe(true);
- expect(fs.existsSync(multiTerminalHistoryLogPath(logsDir, "thread-1", "default"))).toBe(false);
- expect(fs.existsSync(multiTerminalHistoryLogPath(logsDir, "thread-1", "sidecar"))).toBe(false);
+ yield* manager.open(openInput());
+ yield* waitFor(
+ Effect.sync(() => checks > 0),
+ "1200 millis",
+ );
+ }),
+ );
+
+ it.effect("caps persisted history to configured line limit", () =>
+ 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\nline2\nline3\nline4\n");
+ yield* manager.close({ threadId: "thread-1" });
+
+ const reopened = yield* manager.open(openInput());
+ const nonEmptyLines = reopened.history.split("\n").filter((line) => line.length > 0);
+ expect(nonEmptyLines).toEqual(["line2", "line3", "line4"]);
+ }),
+ );
+
+ it.effect("strips replay-unsafe terminal query and reply sequences from persisted history", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter } = yield* createManager();
+ yield* manager.open(openInput());
+ const process = ptyAdapter.processes[0];
+ expect(process).toBeDefined();
+ if (!process) return;
+
+ process.emitData("prompt ");
+ process.emitData("\u001b[32mok\u001b[0m ");
+ process.emitData("\u001b]11;rgb:ffff/ffff/ffff\u0007");
+ process.emitData("\u001b[1;1R");
+ process.emitData("done\n");
+
+ yield* manager.close({ threadId: "thread-1" });
+
+ const reopened = yield* manager.open(openInput());
+ assert.equal(reopened.history, "prompt \u001b[32mok\u001b[0m done\n");
+ }),
+ );
+
+ it.effect(
+ "preserves clear and style control sequences while dropping chunk-split query traffic",
+ () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter } = yield* createManager();
+ yield* manager.open(openInput());
+ const process = ptyAdapter.processes[0];
+ expect(process).toBeDefined();
+ if (!process) return;
+
+ process.emitData("before clear\n");
+ process.emitData("\u001b[H\u001b[2J");
+ process.emitData("prompt ");
+ process.emitData("\u001b]11;");
+ process.emitData("rgb:ffff/ffff/ffff\u0007\u001b[1;1");
+ process.emitData("R\u001b[36mdone\u001b[0m\n");
+
+ yield* manager.close({ threadId: "thread-1" });
+
+ const reopened = yield* manager.open(openInput());
+ assert.equal(
+ reopened.history,
+ "before clear\n\u001b[H\u001b[2Jprompt \u001b[36mdone\u001b[0m\n",
+ );
+ }),
+ );
+
+ it.effect("does not leak final bytes from ESC sequences with intermediate bytes", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter } = yield* createManager();
+ yield* manager.open(openInput());
+ const process = ptyAdapter.processes[0];
+ expect(process).toBeDefined();
+ if (!process) return;
+
+ process.emitData("before ");
+ process.emitData("\u001b(B");
+ process.emitData("after\n");
+
+ yield* manager.close({ threadId: "thread-1" });
+
+ const reopened = yield* manager.open(openInput());
+ assert.equal(reopened.history, "before \u001b(Bafter\n");
+ }),
+ );
+
+ it.effect(
+ "preserves chunk-split ESC sequences with intermediate bytes without leaking final bytes",
+ () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter } = yield* createManager();
+ yield* manager.open(openInput());
+ const process = ptyAdapter.processes[0];
+ expect(process).toBeDefined();
+ if (!process) return;
+
+ process.emitData("before ");
+ process.emitData("\u001b(");
+ process.emitData("Bafter\n");
+
+ yield* manager.close({ threadId: "thread-1" });
+
+ const reopened = yield* manager.open(openInput());
+ assert.equal(reopened.history, "before \u001b(Bafter\n");
+ }),
+ );
+
+ it.effect("deletes history file when close(deleteHistory=true)", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter, logsDir } = yield* createManager();
+ yield* manager.open(openInput());
+ const process = ptyAdapter.processes[0];
+ expect(process).toBeDefined();
+ if (!process) return;
+ process.emitData("bye\n");
+ yield* waitFor(pathExists(historyLogPath(logsDir)));
+
+ yield* manager.close({ threadId: "thread-1", deleteHistory: true });
+ expect(yield* pathExists(historyLogPath(logsDir))).toBe(false);
+ }),
+ );
+
+ it.effect("closes all terminals for a thread when close omits terminalId", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter, logsDir } = yield* createManager();
+ yield* manager.open(openInput({ terminalId: "default" }));
+ yield* manager.open(openInput({ terminalId: "sidecar" }));
+ const defaultProcess = ptyAdapter.processes[0];
+ const sidecarProcess = ptyAdapter.processes[1];
+ expect(defaultProcess).toBeDefined();
+ expect(sidecarProcess).toBeDefined();
+ if (!defaultProcess || !sidecarProcess) return;
+
+ defaultProcess.emitData("default\n");
+ sidecarProcess.emitData("sidecar\n");
+ yield* waitFor(pathExists(multiTerminalHistoryLogPath(logsDir, "thread-1", "default")));
+ yield* waitFor(pathExists(multiTerminalHistoryLogPath(logsDir, "thread-1", "sidecar")));
+
+ yield* manager.close({ threadId: "thread-1", deleteHistory: true });
+
+ assert.equal(defaultProcess.killed, true);
+ assert.equal(sidecarProcess.killed, true);
+ expect(yield* pathExists(multiTerminalHistoryLogPath(logsDir, "thread-1", "default"))).toBe(
+ false,
+ );
+ expect(yield* pathExists(multiTerminalHistoryLogPath(logsDir, "thread-1", "sidecar"))).toBe(
+ false,
+ );
+ }),
+ );
+
+ it.effect("escalates terminal shutdown to SIGKILL when process does not exit in time", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter } = yield* createManager(5, { processKillGraceMs: 10 });
+ yield* manager.open(openInput());
+ const process = ptyAdapter.processes[0];
+ expect(process).toBeDefined();
+ if (!process) return;
+
+ const closeFiber = yield* manager.close({ threadId: "thread-1" }).pipe(Effect.forkScoped);
+ yield* Effect.yieldNow;
+ yield* TestClock.adjust("10 millis");
+ yield* Fiber.join(closeFiber);
+
+ assert.equal(process.killSignals[0], "SIGTERM");
+ expect(process.killSignals).toContain("SIGKILL");
+ }).pipe(Effect.provide(TestClock.layer())),
+ );
+
+ it.effect("evicts oldest inactive terminal sessions when retention limit is exceeded", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter, logsDir, getEvents } = yield* createManager(5, {
+ maxRetainedInactiveSessions: 1,
+ });
- manager.dispose();
- });
+ yield* manager.open(openInput({ threadId: "thread-1" }));
+ yield* manager.open(openInput({ threadId: "thread-2" }));
+
+ const first = ptyAdapter.processes[0];
+ const second = ptyAdapter.processes[1];
+ expect(first).toBeDefined();
+ expect(second).toBeDefined();
+ if (!first || !second) return;
+
+ first.emitData("first-history\n");
+ second.emitData("second-history\n");
+ yield* waitFor(pathExists(historyLogPath(logsDir, "thread-1")));
+ first.emitExit({ exitCode: 0, signal: 0 });
+ yield* Effect.sleep(Duration.millis(5));
+ second.emitExit({ exitCode: 0, signal: 0 });
+
+ yield* waitFor(
+ Effect.map(
+ getEvents,
+ (events) => events.filter((event) => event.type === "exited").length === 2,
+ ),
+ );
- it("escalates terminal shutdown to SIGKILL when process does not exit in time", async () => {
- const { manager, ptyAdapter } = makeManager(5, { processKillGraceMs: 10 });
- await manager.open(openInput());
- const process = ptyAdapter.processes[0];
- expect(process).toBeDefined();
- if (!process) return;
+ const reopenedSecond = yield* manager.open(openInput({ threadId: "thread-2" }));
+ const reopenedFirst = yield* manager.open(openInput({ threadId: "thread-1" }));
+
+ assert.equal(reopenedFirst.history, "first-history\n");
+ assert.equal(reopenedSecond.history, "");
+ }),
+ );
+
+ it.effect("migrates legacy transcript filenames to terminal-scoped history path on open", () =>
+ Effect.gen(function* () {
+ const { manager, logsDir } = yield* createManager();
+ const legacyPath = path.join(logsDir, "thread-1.log");
+ const nextPath = historyLogPath(logsDir);
+ yield* writeFileString(legacyPath, "legacy-line\n");
+
+ const snapshot = yield* manager.open(openInput());
+
+ assert.equal(snapshot.history, "legacy-line\n");
+ expect(yield* pathExists(nextPath)).toBe(true);
+ expect(yield* readFileString(nextPath)).toBe("legacy-line\n");
+ expect(yield* pathExists(legacyPath)).toBe(false);
+ }),
+ );
+
+ it.effect("retries with fallback shells when preferred shell spawn fails", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter } = yield* createManager(5, {
+ shellResolver: () => "/definitely/missing-shell -l",
+ });
+ ptyAdapter.spawnFailures.push(new Error("posix_spawnp failed."));
+
+ const snapshot = yield* manager.open(openInput());
+
+ assert.equal(snapshot.status, "running");
+ expect(ptyAdapter.spawnInputs.length).toBeGreaterThanOrEqual(2);
+ expect(ptyAdapter.spawnInputs[0]?.shell).toBe("/definitely/missing-shell");
+
+ if (process.platform === "win32") {
+ expect(
+ ptyAdapter.spawnInputs.some(
+ (input) => input.shell === "cmd.exe" || input.shell === "powershell.exe",
+ ),
+ ).toBe(true);
+ } else {
+ expect(
+ ptyAdapter.spawnInputs
+ .slice(1)
+ .some((input) => input.shell !== "/definitely/missing-shell"),
+ ).toBe(true);
+ }
+ }),
+ );
+
+ it.effect("filters app runtime env variables from terminal sessions", () =>
+ Effect.gen(function* () {
+ const originalValues = new Map<string, string | undefined>();
+ const setEnv = (key: string, value: string | undefined) => {
+ if (!originalValues.has(key)) {
+ originalValues.set(key, process.env[key]);
+ }
+ if (value === undefined) {
+ delete process.env[key];
+ return;
+ }
+ process.env[key] = value;
+ };
+ const restoreEnv = () => {
+ for (const [key, value] of originalValues) {
+ if (value === undefined) {
+ delete process.env[key];
+ } else {
+ process.env[key] = value;
+ }
+ }
+ };
+
+ setEnv("PORT", "5173");
+ setEnv("T3CODE_PORT", "3773");
+ setEnv("VITE_DEV_SERVER_URL", "http://localhost:5173");
+ setEnv("TEST_TERMINAL_KEEP", "keep-me");
+
+ try {
+ const { manager, ptyAdapter } = yield* createManager();
+ yield* manager.open(openInput());
+ const spawnInput = ptyAdapter.spawnInputs[0];
+ expect(spawnInput).toBeDefined();
+ if (!spawnInput) return;
+
+ expect(spawnInput.env.PORT).toBeUndefined();
+ expect(spawnInput.env.T3CODE_PORT).toBeUndefined();
+ expect(spawnInput.env.VITE_DEV_SERVER_URL).toBeUndefined();
+ expect(spawnInput.env.TEST_TERMINAL_KEEP).toBe("keep-me");
+ } finally {
+ restoreEnv();
+ }
+ }),
+ );
+
+ it.effect("injects runtime env overrides into spawned terminals", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter } = yield* createManager();
+ yield* manager.open(
+ openInput({
+ env: {
+ T3CODE_PROJECT_ROOT: "/repo",
+ T3CODE_WORKTREE_PATH: "/repo/worktree-a",
+ CUSTOM_FLAG: "1",
+ },
+ }),
+ );
+ const spawnInput = ptyAdapter.spawnInputs[0];
+ expect(spawnInput).toBeDefined();
+ if (!spawnInput) return;
- await manager.close({ threadId: "thread-1" });
- await waitFor(() => process.killSignals.includes("SIGKILL"));
+ assert.equal(spawnInput.env.T3CODE_PROJECT_ROOT, "/repo");
+ assert.equal(spawnInput.env.T3CODE_WORKTREE_PATH, "/repo/worktree-a");
+ assert.equal(spawnInput.env.CUSTOM_FLAG, "1");
+ }),
+ );
+
+ it.effect("starts zsh with prompt spacer disabled to avoid `%` end markers", () =>
+ Effect.gen(function* () {
+ if (process.platform === "win32") return;
+ const { manager, ptyAdapter } = yield* createManager(5, {
+ shellResolver: () => "/bin/zsh",
+ });
+ yield* manager.open(openInput());
+ const spawnInput = ptyAdapter.spawnInputs[0];
+ expect(spawnInput).toBeDefined();
+ if (!spawnInput) return;
- expect(process.killSignals[0]).toBe("SIGTERM");
- expect(process.killSignals).toContain("SIGKILL");
+ expect(spawnInput.args).toEqual(["-o", "nopromptsp"]);
+ }),
+ );
- manager.dispose();
- });
+ it.effect("bridges PTY callbacks back into Effect-managed event streaming", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter, getEvents } = yield* createManager(5, {
+ ptyAdapter: new FakePtyAdapter("async"),
+ });
- it("evicts oldest inactive terminal sessions when retention limit is exceeded", async () => {
- const { manager, ptyAdapter } = makeManager(5, { maxRetainedInactiveSessions: 1 });
+ yield* manager.open(openInput());
+ const process = ptyAdapter.processes[0];
+ expect(process).toBeDefined();
+ if (!process) return;
- await manager.open(openInput({ threadId: "thread-1" }));
- await manager.open(openInput({ threadId: "thread-2" }));
-
- const first = ptyAdapter.processes[0];
- const second = ptyAdapter.processes[1];
- expect(first).toBeDefined();
- expect(second).toBeDefined();
- if (!first || !second) return;
+ process.emitData("hello from callback\n");
- first.emitExit({ exitCode: 0, signal: 0 });
- await new Promise((resolve) => setTimeout(resolve, 5));
- second.emitExit({ exitCode: 0, signal: 0 });
+ yield* waitFor(
+ Effect.map(getEvents, (events) =>
+ events.some((event) => event.type === "output" && event.data === "hello from callback\n"),
+ ),
+ "1200 millis",
+ );
+ }),
+ );
- await waitFor(() => {
- const sessions = (manager as unknown as { sessions: Map<string, unknown> }).sessions;
- return sessions.size === 1;
- });
-
- const sessions = (manager as unknown as { sessions: Map<string, unknown> }).sessions;
- const keys = [...sessions.keys()];
- expect(keys).toEqual(["thread-2\u0000default"]);
-
- manager.dispose();
- });
-
- it("migrates legacy transcript filenames to terminal-scoped history path on open", async () => {
- const { manager, logsDir } = makeManager();
- const legacyPath = path.join(logsDir, "thread-1.log");
- const nextPath = historyLogPath(logsDir);
- fs.writeFileSync(legacyPath, "legacy-line\n", "utf8");
-
- const snapshot = await manager.open(openInput());
+ it.effect("pushes PTY callbacks to direct event subscribers", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter } = yield* createManager(5, {
+ ptyAdapter: new FakePtyAdapter("async"),
+ });
+ const scope = yield* Effect.scope;
+ const subscriberEvents = yield* Ref.make<ReadonlyArray<TerminalEvent>>([]);
+ const unsubscribe = yield* manager.subscribe((event) =>
+ Ref.update(subscriberEvents, (events) => [...events, event]),
+ );
+ yield* Scope.addFinalizer(scope, Effect.sync(unsubscribe));
- expect(snapshot.history).toBe("legacy-line\n");
- expect(fs.existsSync(nextPath)).toBe(true);
- expect(fs.readFileSync(nextPath, "utf8")).toBe("legacy-line\n");
- expect(fs.existsSync(legacyPath)).toBe(false);
-
- manager.dispose();
- });
-
- it("retries with fallback shells when preferred shell spawn fails", async () => {
- const { manager, ptyAdapter } = makeManager(5, {
- shellResolver: () => "/definitely/missing-shell -l",
- });
- ptyAdapter.spawnFailures.push(new Error("posix_spawnp failed."));
-
- const snapshot = await manager.open(openInput());
+ yield* manager.open(openInput());
+ const process = ptyAdapter.processes[0];
+ expect(process).toBeDefined();
+ if (!process) return;
- expect(snapshot.status).toBe("running");
- expect(ptyAdapter.spawnInputs.length).toBeGreaterThanOrEqual(2);
- expect(ptyAdapter.spawnInputs[0]?.shell).toBe("/definitely/missing-shell");
+ process.emitData("hello from subscriber\n");
- if (process.platform === "win32") {
- expect(
- ptyAdapter.spawnInputs.some(
- (input) => input.shell === "cmd.exe" || input.shell === "powershell.exe",
+ yield* waitFor(
+ Effect.map(Ref.get(subscriberEvents), (events) =>
+ events.some(
+ (event) => event.type === "output" && event.data === "hello from subscriber\n",
+ ),
),
- ).toBe(true);
- } else {
- expect(
- ptyAdapter.spawnInputs
- .slice(1)
- .some((input) => input.shell !== "/definitely/missing-shell"),
- ).toBe(true);
- }
-
- manager.dispose();
- });
-
- it("filters app runtime env variables from terminal sessions", async () => {
- const originalValues = new Map<string, string | undefined>();
- const setEnv = (key: string, value: string | undefined) => {
- if (!originalValues.has(key)) {
- originalValues.set(key, process.env[key]);
- }
- if (value === undefined) {
- delete process.env[key];
- return;
- }
- process.env[key] = value;
- };
- const restoreEnv = () => {
- for (const [key, value] of originalValues) {
- if (value === undefined) {
- delete process.env[key];
- } else {
- process.env[key] = value;
- }
- }
- };
-
- setEnv("PORT", "5173");
- setEnv("T3CODE_PORT", "3773");
- setEnv("VITE_DEV_SERVER_URL", "http://localhost:5173");
- setEnv("TEST_TERMINAL_KEEP", "keep-me");
+ "1200 millis",
+ );
+ }),
+ );
- try {
- const { manager, ptyAdapter } = makeManager();
- await manager.open(openInput());
- const spawnInput = ptyAdapter.spawnInputs[0];
- expect(spawnInput).toBeDefined();
- if (!spawnInput) return;
+ it.effect("preserves queued PTY output ordering through exit callbacks", () =>
+ Effect.gen(function* () {
+ const { manager, ptyAdapter, getEvents } = yield* createManager(5, {
+ ptyAdapter: new FakePtyAdapter("async"),
+ });
- expect(spawnInput.env.PORT).toBeUndefined();
- expect(spawnInput.env.T3CODE_PORT).toBeUndefined();
- expect(spawnInput.env.VITE_DEV_SERVER_URL).toBeUndefined();
- expect(spawnInput.env.TEST_TERMINAL_KEEP).toBe("keep-me");
+ yield* manager.open(openInput());
+ const process = ptyAdapter.processes[0];
+ expect(process).toBeDefined();
+ if (!process) return;
+
+ process.emitData("first\n");
+ process.emitData("second\n");
+ process.emitExit({ exitCode: 0, signal: 0 });
+
+ yield* waitFor(
+ Effect.map(getEvents, (events) => {
+ const relevant = events.filter(
+ (event) => event.type === "output" || event.type === "exited",
+ );
+ return relevant.length >= 3;
+ }),
+ "1200 millis",
+ );
- manager.dispose();
- } finally {
- restoreEnv();
- }
- });
-
- it("injects runtime env overrides into spawned terminals", async () => {
- const { manager, ptyAdapter } = makeManager();
- await manager.open(
- openInput({
- env: {
- T3CODE_PROJECT_ROOT: "/repo",
- T3CODE_WORKTREE_PATH: "/repo/worktree-a",
- CUSTOM_FLAG: "1",
- },
- }),
- );
- const spawnInput = ptyAdapter.spawnInputs[0];
- expect(spawnInput).toBeDefined();
- if (!spawnInput) return;
-
- expect(spawnInput.env.T3CODE_PROJECT_ROOT).toBe("/repo");
- expect(spawnInput.env.T3CODE_WORKTREE_PATH).toBe("/repo/worktree-a");
- expect(spawnInput.env.CUSTOM_FLAG).toBe("1");
-
- manager.dispose();
- });
-
- it("starts zsh with prompt spacer disabled to avoid `%` end markers", async () => {
- if (process.platform === "win32") return;
- const { manager, ptyAdapter } = makeManager(5, {
- shellResolver: () => "/bin/zsh",
- });
- await manager.open(openInput());
- const spawnInput = ptyAdapter.spawnInputs[0];
- expect(spawnInput).toBeDefined();
- if (!spawnInput) return;
-
- expect(spawnInput.shell).toBe("/bin/zsh");
- expect(spawnInput.args).toEqual(["-o", "nopromptsp"]);
-
- manager.dispose();
- });
+ const relevant = (yield* getEvents).filter(
+ (event) => event.type === "output" || event.type === "exited",
+ );
+ expect(relevant).toEqual([
+ expect.objectContaining({ type: "output", data: "first\n" }),
+ expect.objectContaining({ type: "output", data: "second\n" }),
+ expect.objectContaining({ type: "exited", exitCode: 0, exitSignal: 0 }),
+ ]);
+ }),
+ );
+
+ it.effect("scoped runtime shutdown stops active terminals cleanly", () =>
+ Effect.gen(function* () {
+ const scope = yield* Scope.make("sequential");
+ const { manager, ptyAdapter } = yield* createManager(5, {
+ processKillGraceMs: 10,
+ }).pipe(Effect.provideService(Scope.Scope, scope));
+ yield* manager.open(openInput());
+ const process = ptyAdapter.processes[0];
+ expect(process).toBeDefined();
+ if (!process) return;
+
+ const closeScope = yield* Scope.close(scope, Exit.void).pipe(Effect.forkScoped);
+ yield* Effect.yieldNow;
+ yield* TestClock.adjust("10 millis");
+ yield* Fiber.join(closeScope);
+
+ assert.equal(process.killSignals[0], "SIGTERM");
+ expect(process.killSignals).toContain("SIGKILL");
+ }).pipe(Effect.provide(TestClock.layer())),
+ );
});
diff --git a/apps/server/src/terminal/Layers/Manager.ts b/apps/server/src/terminal/Layers/Manager.ts
index b5085220c..7ef18b165 100644
--- a/apps/server/src/terminal/Layers/Manager.ts
+++ b/apps/server/src/terminal/Layers/Manager.ts
@@ -1,32 +1,44 @@
-import { EventEmitter } from "node:events";
-import fs from "node:fs";
import path from "node:path";
import {
DEFAULT_TERMINAL_ID,
- TerminalClearInput,
- TerminalCloseInput,
- TerminalOpenInput,
- TerminalResizeInput,
- TerminalRestartInput,
- TerminalWriteInput,
type TerminalEvent,
type TerminalSessionSnapshot,
+ type TerminalSessionStatus,
} from "@t3tools/contracts";
-import { Effect, Encoding, Layer, Schema } from "effect";
+import { makeKeyedCoalescingWorker } from "@t3tools/shared/KeyedCoalescingWorker";
+import {
+ Data,
+ Effect,
+ Encoding,
+ Equal,
+ Exit,
+ Fiber,
+ FileSystem,
+ Layer,
+ Option,
+ Scope,
+ Semaphore,
+ SynchronizedRef,
+} from "effect";
-import { createLogger } from "../../logger";
-import { PtyAdapter, PtyAdapterShape, type PtyExitEvent, type PtyProcess } from "../Services/PTY";
-import { runProcess } from "../../processRunner";
import { ServerConfig } from "../../config";
+import { runProcess } from "../../processRunner";
import {
- ShellCandidate,
- TerminalError,
+ TerminalCwdError,
+ TerminalHistoryError,
TerminalManager,
- TerminalManagerShape,
- TerminalSessionState,
- TerminalStartInput,
+ TerminalNotRunningError,
+ TerminalSessionLookupError,
+ type TerminalManagerShape,
} from "../Services/Manager";
+import {
+ PtyAdapter,
+ PtySpawnError,
+ type PtyAdapterShape,
+ type PtyExitEvent,
+ type PtyProcess,
+} from "../Services/PTY";
const DEFAULT_HISTORY_LINE_LIMIT = 5_000;
const DEFAULT_PERSIST_DEBOUNCE_MS = 40;
@@ -37,14 +49,128 @@ const DEFAULT_OPEN_COLS = 120;
const DEFAULT_OPEN_ROWS = 30;
const TERMINAL_ENV_BLOCKLIST = new Set(["PORT", "ELECTRON_RENDERER_PORT", "ELECTRON_RUN_AS_NODE"]);
-const decodeTerminalOpenInput = Schema.decodeUnknownSync(TerminalOpenInput);
-const decodeTerminalRestartInput = Schema.decodeUnknownSync(TerminalRestartInput);
-const decodeTerminalWriteInput = Schema.decodeUnknownSync(TerminalWriteInput);
-const decodeTerminalResizeInput = Schema.decodeUnknownSync(TerminalResizeInput);
-const decodeTerminalClearInput = Schema.decodeUnknownSync(TerminalClearInput);
-const decodeTerminalCloseInput = Schema.decodeUnknownSync(TerminalCloseInput);
+type TerminalSubprocessChecker = (
+ terminalPid: number,
+) => Effect.Effect<boolean, TerminalSubprocessCheckError>;
+
+class TerminalSubprocessCheckError extends Data.TaggedError("TerminalSubprocessCheckError")<{
+ readonly message: string;
+ readonly cause?: unknown;
+ readonly terminalPid: number;
+ readonly command: "powershell" | "pgrep" | "ps";
+}> {}
+
+class TerminalProcessSignalError extends Data.TaggedError("TerminalProcessSignalError")<{
+ readonly message: string;
+ readonly cause?: unknown;
+ readonly signal: "SIGTERM" | "SIGKILL";
+}> {}
+
+interface ShellCandidate {
+ shell: string;
+ args?: string[];
+}
+
+interface TerminalStartInput {
+ threadId: string;
+ terminalId: string;
+ cwd: string;
+ cols: number;
+ rows: number;
+ env?: Record<string, string>;
+}
+
+interface TerminalSessionState {
+ threadId: string;
+ terminalId: string;
+ cwd: string;
+ status: TerminalSessionStatus;
+ pid: number | null;
+ history: string;
+ pendingHistoryControlSequence: string;
+ pendingProcessEvents: Array<PendingProcessEvent>;
+ pendingProcessEventIndex: number;
+ processEventDrainRunning: boolean;
+ exitCode: number | null;
+ exitSignal: number | null;
+ updatedAt: string;
+ cols: number;
+ rows: number;
+ process: PtyProcess | null;
+ unsubscribeData: (() => void) | null;
+ unsubscribeExit: (() => void) | null;
+ hasRunningSubprocess: boolean;
+ runtimeEnv: Record<string, string> | null;
+}
+
+interface PersistHistoryRequest {
+ history: string;
+ immediate: boolean;
+}
+
+type PendingProcessEvent = { type: "output"; data: string } | { type: "exit"; event: PtyExitEvent };
+
+type DrainProcessEventAction =
+ | { type: "idle" }
+ | {
+ type: "output";
+ threadId: string;
+ terminalId: string;
+ history: string | null;
+ data: string;
+ }
+ | {
+ type: "exit";
+ process: PtyProcess | null;
+ threadId: string;
+ terminalId: string;
+ exitCode: number | null;
+ exitSignal: number | null;
+ };
+
+interface TerminalManagerState {
+ sessions: Map<string, TerminalSessionState>;
+ killFibers: Map<PtyProcess, Fiber.Fiber<void, never>>;
+}
+
+function snapshot(session: TerminalSessionState): TerminalSessionSnapshot {
+ return {
+ threadId: session.threadId,
+ terminalId: session.terminalId,
+ cwd: session.cwd,
+ status: session.status,
+ pid: session.pid,
+ history: session.history,
+ exitCode: session.exitCode,
+ exitSignal: session.exitSignal,
+ updatedAt: session.updatedAt,
+ };
+}
+
+function cleanupProcessHandles(session: TerminalSessionState): void {
+ session.unsubscribeData?.();
+ session.unsubscribeData = null;
+ session.unsubscribeExit?.();
+ session.unsubscribeExit = null;
+}
+
+function enqueueProcessEvent(
+ session: TerminalSessionState,
+ expectedPid: number,
+ event: PendingProcessEvent,
+): boolean {
+ if (!session.process || session.status !== "running" || session.pid !== expectedPid) {
+ return false;
+ }
+
+ session.pendingProcessEvents.push(event);
+ if (session.processEventDrainRunning) {
+ return false;
+ }
-type TerminalSubprocessChecker = (terminalPid: number) => Promise<boolean>;
+ session.processEventDrainRunning = true;
+ return true;
+}
function defaultShellResolver(): string {
if (process.platform === "win32") {
@@ -118,7 +244,7 @@ function resolveShellCandidates(shellResolver: () => string): ShellCandidate[] {
]);
}
-function isRetryableShellSpawnError(error: unknown): boolean {
+function isRetryableShellSpawnError(error: PtySpawnError): boolean {
const queue: unknown[] = [error];
const seen = new Set<unknown>();
const messages: string[] = [];
@@ -165,82 +291,107 @@ function isRetryableShellSpawnError(error: unknown): boolean {
);
}
-async function checkWindowsSubprocessActivity(terminalPid: number): Promise<boolean> {
+function checkWindowsSubprocessActivity(
+ terminalPid: number,
+): Effect.Effect<boolean, TerminalSubprocessCheckError> {
const command = [
`$children = Get-CimInstance Win32_Process -Filter "ParentProcessId = ${terminalPid}" -ErrorAction SilentlyContinue`,
"if ($children) { exit 0 }",
"exit 1",
].join("; ");
- try {
- const result = await runProcess(
- "powershell.exe",
- ["-NoProfile", "-NonInteractive", "-Command", command],
- {
+ return Effect.tryPromise({
+ try: () =>
+ runProcess("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", command], {
timeoutMs: 1_500,
allowNonZeroExit: true,
maxBufferBytes: 32_768,
outputMode: "truncate",
- },
- );
- return result.code === 0;
- } catch {
- return false;
- }
+ }),
+ catch: (cause) =>
+ new TerminalSubprocessCheckError({
+ message: "Failed to check Windows terminal subprocess activity.",
+ cause,
+ terminalPid,
+ command: "powershell",
+ }),
+ }).pipe(Effect.map((result) => result.code === 0));
}
-async function checkPosixSubprocessActivity(terminalPid: number): Promise<boolean> {
- try {
- const pgrepResult = await runProcess("pgrep", ["-P", String(terminalPid)], {
- timeoutMs: 1_000,
- allowNonZeroExit: true,
- maxBufferBytes: 32_768,
- outputMode: "truncate",
- });
- if (pgrepResult.code === 0) {
- return pgrepResult.stdout.trim().length > 0;
+const checkPosixSubprocessActivity = Effect.fn("terminal.checkPosixSubprocessActivity")(function* (
+ terminalPid: number,
+): Effect.fn.Return<boolean, TerminalSubprocessCheckError> {
+ const runPgrep = Effect.tryPromise({
+ try: () =>
+ runProcess("pgrep", ["-P", String(terminalPid)], {
+ timeoutMs: 1_000,
+ allowNonZeroExit: true,
+ maxBufferBytes: 32_768,
+ outputMode: "truncate",
+ }),
+ catch: (cause) =>
+ new TerminalSubprocessCheckError({
+ message: "Failed to inspect terminal subprocesses with pgrep.",
+ cause,
+ terminalPid,
+ command: "pgrep",
+ }),
+ });
+
+ const runPs = Effect.tryPromise({
+ try: () =>
+ runProcess("ps", ["-eo", "pid=,ppid="], {
+ timeoutMs: 1_000,
+ allowNonZeroExit: true,
+ maxBufferBytes: 262_144,
+ outputMode: "truncate",
+ }),
+ catch: (cause) =>
+ new TerminalSubprocessCheckError({
+ message: "Failed to inspect terminal subprocesses with ps.",
+ cause,
+ terminalPid,
+ command: "ps",
+ }),
+ });
+
+ const pgrepResult = yield* Effect.exit(runPgrep);
+ if (pgrepResult._tag === "Success") {
+ if (pgrepResult.value.code === 0) {
+ return pgrepResult.value.stdout.trim().length > 0;
}
- if (pgrepResult.code === 1) {
+ if (pgrepResult.value.code === 1) {
return false;
}
- } catch {
- // Fall back to ps when pgrep is unavailable.
}
- try {
- const psResult = await runProcess("ps", ["-eo", "pid=,ppid="], {
- timeoutMs: 1_000,
- allowNonZeroExit: true,
- maxBufferBytes: 262_144,
- outputMode: "truncate",
- });
- if (psResult.code !== 0) {
- return false;
- }
+ const psResult = yield* Effect.exit(runPs);
+ if (psResult._tag === "Failure" || psResult.value.code !== 0) {
+ return false;
+ }
- for (const line of psResult.stdout.split(/\r?\n/g)) {
- const [pidRaw, ppidRaw] = line.trim().split(/\s+/g);
- const pid = Number(pidRaw);
- const ppid = Number(ppidRaw);
- if (!Number.isInteger(pid) || !Number.isInteger(ppid)) continue;
- if (ppid === terminalPid) {
- return true;
- }
+ for (const line of psResult.value.stdout.split(/\r?\n/g)) {
+ const [pidRaw, ppidRaw] = line.trim().split(/\s+/g);
+ const pid = Number(pidRaw);
+ const ppid = Number(ppidRaw);
+ if (!Number.isInteger(pid) || !Number.isInteger(ppid)) continue;
+ if (ppid === terminalPid) {
+ return true;
}
- return false;
- } catch {
- return false;
}
-}
+ return false;
+});
-async function defaultSubprocessChecker(terminalPid: number): Promise<boolean> {
+const defaultSubprocessChecker = Effect.fn("terminal.defaultSubprocessChecker")(function* (
+ terminalPid: number,
+): Effect.fn.Return<boolean, TerminalSubprocessCheckError> {
if (!Number.isInteger(terminalPid) || terminalPid <= 0) {
return false;
}
if (process.platform === "win32") {
- return checkWindowsSubprocessActivity(terminalPid);
+ return yield* checkWindowsSubprocessActivity(terminalPid);
}
- return checkPosixSubprocessActivity(terminalPid);
-}
+ return yield* checkPosixSubprocessActivity(terminalPid);
+});
function capHistory(history: string, maxLines: number): string {
if (history.length === 0) return history;
@@ -482,12 +633,8 @@ function normalizedRuntimeEnv(
return Object.fromEntries(entries.toSorted(([left], [right]) => left.localeCompare(right)));
}
-interface TerminalManagerEvents {
- event: [event: TerminalEvent];
-}
-
interface TerminalManagerOptions {
- logsDir?: string;
+ logsDir: string;
historyLineLimit?: number;
ptyAdapter: PtyAdapterShape;
shellResolver?: () => string;
@@ -497,917 +644,1192 @@ interface TerminalManagerOptions {
maxRetainedInactiveSessions?: number;
}
-export class TerminalManagerRuntime extends EventEmitter<TerminalManagerEvents> {
- private readonly sessions = new Map<string, TerminalSessionState>();
- private readonly logsDir: string;
- private readonly historyLineLimit: number;
- private readonly ptyAdapter: PtyAdapterShape;
- private readonly shellResolver: () => string;
- private readonly persistQueues = new Map<string, Promise<void>>();
- private readonly persistTimers = new Map<string, ReturnType<typeof setTimeout>>();
- private readonly pendingPersistHistory = new Map<string, string>();
- private readonly threadLocks = new Map<string, Promise<void>>();
- private readonly persistDebounceMs: number;
- private readonly subprocessChecker: TerminalSubprocessChecker;
- private readonly subprocessPollIntervalMs: number;
- private readonly processKillGraceMs: number;
- private readonly maxRetainedInactiveSessions: number;
- private subprocessPollTimer: ReturnType<typeof setInterval> | null = null;
- private subprocessPollInFlight = false;
- private readonly killEscalationTimers = new Map<PtyProcess, ReturnType<typeof setTimeout>>();
- private readonly logger = createLogger("terminal");
-
- constructor(options: TerminalManagerOptions) {
- super();
- this.logsDir = options.logsDir ?? path.resolve(process.cwd(), ".logs", "terminals");
- this.historyLineLimit = options.historyLineLimit ?? DEFAULT_HISTORY_LINE_LIMIT;
- this.ptyAdapter = options.ptyAdapter;
- this.shellResolver = options.shellResolver ?? defaultShellResolver;
- this.persistDebounceMs = DEFAULT_PERSIST_DEBOUNCE_MS;
- this.subprocessChecker = options.subprocessChecker ?? defaultSubprocessChecker;
- this.subprocessPollIntervalMs =
+const makeTerminalManager = Effect.fn("makeTerminalManager")(function* () {
+ const { terminalLogsDir } = yield* ServerConfig;
+ const ptyAdapter = yield* PtyAdapter;
+ return yield* makeTerminalManagerWithOptions({
+ logsDir: terminalLogsDir,
+ ptyAdapter,
+ });
+});
+
+export const makeTerminalManagerWithOptions = Effect.fn("makeTerminalManagerWithOptions")(
+ function* (options: TerminalManagerOptions) {
+ const fileSystem = yield* FileSystem.FileSystem;
+ const services = yield* Effect.services();
+ const runFork = Effect.runForkWith(services);
+
+ const logsDir = options.logsDir;
+ const historyLineLimit = options.historyLineLimit ?? DEFAULT_HISTORY_LINE_LIMIT;
+ const shellResolver = options.shellResolver ?? defaultShellResolver;
+ const subprocessChecker = options.subprocessChecker ?? defaultSubprocessChecker;
+ const subprocessPollIntervalMs =
options.subprocessPollIntervalMs ?? DEFAULT_SUBPROCESS_POLL_INTERVAL_MS;
- this.processKillGraceMs = options.processKillGraceMs ?? DEFAULT_PROCESS_KILL_GRACE_MS;
- this.maxRetainedInactiveSessions =
+ const processKillGraceMs = options.processKillGraceMs ?? DEFAULT_PROCESS_KILL_GRACE_MS;
+ const maxRetainedInactiveSessions =
options.maxRetainedInactiveSessions ?? DEFAULT_MAX_RETAINED_INACTIVE_SESSIONS;
- fs.mkdirSync(this.logsDir, { recursive: true });
- }
- async open(raw: TerminalOpenInput): Promise<TerminalSessionSnapshot> {
- const input = decodeTerminalOpenInput(raw);
- return this.runWithThreadLock(input.threadId, async () => {
- await this.assertValidCwd(input.cwd);
-
- const sessionKey = toSessionKey(input.threadId, input.terminalId);
- const existing = this.sessions.get(sessionKey);
- if (!existing) {
- await this.flushPersistQueue(input.threadId, input.terminalId);
- const history = await this.readHistory(input.threadId, input.terminalId);
- const cols = input.cols ?? DEFAULT_OPEN_COLS;
- const rows = input.rows ?? DEFAULT_OPEN_ROWS;
- const session: TerminalSessionState = {
- threadId: input.threadId,
- terminalId: input.terminalId,
- cwd: input.cwd,
- status: "starting",
- pid: null,
- history,
- pendingHistoryControlSequence: "",
- exitCode: null,
- exitSignal: null,
- updatedAt: new Date().toISOString(),
- cols,
- rows,
- process: null,
- unsubscribeData: null,
- unsubscribeExit: null,
- hasRunningSubprocess: false,
- runtimeEnv: normalizedRuntimeEnv(input.env),
- };
- this.sessions.set(sessionKey, session);
- this.evictInactiveSessionsIfNeeded();
- await this.startSession(session, { ...input, cols, rows }, "started");
- return this.snapshot(session);
- }
+ yield* fileSystem.makeDirectory(logsDir, { recursive: true }).pipe(Effect.orDie);
- const nextRuntimeEnv = normalizedRuntimeEnv(input.env);
- const currentRuntimeEnv = existing.runtimeEnv;
- const targetCols = input.cols ?? existing.cols;
- const targetRows = input.rows ?? existing.rows;
- const runtimeEnvChanged =
- JSON.stringify(currentRuntimeEnv) !== JSON.stringify(nextRuntimeEnv);
-
- if (existing.cwd !== input.cwd || runtimeEnvChanged) {
- this.stopProcess(existing);
- existing.cwd = input.cwd;
- existing.runtimeEnv = nextRuntimeEnv;
- existing.history = "";
- existing.pendingHistoryControlSequence = "";
- await this.persistHistory(existing.threadId, existing.terminalId, existing.history);
- } else if (existing.status === "exited" || existing.status === "error") {
- existing.runtimeEnv = nextRuntimeEnv;
- existing.history = "";
- existing.pendingHistoryControlSequence = "";
- await this.persistHistory(existing.threadId, existing.terminalId, existing.history);
- } else if (currentRuntimeEnv !== nextRuntimeEnv) {
- existing.runtimeEnv = nextRuntimeEnv;
+ const managerStateRef = yield* SynchronizedRef.make<TerminalManagerState>({
+ sessions: new Map(),
+ killFibers: new Map(),
+ });
+ const threadLocksRef = yield* SynchronizedRef.make(new Map<string, Semaphore.Semaphore>());
+ const terminalEventListeners = new Set<(event: TerminalEvent) => Effect.Effect<void>>();
+ const workerScope = yield* Scope.make("sequential");
+ yield* Effect.addFinalizer(() => Scope.close(workerScope, Exit.void));
+
+ const publishEvent = (event: TerminalEvent) =>
+ Effect.gen(function* () {
+ for (const listener of terminalEventListeners) {
+ yield* listener(event).pipe(Effect.ignoreCause({ log: true }));
+ }
+ });
+
+ const historyPath = (threadId: string, terminalId: string) => {
+ const threadPart = toSafeThreadId(threadId);
+ if (terminalId === DEFAULT_TERMINAL_ID) {
+ return path.join(logsDir, `${threadPart}.log`);
}
+ return path.join(logsDir, `${threadPart}_${toSafeTerminalId(terminalId)}.log`);
+ };
+
+ const legacyHistoryPath = (threadId: string) =>
+ path.join(logsDir, `${legacySafeThreadId(threadId)}.log`);
- if (!existing.process) {
- await this.startSession(
- existing,
- { ...input, cols: targetCols, rows: targetRows },
- "started",
+ const toTerminalHistoryError =
+ (operation: "read" | "truncate" | "migrate", threadId: string, terminalId: string) =>
+ (cause: unknown) =>
+ new TerminalHistoryError({
+ operation,
+ threadId,
+ terminalId,
+ cause,
+ });
+
+ const readManagerState = SynchronizedRef.get(managerStateRef);
+
+ const modifyManagerState = <A>(
+ f: (state: TerminalManagerState) => readonly [A, TerminalManagerState],
+ ) => SynchronizedRef.modify(managerStateRef, f);
+
+ const getThreadSemaphore = (threadId: string) =>
+ SynchronizedRef.modifyEffect(threadLocksRef, (current) => {
+ const existing: Option.Option<Semaphore.Semaphore> = Option.fromNullishOr(
+ current.get(threadId),
);
- return this.snapshot(existing);
- }
+ return Option.match(existing, {
+ onNone: () =>
+ Semaphore.make(1).pipe(
+ Effect.map((semaphore) => {
+ const next = new Map(current);
+ next.set(threadId, semaphore);
+ return [semaphore, next] as const;
+ }),
+ ),
+ onSome: (semaphore) => Effect.succeed([semaphore, current] as const),
+ });
+ });
- if (existing.cols !== targetCols || existing.rows !== targetRows) {
- existing.cols = targetCols;
- existing.rows = targetRows;
- existing.process.resize(targetCols, targetRows);
- existing.updatedAt = new Date().toISOString();
+ const withThreadLock = <A, E, R>(
+ threadId: string,
+ effect: Effect.Effect<A, E, R>,
+ ): Effect.Effect<A, E, R> =>
+ Effect.flatMap(getThreadSemaphore(threadId), (semaphore) => semaphore.withPermit(effect));
+
+ const clearKillFiber = Effect.fn("terminal.clearKillFiber")(function* (
+ process: PtyProcess | null,
+ ) {
+ if (!process) return;
+ const fiber: Option.Option<Fiber.Fiber<void, never>> = yield* modifyManagerState<
+ Option.Option<Fiber.Fiber<void, never>>
+ >((state) => {
+ const existing: Option.Option<Fiber.Fiber<void, never>> = Option.fromNullishOr(
+ state.killFibers.get(process),
+ );
+ if (Option.isNone(existing)) {
+ return [Option.none<Fiber.Fiber<void, never>>(), state] as const;
+ }
+ const killFibers = new Map(state.killFibers);
+ killFibers.delete(process);
+ return [existing, { ...state, killFibers }] as const;
+ });
+ if (Option.isSome(fiber)) {
+ yield* Fiber.interrupt(fiber.value).pipe(Effect.ignore);
}
+ });
- return this.snapshot(existing);
+ const registerKillFiber = Effect.fn("terminal.registerKillFiber")(function* (
+ process: PtyProcess,
+ fiber: Fiber.Fiber<void, never>,
+ ) {
+ yield* modifyManagerState((state) => {
+ const killFibers = new Map(state.killFibers);
+ killFibers.set(process, fiber);
+ return [undefined, { ...state, killFibers }] as const;
+ });
});
- }
- async write(raw: TerminalWriteInput): Promise<void> {
- const input = decodeTerminalWriteInput(raw);
- const session = this.requireSession(input.threadId, input.terminalId);
- if (!session.process || session.status !== "running") {
- if (session.status === "exited") {
+ const runKillEscalation = Effect.fn("terminal.runKillEscalation")(function* (
+ process: PtyProcess,
+ threadId: string,
+ terminalId: string,
+ ) {
+ const terminated = yield* Effect.try({
+ try: () => process.kill("SIGTERM"),
+ catch: (cause) =>
+ new TerminalProcessSignalError({
+ message: "Failed to send SIGTERM to terminal process.",
+ cause,
+ signal: "SIGTERM",
+ }),
+ }).pipe(
+ Effect.as(true),
+ Effect.catch((error) =>
+ Effect.logWarning("failed to kill terminal process", {
+ threadId,
+ terminalId,
+ signal: "SIGTERM",
+ error: error.message,
+ }).pipe(Effect.as(false)),
+ ),
+ );
+ if (!terminated) {
return;
}
- throw new Error(
- `Terminal is not running for thread: ${input.threadId}, terminal: ${input.terminalId}`,
+
+ yield* Effect.sleep(processKillGraceMs);
+
+ yield* Effect.try({
+ try: () => process.kill("SIGKILL"),
+ catch: (cause) =>
+ new TerminalProcessSignalError({
+ message: "Failed to send SIGKILL to terminal process.",
+ cause,
+ signal: "SIGKILL",
+ }),
+ }).pipe(
+ Effect.catch((error) =>
+ Effect.logWarning("failed to force-kill terminal process", {
+ threadId,
+ terminalId,
+ signal: "SIGKILL",
+ error: error.message,
+ }),
+ ),
);
- }
- session.process.write(input.data);
- }
+ });
- async resize(raw: TerminalResizeInput): Promise<void> {
- const input = decodeTerminalResizeInput(raw);
- const session = this.requireSession(input.threadId, input.terminalId);
- if (!session.process || session.status !== "running") {
- throw new Error(
- `Terminal is not running for thread: ${input.threadId}, terminal: ${input.terminalId}`,
+ const startKillEscalation = Effect.fn("terminal.startKillEscalation")(function* (
+ process: PtyProcess,
+ threadId: string,
+ terminalId: string,
+ ) {
+ const fiber = yield* runKillEscalation(process, threadId, terminalId).pipe(
+ Effect.ensuring(
+ modifyManagerState((state) => {
+ if (!state.killFibers.has(process)) {
+ return [undefined, state] as const;
+ }
+ const killFibers = new Map(state.killFibers);
+ killFibers.delete(process);
+ return [undefined, { ...state, killFibers }] as const;
+ }),
+ ),
+ Effect.forkIn(workerScope),
);
- }
- session.cols = input.cols;
- session.rows = input.rows;
- session.updatedAt = new Date().toISOString();
- session.process.resize(input.cols, input.rows);
- }
- async clear(raw: TerminalClearInput): Promise<void> {
- const input = decodeTerminalClearInput(raw);
- await this.runWithThreadLock(input.threadId, async () => {
- const session = this.requireSession(input.threadId, input.terminalId);
- session.history = "";
- session.pendingHistoryControlSequence = "";
- session.updatedAt = new Date().toISOString();
- await this.persistHistory(input.threadId, input.terminalId, session.history);
- this.emitEvent({
- type: "cleared",
- threadId: input.threadId,
- terminalId: input.terminalId,
- createdAt: new Date().toISOString(),
+ yield* registerKillFiber(process, fiber);
+ });
+
+ const persistWorker = yield* makeKeyedCoalescingWorker<
+ string,
+ PersistHistoryRequest,
+ never,
+ never
+ >({
+ merge: (current, next) => ({
+ history: next.history,
+ immediate: current.immediate || next.immediate,
+ }),
+ process: Effect.fn("terminal.persistHistoryWorker")(function* (sessionKey, request) {
+ if (!request.immediate) {
+ yield* Effect.sleep(DEFAULT_PERSIST_DEBOUNCE_MS);
+ }
+
+ const [threadId, terminalId] = sessionKey.split("\u0000");
+ if (!threadId || !terminalId) {
+ return;
+ }
+
+ yield* fileSystem.writeFileString(historyPath(threadId, terminalId), request.history).pipe(
+ Effect.catch((error) =>
+ Effect.logWarning("failed to persist terminal history", {
+ threadId,
+ terminalId,
+ error: error instanceof Error ? error.message : String(error),
+ }),
+ ),
+ );
+ }),
+ });
+
+ const queuePersist = Effect.fn("terminal.queuePersist")(function* (
+ threadId: string,
+ terminalId: string,
+ history: string,
+ ) {
+ yield* persistWorker.enqueue(toSessionKey(threadId, terminalId), {
+ history,
+ immediate: false,
});
});
- }
- async restart(raw: TerminalRestartInput): Promise<TerminalSessionSnapshot> {
- const input = decodeTerminalRestartInput(raw);
- return this.runWithThreadLock(input.threadId, async () => {
- await this.assertValidCwd(input.cwd);
-
- const sessionKey = toSessionKey(input.threadId, input.terminalId);
- let session = this.sessions.get(sessionKey);
- if (!session) {
- const cols = input.cols ?? DEFAULT_OPEN_COLS;
- const rows = input.rows ?? DEFAULT_OPEN_ROWS;
- session = {
- threadId: input.threadId,
- terminalId: input.terminalId,
- cwd: input.cwd,
- status: "starting",
- pid: null,
- history: "",
- pendingHistoryControlSequence: "",
- exitCode: null,
- exitSignal: null,
- updatedAt: new Date().toISOString(),
- cols,
- rows,
- process: null,
- unsubscribeData: null,
- unsubscribeExit: null,
- hasRunningSubprocess: false,
- runtimeEnv: normalizedRuntimeEnv(input.env),
- };
- this.sessions.set(sessionKey, session);
- this.evictInactiveSessionsIfNeeded();
- } else {
- this.stopProcess(session);
- session.cwd = input.cwd;
- session.runtimeEnv = normalizedRuntimeEnv(input.env);
+ const flushPersist = Effect.fn("terminal.flushPersist")(function* (
+ threadId: string,
+ terminalId: string,
+ ) {
+ yield* persistWorker.drainKey(toSessionKey(threadId, terminalId));
+ });
+
+ const persistHistory = Effect.fn("terminal.persistHistory")(function* (
+ threadId: string,
+ terminalId: string,
+ history: string,
+ ) {
+ yield* persistWorker.enqueue(toSessionKey(threadId, terminalId), {
+ history,
+ immediate: true,
+ });
+ yield* flushPersist(threadId, terminalId);
+ });
+
+ const readHistory = Effect.fn("terminal.readHistory")(function* (
+ threadId: string,
+ terminalId: string,
+ ) {
+ const nextPath = historyPath(threadId, terminalId);
+ if (
+ yield* fileSystem
+ .exists(nextPath)
+ .pipe(Effect.mapError(toTerminalHistoryError("read", threadId, terminalId)))
+ ) {
+ const raw = yield* fileSystem
+ .readFileString(nextPath)
+ .pipe(Effect.mapError(toTerminalHistoryError("read", threadId, terminalId)));
+ const capped = capHistory(raw, historyLineLimit);
+ if (capped !== raw) {
+ yield* fileSystem
+ .writeFileString(nextPath, capped)
+ .pipe(Effect.mapError(toTerminalHistoryError("truncate", threadId, terminalId)));
+ }
+ return capped;
+ }
+
+ if (terminalId !== DEFAULT_TERMINAL_ID) {
+ return "";
}
- const cols = input.cols ?? session.cols;
- const rows = input.rows ?? session.rows;
+ const legacyPath = legacyHistoryPath(threadId);
+ if (
+ !(yield* fileSystem
+ .exists(legacyPath)
+ .pipe(Effect.mapError(toTerminalHistoryError("migrate", threadId, terminalId))))
+ ) {
+ return "";
+ }
- session.history = "";
- session.pendingHistoryControlSequence = "";
- await this.persistHistory(input.threadId, input.terminalId, session.history);
- await this.startSession(session, { ...input, cols, rows }, "restarted");
- return this.snapshot(session);
+ const raw = yield* fileSystem
+ .readFileString(legacyPath)
+ .pipe(Effect.mapError(toTerminalHistoryError("migrate", threadId, terminalId)));
+ const capped = capHistory(raw, historyLineLimit);
+ yield* fileSystem
+ .writeFileString(nextPath, capped)
+ .pipe(Effect.mapError(toTerminalHistoryError("migrate", threadId, terminalId)));
+ yield* fileSystem.remove(legacyPath, { force: true }).pipe(
+ Effect.catch((cleanupError) =>
+ Effect.logWarning("failed to remove legacy terminal history", {
+ threadId,
+ error: cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
+ }),
+ ),
+ );
+ return capped;
});
- }
- async close(raw: TerminalCloseInput): Promise<void> {
- const input = decodeTerminalCloseInput(raw);
- await this.runWithThreadLock(input.threadId, async () => {
- if (input.terminalId) {
- await this.closeSession(input.threadId, input.terminalId, input.deleteHistory === true);
- return;
+ const deleteHistory = Effect.fn("terminal.deleteHistory")(function* (
+ threadId: string,
+ terminalId: string,
+ ) {
+ yield* fileSystem.remove(historyPath(threadId, terminalId), { force: true }).pipe(
+ Effect.catch((error) =>
+ Effect.logWarning("failed to delete terminal history", {
+ threadId,
+ terminalId,
+ error: error instanceof Error ? error.message : String(error),
+ }),
+ ),
+ );
+ if (terminalId === DEFAULT_TERMINAL_ID) {
+ yield* fileSystem.remove(legacyHistoryPath(threadId), { force: true }).pipe(
+ Effect.catch((error) =>
+ Effect.logWarning("failed to delete terminal history", {
+ threadId,
+ terminalId,
+ error: error instanceof Error ? error.message : String(error),
+ }),
+ ),
+ );
}
+ });
- const threadSessions = this.sessionsForThread(input.threadId);
- for (const session of threadSessions) {
- this.stopProcess(session);
- this.sessions.delete(toSessionKey(session.threadId, session.terminalId));
- }
- await Promise.all(
- threadSessions.map((session) =>
- this.flushPersistQueue(session.threadId, session.terminalId),
+ const deleteAllHistoryForThread = Effect.fn("terminal.deleteAllHistoryForThread")(function* (
+ threadId: string,
+ ) {
+ const threadPrefix = `${toSafeThreadId(threadId)}_`;
+ const entries = yield* fileSystem
+ .readDirectory(logsDir, { recursive: false })
+ .pipe(Effect.catch(() => Effect.succeed([] as Array<string>)));
+ yield* Effect.forEach(
+ entries.filter(
+ (name) =>
+ name === `${toSafeThreadId(threadId)}.log` ||
+ name === `${legacySafeThreadId(threadId)}.log` ||
+ name.startsWith(threadPrefix),
),
+ (name) =>
+ fileSystem.remove(path.join(logsDir, name), { force: true }).pipe(
+ Effect.catch((error) =>
+ Effect.logWarning("failed to delete terminal histories for thread", {
+ threadId,
+ error: error instanceof Error ? error.message : String(error),
+ }),
+ ),
+ ),
+ { discard: true },
);
+ });
- if (input.deleteHistory) {
- await this.deleteAllHistoryForThread(input.threadId);
+ const assertValidCwd = Effect.fn("terminal.assertValidCwd")(function* (cwd: string) {
+ const stats = yield* fileSystem.stat(cwd).pipe(
+ Effect.mapError(
+ (cause) =>
+ new TerminalCwdError({
+ cwd,
+ reason: cause.reason._tag === "NotFound" ? "notFound" : "statFailed",
+ cause,
+ }),
+ ),
+ );
+ if (stats.type !== "Directory") {
+ return yield* new TerminalCwdError({
+ cwd,
+ reason: "notDirectory",
+ });
}
- this.updateSubprocessPollingState();
});
- }
- dispose(): void {
- this.stopSubprocessPolling();
- const sessions = [...this.sessions.values()];
- this.sessions.clear();
- for (const session of sessions) {
- this.stopProcess(session);
- }
- for (const timer of this.persistTimers.values()) {
- clearTimeout(timer);
- }
- this.persistTimers.clear();
- for (const timer of this.killEscalationTimers.values()) {
- clearTimeout(timer);
- }
- this.killEscalationTimers.clear();
- this.pendingPersistHistory.clear();
- this.threadLocks.clear();
- this.persistQueues.clear();
- }
+ const getSession = Effect.fn("terminal.getSession")(function* (
+ threadId: string,
+ terminalId: string,
+ ): Effect.fn.Return<Option.Option<TerminalSessionState>> {
+ return yield* Effect.map(readManagerState, (state) =>
+ Option.fromNullishOr(state.sessions.get(toSessionKey(threadId, terminalId))),
+ );
+ });
- private async startSession(
- session: TerminalSessionState,
- input: TerminalStartInput,
- eventType: "started" | "restarted",
- ): Promise<void> {
- this.stopProcess(session);
-
- session.status = "starting";
- session.cwd = input.cwd;
- session.cols = input.cols;
- session.rows = input.rows;
- session.exitCode = null;
- session.exitSignal = null;
- session.hasRunningSubprocess = false;
- session.updatedAt = new Date().toISOString();
-
- let ptyProcess: PtyProcess | null = null;
- let startedShell: string | null = null;
- try {
- const shellCandidates = resolveShellCandidates(this.shellResolver);
- const terminalEnv = createTerminalSpawnEnv(process.env, session.runtimeEnv);
- let lastSpawnError: unknown = null;
-
- const spawnWithCandidate = (candidate: ShellCandidate) =>
- Effect.runPromise(
- this.ptyAdapter.spawn({
- shell: candidate.shell,
- ...(candidate.args ? { args: candidate.args } : {}),
- cwd: session.cwd,
- cols: session.cols,
- rows: session.rows,
- env: terminalEnv,
- }),
- );
+ const requireSession = Effect.fn("terminal.requireSession")(function* (
+ threadId: string,
+ terminalId: string,
+ ): Effect.fn.Return<TerminalSessionState, TerminalSessionLookupError> {
+ return yield* Effect.flatMap(getSession(threadId, terminalId), (session) =>
+ Option.match(session, {
+ onNone: () =>
+ Effect.fail(
+ new TerminalSessionLookupError({
+ threadId,
+ terminalId,
+ }),
+ ),
+ onSome: Effect.succeed,
+ }),
+ );
+ });
- const trySpawn = async (
- candidates: ShellCandidate[],
- index = 0,
- ): Promise<{ process: PtyProcess; shellLabel: string } | null> => {
- if (index >= candidates.length) {
- return null;
- }
- const candidate = candidates[index];
- if (!candidate) {
- return null;
+ const sessionsForThread = Effect.fn("terminal.sessionsForThread")(function* (threadId: string) {
+ return yield* readManagerState.pipe(
+ Effect.map((state) =>
+ [...state.sessions.values()].filter((session) => session.threadId === threadId),
+ ),
+ );
+ });
+
+ const evictInactiveSessionsIfNeeded = Effect.fn("terminal.evictInactiveSessionsIfNeeded")(
+ function* () {
+ yield* modifyManagerState((state) => {
+ const inactiveSessions = [...state.sessions.values()].filter(
+ (session) => session.status !== "running",
+ );
+ if (inactiveSessions.length <= maxRetainedInactiveSessions) {
+ return [undefined, state] as const;
+ }
+
+ inactiveSessions.sort(
+ (left, right) =>
+ left.updatedAt.localeCompare(right.updatedAt) ||
+ left.threadId.localeCompare(right.threadId) ||
+ left.terminalId.localeCompare(right.terminalId),
+ );
+
+ const sessions = new Map(state.sessions);
+
+ const toEvict = inactiveSessions.length - maxRetainedInactiveSessions;
+ for (const session of inactiveSessions.slice(0, toEvict)) {
+ const key = toSessionKey(session.threadId, session.terminalId);
+ sessions.delete(key);
+ }
+
+ return [undefined, { ...state, sessions }] as const;
+ });
+ },
+ );
+
+ const drainProcessEvents = Effect.fn("terminal.drainProcessEvents")(function* (
+ session: TerminalSessionState,
+ expectedPid: number,
+ ) {
+ while (true) {
+ const action: DrainProcessEventAction = yield* Effect.sync(() => {
+ if (session.pid !== expectedPid || !session.process || session.status !== "running") {
+ session.pendingProcessEvents = [];
+ session.pendingProcessEventIndex = 0;
+ session.processEventDrainRunning = false;
+ return { type: "idle" } as const;
+ }
+
+ const nextEvent = session.pendingProcessEvents[session.pendingProcessEventIndex];
+ if (!nextEvent) {
+ session.pendingProcessEvents = [];
+ session.pendingProcessEventIndex = 0;
+ session.processEventDrainRunning = false;
+ return { type: "idle" } as const;
+ }
+
+ session.pendingProcessEventIndex += 1;
+ if (session.pendingProcessEventIndex >= session.pendingProcessEvents.length) {
+ session.pendingProcessEvents = [];
+ session.pendingProcessEventIndex = 0;
+ }
+
+ if (nextEvent.type === "output") {
+ const sanitized = sanitizeTerminalHistoryChunk(
+ session.pendingHistoryControlSequence,
+ nextEvent.data,
+ );
+ session.pendingHistoryControlSequence = sanitized.pendingControlSequence;
+ if (sanitized.visibleText.length > 0) {
+ session.history = capHistory(
+ `${session.history}${sanitized.visibleText}`,
+ historyLineLimit,
+ );
+ }
+ session.updatedAt = new Date().toISOString();
+
+ return {
+ type: "output",
+ threadId: session.threadId,
+ terminalId: session.terminalId,
+ history: sanitized.visibleText.length > 0 ? session.history : null,
+ data: nextEvent.data,
+ } as const;
+ }
+
+ const process = session.process;
+ cleanupProcessHandles(session);
+ session.process = null;
+ session.pid = null;
+ session.hasRunningSubprocess = false;
+ session.status = "exited";
+ session.pendingHistoryControlSequence = "";
+ session.pendingProcessEvents = [];
+ session.pendingProcessEventIndex = 0;
+ session.processEventDrainRunning = false;
+ session.exitCode = Number.isInteger(nextEvent.event.exitCode)
+ ? nextEvent.event.exitCode
+ : null;
+ session.exitSignal = Number.isInteger(nextEvent.event.signal)
+ ? nextEvent.event.signal
+ : null;
+ session.updatedAt = new Date().toISOString();
+
+ return {
+ type: "exit",
+ process,
+ threadId: session.threadId,
+ terminalId: session.terminalId,
+ exitCode: session.exitCode,
+ exitSignal: session.exitSignal,
+ } as const;
+ });
+
+ if (action.type === "idle") {
+ return;
}
- try {
- const process = await spawnWithCandidate(candidate);
- return { process, shellLabel: formatShellCandidate(candidate) };
- } catch (error) {
- lastSpawnError = error;
- if (!isRetryableShellSpawnError(error)) {
- throw error;
+ if (action.type === "output") {
+ if (action.history !== null) {
+ yield* queuePersist(action.threadId, action.terminalId, action.history);
}
- return trySpawn(candidates, index + 1);
+
+ yield* publishEvent({
+ type: "output",
+ threadId: action.threadId,
+ terminalId: action.terminalId,
+ createdAt: new Date().toISOString(),
+ data: action.data,
+ });
+ continue;
}
- };
- const spawnResult = await trySpawn(shellCandidates);
- if (spawnResult) {
- ptyProcess = spawnResult.process;
- startedShell = spawnResult.shellLabel;
+ yield* clearKillFiber(action.process);
+ yield* publishEvent({
+ type: "exited",
+ threadId: action.threadId,
+ terminalId: action.terminalId,
+ createdAt: new Date().toISOString(),
+ exitCode: action.exitCode,
+ exitSignal: action.exitSignal,
+ });
+ yield* evictInactiveSessionsIfNeeded();
+ return;
}
+ });
+
+ const stopProcess = Effect.fn("terminal.stopProcess")(function* (
+ session: TerminalSessionState,
+ ) {
+ const process = session.process;
+ if (!process) return;
+
+ yield* modifyManagerState((state) => {
+ cleanupProcessHandles(session);
+ session.process = null;
+ session.pid = null;
+ session.hasRunningSubprocess = false;
+ session.status = "exited";
+ session.pendingHistoryControlSequence = "";
+ session.pendingProcessEvents = [];
+ session.pendingProcessEventIndex = 0;
+ session.processEventDrainRunning = false;
+ session.updatedAt = new Date().toISOString();
+ return [undefined, state] as const;
+ });
- if (!ptyProcess) {
- const detail =
- lastSpawnError instanceof Error ? lastSpawnError.message : "Terminal start failed";
+ yield* clearKillFiber(process);
+ yield* startKillEscalation(process, session.threadId, session.terminalId);
+ yield* evictInactiveSessionsIfNeeded();
+ });
+
+ const trySpawn = Effect.fn("terminal.trySpawn")(function* (
+ shellCandidates: ReadonlyArray<ShellCandidate>,
+ spawnEnv: NodeJS.ProcessEnv,
+ session: TerminalSessionState,
+ index = 0,
+ lastError: PtySpawnError | null = null,
+ ): Effect.fn.Return<{ process: PtyProcess; shellLabel: string }, PtySpawnError> {
+ if (index >= shellCandidates.length) {
+ const detail = lastError?.message ?? "Failed to spawn PTY process";
const tried =
shellCandidates.length > 0
? ` Tried shells: ${shellCandidates.map((candidate) => formatShellCandidate(candidate)).join(", ")}.`
: "";
- throw new Error(`${detail}.${tried}`.trim());
+ return yield* new PtySpawnError({
+ adapter: "terminal-manager",
+ message: `${detail}.${tried}`.trim(),
+ ...(lastError ? { cause: lastError } : {}),
+ });
}
- session.process = ptyProcess;
- session.pid = ptyProcess.pid;
- session.status = "running";
- session.updatedAt = new Date().toISOString();
- session.unsubscribeData = ptyProcess.onData((data) => {
- this.onProcessData(session, data);
- });
- session.unsubscribeExit = ptyProcess.onExit((event) => {
- this.onProcessExit(session, event);
- });
- this.updateSubprocessPollingState();
- this.emitEvent({
- type: eventType,
- threadId: session.threadId,
- terminalId: session.terminalId,
- createdAt: new Date().toISOString(),
- snapshot: this.snapshot(session),
- });
- } catch (error) {
- if (ptyProcess) {
- this.killProcessWithEscalation(ptyProcess, session.threadId, session.terminalId);
+ const candidate = shellCandidates[index];
+ if (!candidate) {
+ return yield* (
+ lastError ??
+ new PtySpawnError({
+ adapter: "terminal-manager",
+ message: "No shell candidate available for PTY spawn.",
+ })
+ );
}
- session.status = "error";
- session.pid = null;
- session.process = null;
- session.hasRunningSubprocess = false;
- session.updatedAt = new Date().toISOString();
- this.evictInactiveSessionsIfNeeded();
- this.updateSubprocessPollingState();
- const message = error instanceof Error ? error.message : "Terminal start failed";
- this.emitEvent({
- type: "error",
- threadId: session.threadId,
- terminalId: session.terminalId,
- createdAt: new Date().toISOString(),
- message,
- });
- this.logger.error("failed to start terminal", {
- threadId: session.threadId,
- terminalId: session.terminalId,
- error: message,
- ...(startedShell ? { shell: startedShell } : {}),
- });
- }
- }
- private onProcessData(session: TerminalSessionState, data: string): void {
- const sanitized = sanitizeTerminalHistoryChunk(session.pendingHistoryControlSequence, data);
- session.pendingHistoryControlSequence = sanitized.pendingControlSequence;
- if (sanitized.visibleText.length > 0) {
- session.history = capHistory(
- `${session.history}${sanitized.visibleText}`,
- this.historyLineLimit,
+ const attempt = yield* Effect.result(
+ options.ptyAdapter.spawn({
+ shell: candidate.shell,
+ ...(candidate.args ? { args: candidate.args } : {}),
+ cwd: session.cwd,
+ cols: session.cols,
+ rows: session.rows,
+ env: spawnEnv,
+ }),
);
- this.queuePersist(session.threadId, session.terminalId, session.history);
- }
- session.updatedAt = new Date().toISOString();
- this.emitEvent({
- type: "output",
- threadId: session.threadId,
- terminalId: session.terminalId,
- createdAt: new Date().toISOString(),
- data,
- });
- }
- private onProcessExit(session: TerminalSessionState, event: PtyExitEvent): void {
- this.clearKillEscalationTimer(session.process);
- this.cleanupProcessHandles(session);
- session.process = null;
- session.pid = null;
- session.hasRunningSubprocess = false;
- session.status = "exited";
- session.pendingHistoryControlSequence = "";
- session.exitCode = Number.isInteger(event.exitCode) ? event.exitCode : null;
- session.exitSignal = Number.isInteger(event.signal) ? event.signal : null;
- session.updatedAt = new Date().toISOString();
- this.emitEvent({
- type: "exited",
- threadId: session.threadId,
- terminalId: session.terminalId,
- createdAt: new Date().toISOString(),
- exitCode: session.exitCode,
- exitSignal: session.exitSignal,
- });
- this.evictInactiveSessionsIfNeeded();
- this.updateSubprocessPollingState();
- }
+ if (attempt._tag === "Success") {
+ return {
+ process: attempt.success,
+ shellLabel: formatShellCandidate(candidate),
+ };
+ }
- private stopProcess(session: TerminalSessionState): void {
- const process = session.process;
- if (!process) return;
- this.cleanupProcessHandles(session);
- session.process = null;
- session.pid = null;
- session.hasRunningSubprocess = false;
- session.status = "exited";
- session.pendingHistoryControlSequence = "";
- session.updatedAt = new Date().toISOString();
- this.killProcessWithEscalation(process, session.threadId, session.terminalId);
- this.evictInactiveSessionsIfNeeded();
- this.updateSubprocessPollingState();
- }
+ const spawnError = attempt.failure;
+ if (!isRetryableShellSpawnError(spawnError)) {
+ return yield* spawnError;
+ }
- private cleanupProcessHandles(session: TerminalSessionState): void {
- session.unsubscribeData?.();
- session.unsubscribeData = null;
- session.unsubscribeExit?.();
- session.unsubscribeExit = null;
- }
+ return yield* trySpawn(shellCandidates, spawnEnv, session, index + 1, spawnError);
+ });
- private clearKillEscalationTimer(process: PtyProcess | null): void {
- if (!process) return;
- const timer = this.killEscalationTimers.get(process);
- if (!timer) return;
- clearTimeout(timer);
- this.killEscalationTimers.delete(process);
- }
+ const startSession = Effect.fn("terminal.startSession")(function* (
+ session: TerminalSessionState,
+ input: TerminalStartInput,
+ eventType: "started" | "restarted",
+ ) {
+ yield* stopProcess(session);
- private killProcessWithEscalation(
- process: PtyProcess,
- threadId: string,
- terminalId: string,
- ): void {
- this.clearKillEscalationTimer(process);
- try {
- process.kill("SIGTERM");
- } catch (error) {
- const message = error instanceof Error ? error.message : String(error);
- this.logger.warn("failed to kill terminal process", {
- threadId,
- terminalId,
- signal: "SIGTERM",
- error: message,
+ yield* modifyManagerState((state) => {
+ session.status = "starting";
+ session.cwd = input.cwd;
+ session.cols = input.cols;
+ session.rows = input.rows;
+ session.exitCode = null;
+ session.exitSignal = null;
+ session.hasRunningSubprocess = false;
+ session.pendingProcessEvents = [];
+ session.pendingProcessEventIndex = 0;
+ session.processEventDrainRunning = false;
+ session.updatedAt = new Date().toISOString();
+ return [undefined, state] as const;
});
- return;
- }
- const timer = setTimeout(() => {
- this.killEscalationTimers.delete(process);
- try {
- process.kill("SIGKILL");
- } catch (error) {
- const message = error instanceof Error ? error.message : String(error);
- this.logger.warn("failed to force-kill terminal process", {
- threadId,
- terminalId,
- signal: "SIGKILL",
- error: message,
- });
- }
- }, this.processKillGraceMs);
- timer.unref?.();
- this.killEscalationTimers.set(process, timer);
- }
+ let ptyProcess: PtyProcess | null = null;
+ let startedShell: string | null = null;
+
+ const startResult = yield* Effect.result(
+ Effect.gen(function* () {
+ const shellCandidates = resolveShellCandidates(shellResolver);
+ const terminalEnv = createTerminalSpawnEnv(process.env, session.runtimeEnv);
+ const spawnResult = yield* trySpawn(shellCandidates, terminalEnv, session);
+ ptyProcess = spawnResult.process;
+ startedShell = spawnResult.shellLabel;
+
+ const processPid = ptyProcess.pid;
+ const unsubscribeData = ptyProcess.onData((data) => {
+ if (!enqueueProcessEvent(session, processPid, { type: "output", data })) {
+ return;
+ }
+ runFork(drainProcessEvents(session, processPid));
+ });
+ const unsubscribeExit = ptyProcess.onExit((event) => {
+ if (!enqueueProcessEvent(session, processPid, { type: "exit", event })) {
+ return;
+ }
+ runFork(drainProcessEvents(session, processPid));
+ });
- private evictInactiveSessionsIfNeeded(): void {
- const inactiveSessions = [...this.sessions.values()].filter(
- (session) => session.status !== "running",
- );
- if (inactiveSessions.length <= this.maxRetainedInactiveSessions) {
- return;
- }
+ yield* modifyManagerState((state) => {
+ session.process = ptyProcess;
+ session.pid = processPid;
+ session.status = "running";
+ session.updatedAt = new Date().toISOString();
+ session.unsubscribeData = unsubscribeData;
+ session.unsubscribeExit = unsubscribeExit;
+ return [undefined, state] as const;
+ });
- inactiveSessions.sort(
- (left, right) =>
- left.updatedAt.localeCompare(right.updatedAt) ||
- left.threadId.localeCompare(right.threadId) ||
- left.terminalId.localeCompare(right.terminalId),
- );
- const toEvict = inactiveSessions.length - this.maxRetainedInactiveSessions;
- for (const session of inactiveSessions.slice(0, toEvict)) {
- const key = toSessionKey(session.threadId, session.terminalId);
- this.sessions.delete(key);
- this.clearPersistTimer(session.threadId, session.terminalId);
- this.pendingPersistHistory.delete(key);
- this.persistQueues.delete(key);
- this.clearKillEscalationTimer(session.process);
- }
- }
+ yield* publishEvent({
+ type: eventType,
+ threadId: session.threadId,
+ terminalId: session.terminalId,
+ createdAt: new Date().toISOString(),
+ snapshot: snapshot(session),
+ });
+ }),
+ );
- private queuePersist(threadId: string, terminalId: string, history: string): void {
- const persistenceKey = toSessionKey(threadId, terminalId);
- this.pendingPersistHistory.set(persistenceKey, history);
- this.schedulePersist(threadId, terminalId);
- }
+ if (startResult._tag === "Success") {
+ return;
+ }
- private async persistHistory(
- threadId: string,
- terminalId: string,
- history: string,
- ): Promise<void> {
- const persistenceKey = toSessionKey(threadId, terminalId);
- this.clearPersistTimer(threadId, terminalId);
- this.pendingPersistHistory.delete(persistenceKey);
- await this.enqueuePersistWrite(threadId, terminalId, history);
- }
+ {
+ const error = startResult.failure;
+ if (ptyProcess) {
+ yield* startKillEscalation(ptyProcess, session.threadId, session.terminalId);
+ }
- private enqueuePersistWrite(
- threadId: string,
- terminalId: string,
- history: string,
- ): Promise<void> {
- const persistenceKey = toSessionKey(threadId, terminalId);
- const task = async () => {
- await fs.promises.writeFile(this.historyPath(threadId, terminalId), history, "utf8");
- };
- const previous = this.persistQueues.get(persistenceKey) ?? Promise.resolve();
- const next = previous
- .catch(() => undefined)
- .then(task)
- .catch((error) => {
- this.logger.warn("failed to persist terminal history", {
- threadId,
- terminalId,
- error: error instanceof Error ? error.message : String(error),
+ yield* modifyManagerState((state) => {
+ session.status = "error";
+ session.pid = null;
+ session.process = null;
+ session.unsubscribeData = null;
+ session.unsubscribeExit = null;
+ session.hasRunningSubprocess = false;
+ session.pendingProcessEvents = [];
+ session.pendingProcessEventIndex = 0;
+ session.processEventDrainRunning = false;
+ session.updatedAt = new Date().toISOString();
+ return [undefined, state] as const;
+ });
+
+ yield* evictInactiveSessionsIfNeeded();
+
+ const message = error.message;
+ yield* publishEvent({
+ type: "error",
+ threadId: session.threadId,
+ terminalId: session.terminalId,
+ createdAt: new Date().toISOString(),
+ message,
+ });
+ yield* Effect.logError("failed to start terminal", {
+ threadId: session.threadId,
+ terminalId: session.terminalId,
+ error: message,
+ ...(startedShell ? { shell: startedShell } : {}),
});
- });
- this.persistQueues.set(persistenceKey, next);
- const finalized = next.finally(() => {
- if (this.persistQueues.get(persistenceKey) === next) {
- this.persistQueues.delete(persistenceKey);
- }
- if (
- this.pendingPersistHistory.has(persistenceKey) &&
- !this.persistTimers.has(persistenceKey)
- ) {
- this.schedulePersist(threadId, terminalId);
}
});
- void finalized.catch(() => undefined);
- return finalized;
- }
- private schedulePersist(threadId: string, terminalId: string): void {
- const persistenceKey = toSessionKey(threadId, terminalId);
- if (this.persistTimers.has(persistenceKey)) return;
- const timer = setTimeout(() => {
- this.persistTimers.delete(persistenceKey);
- const pendingHistory = this.pendingPersistHistory.get(persistenceKey);
- if (pendingHistory === undefined) return;
- this.pendingPersistHistory.delete(persistenceKey);
- void this.enqueuePersistWrite(threadId, terminalId, pendingHistory);
- }, this.persistDebounceMs);
- this.persistTimers.set(persistenceKey, timer);
- }
+ const closeSession = Effect.fn("terminal.closeSession")(function* (
+ threadId: string,
+ terminalId: string,
+ deleteHistoryOnClose: boolean,
+ ) {
+ const key = toSessionKey(threadId, terminalId);
+ const session = yield* getSession(threadId, terminalId);
+
+ if (Option.isSome(session)) {
+ yield* stopProcess(session.value);
+ yield* persistHistory(threadId, terminalId, session.value.history);
+ }
- private clearPersistTimer(threadId: string, terminalId: string): void {
- const persistenceKey = toSessionKey(threadId, terminalId);
- const timer = this.persistTimers.get(persistenceKey);
- if (!timer) return;
- clearTimeout(timer);
- this.persistTimers.delete(persistenceKey);
- }
+ yield* flushPersist(threadId, terminalId);
- private async readHistory(threadId: string, terminalId: string): Promise<string> {
- const nextPath = this.historyPath(threadId, terminalId);
- try {
- const raw = await fs.promises.readFile(nextPath, "utf8");
- const capped = capHistory(raw, this.historyLineLimit);
- if (capped !== raw) {
- await fs.promises.writeFile(nextPath, capped, "utf8");
- }
- return capped;
- } catch (error) {
- if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
- throw error;
+ yield* modifyManagerState((state) => {
+ if (!state.sessions.has(key)) {
+ return [undefined, state] as const;
+ }
+ const sessions = new Map(state.sessions);
+ sessions.delete(key);
+ return [undefined, { ...state, sessions }] as const;
+ });
+
+ if (deleteHistoryOnClose) {
+ yield* deleteHistory(threadId, terminalId);
}
- }
+ });
- if (terminalId !== DEFAULT_TERMINAL_ID) {
- return "";
- }
+ const pollSubprocessActivity = Effect.fn("terminal.pollSubprocessActivity")(function* () {
+ const state = yield* readManagerState;
+ const runningSessions = [...state.sessions.values()].filter(
+ (session): session is TerminalSessionState & { pid: number } =>
+ session.status === "running" && Number.isInteger(session.pid),
+ );
- const legacyPath = this.legacyHistoryPath(threadId);
- try {
- const raw = await fs.promises.readFile(legacyPath, "utf8");
- const capped = capHistory(raw, this.historyLineLimit);
-
- // Migrate legacy transcript filename to the terminal-scoped path.
- await fs.promises.writeFile(nextPath, capped, "utf8");
- try {
- await fs.promises.rm(legacyPath, { force: true });
- } catch (cleanupError) {
- this.logger.warn("failed to remove legacy terminal history", {
- threadId,
- error: cleanupError instanceof Error ? cleanupError.message : String(cleanupError),
- });
+ if (runningSessions.length === 0) {
+ return;
}
- return capped;
- } catch (error) {
- if ((error as NodeJS.ErrnoException).code === "ENOENT") {
- return "";
- }
- throw error;
- }
- }
+ const checkSubprocessActivity = Effect.fn("terminal.checkSubprocessActivity")(function* (
+ session: TerminalSessionState & { pid: number },
+ ) {
+ const terminalPid = session.pid;
+ const hasRunningSubprocess = yield* subprocessChecker(terminalPid).pipe(
+ Effect.map(Option.some),
+ Effect.catch((error) =>
+ Effect.logWarning("failed to check terminal subprocess activity", {
+ threadId: session.threadId,
+ terminalId: session.terminalId,
+ terminalPid,
+ error: error instanceof Error ? error.message : String(error),
+ }).pipe(Effect.as(Option.none<boolean>())),
+ ),
+ );
- private async deleteHistory(threadId: string, terminalId: string): Promise<void> {
- const deletions = [fs.promises.rm(this.historyPath(threadId, terminalId), { force: true })];
- if (terminalId === DEFAULT_TERMINAL_ID) {
- deletions.push(fs.promises.rm(this.legacyHistoryPath(threadId), { force: true }));
- }
- try {
- await Promise.all(deletions);
- } catch (error) {
- this.logger.warn("failed to delete terminal history", {
- threadId,
- terminalId,
- error: error instanceof Error ? error.message : String(error),
- });
- }
- }
+ if (Option.isNone(hasRunningSubprocess)) {
+ return;
+ }
- private async flushPersistQueue(threadId: string, terminalId: string): Promise<void> {
- const persistenceKey = toSessionKey(threadId, terminalId);
- this.clearPersistTimer(threadId, terminalId);
+ const event = yield* modifyManagerState((state) => {
+ const liveSession: Option.Option<TerminalSessionState> = Option.fromNullishOr(
+ state.sessions.get(toSessionKey(session.threadId, session.terminalId)),
+ );
+ if (
+ Option.isNone(liveSession) ||
+ liveSession.value.status !== "running" ||
+ liveSession.value.pid !== terminalPid ||
+ liveSession.value.hasRunningSubprocess === hasRunningSubprocess.value
+ ) {
+ return [Option.none(), state] as const;
+ }
- while (true) {
- const pendingHistory = this.pendingPersistHistory.get(persistenceKey);
- if (pendingHistory !== undefined) {
- this.pendingPersistHistory.delete(persistenceKey);
- await this.enqueuePersistWrite(threadId, terminalId, pendingHistory);
- }
+ liveSession.value.hasRunningSubprocess = hasRunningSubprocess.value;
+ liveSession.value.updatedAt = new Date().toISOString();
+
+ return [
+ Option.some({
+ type: "activity" as const,
+ threadId: liveSession.value.threadId,
+ terminalId: liveSession.value.terminalId,
+ createdAt: new Date().toISOString(),
+ hasRunningSubprocess: hasRunningSubprocess.value,
+ }),
+ state,
+ ] as const;
+ });
- const pending = this.persistQueues.get(persistenceKey);
- if (!pending) {
- return;
- }
- await pending.catch(() => undefined);
- }
- }
+ if (Option.isSome(event)) {
+ yield* publishEvent(event.value);
+ }
+ });
- private updateSubprocessPollingState(): void {
- const hasRunningSessions = [...this.sessions.values()].some(
- (session) => session.status === "running" && session.pid !== null,
- );
- if (hasRunningSessions) {
- this.ensureSubprocessPolling();
- return;
- }
- this.stopSubprocessPolling();
- }
+ yield* Effect.forEach(runningSessions, checkSubprocessActivity, {
+ concurrency: "unbounded",
+ discard: true,
+ });
+ });
- private ensureSubprocessPolling(): void {
- if (this.subprocessPollTimer) return;
- this.subprocessPollTimer = setInterval(() => {
- void this.pollSubprocessActivity();
- }, this.subprocessPollIntervalMs);
- this.subprocessPollTimer.unref?.();
- void this.pollSubprocessActivity();
- }
+ const hasRunningSessions = readManagerState.pipe(
+ Effect.map((state) =>
+ [...state.sessions.values()].some((session) => session.status === "running"),
+ ),
+ );
- private stopSubprocessPolling(): void {
- if (!this.subprocessPollTimer) return;
- clearInterval(this.subprocessPollTimer);
- this.subprocessPollTimer = null;
- }
+ yield* Effect.forever(
+ hasRunningSessions.pipe(
+ Effect.flatMap((active) =>
+ active
+ ? pollSubprocessActivity().pipe(
+ Effect.flatMap(() => Effect.sleep(subprocessPollIntervalMs)),
+ )
+ : Effect.sleep(subprocessPollIntervalMs),
+ ),
+ ),
+ ).pipe(Effect.forkIn(workerScope));
+
+ yield* Effect.addFinalizer(() =>
+ Effect.gen(function* () {
+ const sessions = yield* modifyManagerState(
+ (state) =>
+ [
+ [...state.sessions.values()],
+ {
+ ...state,
+ sessions: new Map(),
+ },
+ ] as const,
+ );
- private async pollSubprocessActivity(): Promise<void> {
- if (this.subprocessPollInFlight) return;
+ const cleanupSession = Effect.fn("terminal.cleanupSession")(function* (
+ session: TerminalSessionState,
+ ) {
+ cleanupProcessHandles(session);
+ if (!session.process) return;
+ yield* clearKillFiber(session.process);
+ yield* runKillEscalation(session.process, session.threadId, session.terminalId);
+ });
- const runningSessions = [...this.sessions.values()].filter(
- (session): session is TerminalSessionState & { pid: number } =>
- session.status === "running" && Number.isInteger(session.pid),
+ yield* Effect.forEach(sessions, cleanupSession, {
+ concurrency: "unbounded",
+ discard: true,
+ });
+ }).pipe(Effect.ignoreCause({ log: true })),
);
- if (runningSessions.length === 0) {
- this.stopSubprocessPolling();
- return;
- }
- this.subprocessPollInFlight = true;
- try {
- await Promise.all(
- runningSessions.map(async (session) => {
- const terminalPid = session.pid;
- let hasRunningSubprocess = false;
- try {
- hasRunningSubprocess = await this.subprocessChecker(terminalPid);
- } catch (error) {
- this.logger.warn("failed to check terminal subprocess activity", {
- threadId: session.threadId,
- terminalId: session.terminalId,
- terminalPid,
- error: error instanceof Error ? error.message : String(error),
+ const open: TerminalManagerShape["open"] = (input) =>
+ withThreadLock(
+ input.threadId,
+ Effect.gen(function* () {
+ const terminalId = input.terminalId ?? DEFAULT_TERMINAL_ID;
+ yield* assertValidCwd(input.cwd);
+
+ const sessionKey = toSessionKey(input.threadId, terminalId);
+ const existing = yield* getSession(input.threadId, terminalId);
+ if (Option.isNone(existing)) {
+ yield* flushPersist(input.threadId, terminalId);
+ const history = yield* readHistory(input.threadId, terminalId);
+ const cols = input.cols ?? DEFAULT_OPEN_COLS;
+ const rows = input.rows ?? DEFAULT_OPEN_ROWS;
+ const session: TerminalSessionState = {
+ threadId: input.threadId,
+ terminalId,
+ cwd: input.cwd,
+ status: "starting",
+ pid: null,
+ history,
+ pendingHistoryControlSequence: "",
+ pendingProcessEvents: [],
+ pendingProcessEventIndex: 0,
+ processEventDrainRunning: false,
+ exitCode: null,
+ exitSignal: null,
+ updatedAt: new Date().toISOString(),
+ cols,
+ rows,
+ process: null,
+ unsubscribeData: null,
+ unsubscribeExit: null,
+ hasRunningSubprocess: false,
+ runtimeEnv: normalizedRuntimeEnv(input.env),
+ };
+
+ const createdSession = session;
+ yield* modifyManagerState((state) => {
+ const sessions = new Map(state.sessions);
+ sessions.set(sessionKey, createdSession);
+ return [undefined, { ...state, sessions }] as const;
});
- return;
+
+ yield* evictInactiveSessionsIfNeeded();
+ yield* startSession(
+ session,
+ {
+ threadId: input.threadId,
+ terminalId,
+ cwd: input.cwd,
+ cols,
+ rows,
+ ...(input.env ? { env: input.env } : {}),
+ },
+ "started",
+ );
+ return snapshot(session);
}
- const liveSession = this.sessions.get(toSessionKey(session.threadId, session.terminalId));
- if (!liveSession || liveSession.status !== "running" || liveSession.pid !== terminalPid) {
- return;
+ const liveSession = existing.value;
+ const nextRuntimeEnv = normalizedRuntimeEnv(input.env);
+ const currentRuntimeEnv = liveSession.runtimeEnv;
+ const targetCols = input.cols ?? liveSession.cols;
+ const targetRows = input.rows ?? liveSession.rows;
+ const runtimeEnvChanged = !Equal.equals(currentRuntimeEnv, nextRuntimeEnv);
+
+ if (liveSession.cwd !== input.cwd || runtimeEnvChanged) {
+ yield* stopProcess(liveSession);
+ liveSession.cwd = input.cwd;
+ liveSession.runtimeEnv = nextRuntimeEnv;
+ liveSession.history = "";
+ liveSession.pendingHistoryControlSequence = "";
+ liveSession.pendingProcessEvents = [];
+ liveSession.pendingProcessEventIndex = 0;
+ liveSession.processEventDrainRunning = false;
+ yield* persistHistory(
+ liveSession.threadId,
+ liveSession.terminalId,
+ liveSession.history,
+ );
+ } else if (liveSession.status === "exited" || liveSession.status === "error") {
+ liveSession.runtimeEnv = nextRuntimeEnv;
+ liveSession.history = "";
+ liveSession.pendingHistoryControlSequence = "";
+ liveSession.pendingProcessEvents = [];
+ liveSession.pendingProcessEventIndex = 0;
+ liveSession.processEventDrainRunning = false;
+ yield* persistHistory(
+ liveSession.threadId,
+ liveSession.terminalId,
+ liveSession.history,
+ );
}
- if (liveSession.hasRunningSubprocess === hasRunningSubprocess) {
- return;
+
+ if (!liveSession.process) {
+ yield* startSession(
+ liveSession,
+ {
+ threadId: input.threadId,
+ terminalId,
+ cwd: input.cwd,
+ cols: targetCols,
+ rows: targetRows,
+ ...(input.env ? { env: input.env } : {}),
+ },
+ "started",
+ );
+ return snapshot(liveSession);
}
- liveSession.hasRunningSubprocess = hasRunningSubprocess;
- liveSession.updatedAt = new Date().toISOString();
- this.emitEvent({
- type: "activity",
- threadId: liveSession.threadId,
- terminalId: liveSession.terminalId,
- createdAt: new Date().toISOString(),
- hasRunningSubprocess,
- });
+ if (liveSession.cols !== targetCols || liveSession.rows !== targetRows) {
+ liveSession.cols = targetCols;
+ liveSession.rows = targetRows;
+ liveSession.updatedAt = new Date().toISOString();
+ liveSession.process.resize(targetCols, targetRows);
+ }
+
+ return snapshot(liveSession);
}),
);
- } finally {
- this.subprocessPollInFlight = false;
- }
- }
- private async assertValidCwd(cwd: string): Promise<void> {
- let stats: fs.Stats;
- try {
- stats = await fs.promises.stat(cwd);
- } catch (error) {
- if ((error as NodeJS.ErrnoException).code === "ENOENT") {
- throw new Error(`Terminal cwd does not exist: ${cwd}`, { cause: error });
+ const write: TerminalManagerShape["write"] = Effect.fn("terminal.write")(function* (input) {
+ const terminalId = input.terminalId ?? DEFAULT_TERMINAL_ID;
+ const session = yield* requireSession(input.threadId, terminalId);
+ const process = session.process;
+ if (!process || session.status !== "running") {
+ if (session.status === "exited") return;
+ return yield* new TerminalNotRunningError({
+ threadId: input.threadId,
+ terminalId,
+ });
}
- throw error;
- }
- if (!stats.isDirectory()) {
- throw new Error(`Terminal cwd is not a directory: ${cwd}`);
- }
- }
-
- private async closeSession(
- threadId: string,
- terminalId: string,
- deleteHistory: boolean,
- ): Promise<void> {
- const key = toSessionKey(threadId, terminalId);
- const session = this.sessions.get(key);
- if (session) {
- this.stopProcess(session);
- this.sessions.delete(key);
- }
- this.updateSubprocessPollingState();
- await this.flushPersistQueue(threadId, terminalId);
- if (deleteHistory) {
- await this.deleteHistory(threadId, terminalId);
- }
- }
-
- private sessionsForThread(threadId: string): TerminalSessionState[] {
- return [...this.sessions.values()].filter((session) => session.threadId === threadId);
- }
-
- private async deleteAllHistoryForThread(threadId: string): Promise<void> {
- const threadPrefix = `${toSafeThreadId(threadId)}_`;
- try {
- const entries = await fs.promises.readdir(this.logsDir, { withFileTypes: true });
- const removals = entries
- .filter((entry) => entry.isFile())
- .map((entry) => entry.name)
- .filter(
- (name) =>
- name === `${toSafeThreadId(threadId)}.log` ||
- name === `${legacySafeThreadId(threadId)}.log` ||
- name.startsWith(threadPrefix),
- )
- .map((name) => fs.promises.rm(path.join(this.logsDir, name), { force: true }));
- await Promise.all(removals);
- } catch (error) {
- this.logger.warn("failed to delete terminal histories for thread", {
- threadId,
- error: error instanceof Error ? error.message : String(error),
- });
- }
- }
-
- private requireSession(threadId: string, terminalId: string): TerminalSessionState {
- const session = this.sessions.get(toSessionKey(threadId, terminalId));
- if (!session) {
- throw new Error(`Unknown terminal thread: ${threadId}, terminal: ${terminalId}`);
- }
- return session;
- }
+ yield* Effect.sync(() => process.write(input.data));
+ });
- private snapshot(session: TerminalSessionState): TerminalSessionSnapshot {
- return {
- threadId: session.threadId,
- terminalId: session.terminalId,
- cwd: session.cwd,
- status: session.status,
- pid: session.pid,
- history: session.history,
- exitCode: session.exitCode,
- exitSignal: session.exitSignal,
- updatedAt: session.updatedAt,
- };
- }
+ const resize: TerminalManagerShape["resize"] = Effect.fn("terminal.resize")(function* (input) {
+ const terminalId = input.terminalId ?? DEFAULT_TERMINAL_ID;
+ const session = yield* requireSession(input.threadId, terminalId);
+ const process = session.process;
+ if (!process || session.status !== "running") {
+ return yield* new TerminalNotRunningError({
+ threadId: input.threadId,
+ terminalId,
+ });
+ }
+ session.cols = input.cols;
+ session.rows = input.rows;
+ session.updatedAt = new Date().toISOString();
+ yield* Effect.sync(() => process.resize(input.cols, input.rows));
+ });
- private emitEvent(event: TerminalEvent): void {
- this.emit("event", event);
- }
+ const clear: TerminalManagerShape["clear"] = (input) =>
+ withThreadLock(
+ input.threadId,
+ Effect.gen(function* () {
+ const terminalId = input.terminalId ?? DEFAULT_TERMINAL_ID;
+ const session = yield* requireSession(input.threadId, terminalId);
+ session.history = "";
+ session.pendingHistoryControlSequence = "";
+ session.pendingProcessEvents = [];
+ session.pendingProcessEventIndex = 0;
+ session.processEventDrainRunning = false;
+ session.updatedAt = new Date().toISOString();
+ yield* persistHistory(input.threadId, terminalId, session.history);
+ yield* publishEvent({
+ type: "cleared",
+ threadId: input.threadId,
+ terminalId,
+ createdAt: new Date().toISOString(),
+ });
+ }),
+ );
- private historyPath(threadId: string, terminalId: string): string {
- const threadPart = toSafeThreadId(threadId);
- if (terminalId === DEFAULT_TERMINAL_ID) {
- return path.join(this.logsDir, `${threadPart}.log`);
- }
- return path.join(this.logsDir, `${threadPart}_${toSafeTerminalId(terminalId)}.log`);
- }
+ const restart: TerminalManagerShape["restart"] = (input) =>
+ withThreadLock(
+ input.threadId,
+ Effect.gen(function* () {
+ const terminalId = input.terminalId ?? DEFAULT_TERMINAL_ID;
+ yield* assertValidCwd(input.cwd);
+
+ const sessionKey = toSessionKey(input.threadId, terminalId);
+ const existingSession = yield* getSession(input.threadId, terminalId);
+ let session: TerminalSessionState;
+ if (Option.isNone(existingSession)) {
+ const cols = input.cols ?? DEFAULT_OPEN_COLS;
+ const rows = input.rows ?? DEFAULT_OPEN_ROWS;
+ session = {
+ threadId: input.threadId,
+ terminalId,
+ cwd: input.cwd,
+ status: "starting",
+ pid: null,
+ history: "",
+ pendingHistoryControlSequence: "",
+ pendingProcessEvents: [],
+ pendingProcessEventIndex: 0,
+ processEventDrainRunning: false,
+ exitCode: null,
+ exitSignal: null,
+ updatedAt: new Date().toISOString(),
+ cols,
+ rows,
+ process: null,
+ unsubscribeData: null,
+ unsubscribeExit: null,
+ hasRunningSubprocess: false,
+ runtimeEnv: normalizedRuntimeEnv(input.env),
+ };
+ const createdSession = session;
+ yield* modifyManagerState((state) => {
+ const sessions = new Map(state.sessions);
+ sessions.set(sessionKey, createdSession);
+ return [undefined, { ...state, sessions }] as const;
+ });
+ yield* evictInactiveSessionsIfNeeded();
+ } else {
+ session = existingSession.value;
+ yield* stopProcess(session);
+ session.cwd = input.cwd;
+ session.runtimeEnv = normalizedRuntimeEnv(input.env);
+ }
- private legacyHistoryPath(threadId: string): string {
- return path.join(this.logsDir, `${legacySafeThreadId(threadId)}.log`);
- }
+ const cols = input.cols ?? session.cols;
+ const rows = input.rows ?? session.rows;
+
+ session.history = "";
+ session.pendingHistoryControlSequence = "";
+ session.pendingProcessEvents = [];
+ session.pendingProcessEventIndex = 0;
+ session.processEventDrainRunning = false;
+ yield* persistHistory(input.threadId, terminalId, session.history);
+ yield* startSession(
+ session,
+ {
+ threadId: input.threadId,
+ terminalId,
+ cwd: input.cwd,
+ cols,
+ rows,
+ ...(input.env ? { env: input.env } : {}),
+ },
+ "restarted",
+ );
+ return snapshot(session);
+ }),
+ );
- private async runWithThreadLock<T>(threadId: string, task: () => Promise<T>): Promise<T> {
- const previous = this.threadLocks.get(threadId) ?? Promise.resolve();
- let release!: () => void;
- const current = new Promise<void>((resolve) => {
- release = resolve;
- });
- this.threadLocks.set(threadId, current);
- await previous.catch(() => undefined);
- try {
- return await task();
- } finally {
- release();
- if (this.threadLocks.get(threadId) === current) {
- this.threadLocks.delete(threadId);
- }
- }
- }
-}
+ const close: TerminalManagerShape["close"] = (input) =>
+ withThreadLock(
+ input.threadId,
+ Effect.gen(function* () {
+ if (input.terminalId) {
+ yield* closeSession(input.threadId, input.terminalId, input.deleteHistory === true);
+ return;
+ }
-export const TerminalManagerLive = Layer.effect(
- TerminalManager,
- Effect.gen(function* () {
- const { terminalLogsDir } = yield* ServerConfig;
+ const threadSessions = yield* sessionsForThread(input.threadId);
+ yield* Effect.forEach(
+ threadSessions,
+ (session) => closeSession(input.threadId, session.terminalId, false),
+ { discard: true },
+ );
- const ptyAdapter = yield* PtyAdapter;
- const runtime = yield* Effect.acquireRelease(
- Effect.sync(() => new TerminalManagerRuntime({ logsDir: terminalLogsDir, ptyAdapter })),
- (r) => Effect.sync(() => r.dispose()),
- );
+ if (input.deleteHistory) {
+ yield* deleteAllHistoryForThread(input.threadId);
+ }
+ }),
+ );
return {
- open: (input) =>
- Effect.tryPromise({
- try: () => runtime.open(input),
- catch: (cause) => new TerminalError({ message: "Failed to open terminal", cause }),
- }),
- write: (input) =>
- Effect.tryPromise({
- try: () => runtime.write(input),
- catch: (cause) => new TerminalError({ message: "Failed to write to terminal", cause }),
- }),
- resize: (input) =>
- Effect.tryPromise({
- try: () => runtime.resize(input),
- catch: (cause) => new TerminalError({ message: "Failed to resize terminal", cause }),
- }),
- clear: (input) =>
- Effect.tryPromise({
- try: () => runtime.clear(input),
- catch: (cause) => new TerminalError({ message: "Failed to clear terminal", cause }),
- }),
- restart: (input) =>
- Effect.tryPromise({
- try: () => runtime.restart(input),
- catch: (cause) => new TerminalError({ message: "Failed to restart terminal", cause }),
- }),
- close: (input) =>
- Effect.tryPromise({
- try: () => runtime.close(input),
- catch: (cause) => new TerminalError({ message: "Failed to close terminal", cause }),
- }),
+ open,
+ write,
+ resize,
+ clear,
+ restart,
+ close,
subscribe: (listener) =>
Effect.sync(() => {
- runtime.on("event", listener);
+ terminalEventListeners.add(listener);
return () => {
- runtime.off("event", listener);
+ terminalEventListeners.delete(listener);
};
}),
- dispose: Effect.sync(() => runtime.dispose()),
} satisfies TerminalManagerShape;
- }),
+ },
);
+
+export const TerminalManagerLive = Layer.effect(TerminalManager, makeTerminalManager());
diff --git a/apps/server/src/terminal/Services/Manager.ts b/apps/server/src/terminal/Services/Manager.ts
index c2539da4b..067cd5543 100644
--- a/apps/server/src/terminal/Services/Manager.ts
+++ b/apps/server/src/terminal/Services/Manager.ts
@@ -14,47 +14,81 @@ import {
TerminalResizeInput,
TerminalRestartInput,
TerminalSessionSnapshot,
- TerminalSessionStatus,
TerminalWriteInput,
} from "@t3tools/contracts";
-import { PtyProcess } from "./PTY";
import { Effect, Schema, ServiceMap } from "effect";
-export class TerminalError extends Schema.TaggedErrorClass<TerminalError>()("TerminalError", {
- message: Schema.String,
- cause: Schema.optional(Schema.Defect),
-}) {}
+export class TerminalCwdError extends Schema.TaggedErrorClass<TerminalCwdError>()(
+ "TerminalCwdError",
+ {
+ cwd: Schema.String,
+ reason: Schema.Literals(["notFound", "notDirectory", "statFailed"]),
+ cause: Schema.optional(Schema.Defect),
+ },
+) {
+ override get message() {
+ if (this.reason === "notDirectory") {
+ return `Terminal cwd is not a directory: ${this.cwd}`;
+ }
+ if (this.reason === "notFound") {
+ return `Terminal cwd does not exist: ${this.cwd}`;
+ }
+ const causeMessage =
+ this.cause && typeof this.cause === "object" && "message" in this.cause
+ ? this.cause.message
+ : undefined;
+ return causeMessage
+ ? `Failed to access terminal cwd: ${this.cwd} (${causeMessage})`
+ : `Failed to access terminal cwd: ${this.cwd}`;
+ }
+}
-export interface TerminalSessionState {
- threadId: string;
- terminalId: string;
- cwd: string;
- status: TerminalSessionStatus;
- pid: number | null;
- history: string;
- pendingHistoryControlSequence: string;
- exitCode: number | null;
- exitSignal: number | null;
- updatedAt: string;
- cols: number;
- rows: number;
- process: PtyProcess | null;
- unsubscribeData: (() => void) | null;
- unsubscribeExit: (() => void) | null;
- hasRunningSubprocess: boolean;
- runtimeEnv: Record<string, string> | null;
+export class TerminalHistoryError extends Schema.TaggedErrorClass<TerminalHistoryError>()(
+ "TerminalHistoryError",
+ {
+ operation: Schema.Literals(["read", "truncate", "migrate"]),
+ threadId: Schema.String,
+ terminalId: Schema.String,
+ cause: Schema.optional(Schema.Defect),
+ },
+) {
+ override get message() {
+ return `Failed to ${this.operation} terminal history for thread: ${this.threadId}, terminal: ${this.terminalId}`;
+ }
}
-export interface ShellCandidate {
- shell: string;
- args?: string[];
+export class TerminalSessionLookupError extends Schema.TaggedErrorClass<TerminalSessionLookupError>()(
+ "TerminalSessionLookupError",
+ {
+ threadId: Schema.String,
+ terminalId: Schema.String,
+ },
+) {
+ override get message() {
+ return `Unknown terminal thread: ${this.threadId}, terminal: ${this.terminalId}`;
+ }
}
-export interface TerminalStartInput extends TerminalOpenInput {
- cols: number;
- rows: number;
+export class TerminalNotRunningError extends Schema.TaggedErrorClass<TerminalNotRunningError>()(
+ "TerminalNotRunningError",
+ {
+ threadId: Schema.String,
+ terminalId: Schema.String,
+ },
+) {
+ override get message() {
+ return `Terminal is not running for thread: ${this.threadId}, terminal: ${this.terminalId}`;
+ }
}
+export const TerminalError = Schema.Union([
+ TerminalCwdError,
+ TerminalHistoryError,
+ TerminalSessionLookupError,
+ TerminalNotRunningError,
+]);
+export type TerminalError = typeof TerminalError.Type;
+
/**
* TerminalManagerShape - Service API for terminal session lifecycle operations.
*/
@@ -101,14 +135,13 @@ export interface TerminalManagerShape {
readonly close: (input: TerminalCloseInput) => Effect.Effect<void, TerminalError>;
/**
- * Subscribe to terminal runtime events.
- */
- readonly subscribe: (listener: (event: TerminalEvent) => void) => Effect.Effect<() => void>;
-
- /**
- * Dispose all managed terminal resources.
+ * Subscribe to terminal runtime events with a direct callback.
+ *
+ * Returns an unsubscribe function.
*/
- readonly dispose: Effect.Effect<void>;
+ readonly subscribe: (
+ listener: (event: TerminalEvent) => Effect.Effect<void>,
+ ) => Effect.Effect<() => void>;
}
/**
diff --git a/apps/server/src/wsServer.test.ts b/apps/server/src/wsServer.test.ts
index 6dcf8b38e..0e06650fe 100644
--- a/apps/server/src/wsServer.test.ts
+++ b/apps/server/src/wsServer.test.ts
@@ -4,7 +4,7 @@ import os from "node:os";
import path from "node:path";
import * as NodeServices from "@effect/platform-node/NodeServices";
-import { Effect, Exit, Layer, PlatformError, PubSub, Scope, Stream } from "effect";
+import { Effect, Exit, Fiber, Layer, PlatformError, PubSub, Scope, Stream } from "effect";
import { describe, expect, it, afterEach, vi } from "vitest";
import { createServer } from "./wsServer";
import WebSocket from "ws";
@@ -90,20 +90,19 @@ const defaultServerSettings = DEFAULT_SERVER_SETTINGS;
class MockTerminalManager implements TerminalManagerShape {
private readonly sessions = new Map<string, TerminalSessionSnapshot>();
- private readonly listeners = new Set<(event: TerminalEvent) => void>();
+ private readonly eventPubSub = Effect.runSync(PubSub.unbounded<TerminalEvent>());
+ private activeSubscriptions = 0;
private key(threadId: string, terminalId: string): string {
return `${threadId}\u0000${terminalId}`;
}
emitEvent(event: TerminalEvent): void {
- for (const listener of this.listeners) {
- listener(event);
- }
+ Effect.runSync(PubSub.publish(this.eventPubSub, event));
}
subscriptionCount(): number {
- return this.listeners.size;
+ return this.activeSubscriptions;
}
readonly open: TerminalManagerShape["open"] = (input: TerminalOpenInput) =>
@@ -210,13 +209,15 @@ class MockTerminalManager implements TerminalManagerShape {
readonly subscribe: TerminalManagerShape["subscribe"] = (listener) =>
Effect.sync(() => {
- this.listeners.add(listener);
+ this.activeSubscriptions += 1;
+ const fiber = Effect.runFork(
+ Stream.runForEach(Stream.fromPubSub(this.eventPubSub), (event) => listener(event)),
+ );
return () => {
- this.listeners.delete(listener);
+ this.activeSubscriptions -= 1;
+ Effect.runFork(Fiber.interrupt(fiber).pipe(Effect.ignore));
};
});
-
- readonly dispose: TerminalManagerShape["dispose"] = Effect.void;
}
// ---------------------------------------------------------------------------
@@ -1454,19 +1455,25 @@ describe("WebSocket Server", () => {
expect(push.channel).toBe(WS_CHANNELS.terminalEvent);
});
- it("detaches terminal event listener on stop for injected manager", async () => {
+ it("shuts down cleanly for injected terminal managers", async () => {
const terminalManager = new MockTerminalManager();
server = await createTestServer({
cwd: "/test",
terminalManager,
});
- expect(terminalManager.subscriptionCount()).toBe(1);
-
await closeTestServer();
server = null;
- expect(terminalManager.subscriptionCount()).toBe(0);
+ expect(() =>
+ terminalManager.emitEvent({
+ type: "output",
+ threadId: "thread-1",
+ terminalId: DEFAULT_TERMINAL_ID,
+ createdAt: new Date().toISOString(),
+ data: "after shutdown\n",
+ }),
+ ).not.toThrow();
});
it("returns validation errors for invalid terminal open params", async () => {
diff --git a/apps/server/src/wsServer.ts b/apps/server/src/wsServer.ts
index c04d913d5..25f815892 100644
--- a/apps/server/src/wsServer.ts
+++ b/apps/server/src/wsServer.ts
@@ -719,9 +719,9 @@ export const createServer = Effect.fn(function* (): Effect.fn.Return<
}
const unsubscribeTerminalEvents = yield* terminalManager.subscribe((event) =>
- runPromise(pushBus.publishAll(WS_CHANNELS.terminalEvent, event)),
+ pushBus.publishAll(WS_CHANNELS.terminalEvent, event),
);
- yield* Effect.addFinalizer(() => Effect.sync(() => unsubscribeTerminalEvents()));
+ yield* Scope.addFinalizer(subscriptionsScope, Effect.sync(unsubscribeTerminalEvents));
yield* readiness.markTerminalSubscriptionsReady;
yield* NodeHttpServer.make(() => httpServer, listenOptions).pipe(
diff --git a/packages/contracts/src/ipc.ts b/packages/contracts/src/ipc.ts
index 5585e7f30..e8b1c4627 100644
--- a/packages/contracts/src/ipc.ts
+++ b/packages/contracts/src/ipc.ts
@@ -130,12 +130,12 @@ export interface NativeApi {
confirm: (message: string) => Promise<boolean>;
};
terminal: {
- open: (input: TerminalOpenInput) => Promise<TerminalSessionSnapshot>;
- write: (input: TerminalWriteInput) => Promise<void>;
- resize: (input: TerminalResizeInput) => Promise<void>;
- clear: (input: TerminalClearInput) => Promise<void>;
- restart: (input: TerminalRestartInput) => Promise<TerminalSessionSnapshot>;
- close: (input: TerminalCloseInput) => Promise<void>;
+ open: (input: typeof TerminalOpenInput.Encoded) => Promise<TerminalSessionSnapshot>;
+ write: (input: typeof TerminalWriteInput.Encoded) => Promise<void>;
+ resize: (input: typeof TerminalResizeInput.Encoded) => Promise<void>;
+ clear: (input: typeof TerminalClearInput.Encoded) => Promise<void>;
+ restart: (input: typeof TerminalRestartInput.Encoded) => Promise<TerminalSessionSnapshot>;
+ close: (input: typeof TerminalCloseInput.Encoded) => Promise<void>;
onEvent: (callback: (event: TerminalEvent) => void) => () => void;
};
projects: {
diff --git a/packages/contracts/src/terminal.ts b/packages/contracts/src/terminal.ts
index b0493d95c..f9729da66 100644
--- a/packages/contracts/src/terminal.ts
+++ b/packages/contracts/src/terminal.ts
@@ -26,7 +26,7 @@ const TerminalIdWithDefaultSchema = TerminalIdSchema.pipe(
export const TerminalThreadInput = Schema.Struct({
threadId: TrimmedNonEmptyStringSchema,
});
-export type TerminalThreadInput = Schema.Codec.Encoded<typeof TerminalThreadInput>;
+export type TerminalThreadInput = typeof TerminalThreadInput.Type;
const TerminalSessionInput = Schema.Struct({
...TerminalThreadInput.fields,
@@ -73,7 +73,7 @@ export const TerminalCloseInput = Schema.Struct({
terminalId: Schema.optional(TerminalIdSchema),
deleteHistory: Schema.optional(Schema.Boolean),
});
-export type TerminalCloseInput = Schema.Codec.Encoded<typeof TerminalCloseInput>;
+export type TerminalCloseInput = typeof TerminalCloseInput.Type;
export const TerminalSessionStatus = Schema.Literals(["starting", "running", "exited", "error"]);
export type TerminalSessionStatus = typeof TerminalSessionStatus.Type;
diff --git a/packages/shared/package.json b/packages/shared/package.json
index 40ffbf35c..b35d23ef1 100644
--- a/packages/shared/package.json
+++ b/packages/shared/package.json
@@ -28,6 +28,10 @@
"types": "./src/DrainableWorker.ts",
"import": "./src/DrainableWorker.ts"
},
+ "./KeyedCoalescingWorker": {
+ "types": "./src/KeyedCoalescingWorker.ts",
+ "import": "./src/KeyedCoalescingWorker.ts"
+ },
"./schemaJson": {
"types": "./src/schemaJson.ts",
"import": "./src/schemaJson.ts"
diff --git a/packages/shared/src/KeyedCoalescingWorker.test.ts b/packages/shared/src/KeyedCoalescingWorker.test.ts
new file mode 100644
index 000000000..2226bbd00
--- /dev/null
+++ b/packages/shared/src/KeyedCoalescingWorker.test.ts
@@ -0,0 +1,96 @@
+import { it } from "@effect/vitest";
+import { describe, expect } from "vitest";
+import { Deferred, Effect } from "effect";
+
+import { makeKeyedCoalescingWorker } from "./KeyedCoalescingWorker";
+
+describe("makeKeyedCoalescingWorker", () => {
+ it.live("waits for latest work enqueued during active processing before draining the key", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const processed: string[] = [];
+ const firstStarted = yield* Deferred.make<void>();
+ const releaseFirst = yield* Deferred.make<void>();
+ const secondStarted = yield* Deferred.make<void>();
+ const releaseSecond = yield* Deferred.make<void>();
+
+ const worker = yield* makeKeyedCoalescingWorker<string, string, never, never>({
+ merge: (_current, next) => next,
+ process: (key, value) =>
+ Effect.gen(function* () {
+ processed.push(`${key}:${value}`);
+
+ if (value === "first") {
+ yield* Deferred.succeed(firstStarted, undefined).pipe(Effect.orDie);
+ yield* Deferred.await(releaseFirst);
+ }
+
+ if (value === "second") {
+ yield* Deferred.succeed(secondStarted, undefined).pipe(Effect.orDie);
+ yield* Deferred.await(releaseSecond);
+ }
+ }),
+ });
+
+ yield* worker.enqueue("terminal-1", "first");
+ yield* Deferred.await(firstStarted);
+
+ const drained = yield* Deferred.make<void>();
+ yield* Effect.forkChild(
+ worker
+ .drainKey("terminal-1")
+ .pipe(Effect.tap(() => Deferred.succeed(drained, undefined).pipe(Effect.orDie))),
+ );
+
+ yield* worker.enqueue("terminal-1", "second");
+ yield* Deferred.succeed(releaseFirst, undefined);
+ yield* Deferred.await(secondStarted);
+
+ expect(yield* Deferred.isDone(drained)).toBe(false);
+
+ yield* Deferred.succeed(releaseSecond, undefined);
+ yield* Deferred.await(drained);
+
+ expect(processed).toEqual(["terminal-1:first", "terminal-1:second"]);
+ }),
+ ),
+ );
+
+ it.live("requeues pending work for a key after a processor failure and keeps draining", () =>
+ Effect.scoped(
+ Effect.gen(function* () {
+ const processed: string[] = [];
+ const firstStarted = yield* Deferred.make<void>();
+ const releaseFailure = yield* Deferred.make<void>();
+ const secondProcessed = yield* Deferred.make<void>();
+
+ const worker = yield* makeKeyedCoalescingWorker<string, string, string, never>({
+ merge: (_current, next) => next,
+ process: (key, value) =>
+ Effect.gen(function* () {
+ processed.push(`${key}:${value}`);
+
+ if (value === "first") {
+ yield* Deferred.succeed(firstStarted, undefined).pipe(Effect.orDie);
+ yield* Deferred.await(releaseFailure);
+ yield* Effect.fail("boom");
+ }
+
+ if (value === "second") {
+ yield* Deferred.succeed(secondProcessed, undefined).pipe(Effect.orDie);
+ }
+ }),
+ });
+
+ yield* worker.enqueue("terminal-1", "first");
+ yield* Deferred.await(firstStarted);
+ yield* worker.enqueue("terminal-1", "second");
+ yield* Deferred.succeed(releaseFailure, undefined);
+ yield* Deferred.await(secondProcessed);
+ yield* worker.drainKey("terminal-1");
+
+ expect(processed).toEqual(["terminal-1:first", "terminal-1:second"]);
+ }),
+ ),
+ );
+});
diff --git a/packages/shared/src/KeyedCoalescingWorker.ts b/packages/shared/src/KeyedCoalescingWorker.ts
new file mode 100644
index 000000000..567c1dac1
--- /dev/null
+++ b/packages/shared/src/KeyedCoalescingWorker.ts
@@ -0,0 +1,140 @@
+/**
+ * KeyedCoalescingWorker - A keyed worker that keeps only the latest value per key.
+ *
+ * Enqueues for an active or already-queued key are merged atomically instead of
+ * creating duplicate queued items. `drainKey()` resolves only when that key has
+ * no queued, pending, or active work left.
+ *
+ * @module KeyedCoalescingWorker
+ */
+import type { Scope } from "effect";
+import { Effect, TxQueue, TxRef } from "effect";
+
+export interface KeyedCoalescingWorker<K, V> {
+ readonly enqueue: (key: K, value: V) => Effect.Effect<void>;
+ readonly drainKey: (key: K) => Effect.Effect<void>;
+}
+
+interface KeyedCoalescingWorkerState<K, V> {
+ readonly latestByKey: Map<K, V>;
+ readonly queuedKeys: Set<K>;
+ readonly activeKeys: Set<K>;
+}
+
+export const makeKeyedCoalescingWorker = <K, V, E, R>(options: {
+ readonly merge: (current: V, next: V) => V;
+ readonly process: (key: K, value: V) => Effect.Effect<void, E, R>;
+}): Effect.Effect<KeyedCoalescingWorker<K, V>, never, Scope.Scope | R> =>
+ Effect.gen(function* () {
+ const queue = yield* Effect.acquireRelease(TxQueue.unbounded<K>(), TxQueue.shutdown);
+ const stateRef = yield* TxRef.make<KeyedCoalescingWorkerState<K, V>>({
+ latestByKey: new Map(),
+ queuedKeys: new Set(),
+ activeKeys: new Set(),
+ });
+
+ const processKey = (key: K, value: V): Effect.Effect<void, E, R> =>
+ options.process(key, value).pipe(
+ Effect.flatMap(() =>
+ TxRef.modify(stateRef, (state) => {
+ const nextValue = state.latestByKey.get(key);
+ if (nextValue === undefined) {
+ const activeKeys = new Set(state.activeKeys);
+ activeKeys.delete(key);
+ return [null, { ...state, activeKeys }] as const;
+ }
+
+ const latestByKey = new Map(state.latestByKey);
+ latestByKey.delete(key);
+ return [nextValue, { ...state, latestByKey }] as const;
+ }).pipe(Effect.tx),
+ ),
+ Effect.flatMap((nextValue) =>
+ nextValue === null ? Effect.void : processKey(key, nextValue),
+ ),
+ );
+
+ const cleanupFailedKey = (key: K): Effect.Effect<void> =>
+ TxRef.modify(stateRef, (state) => {
+ const activeKeys = new Set(state.activeKeys);
+ activeKeys.delete(key);
+
+ if (state.latestByKey.has(key) && !state.queuedKeys.has(key)) {
+ const queuedKeys = new Set(state.queuedKeys);
+ queuedKeys.add(key);
+ return [true, { ...state, activeKeys, queuedKeys }] as const;
+ }
+
+ return [false, { ...state, activeKeys }] as const;
+ }).pipe(
+ Effect.tx,
+ Effect.flatMap((shouldRequeue) =>
+ shouldRequeue ? TxQueue.offer(queue, key) : Effect.void,
+ ),
+ );
+
+ yield* TxQueue.take(queue).pipe(
+ Effect.flatMap((key) =>
+ TxRef.modify(stateRef, (state) => {
+ const queuedKeys = new Set(state.queuedKeys);
+ queuedKeys.delete(key);
+
+ const value = state.latestByKey.get(key);
+ if (value === undefined) {
+ return [null, { ...state, queuedKeys }] as const;
+ }
+
+ const latestByKey = new Map(state.latestByKey);
+ latestByKey.delete(key);
+ const activeKeys = new Set(state.activeKeys);
+ activeKeys.add(key);
+
+ return [
+ { key, value } as const,
+ { ...state, latestByKey, queuedKeys, activeKeys },
+ ] as const;
+ }).pipe(Effect.tx),
+ ),
+ Effect.flatMap((item) =>
+ item === null
+ ? Effect.void
+ : processKey(item.key, item.value).pipe(
+ Effect.catchCause(() => cleanupFailedKey(item.key)),
+ ),
+ ),
+ Effect.forever,
+ Effect.forkScoped,
+ );
+
+ const enqueue: KeyedCoalescingWorker<K, V>["enqueue"] = (key, value) =>
+ TxRef.modify(stateRef, (state) => {
+ const latestByKey = new Map(state.latestByKey);
+ const existing = latestByKey.get(key);
+ latestByKey.set(key, existing === undefined ? value : options.merge(existing, value));
+
+ if (state.queuedKeys.has(key) || state.activeKeys.has(key)) {
+ return [false, { ...state, latestByKey }] as const;
+ }
+
+ const queuedKeys = new Set(state.queuedKeys);
+ queuedKeys.add(key);
+ return [true, { ...state, latestByKey, queuedKeys }] as const;
+ }).pipe(
+ Effect.flatMap((shouldOffer) => (shouldOffer ? TxQueue.offer(queue, key) : Effect.void)),
+ Effect.tx,
+ Effect.asVoid,
+ );
+
+ const drainKey: KeyedCoalescingWorker<K, V>["drainKey"] = (key) =>
+ TxRef.get(stateRef).pipe(
+ Effect.tap((state) =>
+ state.latestByKey.has(key) || state.queuedKeys.has(key) || state.activeKeys.has(key)
+ ? Effect.txRetry
+ : Effect.void,
+ ),
+ Effect.asVoid,
+ Effect.tx,
+ );
+
+ return { enqueue, drainKey } satisfies KeyedCoalescingWorker<K, V>;
+ });