@otto-code/server 0.5.0

package/dist/server/terminal/terminal-manager.js

@@ -0,0 +1,319 @@
+import { createTerminal, } from "./terminal.js";
+import { captureTerminalLines } from "./terminal-capture.js";
+import { randomBytes, randomUUID } from "node:crypto";
+import { resolve, sep } from "node:path";
+import { assertAbsolutePath, isSameOrDescendantPath } from "../server/path-utils.js";
+import { deriveTerminalActivityStatusBucket } from "@otto-code/protocol/terminal-activity";
+function createActivityToken() {
+    return randomBytes(32).toString("base64url");
+}
+export function createTerminalManager(managerOptions = {}) {
+    const terminalsByCwd = new Map();
+    const terminalsById = new Map();
+    const terminalExitUnsubscribeById = new Map();
+    const terminalTitleUnsubscribeById = new Map();
+    const terminalActivityUnsubscribeById = new Map();
+    const terminalActivityTokenById = new Map();
+    const terminalsChangedListeners = new Set();
+    const terminalActivityListeners = new Set();
+    const terminalWorkspaceContributionChangedListeners = new Set();
+    const defaultEnvByRootCwd = new Map();
+    function removeSessionById(id, options) {
+        const session = terminalsById.get(id);
+        if (!session) {
+            return;
+        }
+        const unsubscribeExit = terminalExitUnsubscribeById.get(id);
+        if (unsubscribeExit) {
+            unsubscribeExit();
+            terminalExitUnsubscribeById.delete(id);
+        }
+        const unsubscribeTitle = terminalTitleUnsubscribeById.get(id);
+        if (unsubscribeTitle) {
+            unsubscribeTitle();
+            terminalTitleUnsubscribeById.delete(id);
+        }
+        const unsubscribeActivity = terminalActivityUnsubscribeById.get(id);
+        if (unsubscribeActivity) {
+            unsubscribeActivity();
+            terminalActivityUnsubscribeById.delete(id);
+        }
+        terminalsById.delete(id);
+        terminalActivityTokenById.delete(id);
+        const terminals = terminalsByCwd.get(session.cwd);
+        if (terminals) {
+            const index = terminals.findIndex((terminal) => terminal.id === id);
+            if (index !== -1) {
+                terminals.splice(index, 1);
+            }
+            if (terminals.length === 0) {
+                terminalsByCwd.delete(session.cwd);
+            }
+        }
+        if (options.kill) {
+            session.kill();
+        }
+        const previousActivity = session.getActivity();
+        const previousBucket = deriveTerminalActivityStatusBucket(previousActivity);
+        if (previousBucket !== null) {
+            emitTerminalWorkspaceContributionChanged({
+                terminalId: session.id,
+                cwd: session.cwd,
+                workspaceId: session.workspaceId,
+            });
+        }
+        emitTerminalsChanged({ cwd: session.cwd });
+    }
+    function resolveDefaultEnvForCwd(cwd) {
+        const normalizedCwd = resolve(cwd);
+        let bestMatchRoot = null;
+        for (const rootCwd of defaultEnvByRootCwd.keys()) {
+            const matches = normalizedCwd === rootCwd || normalizedCwd.startsWith(`${rootCwd}${sep}`);
+            if (!matches) {
+                continue;
+            }
+            if (!bestMatchRoot || rootCwd.length > bestMatchRoot.length) {
+                bestMatchRoot = rootCwd;
+            }
+        }
+        return bestMatchRoot ? defaultEnvByRootCwd.get(bestMatchRoot) : undefined;
+    }
+    function registerSession(session) {
+        terminalsById.set(session.id, session);
+        const unsubscribeExit = session.onExit(() => {
+            removeSessionById(session.id, { kill: false });
+        });
+        const unsubscribeTitle = session.onTitleChange(() => {
+            emitTerminalsChanged({ cwd: session.cwd });
+        });
+        const unsubscribeActivity = session.onActivityChange((transition) => {
+            emitTerminalActivityTransition({ session, transition });
+            emitTerminalsChanged({ cwd: session.cwd });
+            const previousBucket = deriveTerminalActivityStatusBucket(transition.previous);
+            const nextBucket = deriveTerminalActivityStatusBucket(transition.activity);
+            if (previousBucket !== nextBucket) {
+                emitTerminalWorkspaceContributionChanged({
+                    terminalId: session.id,
+                    cwd: session.cwd,
+                    workspaceId: session.workspaceId,
+                });
+            }
+        });
+        terminalExitUnsubscribeById.set(session.id, unsubscribeExit);
+        terminalTitleUnsubscribeById.set(session.id, unsubscribeTitle);
+        terminalActivityUnsubscribeById.set(session.id, unsubscribeActivity);
+        return session;
+    }
+    function toTerminalListItem(input) {
+        return {
+            id: input.session.id,
+            name: input.session.name,
+            cwd: input.session.cwd,
+            workspaceId: input.session.workspaceId,
+            title: input.session.getTitle(),
+            activity: input.session.getActivity(),
+        };
+    }
+    function emitTerminalsChanged(input) {
+        if (terminalsChangedListeners.size === 0) {
+            return;
+        }
+        const terminals = (terminalsByCwd.get(input.cwd) ?? []).map((session) => toTerminalListItem({ session }));
+        const event = {
+            cwd: input.cwd,
+            terminals,
+        };
+        for (const listener of terminalsChangedListeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // no-op
+            }
+        }
+    }
+    function emitTerminalActivityTransition(input) {
+        if (terminalActivityListeners.size === 0) {
+            return;
+        }
+        const event = {
+            terminalId: input.session.id,
+            name: input.session.name,
+            cwd: input.session.cwd,
+            workspaceId: input.session.workspaceId,
+            activity: input.transition.activity,
+            previous: input.transition.previous,
+        };
+        for (const listener of terminalActivityListeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // no-op
+            }
+        }
+    }
+    function emitTerminalWorkspaceContributionChanged(event) {
+        for (const listener of terminalWorkspaceContributionChangedListeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // no-op
+            }
+        }
+    }
+    return {
+        async getTerminals(cwd, options) {
+            assertAbsolutePath(cwd);
+            // Terminals are bucketed by exact cwd, but an agent can open a terminal in
+            // a subdirectory of the workspace. A query for the workspace root must
+            // surface those too, so aggregate every bucket at or below `cwd`.
+            const sessions = [];
+            for (const [bucketCwd, bucketSessions] of terminalsByCwd) {
+                if (isSameOrDescendantPath(cwd, bucketCwd)) {
+                    sessions.push(...bucketSessions);
+                }
+            }
+            // When the query carries a workspaceId, two workspaces sharing a cwd must
+            // not see each other's terminals. A missing owner is not workspace
+            // membership; unscoped callers can still list those legacy terminals.
+            if (options?.workspaceId !== undefined) {
+                return sessions.filter((session) => session.workspaceId === options.workspaceId);
+            }
+            return sessions;
+        },
+        async createTerminal(options) {
+            assertAbsolutePath(options.cwd);
+            const terminals = terminalsByCwd.get(options.cwd) ?? [];
+            const defaultName = `Terminal ${terminals.length + 1}`;
+            const inheritedEnv = resolveDefaultEnvForCwd(options.cwd);
+            const mergedEnv = inheritedEnv || options.env ? { ...inheritedEnv, ...options.env } : undefined;
+            const terminalId = options.id ?? randomUUID();
+            const activityToken = options.activityToken ?? createActivityToken();
+            const terminalActivityUrl = options.activityUrl === undefined
+                ? (managerOptions.getTerminalActivityUrl?.() ?? null)
+                : options.activityUrl;
+            const activityEnv = {
+                OTTO_TERMINAL_ID: terminalId,
+                OTTO_ACTIVITY_TOKEN: activityToken,
+                ...(terminalActivityUrl ? { OTTO_TERMINAL_ACTIVITY_URL: terminalActivityUrl } : {}),
+            };
+            terminalActivityTokenById.set(terminalId, activityToken);
+            let session;
+            try {
+                session = registerSession(await createTerminal({
+                    id: terminalId,
+                    cwd: options.cwd,
+                    workspaceId: options.workspaceId,
+                    name: options.name ?? defaultName,
+                    ...(options.title ? { title: options.title } : {}),
+                    ...(options.command ? { command: options.command } : {}),
+                    ...(options.args ? { args: options.args } : {}),
+                    ...(mergedEnv ? { env: mergedEnv } : {}),
+                    activityEnv,
+                }));
+            }
+            catch (error) {
+                terminalActivityTokenById.delete(terminalId);
+                throw error;
+            }
+            terminals.push(session);
+            terminalsByCwd.set(options.cwd, terminals);
+            emitTerminalsChanged({ cwd: options.cwd });
+            return session;
+        },
+        registerCwdEnv(options) {
+            assertAbsolutePath(options.cwd);
+            defaultEnvByRootCwd.set(resolve(options.cwd), { ...options.env });
+        },
+        validateTerminalActivityToken(terminalId, token) {
+            const expected = terminalActivityTokenById.get(terminalId);
+            if (!expected) {
+                return "unknown";
+            }
+            return expected === token ? "valid" : "invalid";
+        },
+        getTerminal(id) {
+            return terminalsById.get(id);
+        },
+        async getTerminalState(id, options) {
+            return terminalsById.get(id)?.getStateSnapshot(options) ?? null;
+        },
+        setTerminalTitle(id, title) {
+            const session = terminalsById.get(id);
+            if (!session) {
+                return false;
+            }
+            session.setTitle(title);
+            return true;
+        },
+        async setTerminalActivity(id, state) {
+            const session = terminalsById.get(id);
+            if (!session) {
+                return false;
+            }
+            session.setActivity(state);
+            return true;
+        },
+        async clearTerminalAttention(id) {
+            const session = terminalsById.get(id);
+            if (!session) {
+                return false;
+            }
+            return session.clearActivityAttention();
+        },
+        killTerminal(id) {
+            removeSessionById(id, { kill: true });
+        },
+        async killTerminalAndWait(id, options) {
+            const session = terminalsById.get(id);
+            if (!session) {
+                return;
+            }
+            try {
+                await session.killAndWait(options);
+            }
+            finally {
+                removeSessionById(id, { kill: false });
+            }
+        },
+        async captureTerminal(id, options) {
+            const session = terminalsById.get(id);
+            if (!session) {
+                return {
+                    lines: [],
+                    totalLines: 0,
+                };
+            }
+            return captureTerminalLines(session, options);
+        },
+        listDirectories() {
+            return Array.from(terminalsByCwd.keys());
+        },
+        killAll() {
+            for (const id of Array.from(terminalsById.keys())) {
+                removeSessionById(id, { kill: true });
+            }
+        },
+        subscribeTerminalsChanged(listener) {
+            terminalsChangedListeners.add(listener);
+            return () => {
+                terminalsChangedListeners.delete(listener);
+            };
+        },
+        subscribeTerminalActivity(listener) {
+            terminalActivityListeners.add(listener);
+            return () => {
+                terminalActivityListeners.delete(listener);
+            };
+        },
+        subscribeTerminalWorkspaceContributionChanged(listener) {
+            terminalWorkspaceContributionChangedListeners.add(listener);
+            return () => {
+                terminalWorkspaceContributionChangedListeners.delete(listener);
+            };
+        },
+    };
+}
+//# sourceMappingURL=terminal-manager.js.map

