@exagone313/dsh-podman 0.2.0-rc.4 → 0.2.0

package/dist/terminal-preference.test.js

@@ -0,0 +1,62 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readTerminalTarget, TERMINAL_TARGET_KEY, writeTerminalTarget, } from "./client/terminal-preference.js";
+function fakeStorage(initial) {
+    const values = new Map();
+    if (initial !== undefined)
+        values.set(TERMINAL_TARGET_KEY, initial);
+    return {
+        values,
+        getItem: (key) => values.get(key) ?? null,
+        setItem: (key, value) => {
+            values.set(key, value);
+        },
+    };
+}
+test("the terminal card remembers the target it started", () => {
+    const storage = fakeStorage();
+    assert.equal(readTerminalTarget(storage), undefined);
+    writeTerminalTarget({ container: "dev", shell: "/usr/bin/bash" }, storage);
+    assert.deepEqual(readTerminalTarget(storage), {
+        container: "dev",
+        shell: "/usr/bin/bash",
+    });
+    // The default container is a real choice and must survive the round trip.
+    writeTerminalTarget({ container: "", shell: "/bin/sh" }, storage);
+    assert.deepEqual(readTerminalTarget(storage), {
+        container: "",
+        shell: "/bin/sh",
+    });
+});
+test("unusable stored values leave the card without a preference", () => {
+    for (const raw of [
+        "",
+        "{",
+        "null",
+        "[]",
+        '"text"',
+        "{}",
+        '{"container":1}',
+        '{"shell":2}',
+        '{"container":null,"shell":false}',
+    ]) {
+        assert.equal(readTerminalTarget(fakeStorage(raw)), undefined, raw);
+    }
+    // A partial record keeps the half that is usable.
+    assert.deepEqual(readTerminalTarget(fakeStorage('{"shell":"/bin/sh","extra":true}')), { shell: "/bin/sh" });
+});
+test("a storage that refuses to answer never breaks the card", () => {
+    const failing = {
+        getItem() {
+            throw new Error("denied");
+        },
+        setItem() {
+            throw new Error("denied");
+        },
+    };
+    assert.equal(readTerminalTarget(failing), undefined);
+    assert.doesNotThrow(() => writeTerminalTarget({ container: "", shell: "/bin/sh" }, failing));
+});

package/dist/terminal-route.d.ts

@@ -0,0 +1,10 @@
+import { type TerminalSessions } from "./terminal-sessions.js";
+import { type WorkspaceResolver } from "./workspace-binding.js";
+/**
+ * Register the terminal routes on the connection service.
+ * @param ctx - plugin host context carrying the connection service.
+ * @param resolver - workspace/container resolver.
+ * @param sessions - live terminal registry.
+ * @param workspaceRegistry - the harness workspace registry, when present.
+ */
+export declare function registerTerminalRoutes(ctx: any, resolver: WorkspaceResolver, sessions: TerminalSessions, workspaceRegistry?: any): void;

package/dist/terminal-route.js

