@getpaseo/server 0.1.96 → 0.1.97-beta.2

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

@@ -1,4 +1,5 @@
 import type { TerminalState } from "@getpaseo/protocol/messages";
+import type { TerminalActivity, TerminalActivityState } from "@getpaseo/protocol/terminal-activity";
 export interface TerminalExitInfo {
     exitCode: number | null;
     signal: number | null;
@@ -10,6 +11,7 @@ export interface TerminalCommandFinishedInfo {
 export interface TerminalStateSnapshot {
     state: TerminalState;
     revision: number;
+    replayPreamble?: string;
 }
 export interface TerminalStateSnapshotOptions {
     scrollbackLines?: number;
@@ -43,19 +45,26 @@ export type ServerMessage = {
 } | {
     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;
@@ -64,6 +73,9 @@ export interface TerminalSession {
     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;
@@ -75,8 +87,10 @@ export interface TerminalSession {
 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;
@@ -88,6 +102,8 @@ interface BuildTerminalEnvironmentInput {
     shell: string;
     env: Record<string, string>;
     zshShellIntegrationDir?: string;
+    paseoCliBinDir?: string | null;
+    paseoHookCliPath?: string | null;
 }
 interface EnsureNodePtySpawnHelperExecutableOptions {
     packageRoot?: string;
@@ -100,7 +116,33 @@ 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;

package/dist/server/terminal/terminal.js

@@ -3,14 +3,17 @@ import xterm from "@xterm/headless";
 import { randomUUID } from "crypto";
 import { chmodSync, existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { tmpdir, userInfo } from "node:os";
-import { basename, dirname, join } from "node:path";
+import { basename, delimiter, dirname, extname, join, resolve as resolvePath } from "node:path";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { createExternalProcessEnv } from "../server/paseo-env.js";
 import { writePrivateFileAtomicSync } from "../server/private-files.js";
+import { findExecutable } from "../executable-resolution/executable-resolution.js";
 import { TerminalInputModeTracker } from "@getpaseo/protocol/terminal-input-mode";
+import { TerminalActivityTracker } from "./activity/terminal-activity-tracker.js";
 const { Terminal } = xterm;
 const require = createRequire(import.meta.url);
+const PASEO_CLI_BIN_ENTRY = "@getpaseo/cli/bin/paseo";
 let nodePtySpawnHelperChecked = false;
 const TERMINAL_TITLE_DEBOUNCE_MS = 150;
 const TERMINAL_EXIT_OUTPUT_LINE_LIMIT = 12;
@@ -36,6 +39,19 @@ function parseCommandFinishedOsc(data) {
     }
     return { exitCode: Number(parts[1]) };
 }
+function toTerminalActivity(snapshot) {
+    if (!snapshot.state) {
+        return null;
+    }
+    return {
+        state: snapshot.state,
+        ...(snapshot.attentionReason ? { attentionReason: snapshot.attentionReason } : {}),
+        changedAt: snapshot.changedAt,
+    };
+}
+function resolveInitialTitleMode(presetTitle) {
+    return presetTitle?.trim() ? "manual" : "auto";
+}
 function resolveNodePtyPackageRoot() {
     try {
         const packageJsonPath = require.resolve("node-pty/package.json");
@@ -97,11 +113,110 @@ export function resolveDefaultTerminalShell(options = {}) {
     }
     return env.SHELL || "/bin/sh";
 }
+/**
+ * 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 async function resolveTerminalSpawnCommand(command, args, options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform !== "win32") {
+        return { command, args };
+    }
+    const resolveExecutable = options.resolveExecutable ?? findExecutable;
+    const resolved = await resolveExecutable(command);
+    if (!resolved) {
+        // Leave the command as-is so the terminal itself surfaces the "not found"
+        // error to the user instead of silently doing nothing.
+        return { command, args };
+    }
+    // `.cmd`/`.bat` shims are batch scripts that conpty's CreateProcess cannot
+    // launch directly; they must run through cmd.exe (node-pty has no `shell`
+    // option, so build the `cmd /c` invocation ourselves). Checked by extension
+    // rather than isWindowsCommandScript() because that helper gates on the live
+    // process.platform, which is wrong once we're already on the win32 branch.
+    const extension = extname(resolved).toLowerCase();
+    if (extension === ".cmd" || extension === ".bat") {
+        const env = options.env ?? process.env;
+        const comSpec = env.ComSpec || env.COMSPEC || "C:\\Windows\\System32\\cmd.exe";
+        return { command: comSpec, args: ["/c", resolved, ...args] };
+    }
+    return { command: resolved, args };
+}
 export function resolveZshShellIntegrationDir() {
     return fileURLToPath(new URL("./shell-integration/zsh", import.meta.url));
 }
 function resolveExternalProcessPath(filePath) {
-    return filePath.replace(/\.asar(?=\/|$)/, ".asar.unpacked");
+    return filePath.replace(/\.asar(?=[/\\]|$)/, ".asar.unpacked");
+}
+export function resolvePaseoCliBinDir() {
+    const cliEntrypoint = resolvePaseoCliBinEntrypoint();
+    if (!cliEntrypoint) {
+        return null;
+    }
+    const externalCliEntrypoint = resolveExternalProcessPath(cliEntrypoint);
+    return findNpmBinDir(dirname(externalCliEntrypoint)) ?? dirname(externalCliEntrypoint);
+}
+export function resolvePaseoCliExecutablePath() {
+    const cliEntrypoint = resolvePaseoCliBinEntrypoint();
+    if (!cliEntrypoint) {
+        return null;
+    }
+    const externalCliEntrypoint = resolveExternalProcessPath(cliEntrypoint);
+    const npmBinDir = findNpmBinDir(dirname(externalCliEntrypoint));
+    if (npmBinDir) {
+        const shim = resolvePaseoCliShim(npmBinDir);
+        if (shim) {
+            return shim;
+        }
+    }
+    return externalCliEntrypoint;
+}
+function resolvePaseoCliBinEntrypoint() {
+    try {
+        return require.resolve(PASEO_CLI_BIN_ENTRY);
+    }
+    catch {
+        return null;
+    }
+}
+function findNpmBinDir(startPath) {
+    let current = startPath;
+    while (true) {
+        const candidate = join(current, "node_modules", ".bin");
+        if (hasPaseoCliShim(candidate)) {
+            return candidate;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+}
+function hasPaseoCliShim(binDir) {
+    return resolvePaseoCliShim(binDir) !== null;
+}
+function resolvePaseoCliShim(binDir) {
+    for (const name of paseoCliShimNames()) {
+        const candidate = join(binDir, name);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function paseoCliShimNames() {
+    return process.platform === "win32" ? ["paseo.cmd", "paseo.exe", "paseo"] : ["paseo"];
 }
 function resolveZshShellIntegrationRuntimeDir() {
     let username = "unknown";
@@ -127,16 +242,45 @@ export function buildTerminalEnvironment(input) {
         TERM: "xterm-256color",
         TERM_PROGRAM: "kitty",
     });
+    const envWithAgentHooks = prependPaseoCliToPath(baseEnv, input.paseoCliBinDir === undefined ? resolvePaseoCliBinDir() : input.paseoCliBinDir);
+    const envWithHookCli = injectPaseoHookCli(envWithAgentHooks, input.paseoHookCliPath === undefined ? resolvePaseoCliExecutablePath() : input.paseoHookCliPath);
     if (basename(input.shell) !== "zsh") {
-        return baseEnv;
+        return envWithHookCli;
     }
-    const originalZdotdir = baseEnv.ZDOTDIR ?? "";
+    const originalZdotdir = envWithHookCli.ZDOTDIR ?? "";
     return {
-        ...baseEnv,
+        ...envWithHookCli,
         PASEO_ZSH_ZDOTDIR: originalZdotdir,
         ZDOTDIR: prepareZshShellIntegrationRuntimeDir(input.zshShellIntegrationDir),
     };
 }
+function injectPaseoHookCli(env, cliPath) {
+    if (!cliPath) {
+        return env;
+    }
+    return {
+        ...env,
+        PASEO_HOOK_CLI: resolvePath(resolveExternalProcessPath(cliPath)),
+    };
+}
+function prependPaseoCliToPath(env, cliBinDir) {
+    if (!cliBinDir) {
+        return env;
+    }
+    const pathKey = getPathEnvKey(env);
+    const currentPath = env[pathKey] ?? "";
+    return {
+        ...env,
+        [pathKey]: prependPathEntry(currentPath, cliBinDir),
+    };
+}
+function getPathEnvKey(env) {
+    return Object.keys(env).find((key) => key.toLowerCase() === "path") ?? "PATH";
+}
+function prependPathEntry(currentPath, entry) {
+    const entries = currentPath.split(delimiter).filter((value) => value && value !== entry);
+    return [entry, ...entries].join(delimiter);
+}
 function extractCell(terminal, row, col) {
     const buffer = terminal.buffer.active;
     const line = buffer.getLine(row);
@@ -411,7 +555,7 @@ function extractLastOutputLinesFromText(text, limit) {
     return lines.slice(-limit);
 }
 export async function createTerminal(options) {
-    const { cwd, shell, env = {}, rows = 24, cols = 80, name = "Terminal", title: presetTitle, command, args = [], } = options;
+    const { cwd, workspaceId, shell, env = {}, activityEnv = {}, rows = 24, cols = 80, name = "Terminal", title: presetTitle, command, args = [], } = options;
     const resolvedShell = shell ?? resolveDefaultTerminalShell();
     const id = options.id ?? randomUUID();
     const listeners = new Set();
@@ -424,15 +568,22 @@ export async function createTerminal(options) {
     let processExited = false;
     const processExitWaiters = new Set();
     let exitInfo = null;
-    let recentOutputText = "";
+    // Recent output is retained as whole chunks plus a running char length so we
+    // avoid reallocating a ~16KB string on every pty chunk. We keep enough whole
+    // chunks that their join always contains at least the last
+    // TERMINAL_EXIT_OUTPUT_CHAR_LIMIT chars; the exact tail is sliced at exit.
+    const recentOutputChunks = [];
+    let recentOutputLength = 0;
     let title;
-    let titleMode = presetTitle?.trim() ? "manual" : "auto";
+    let titleMode = resolveInitialTitleMode(presetTitle);
     let pendingTitle;
     let titleDebounceTimer = null;
     let pendingInput = "";
     let inputFlushImmediate = null;
     let stateRevision = 0;
     const inputModeTracker = new TerminalInputModeTracker();
+    const activityTracker = new TerminalActivityTracker();
+    const activityChangeListeners = new Set();
     let titleChangeSubscription = null;
     // Create xterm.js headless terminal
     const terminal = new Terminal({
@@ -443,14 +594,22 @@ export async function createTerminal(options) {
     });
     ensureNodePtySpawnHelperExecutableForCurrentPlatform();
     // Create PTY
-    const spawnCommand = command ?? resolvedShell;
-    const spawnArgs = command ? args : [];
+    const { command: spawnCommand, args: spawnArgs } = command
+        ? await resolveTerminalSpawnCommand(command, args)
+        : { command: resolvedShell, args: [] };
     const ptyProcess = pty.spawn(spawnCommand, spawnArgs, {
         name: "xterm-256color",
         cols,
         rows,
         cwd,
-        env: buildTerminalEnvironment({ shell: spawnCommand, env }),
+        env: buildTerminalEnvironment({
+            shell: spawnCommand,
+            env: {
+                ...env,
+                ...activityEnv,
+                PASEO_WORKSPACE_ID: workspaceId,
+            },
+        }),
     });
     function emitTitleChange(nextTitle) {
         if (title === nextTitle) {
@@ -573,6 +732,23 @@ export async function createTerminal(options) {
         }
         return true;
     });
+    activityTracker.onChange((snapshot, previousSnapshot) => {
+        if (disposed || killed) {
+            return;
+        }
+        const transition = {
+            activity: toTerminalActivity(snapshot),
+            previous: toTerminalActivity(previousSnapshot),
+        };
+        for (const listener of Array.from(activityChangeListeners)) {
+            try {
+                listener(transition);
+            }
+            catch {
+                // no-op
+            }
+        }
+    });
     function buildExitInfo(input) {
         const lastOutputLines = extractLastOutputLines(terminal, TERMINAL_EXIT_OUTPUT_LINE_LIMIT);
         return {
@@ -580,7 +756,7 @@ export async function createTerminal(options) {
             signal: input?.signal && input.signal > 0 ? input.signal : null,
             lastOutputLines: lastOutputLines.length > 0
                 ? lastOutputLines
-                : extractLastOutputLinesFromText(recentOutputText, TERMINAL_EXIT_OUTPUT_LINE_LIMIT),
+                : extractLastOutputLinesFromText(recentOutputChunks.join("").slice(-TERMINAL_EXIT_OUTPUT_CHAR_LIMIT), TERMINAL_EXIT_OUTPUT_LINE_LIMIT),
         };
     }
     function emitExit(info) {
@@ -604,7 +780,10 @@ export async function createTerminal(options) {
             return;
         }
         disposed = true;
+        activityTracker.clear();
         pendingInput = "";
+        recentOutputChunks.length = 0;
+        recentOutputLength = 0;
         inputModeTracker.reset();
         if (inputFlushImmediate) {
             clearImmediate(inputFlushImmediate);
@@ -613,11 +792,13 @@ export async function createTerminal(options) {
         clearPendingTitleChange();
         disposeTitleChangeSubscription();
         disposeCommandLifecycleSubscription.dispose();
+        activityTracker.dispose();
         terminal.dispose();
         listeners.clear();
         exitListeners.clear();
         commandFinishedListeners.clear();
         titleChangeListeners.clear();
+        activityChangeListeners.clear();
     }
     function writeOutputToHeadless(data) {
         terminal.write(data, () => {
@@ -638,9 +819,21 @@ export async function createTerminal(options) {
         for (const response of inputModeUpdate.responses) {
             ptyProcess.write(response);
         }
-        recentOutputText = `${recentOutputText}${data}`;
-        if (recentOutputText.length > TERMINAL_EXIT_OUTPUT_CHAR_LIMIT) {
-            recentOutputText = recentOutputText.slice(-TERMINAL_EXIT_OUTPUT_CHAR_LIMIT);
+        recentOutputChunks.push(data);
+        recentOutputLength += data.length;
+        // Drop whole leading chunks while the rest still covers the char limit, so
+        // the retained join always contains at least the last limit chars.
+        while (recentOutputChunks.length > 1 &&
+            recentOutputLength - recentOutputChunks[0].length >= TERMINAL_EXIT_OUTPUT_CHAR_LIMIT) {
+            recentOutputLength -= recentOutputChunks[0].length;
+            recentOutputChunks.shift();
+        }
+        // We never drop the last chunk, so a single chunk larger than the cap would
+        // grow the buffer unbounded; slice its tail to keep the cap hard.
+        if (recentOutputChunks.length === 1 && recentOutputLength > TERMINAL_EXIT_OUTPUT_CHAR_LIMIT) {
+            const tail = recentOutputChunks[0].slice(-TERMINAL_EXIT_OUTPUT_CHAR_LIMIT);
+            recentOutputChunks[0] = tail;
+            recentOutputLength = tail.length;
         }
         writeOutputToHeadless(data);
     });
@@ -775,7 +968,13 @@ export async function createTerminal(options) {
             if (!disposed && active && listeners.has(subscriptionListener)) {
                 snapshotDelivered = true;
                 if (initialSnapshot === "ready") {
-                    listener({ type: "snapshotReady", revision: stateRevision });
+                    // Carry the input-mode preamble so the snapshot-less "ready" path
+                    // (live restore) can replay it without a separate state fetch.
+                    listener({
+                        type: "snapshotReady",
+                        revision: stateRevision,
+                        replayPreamble: getReplayPreamble(),
+                    });
                 }
                 else {
                     listener({ type: "snapshot", ...getStateSnapshot() });
@@ -833,9 +1032,24 @@ export async function createTerminal(options) {
             titleChangeListeners.delete(listener);
         };
     }
+    function onActivityChange(listener) {
+        activityChangeListeners.add(listener);
+        return () => {
+            activityChangeListeners.delete(listener);
+        };
+    }
     function getTitle() {
         return title;
     }
+    function getActivity() {
+        return toTerminalActivity(activityTracker.getSnapshot());
+    }
+    function setActivity(state) {
+        activityTracker.set(state);
+    }
+    function clearActivityAttention() {
+        return activityTracker.clearAttention();
+    }
     function getExitInfo() {
         return exitInfo;
     }
@@ -917,16 +1131,21 @@ export async function createTerminal(options) {
         id,
         name,
         cwd,
+        workspaceId,
         send,
         subscribe,
         onExit,
         onCommandFinished,
         onTitleChange,
+        onActivityChange,
         getSize,
         getState,
         getStateSnapshot,
         getReplayPreamble,
         getTitle,
+        getActivity,
+        setActivity,
+        clearActivityAttention,
         setTitle,
         getExitInfo,
         kill,

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

@@ -12,6 +12,7 @@ interface TerminalWorkerProcess {
 interface WorkerTerminalManagerOptions {
     requestTimeoutMs?: number;
     forkWorker?: () => TerminalWorkerProcess;
+    getTerminalActivityUrl?: () => string | null;
 }
 export declare function createWorkerTerminalManager(managerOptions?: WorkerTerminalManagerOptions): TerminalManager;
 export declare function terminateWorkerTerminalManager(manager: TerminalManager): void;