package/dist/server/terminal/terminal-output-coalescer.d.ts

@@ -0,0 +1,34 @@
+export interface TerminalOutputCoalescerTimers {
+    setTimeout: typeof setTimeout;
+    clearTimeout: typeof clearTimeout;
+}
+export interface TerminalOutputCoalescerFlush {
+    payload: Buffer;
+    chars: number;
+    bytes: number;
+}
+export interface TerminalOutputCoalescerOptions {
+    timers: TerminalOutputCoalescerTimers;
+    flushDelayMs?: number;
+    now?: () => number;
+    onFlush: (payload: TerminalOutputCoalescerFlush) => void;
+}
+export declare class TerminalOutputCoalescer {
+    private readonly timers;
+    private readonly flushDelayMs;
+    private readonly now;
+    private readonly onFlush;
+    private chunks;
+    private bytes;
+    private chars;
+    private flushTimer;
+    private lastFlushAt;
+    constructor(options: TerminalOutputCoalescerOptions);
+    handle(data: string): void;
+    flush(): void;
+    markFlushed(): void;
+    dispose(): void;
+    private clearTimer;
+    private clearPending;
+}
+//# sourceMappingURL=terminal-output-coalescer.d.ts.map

package/dist/server/terminal/terminal-output-coalescer.js

