@hyperdrive.bot/paseo-server 0.2.6

package/dist/server/terminal/terminal-ts-loader.mjs

@@ -0,0 +1,20 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+export async function resolve(specifier, context, nextResolve) {
+  if (
+    context.parentURL?.startsWith("file:") &&
+    specifier.startsWith(".") &&
+    specifier.endsWith(".js")
+  ) {
+    const candidateUrl = new URL(specifier.replace(/\.js$/, ".ts"), context.parentURL);
+    if (existsSync(fileURLToPath(candidateUrl))) {
+      return {
+        url: candidateUrl.href,
+        shortCircuit: true,
+      };
+    }
+  }
+
+  return nextResolve(specifier, context);
+}

package/dist/server/terminal/terminal-worker-process.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=terminal-worker-process.d.ts.map

package/dist/server/terminal/terminal-worker-process.js

@@ -0,0 +1,304 @@
+import { createTerminalManager } from "./terminal-manager.js";
+import { captureTerminalLines } from "./terminal-capture.js";
+import { TerminalOutputCoalescer } from "./terminal-output-coalescer.js";
+const manager = createTerminalManager();
+const unsubscribeByTerminalId = new Map();
+const outputCoalescerByTerminalId = new Map();
+let ipcClosing = false;
+let inFlightTerminalCreateRequest = null;
+// The conpty failure signal is process-scoped, not request-scoped. Serializing
+// creates keeps an async spawn failure attributable to exactly one request.
+let createTerminalQueue = Promise.resolve();
+// node-pty completes its Windows conpty spawn asynchronously on a separate
+// conout worker thread. When that spawn fails (bad cwd, missing command, etc.)
+// it throws an exception there that cannot be caught at the call site and would
+// otherwise crash this worker process and sever every existing terminal.
+process.on("uncaughtException", (error) => {
+    console.error("Terminal worker uncaught exception (kept alive):", error);
+    reportInFlightTerminalCreateFailure(error);
+});
+function sendToParent(message) {
+    if (ipcClosing || !process.connected || !process.send) {
+        return;
+    }
+    try {
+        process.send(message, (error) => {
+            if (error) {
+                ipcClosing = true;
+            }
+        });
+    }
+    catch {
+        ipcClosing = true;
+    }
+}
+function buildTerminalStateResult(session, options) {
+    if (!session) {
+        return null;
+    }
+    return { ...session.getStateSnapshot(options), replayPreamble: session.getReplayPreamble() };
+}
+function toTerminalInfo(session) {
+    return {
+        id: session.id,
+        name: session.name,
+        cwd: session.cwd,
+        workspaceId: session.workspaceId,
+        ...(session.getTitle() ? { title: session.getTitle() } : {}),
+        activity: session.getActivity(),
+    };
+}
+function terminalWorkerErrorMessage(error) {
+    return error instanceof Error ? error.message : "Terminal worker request failed";
+}
+function reportInFlightTerminalCreateFailure(error) {
+    if (!inFlightTerminalCreateRequest || inFlightTerminalCreateRequest.errorReported) {
+        return;
+    }
+    inFlightTerminalCreateRequest.errorReported = true;
+    sendToParent({
+        type: "response",
+        requestId: inFlightTerminalCreateRequest.requestId,
+        ok: false,
+        error: terminalWorkerErrorMessage(error),
+    });
+}
+function clearTerminalSubscriptions(terminalId) {
+    const subscriptions = unsubscribeByTerminalId.get(terminalId);
+    if (subscriptions) {
+        for (const unsubscribe of subscriptions) {
+            try {
+                unsubscribe();
+            }
+            catch {
+                // no-op
+            }
+        }
+    }
+    unsubscribeByTerminalId.delete(terminalId);
+    const coalescer = outputCoalescerByTerminalId.get(terminalId);
+    if (coalescer) {
+        coalescer.dispose();
+        outputCoalescerByTerminalId.delete(terminalId);
+    }
+}
+function watchTerminal(session) {
+    clearTerminalSubscriptions(session.id);
+    // Coalesce pty output chunks into a single IPC message per ~5ms window so a
+    // burst of small chunks no longer costs one process.send each. The batch
+    // carries the LAST chunk's revision (the highest) so downstream snapshot
+    // replay dedup stays correct.
+    let pendingOutputRevision;
+    const outputCoalescer = new TerminalOutputCoalescer({
+        timers: { setTimeout, clearTimeout },
+        onFlush: ({ payload }) => {
+            const revision = pendingOutputRevision;
+            pendingOutputRevision = undefined;
+            sendToParent({
+                type: "terminalMessage",
+                terminalId: session.id,
+                message: { type: "output", data: payload.toString("utf8"), revision },
+            });
+        },
+    });
+    outputCoalescerByTerminalId.set(session.id, outputCoalescer);
+    const unsubscribeMessage = session.subscribe((message) => {
+        if (message.type === "output") {
+            pendingOutputRevision = message.revision;
+            outputCoalescer.handle(message.data);
+            return;
+        }
+        // Non-output messages (snapshot/snapshotReady/titleChange) must not jump
+        // ahead of buffered output: flush the coalescer first, then forward.
+        outputCoalescer.flush();
+        sendToParent({
+            type: "terminalMessage",
+            terminalId: session.id,
+            message,
+        });
+    });
+    const unsubscribeExit = session.onExit((info) => {
+        outputCoalescer.flush();
+        clearTerminalSubscriptions(session.id);
+        sendToParent({
+            type: "terminalExit",
+            terminalId: session.id,
+            info,
+        });
+    });
+    const unsubscribeTitle = session.onTitleChange((title) => {
+        outputCoalescer.flush();
+        sendToParent({
+            type: "terminalTitleChange",
+            terminalId: session.id,
+            title,
+        });
+    });
+    const unsubscribeCommandFinished = session.onCommandFinished((info) => {
+        outputCoalescer.flush();
+        sendToParent({
+            type: "terminalCommandFinished",
+            terminalId: session.id,
+            info,
+        });
+    });
+    const unsubscribeActivity = session.onActivityChange((transition) => {
+        sendToParent({
+            type: "terminalActivityChange",
+            terminalId: session.id,
+            activity: transition.activity,
+            previous: transition.previous,
+        });
+    });
+    unsubscribeByTerminalId.set(session.id, [
+        unsubscribeMessage,
+        unsubscribeExit,
+        unsubscribeTitle,
+        unsubscribeCommandFinished,
+        unsubscribeActivity,
+    ]);
+}
+function enqueueCreateTerminalRequest(message) {
+    const nextRequest = createTerminalQueue.then(() => handleCreateTerminalRequest(message));
+    createTerminalQueue = nextRequest.catch(() => { });
+    return nextRequest;
+}
+async function handleCreateTerminalRequest(message) {
+    const request = {
+        requestId: message.requestId,
+        errorReported: false,
+    };
+    inFlightTerminalCreateRequest = request;
+    try {
+        const { workspaceId } = message.options;
+        if (!workspaceId) {
+            throw new Error("workspaceId is required");
+        }
+        const session = await manager.createTerminal({ ...message.options, workspaceId });
+        if (request.errorReported) {
+            session.kill();
+            return;
+        }
+        watchTerminal(session);
+        const initialSnapshot = session.getStateSnapshot();
+        sendToParent({
+            type: "terminalCreated",
+            terminal: toTerminalInfo(session),
+            state: initialSnapshot.state,
+        });
+        sendToParent({
+            type: "response",
+            requestId: message.requestId,
+            ok: true,
+            result: {
+                terminal: toTerminalInfo(session),
+                state: initialSnapshot.state,
+            },
+        });
+    }
+    catch (error) {
+        reportInFlightTerminalCreateFailure(error);
+    }
+    finally {
+        if (inFlightTerminalCreateRequest === request) {
+            inFlightTerminalCreateRequest = null;
+        }
+    }
+}
+async function handleRequest(message) {
+    switch (message.type) {
+        case "createTerminal": {
+            await enqueueCreateTerminalRequest(message);
+            return;
+        }
+        case "registerCwdEnv": {
+            manager.registerCwdEnv({ cwd: message.cwd, env: message.env });
+            sendToParent({ type: "response", requestId: message.requestId, ok: true });
+            return;
+        }
+        case "setActivity": {
+            await manager.setTerminalActivity(message.terminalId, message.state);
+            sendToParent({ type: "response", requestId: message.requestId, ok: true });
+            return;
+        }
+        case "clearAttention": {
+            await manager.clearTerminalAttention(message.terminalId);
+            sendToParent({ type: "response", requestId: message.requestId, ok: true });
+            return;
+        }
+        case "killTerminal": {
+            manager.killTerminal(message.terminalId);
+            // Removal is owned by session.onExit -> terminalExit; the parent mirror
+            // clears contribution and emits terminalsChanged from that single path.
+            clearTerminalSubscriptions(message.terminalId);
+            sendToParent({ type: "response", requestId: message.requestId, ok: true });
+            return;
+        }
+        case "killTerminalAndWait": {
+            await manager.killTerminalAndWait(message.terminalId, message.options);
+            clearTerminalSubscriptions(message.terminalId);
+            sendToParent({ type: "response", requestId: message.requestId, ok: true });
+            return;
+        }
+        case "getTerminalState": {
+            // Flush buffered output before snapshotting: the headless state already includes it,
+            // so if the coalescer emitted it afterward (in a batch carrying a revision past the
+            // snapshot's) the controller's revision dedup wouldn't drop it and the client would
+            // see the bytes twice. Flushing first sends them with a revision <= the snapshot's.
+            outputCoalescerByTerminalId.get(message.terminalId)?.flush();
+            sendToParent({
+                type: "response",
+                requestId: message.requestId,
+                ok: true,
+                result: buildTerminalStateResult(manager.getTerminal(message.terminalId), message.options),
+            });
+            return;
+        }
+        case "captureTerminal": {
+            const session = manager.getTerminal(message.terminalId);
+            const result = session
+                ? captureTerminalLines(session, {
+                    start: message.start,
+                    end: message.end,
+                    stripAnsi: message.stripAnsi,
+                })
+                : { lines: [], totalLines: 0 };
+            sendToParent({
+                type: "response",
+                requestId: message.requestId,
+                ok: true,
+                result,
+            });
+            return;
+        }
+        case "killAll": {
+            manager.killAll();
+            for (const terminalId of Array.from(unsubscribeByTerminalId.keys())) {
+                clearTerminalSubscriptions(terminalId);
+            }
+            sendToParent({ type: "response", requestId: message.requestId, ok: true });
+            return;
+        }
+        case "send": {
+            const session = manager.getTerminal(message.terminalId);
+            session?.send(message.message);
+            sendToParent({ type: "response", requestId: message.requestId, ok: true });
+            return;
+        }
+    }
+}
+process.on("message", (message) => {
+    void handleRequest(message).catch((error) => {
+        sendToParent({
+            type: "response",
+            requestId: message.requestId,
+            ok: false,
+            error: terminalWorkerErrorMessage(error),
+        });
+    });
+});
+process.once("disconnect", () => {
+    ipcClosing = true;
+    manager.killAll();
+});
+//# sourceMappingURL=terminal-worker-process.js.map