@@ -0,0 +1,270 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+// The browser-facing terminal routes. They are served below the harness API
+// path, so the carrier applies its Host/Origin fence and browser authentication
+// before any handler runs; the handlers themselves only speak the terminal
+// protocol declared in client/terminal-protocol.ts.
+import { TERMINAL_PATH, TERMINAL_RETAINED_PATH, TERMINAL_SHELLS_PATH, TERMINAL_TARGET_PATH, } from "./client/terminal-protocol.js";
+import { discoverShells } from "./terminal-shells.js";
+import { workspaceSlug } from "./workspace-binding.js";
+const MIN_COLS = 2;
+const MAX_COLS = 500;
+const MIN_ROWS = 1;
+const MAX_ROWS = 200;
+function json(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json" },
+    });
+}
+function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function integer(raw, min, max) {
+    if (raw === null || raw === "")
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < min || value > max)
+        return undefined;
+    return value;
+}
+// The workspace's mirrored path under the projects root, or the session's own
+// working directory when the request names no workspace.
+function workspaceCwd(ctx, workspaceRegistry, projectsRoot, projectName, sessionId) {
+    const list = workspaceRegistry?.list?.() ?? [];
+    if (projectName !== "") {
+        for (const workspace of list) {
+            const path = String(workspace.path ?? "");
+            const name = path.startsWith(`${projectsRoot}/`)
+                ? path.slice(projectsRoot.length + 1)
+                : path;
+            if (name === projectName)
+                return path;
+        }
+        return undefined;
+    }
+    const cwd = ctx?.get?.("sessions")?.get?.(sessionId)?.header?.cwd;
+    return typeof cwd === "string" && cwd !== "" ? cwd : undefined;
+}
+// The workspace one session runs in, resolved from the session's own working
+// directory: a Session belongs to one workspace, so the client never asks for
+// one. The longest matching registry path wins, which keeps nested workspace
+// roots unambiguous. Everything the client needs about the target comes from
+// here, so the browser never reads harness Session internals.
+function sessionWorkspace(ctx, workspaceRegistry, projectsRoot, sessionId) {
+    const cwd = ctx?.get?.("sessions")?.get?.(sessionId)?.header?.cwd;
+    if (typeof cwd !== "string" || cwd === "")
+        return undefined;
+    let best;
+    for (const workspace of workspaceRegistry?.list?.() ?? []) {
+        const path = String(workspace.path ?? "");
+        if (path === "" || (cwd !== path && !cwd.startsWith(`${path}/`)))
+            continue;
+        if (best !== undefined && path.length <= best.path.length)
+            continue;
+        const projectName = path.startsWith(`${projectsRoot}/`)
+            ? path.slice(projectsRoot.length + 1)
+            : path;
+        best = { path, projectName, slug: workspaceSlug(workspace.id) };
+    }
+    return best === undefined
+        ? undefined
+        : { workspace: best.projectName, workspaceSlug: best.slug };
+}
+function handleTarget(request, ctx, resolver, workspaceRegistry) {
+    const sessionId = new URL(request.url).searchParams.get("sessionId") ?? "";
+    if (sessionId === "")
+        return json(400, { error: "sessionId is required" });
+    const target = sessionWorkspace(ctx, workspaceRegistry, resolver.getConfig().projectsRoot, sessionId);
+    if (target === undefined) {
+        return json(400, { error: "Cannot determine this session's workspace" });
+    }
+    return json(200, target);
+}
+function controlOf(body) {
+    if (typeof body?.terminalId !== "string" || body.terminalId === "") {
+        return undefined;
+    }
+    const terminalId = body.terminalId;
+    switch (body.kind) {
+        case "input":
+            return typeof body.data === "string"
+                ? { terminalId, kind: "input", data: body.data }
+                : undefined;
+        case "resize": {
+            const cols = integer(String(body.cols ?? ""), MIN_COLS, MAX_COLS);
+            const rows = integer(String(body.rows ?? ""), MIN_ROWS, MAX_ROWS);
+            return cols === undefined || rows === undefined
+                ? undefined
+                : { terminalId, kind: "resize", cols, rows };
+        }
+        case "rename":
+            return typeof body.title === "string" && body.title.trim() !== ""
+                ? { terminalId, kind: "rename", title: body.title.trim().slice(0, 120) }
+                : undefined;
+        case "close":
+            return { terminalId, kind: "close" };
+        default:
+            return undefined;
+    }
+}
+async function bindingFor(resolver, cwd, container, signal) {
+    return container === "" || container === "default"
+        ? await resolver.resolveForPath(cwd, cwd, signal)
+        : await resolver.containerBinding(cwd, container, signal);
+}
+async function handleOpen(request, ctx, resolver, sessions, workspaceRegistry) {
+    const url = new URL(request.url);
+    let options;
+    try {
+        const sessionId = url.searchParams.get("sessionId") ?? "";
+        const tabId = url.searchParams.get("tabId") ?? "";
+        const workspace = url.searchParams.get("workspace") ?? "";
+        const container = url.searchParams.get("container") ?? "";
+        const shell = url.searchParams.get("shell") ?? "";
+        const cols = integer(url.searchParams.get("cols"), MIN_COLS, MAX_COLS);
+        const rows = integer(url.searchParams.get("rows"), MIN_ROWS, MAX_ROWS);
+        if (sessionId === "" || tabId === "" || shell === "" || !shell.startsWith("/")) {
+            throw new Error("sessionId, tabId and an absolute shell are required");
+        }
+        if (cols === undefined || rows === undefined) {
+            throw new Error(`cols must be ${MIN_COLS}..${MAX_COLS} and rows ${MIN_ROWS}..${MAX_ROWS}`);
+        }
+        const cwd = workspaceCwd(ctx, workspaceRegistry, resolver.getConfig().projectsRoot, workspace, sessionId);
+        if (cwd === undefined) {
+            throw new Error(`unknown workspace ${JSON.stringify(workspace)}`);
+        }
+        options = {
+            sessionId,
+            tabId,
+            workspace,
+            cwd,
+            container,
+            shell,
+            cols,
+            rows,
+            reopen: url.searchParams.get("reopen") === "1",
+            signal: request.signal,
+        };
+    }
+    catch (error) {
+        return json(400, { error: message(error) });
+    }
+    let prepared;
+    try {
+        prepared = await sessions.prepare(options);
+    }
+    catch (error) {
+        return json(400, { error: message(error) });
+    }
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+        start(controller) {
+            const write = (frame) => {
+                try {
+                    controller.enqueue(encoder.encode(`${JSON.stringify(frame)}\n`));
+                }
+                catch {
+                    // The consumer is gone; the request signal releases the attachment.
+                }
+            };
+            const detach = sessions.listen(prepared.terminalId, write, request.signal, prepared.snapshot);
+            request.signal.addEventListener("abort", () => {
+                detach();
+                try {
+                    controller.close();
+                }
+                catch {
+                    // Already closed by the consumer.
+                }
+            }, { once: true });
+        },
+    });
+    return new Response(stream, {
+        headers: {
+            "content-type": "application/x-ndjson",
+            "cache-control": "no-store",
+        },
+    });
+}
+async function handleControl(request, sessions) {
+    let body;
+    try {
+        body = await request.json();
+    }
+    catch {
+        return json(400, { error: "invalid terminal control" });
+    }
+    const control = controlOf(body);
+    if (control === undefined) {
+        return json(400, { error: "unknown terminal control" });
+    }
+    return sessions.control(control)
+        ? json(200, { ok: true })
+        : json(404, { error: "unknown terminal" });
+}
+async function handleShells(request, ctx, resolver, workspaceRegistry) {
+    const url = new URL(request.url);
+    const workspace = url.searchParams.get("workspace") ?? "";
+    const container = url.searchParams.get("container") ?? "";
+    const sessionId = url.searchParams.get("sessionId") ?? "";
+    const cwd = workspaceCwd(ctx, workspaceRegistry, resolver.getConfig().projectsRoot, workspace, sessionId);
+    if (cwd === undefined) {
+        return json(400, {
+            error: `unknown workspace ${JSON.stringify(workspace)}`,
+        });
+    }
+    try {
+        const binding = await bindingFor(resolver, cwd, container, request.signal);
+        return json(200, {
+            shells: await discoverShells(binding, cwd, request.signal),
+        });
+    }
+    catch (error) {
+        return json(502, { error: message(error) });
+    }
+}
+function handleRetained(request, sessions) {
+    const sessionId = new URL(request.url).searchParams.get("sessionId") ?? "";
+    if (sessionId === "")
+        return json(400, { error: "sessionId is required" });
+    return json(200, { terminals: sessions.retained(sessionId) });
+}
+/**
+ * Register the terminal routes on the connection service.
+ * @param ctx - plugin host context carrying the connection service.
+ * @param resolver - workspace/container resolver.
+ * @param sessions - live terminal registry.
+ * @param workspaceRegistry - the harness workspace registry, when present.
+ */
+export function registerTerminalRoutes(ctx, resolver, sessions, workspaceRegistry) {
+    ctx.inject(["connection"], (connectionCtx) => {
+        connectionCtx.connection.fetch.register({
+            path: TERMINAL_PATH,
+            methods: ["GET", "POST"],
+            requestBody: "buffered",
+            fetch: (request) => request.method === "POST"
+                ? handleControl(request, sessions)
+                : handleOpen(request, ctx, resolver, sessions, workspaceRegistry),
+        });
+        connectionCtx.connection.fetch.register({
+            path: TERMINAL_SHELLS_PATH,
+            methods: ["GET"],
+            requestBody: "buffered",
+            fetch: (request) => handleShells(request, ctx, resolver, workspaceRegistry),
+        });
+        connectionCtx.connection.fetch.register({
+            path: TERMINAL_TARGET_PATH,
+            methods: ["GET"],
+            requestBody: "buffered",
+            fetch: (request) => handleTarget(request, ctx, resolver, workspaceRegistry),
+        });
+        connectionCtx.connection.fetch.register({
+            path: TERMINAL_RETAINED_PATH,
+            methods: ["GET"],
+            requestBody: "buffered",
+            fetch: (request) => handleRetained(request, sessions),
+        });
+    });
+}