@@ -0,0 +1,73 @@
+const DEFAULT_FLUSH_DELAY_MS = 5;
+export class TerminalOutputCoalescer {
+    constructor(options) {
+        this.chunks = [];
+        this.bytes = 0;
+        this.chars = 0;
+        this.flushTimer = null;
+        this.lastFlushAt = null;
+        this.timers = options.timers;
+        this.flushDelayMs = options.flushDelayMs ?? DEFAULT_FLUSH_DELAY_MS;
+        this.now = options.now ?? Date.now;
+        this.onFlush = options.onFlush;
+    }
+    handle(data) {
+        if (data.length === 0) {
+            return;
+        }
+        const chunk = Buffer.from(data, "utf8");
+        this.chunks.push(chunk);
+        this.bytes += chunk.byteLength;
+        this.chars += data.length;
+        // Leading edge: if nothing is pending and no flush happened within the last
+        // flushDelayMs, flush immediately so interactive echo isn't delayed a full
+        // window. Otherwise accumulate and let the trailing timer drain the burst.
+        if (!this.flushTimer) {
+            const elapsed = this.lastFlushAt === null ? Number.POSITIVE_INFINITY : this.now() - this.lastFlushAt;
+            if (elapsed >= this.flushDelayMs) {
+                this.flush();
+                return;
+            }
+            this.flushTimer = this.timers.setTimeout(() => {
+                this.flushTimer = null;
+                this.flush();
+            }, this.flushDelayMs);
+        }
+    }
+    flush() {
+        this.clearTimer();
+        if (this.chunks.length === 0) {
+            return;
+        }
+        const payload = this.chunks.length === 1 ? this.chunks[0] : Buffer.concat(this.chunks, this.bytes);
+        const bytes = this.bytes;
+        const chars = this.chars;
+        this.clearPending();
+        this.lastFlushAt = this.now();
+        this.onFlush({ payload, bytes, chars });
+    }
+    // Record that a frame was emitted out-of-band on this stream (e.g. a snapshot
+    // frame sent directly, bypassing the coalescer). This keeps the next handled
+    // chunk on the trailing path instead of leading-edge flushing it back-to-back
+    // with that frame, preserving the small gap consumers rely on after a snapshot.
+    markFlushed() {
+        this.lastFlushAt = this.now();
+    }
+    dispose() {
+        this.clearTimer();
+        this.clearPending();
+    }
+    clearTimer() {
+        if (!this.flushTimer) {
+            return;
+        }
+        this.timers.clearTimeout(this.flushTimer);
+        this.flushTimer = null;
+    }
+    clearPending() {
+        this.chunks = [];
+        this.bytes = 0;
+        this.chars = 0;
+    }
+}
+//# sourceMappingURL=terminal-output-coalescer.js.map