package/dist/server/terminal/terminal-worker-protocol.d.ts

@@ -0,0 +1,119 @@
+import type { TerminalExitInfo, ServerMessage, ClientMessage, TerminalStateSnapshot, TerminalStateSnapshotOptions } from "./terminal.js";
+import type { TerminalState } from "@hyperdrive.bot/paseo-protocol/messages";
+import type { TerminalActivity, TerminalActivityState } from "@hyperdrive.bot/paseo-protocol/terminal-activity";
+import type { CaptureTerminalLinesResult } from "./terminal-capture.js";
+export interface WorkerTerminalInfo {
+    id: string;
+    name: string;
+    cwd: string;
+    workspaceId?: string;
+    title?: string;
+    activity: TerminalActivity | null;
+}
+export interface WorkerCreateTerminalOptions {
+    id?: string;
+    cwd: string;
+    workspaceId?: string;
+    name?: string;
+    title?: string;
+    env?: Record<string, string>;
+    command?: string;
+    args?: string[];
+    activityToken?: string;
+    activityUrl?: string | null;
+}
+export interface WorkerKillAndWaitOptions {
+    gracefulTimeoutMs?: number;
+    forceTimeoutMs?: number;
+}
+export type TerminalWorkerRequest = {
+    type: "createTerminal";
+    requestId: string;
+    options: WorkerCreateTerminalOptions;
+} | {
+    type: "registerCwdEnv";
+    requestId: string;
+    cwd: string;
+    env: Record<string, string>;
+} | {
+    type: "setActivity";
+    requestId: string;
+    terminalId: string;
+    state: TerminalActivityState;
+} | {
+    type: "clearAttention";
+    requestId: string;
+    terminalId: string;
+} | {
+    type: "killTerminal";
+    requestId: string;
+    terminalId: string;
+} | {
+    type: "killTerminalAndWait";
+    requestId: string;
+    terminalId: string;
+    options?: WorkerKillAndWaitOptions;
+} | {
+    type: "getTerminalState";
+    requestId: string;
+    terminalId: string;
+    options?: TerminalStateSnapshotOptions;
+} | {
+    type: "captureTerminal";
+    requestId: string;
+    terminalId: string;
+    start?: number;
+    end?: number;
+    stripAnsi?: boolean;
+} | {
+    type: "killAll";
+    requestId: string;
+} | {
+    type: "send";
+    requestId: string;
+    terminalId: string;
+    message: ClientMessage;
+};
+export type TerminalWorkerResponse = {
+    type: "response";
+    requestId: string;
+    ok: true;
+    result?: unknown;
+} | {
+    type: "response";
+    requestId: string;
+    ok: false;
+    error: string;
+};
+export type TerminalWorkerEvent = {
+    type: "terminalCreated";
+    terminal: WorkerTerminalInfo;
+    state: TerminalState;
+} | {
+    type: "terminalMessage";
+    terminalId: string;
+    message: ServerMessage;
+} | {
+    type: "terminalExit";
+    terminalId: string;
+    info: TerminalExitInfo;
+} | {
+    type: "terminalTitleChange";
+    terminalId: string;
+    title?: string;
+} | {
+    type: "terminalCommandFinished";
+    terminalId: string;
+    info: {
+        exitCode: number | null;
+    };
+} | {
+    type: "terminalActivityChange";
+    terminalId: string;
+    activity: TerminalActivity | null;
+    previous: TerminalActivity | null;
+};
+export type TerminalWorkerToParentMessage = TerminalWorkerResponse | TerminalWorkerEvent;
+export type TerminalWorkerCaptureResult = CaptureTerminalLinesResult;
+export type TerminalWorkerStateResult = TerminalStateSnapshot | null;
+//# sourceMappingURL=terminal-worker-protocol.d.ts.map