package/dist/terminal-route.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/terminal-route.test.js

@@ -0,0 +1,265 @@
+// SPDX-FileCopyrightText: 2026 Elouan Martinet <exa@elou.world>
+//
+// SPDX-License-Identifier: MIT
+import test from "node:test";
+import assert from "node:assert/strict";
+import { FakeExecStream, FakeTerminalCall, WORKSPACE_ID, } from "./test-support.js";
+import { TERMINAL_PATH, TERMINAL_RETAINED_PATH, TERMINAL_SHELLS_PATH, TERMINAL_TARGET_PATH, } from "./client/terminal-protocol.js";
+import { workspaceSlug } from "./workspace-binding.js";
+import { discoverShells, requireShell } from "./terminal-shells.js";
+import { TerminalSessions } from "./terminal-sessions.js";
+import { registerTerminalRoutes } from "./terminal-route.js";
+const ROOT = "/projects/team";
+function fakeGuest(options = {}) {
+    const terminal = new FakeTerminalCall();
+    const starts = [];
+    return {
+        terminal,
+        starts,
+        binding: {
+            guest: {
+                exec: () => new FakeExecStream(starts, { stdout: options.stdout ?? "" }),
+                terminal: () => terminal,
+            },
+            token: "t",
+        },
+    };
+}
+function fakeResolver(binding) {
+    const calls = [];
+    return {
+        calls,
+        resolveForPath: async () => {
+            calls.push("default");
+            return binding;
+        },
+        containerBinding: async (_cwd, container) => {
+            calls.push(container);
+            return binding;
+        },
+        getConfig: () => ({ projectsRoot: "/projects" }),
+    };
+}
+function fakeRegistry() {
+    return { list: () => [{ id: WORKSPACE_ID, path: ROOT }] };
+}
+function routeHarness(sessions, resolver, sessionStore) {
+    const routes = new Map();
+    const ctx = {
+        inject: (_names, fn) => {
+            fn({
+                connection: {
+                    fetch: {
+                        register: (route) => {
+                            routes.set(route.path, route);
+                            return async () => { };
+                        },
+                    },
+                },
+            });
+        },
+        get: (name) => name === "sessions" ? sessionStore : undefined,
+    };
+    registerTerminalRoutes(ctx, resolver, sessions, fakeRegistry());
+    return routes;
+}
+test("shell discovery parses the probe, dedups and prefers the most capable shell", async () => {
+    const { binding } = fakeGuest({
+        stdout: "sh\t/usr/bin/sh\nbash\t/usr/bin/bash\nzsh\t/opt/tools/bin/zsh\nnot a path\nbash\t/bin/bash\ndash\t/usr/bin/dash\nfish\t/usr/bin/fish\n",
+    });
+    const shells = await discoverShells(binding, ROOT);
+    assert.deepEqual(shells.map((shell) => `${shell.name}=${shell.path}`), [
+        "zsh=/opt/tools/bin/zsh",
+        "bash=/usr/bin/bash",
+        "fish=/usr/bin/fish",
+        "dash=/usr/bin/dash",
+        "sh=/usr/bin/sh",
+    ]);
+});
+test("shell discovery ignores names outside the candidate list", async () => {
+    const { binding } = fakeGuest({
+        stdout: "rbash\t/usr/bin/rbash\ngit-shell\t/usr/bin/git-shell\n",
+    });
+    assert.deepEqual(await discoverShells(binding, ROOT), []);
+});
+test("the host resolves a session's workspace from its own directory", async () => {
+    const { binding } = fakeGuest();
+    const resolver = fakeResolver(binding);
+    const sessions = new TerminalSessions({ resolver, retentionMs: 60_000 });
+    try {
+        const routes = routeHarness(sessions, resolver, {
+            get: (id) => id === "s1" ? { header: { cwd: `${ROOT}/src` } } : undefined,
+        });
+        const target = routes.get(TERMINAL_TARGET_PATH);
+        assert.ok(target);
+        const found = await target.fetch(new Request(`http://dsh.internal${TERMINAL_TARGET_PATH}?sessionId=s1`));
+        assert.equal(found.status, 200);
+        assert.deepEqual(await found.json(), {
+            workspace: "team",
+            workspaceSlug: workspaceSlug(WORKSPACE_ID),
+        });
+        // A missing id, an unknown session, an empty directory and a directory
+        // outside every workspace all refuse rather than guessing.
+        const missingId = await target.fetch(new Request(`http://dsh.internal${TERMINAL_TARGET_PATH}`));
+        assert.equal(missingId.status, 400);
+        assert.deepEqual(await missingId.json(), {
+            error: "sessionId is required",
+        });
+        for (const store of [
+            { get: () => undefined },
+            { get: () => ({ header: { cwd: "" } }) },
+            { get: () => ({ header: { cwd: "/elsewhere" } }) },
+        ]) {
+            const other = routeHarness(sessions, resolver, store).get(TERMINAL_TARGET_PATH);
+            const refused = await other.fetch(new Request(`http://dsh.internal${TERMINAL_TARGET_PATH}?sessionId=s1`));
+            assert.equal(refused.status, 400);
+            assert.deepEqual(await refused.json(), {
+                error: "Cannot determine this session's workspace",
+            });
+        }
+    }
+    finally {
+        sessions.dispose();
+    }
+});
+test("a shell missing from the probe is refused", async () => {
+    const { binding } = fakeGuest({ stdout: "bash\t/usr/bin/bash\n" });
+    await assert.rejects(() => requireShell(binding, ROOT, "/bin/zsh"), /not available in this container/);
+});
+test("terminal sessions stream frames, retain the shell and control it", async () => {
+    const { binding, terminal } = fakeGuest({ stdout: "bash\t/usr/bin/bash\n" });
+    const resolver = fakeResolver(binding);
+    const sessions = new TerminalSessions({ resolver, retentionMs: 60_000 });
+    try {
+        const prepared = await sessions.prepare({
+            sessionId: "s1",
+            tabId: "t1",
+            workspace: "team",
+            cwd: ROOT,
+            container: "",
+            shell: "/usr/bin/bash",
+            cols: 80,
+            rows: 24,
+        });
+        assert.equal(prepared.attached, false);
+        assert.deepEqual(resolver.calls, ["default"]);
+        const frames = [];
+        const detach = sessions.listen(prepared.terminalId, (frame) => frames.push(frame), new AbortController().signal);
+        assert.equal(frames[0]?.type, "ready");
+        terminal.emitStdout(Buffer.from("hi"));
+        assert.deepEqual(frames.at(-1), {
+            type: "data",
+            data: Buffer.from("hi").toString("base64"),
+        });
+        assert.equal(sessions.control({
+            terminalId: prepared.terminalId,
+            kind: "input",
+            data: Buffer.from("x").toString("base64"),
+        }), true);
+        assert.deepEqual(terminal.stdinChunks, [Buffer.from("x")]);
+        assert.equal(sessions.control({
+            terminalId: prepared.terminalId,
+            kind: "resize",
+            cols: 100,
+            rows: 30,
+        }), true);
+        assert.deepEqual(terminal.resizes, [{ cols: 100, rows: 30 }]);
+        assert.equal(sessions.control({
+            terminalId: prepared.terminalId,
+            kind: "rename",
+            title: "dev",
+        }), true);
+        assert.deepEqual(frames.at(-1), { type: "title", title: "dev" });
+        terminal.emitExit(0);
+        // The exit frame is written from the guest's done promise.
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        assert.equal(frames.at(-1)?.type, "exit");
+        // Reattaching replays the serialized screen and the exit state.
+        const again = await sessions.prepare({
+            sessionId: "s1",
+            tabId: "t1",
+            workspace: "team",
+            cwd: ROOT,
+            container: "",
+            shell: "/usr/bin/bash",
+            cols: 80,
+            rows: 24,
+        });
+        assert.equal(again.attached, true);
+        assert.equal(again.terminalId, prepared.terminalId);
+        const reattached = [];
+        sessions.listen(again.terminalId, (frame) => reattached.push(frame), new AbortController().signal, again.snapshot);
+        assert.equal(reattached[0]?.type, "ready");
+        assert.equal(reattached[1]?.type, "snapshot");
+        assert.equal(reattached.at(-1)?.type, "exit");
+        // A named container resolves through containerBinding.
+        const other = await sessions.prepare({
+            sessionId: "s1",
+            tabId: "t2",
+            workspace: "team",
+            cwd: ROOT,
+            container: "dev",
+            shell: "/usr/bin/bash",
+            cols: 80,
+            rows: 24,
+        });
+        assert.deepEqual(resolver.calls, ["default", "dev"]);
+        assert.equal(sessions.retained("s1").length, 2);
+        assert.equal(sessions.control({ terminalId: other.terminalId, kind: "close" }), true);
+        assert.equal(sessions.retained("s1").length, 1);
+        detach();
+    }
+    finally {
+        sessions.dispose();
+    }
+});
+test("terminal routes open, control, list and validate", async () => {
+    const { binding, terminal } = fakeGuest({ stdout: "bash\t/usr/bin/bash\n" });
+    const resolver = fakeResolver(binding);
+    const sessions = new TerminalSessions({ resolver, retentionMs: 60_000 });
+    try {
+        const routes = routeHarness(sessions, resolver);
+        const open = routes.get(TERMINAL_PATH);
+        assert.ok(open);
+        const missingShell = await open.fetch(new Request(`http://dsh.internal${TERMINAL_PATH}?sessionId=s1&tabId=t1&workspace=team&cols=80&rows=24`));
+        assert.equal(missingShell.status, 400);
+        const unknownWorkspace = await open.fetch(new Request(`http://dsh.internal${TERMINAL_PATH}?sessionId=s1&tabId=t1&workspace=nope&shell=/usr/bin/bash&cols=80&rows=24`));
+        assert.equal(unknownWorkspace.status, 400);
+        const response = await open.fetch(new Request(`http://dsh.internal${TERMINAL_PATH}?sessionId=s1&tabId=t1&workspace=team&shell=/usr/bin/bash&cols=80&rows=24`));
+        assert.equal(response.status, 200);
+        assert.equal(response.headers.get("content-type"), "application/x-ndjson");
+        const reader = response.body.getReader();
+        const first = new TextDecoder().decode((await reader.read()).value);
+        assert.match(first, /"type":"ready"/);
+        const ready = JSON.parse(first.trim().split("\n")[0]);
+        const control = await open.fetch(new Request(`http://dsh.internal${TERMINAL_PATH}`, {
+            method: "POST",
+            body: JSON.stringify({
+                terminalId: ready.terminalId,
+                kind: "resize",
+                cols: 90,
+                rows: 30,
+            }),
+        }));
+        assert.equal(control.status, 200);
+        assert.deepEqual(terminal.resizes, [{ cols: 90, rows: 30 }]);
+        const unknownTerminal = await open.fetch(new Request(`http://dsh.internal${TERMINAL_PATH}`, {
+            method: "POST",
+            body: JSON.stringify({ terminalId: "nope", kind: "close" }),
+        }));
+        assert.equal(unknownTerminal.status, 404);
+        const shellsResponse = await routes.get(TERMINAL_SHELLS_PATH).fetch(new Request(`http://dsh.internal${TERMINAL_SHELLS_PATH}?workspace=team&sessionId=s1`));
+        const shellsBody = (await shellsResponse.json());
+        assert.deepEqual(shellsBody.shells.map((shell) => shell.path), [
+            "/usr/bin/bash",
+        ]);
+        const retainedResponse = await routes.get(TERMINAL_RETAINED_PATH).fetch(new Request(`http://dsh.internal${TERMINAL_RETAINED_PATH}?sessionId=s1`));
+        const retainedBody = (await retainedResponse.json());
+        assert.equal(retainedBody.terminals.length, 1);
+        assert.equal(retainedBody.terminals[0]?.tabId, "t1");
+        await reader.cancel();
+    }
+    finally {
+        sessions.dispose();
+    }
+});