package/dist/server/terminal/terminal-restore.d.ts

@@ -0,0 +1,18 @@
+import type { SubscribeTerminalRequest } from "@otto-code/protocol/messages";
+import type { TerminalStateSnapshot, TerminalStateSnapshotOptions } from "./terminal.js";
+export declare const MAX_TERMINAL_OUTPUT_FRAME_BYTES: number;
+export declare const MAX_CLIENT_BUFFERED_BYTES: number;
+export type TerminalRestoreOptions = NonNullable<SubscribeTerminalRequest["restore"]>;
+export type TerminalSubscriptionSnapshotMode = "state" | "ready";
+export declare function resolveTerminalSubscriptionSnapshotMode(restore: TerminalRestoreOptions | undefined): TerminalSubscriptionSnapshotMode;
+export declare function resolveRestoreAfterOutputOverflow(restore: TerminalRestoreOptions | undefined): TerminalRestoreOptions | undefined;
+export declare function resolveTerminalRestoreSnapshotOptions(restore: TerminalRestoreOptions): TerminalStateSnapshotOptions | null | undefined;
+export declare function encodeLegacyTerminalSnapshotFrame(input: {
+    slot: number;
+    snapshot: TerminalStateSnapshot;
+}): Uint8Array;
+export declare function encodeTerminalRestoreFrame(input: {
+    slot: number;
+    snapshot: TerminalStateSnapshot;
+}): Uint8Array;
+//# sourceMappingURL=terminal-restore.d.ts.map