package/dist/server/terminal/terminal-worker-protocol.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=terminal-worker-protocol.js.map

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

@@ -0,0 +1,151 @@
+import type { TerminalState } from "@hyperdrive.bot/paseo-protocol/messages";
+import type { TerminalActivity, TerminalActivityState } from "@hyperdrive.bot/paseo-protocol/terminal-activity";
+export interface TerminalExitInfo {
+    exitCode: number | null;
+    signal: number | null;
+    lastOutputLines: string[];
+}
+export interface TerminalCommandFinishedInfo {
+    exitCode: number | null;
+}
+export interface TerminalStateSnapshot {
+    state: TerminalState;
+    revision: number;
+    replayPreamble?: string;
+}
+export interface TerminalStateSnapshotOptions {
+    scrollbackLines?: number;
+    includeWrapFlags?: boolean;
+}
+export interface TerminalSubscribeOptions {
+    initialSnapshot?: "state" | "ready";
+}
+export type ClientMessage = {
+    type: "input";
+    data: string;
+} | {
+    type: "resize";
+    rows: number;
+    cols: number;
+} | {
+    type: "mouse";
+    row: number;
+    col: number;
+    button: number;
+    action: "down" | "up" | "move";
+};
+export type ServerMessage = {
+    type: "output";
+    data: string;
+    revision?: number;
+} | {
+    type: "snapshot";
+    state: TerminalState;
+    revision?: number;
+} | {
+    type: "snapshotReady";
+    revision?: number;
+    replayPreamble?: string;
+} | {
+    type: "titleChange";
+    title?: string;
+};
+export interface TerminalActivityTransition {
+    activity: TerminalActivity | null;
+    previous: TerminalActivity | null;
+}
+export interface TerminalSession {
+    id: string;
+    name: string;
+    cwd: string;
+    workspaceId: string;
+    send(msg: ClientMessage): void;
+    subscribe(listener: (msg: ServerMessage) => void, options?: TerminalSubscribeOptions): () => void;
+    onExit(listener: (info: TerminalExitInfo) => void): () => void;
+    onCommandFinished(listener: (info: TerminalCommandFinishedInfo) => void): () => void;
+    onTitleChange(listener: (title?: string) => void): () => void;
+    onActivityChange(listener: (transition: TerminalActivityTransition) => void): () => void;
+    getSize(): {
+        rows: number;
+        cols: number;
+    };
+    getState(): TerminalState;
+    getStateSnapshot(options?: TerminalStateSnapshotOptions): TerminalStateSnapshot;
+    getReplayPreamble(): string;
+    getTitle(): string | undefined;
+    getActivity(): TerminalActivity | null;
+    setActivity(state: TerminalActivityState): void;
+    clearActivityAttention(): boolean;
+    setTitle(title: string): void;
+    getExitInfo(): TerminalExitInfo | null;
+    kill(): void;
+    killAndWait(options?: {
+        gracefulTimeoutMs?: number;
+        forceTimeoutMs?: number;
+    }): Promise<void>;
+}
+export interface CreateTerminalOptions {
+    id?: string;
+    cwd: string;
+    workspaceId: string;
+    shell?: string;
+    env?: Record<string, string>;
+    activityEnv?: Record<string, string>;
+    rows?: number;
+    cols?: number;
+    name?: string;
+    title?: string;
+    command?: string;
+    args?: string[];
+}
+interface BuildTerminalEnvironmentInput {
+    shell: string;
+    env: Record<string, string>;
+    zshShellIntegrationDir?: string;
+    paseoCliBinDir?: string | null;
+    paseoHookCliPath?: string | null;
+}
+interface EnsureNodePtySpawnHelperExecutableOptions {
+    packageRoot?: string;
+    platform?: NodeJS.Platform;
+    arch?: string;
+    force?: boolean;
+}
+export declare function ensureNodePtySpawnHelperExecutableForCurrentPlatform(options?: EnsureNodePtySpawnHelperExecutableOptions): void;
+export declare function resolveDefaultTerminalShell(options?: {
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+}): string;
+export interface ResolvedTerminalCommand {
+    command: string;
+    args: string[];
+}
+export interface ResolveTerminalSpawnCommandOptions {
+    platform?: NodeJS.Platform;
+    env?: Record<string, string | undefined>;
+    resolveExecutable?: (name: string) => Promise<string | null>;
+}
+/**
+ * Resolve a terminal profile command (e.g. `claude`) into something node-pty's
+ * conpty backend can actually launch on Windows.
+ *
+ * On Windows, conpty's underlying `CreateProcess` does not apply `PATHEXT`, so a
+ * bare `claude` (installed by npm as `claude.cmd`) fails with `error code: 2`
+ * (`ERROR_FILE_NOT_FOUND`). Worse, conpty completes the spawn asynchronously on
+ * its own conout worker thread, so that failure surfaces as an uncaught
+ * exception that takes down the whole terminal worker process. Resolving the
+ * real path up front — and routing `.cmd`/`.bat` shims through `cmd.exe /c`
+ * (node-pty has no `shell` option) — keeps the profile launchable.
+ *
+ * Non-Windows and the default-shell path (no explicit command) are unchanged.
+ */
+export declare function resolveTerminalSpawnCommand(command: string, args: string[], options?: ResolveTerminalSpawnCommandOptions): Promise<ResolvedTerminalCommand>;
+export declare function resolveZshShellIntegrationDir(): string;
+export declare function resolvePaseoCliBinDir(): string | null;
+export declare function resolvePaseoCliExecutablePath(): string | null;
+export declare function buildTerminalEnvironment(input: BuildTerminalEnvironmentInput): Record<string, string>;
+export declare function normalizeProcessTitle(processTitle: string): string | undefined;
+export declare function humanizeProcessTitle(processTitle: string): string | undefined;
+export declare function createTerminal(options: CreateTerminalOptions): Promise<TerminalSession>;
+export {};
+//# sourceMappingURL=terminal.d.ts.map