package/dist/terminal-sessions.d.ts

@@ -0,0 +1,69 @@
+import { type TerminalControl, type TerminalFrame, type TerminalRetainedView } from "./client/terminal-protocol.js";
+import { type WorkspaceResolver } from "./workspace-binding.js";
+export declare const TERMINAL_RETENTION_MS = 7200000;
+export interface TerminalOpenOptions {
+    sessionId: string;
+    tabId: string;
+    workspace: string;
+    cwd: string;
+    container: string;
+    shell: string;
+    cols: number;
+    rows: number;
+    reopen?: boolean;
+    signal?: AbortSignal;
+}
+export interface TerminalPrepared {
+    terminalId: string;
+    workspace: string;
+    container: string;
+    shell: string;
+    title: string;
+    attached: boolean;
+    snapshot?: string;
+}
+export interface TerminalSessionsOptions {
+    resolver: WorkspaceResolver;
+    scrollback?: number;
+    retentionMs?: number;
+}
+export declare class TerminalSessions {
+    private readonly options;
+    private readonly entries;
+    private readonly byId;
+    private readonly scrollback;
+    private readonly retentionMs;
+    private readonly sweep;
+    constructor(options: TerminalSessionsOptions);
+    /**
+     * Validate a request and make sure its terminal exists.
+     * @param options - session/tab identity, target container and shell, dimensions.
+     * @returns the terminal identity and, when reattaching, its serialized screen.
+     */
+    prepare(options: TerminalOpenOptions): Promise<TerminalPrepared>;
+    /**
+     * Attach one browser stream as the terminal's input owner.
+     * @param terminalId - a prepared terminal.
+     * @param write - frame sink for this attachment.
+     * @param signal - the request lifetime; aborting detaches without closing.
+     * @param snapshot - serialized screen to replay before live output.
+     * @returns a detach function, idempotent and safe after the entry is gone.
+     */
+    listen(terminalId: string, write: (frame: TerminalFrame) => void, signal: AbortSignal, snapshot?: string): () => void;
+    /**
+     * Apply one control request.
+     * @param control - input, resize, rename, or close.
+     * @returns whether the terminal was found.
+     */
+    control(control: TerminalControl): boolean;
+    /**
+     * List the terminals one session still holds.
+     * @param sessionId - the owning session.
+     * @returns retained terminal metadata, oldest first.
+     */
+    retained(sessionId: string): TerminalRetainedView[];
+    /** Close every terminal and stop the retention sweep. */
+    dispose(): void;
+    private drop;
+    private reap;
+}