package/dist/server/terminal/terminal-restore.js

@@ -0,0 +1,52 @@
+import { TerminalStreamOpcode, encodeTerminalSnapshotPayload, encodeTerminalStreamFrame, } from "@otto-code/protocol/binary-frames/index";
+import { renderTerminalSnapshotToAnsi } from "@otto-code/protocol/terminal-snapshot";
+export const MAX_TERMINAL_OUTPUT_FRAME_BYTES = 256 * 1024;
+// A client is only forced onto the snapshot catch-up path once its transport is
+// genuinely backed up — measured by the socket's bufferedAmount, not by how much
+// the terminal has produced. Set well above any normal in-flight burst (a
+// keeping-up client drains continuously and never approaches this) but low
+// enough that a stalled socket crosses it long before a large burst finishes.
+export const MAX_CLIENT_BUFFERED_BYTES = 4 * 1024 * 1024;
+const DEFAULT_VISIBLE_RESTORE_SCROLLBACK_LINES = 200;
+const MAX_VISIBLE_RESTORE_SCROLLBACK_LINES = 500;
+export function resolveTerminalSubscriptionSnapshotMode(restore) {
+    return restore ? "ready" : "state";
+}
+export function resolveRestoreAfterOutputOverflow(restore) {
+    if (restore?.mode === "live") {
+        return { mode: "visible-snapshot" };
+    }
+    return restore;
+}
+export function resolveTerminalRestoreSnapshotOptions(restore) {
+    if (restore.mode === "live") {
+        return null;
+    }
+    if (restore.mode === "visible-snapshot") {
+        return {
+            scrollbackLines: resolveVisibleRestoreScrollbackLines(restore.scrollbackLines),
+        };
+    }
+    return undefined;
+}
+export function encodeLegacyTerminalSnapshotFrame(input) {
+    return encodeTerminalStreamFrame({
+        opcode: TerminalStreamOpcode.Snapshot,
+        slot: input.slot,
+        payload: encodeTerminalSnapshotPayload(input.snapshot.state),
+    });
+}
+export function encodeTerminalRestoreFrame(input) {
+    return encodeTerminalStreamFrame({
+        opcode: TerminalStreamOpcode.Restore,
+        slot: input.slot,
+        payload: renderTerminalSnapshotToAnsi(input.snapshot.state),
+    });
+}
+function resolveVisibleRestoreScrollbackLines(value) {
+    if (typeof value !== "number") {
+        return DEFAULT_VISIBLE_RESTORE_SCROLLBACK_LINES;
+    }
+    return Math.min(Math.max(0, value), MAX_VISIBLE_RESTORE_SCROLLBACK_LINES);
+}
+//# sourceMappingURL=terminal-restore.js.map

package/dist/server/terminal/terminal-session-controller.d.ts

@@ -0,0 +1,85 @@
+import type pino from "pino";
+import type { SessionInboundMessage, SessionOutboundMessage } from "../server/messages.js";
+import { type TerminalStreamFrame } from "@otto-code/protocol/binary-frames/index";
+import type { TerminalManager } from "./terminal-manager.js";
+export interface TerminalSessionControllerOptions {
+    terminalManager: TerminalManager | null;
+    emit: (msg: SessionOutboundMessage) => void;
+    emitBinary: (frame: Uint8Array) => void;
+    hasBinaryChannel: () => boolean;
+    isPathWithinRoot: (rootPath: string, candidatePath: string) => boolean;
+    sessionLogger: pino.Logger;
+    listTerminalWorkspaceRefs?: () => Promise<readonly TerminalWorkspaceRef[]>;
+    listTerminalWorkspaceRoots?: () => Promise<readonly string[]>;
+    clientSupportsWrapReflow?: () => boolean;
+    getClientBufferedAmount?: () => number | null;
+}
+interface TerminalWorkspaceRef {
+    workspaceId: string;
+    cwd: string;
+}
+export interface TerminalSessionControllerMetrics {
+    directorySubscriptionCount: number;
+    streamSubscriptionCount: number;
+}
+export declare class TerminalSessionController {
+    private readonly terminalManager;
+    private readonly emit;
+    private readonly emitBinary;
+    private readonly hasBinaryChannel;
+    private readonly isPathWithinRoot;
+    private readonly sessionLogger;
+    private readonly listTerminalWorkspaceRefs;
+    private readonly listTerminalWorkspaceRoots;
+    private readonly clientSupportsWrapReflow;
+    private readonly getClientBufferedAmount;
+    private readonly subscribedDirectories;
+    private unsubscribeTerminalsChanged;
+    private readonly exitSubscriptions;
+    private readonly activeStreams;
+    private readonly idToSlot;
+    private nextSlot;
+    constructor(options: TerminalSessionControllerOptions);
+    start(): void;
+    getMetrics(): TerminalSessionControllerMetrics;
+    dispatch(msg: SessionInboundMessage): Promise<void> | undefined;
+    handleBinaryFrame(frame: TerminalStreamFrame): void;
+    killTerminalForClose(terminalId: string): {
+        terminalId: string;
+        success: boolean;
+    };
+    killTerminalsForWorkspace(workspaceId: string): Promise<void>;
+    dispose(): void;
+    private ensureExitSubscription;
+    private handleTerminalExited;
+    private emitTerminalsChangedSnapshot;
+    private toTerminalInfo;
+    private handleTerminalsChanged;
+    private handleSubscribeTerminalsRequest;
+    private handleUnsubscribeTerminalsRequest;
+    private emitTerminalsSnapshotForSubscription;
+    private handleListTerminalsRequest;
+    private getAllTerminalSessions;
+    private getTerminalsForWorkspaceRoot;
+    private terminalBelongsToRoot;
+    private resolveTerminalOwnerRoot;
+    private isSamePath;
+    private handleCreateTerminalRequest;
+    private resolveLegacyTerminalWorkspaceId;
+    private handleRenameTerminalRequest;
+    private handleSubscribeTerminalRequest;
+    private handleUnsubscribeTerminalRequest;
+    private handleTerminalInput;
+    private killTracked;
+    private handleKillTerminalRequest;
+    private handleCaptureTerminalRequest;
+    private bindActiveStream;
+    private trySendSnapshot;
+    private emitLegacySnapshot;
+    private emitRestoreSnapshot;
+    private replayTerminalOutputAfterSnapshot;
+    private allocateSlot;
+    private detachStream;
+}
+export {};
+//# sourceMappingURL=terminal-session-controller.d.ts.map