@monotykamary/localterm-server 2.31.0 → 2.33.0

package/dist/index.js

@@ -17,9 +17,11 @@ import { defaultSnapshotProcesses as defaultCaffeinateSnapshotProcesses, } from
 import { CdpClient } from "./cdp/cdp-client.js";
 import { detectWithExplicitPort } from "./cdp/discover-explicit-endpoint.js";
 import { DaemonConfigStore } from "./daemon-config-store.js";
-import { AUTOMATION_EVENT_DEBOUNCE_MS, AUTOMATION_RECONCILE_MIN_DOWNTIME_MS, AUTOMATION_RUN_QUERY_PARAM, AUTOMATION_WATCH_DEBOUNCE_MS, AUTOMATION_WATCH_POST_RUN_GRACE_MS, AUTOMATION_WEBHOOK_DEBOUNCE_MS, DEFAULT_HOST, DEFAULT_PORT, FRIENDLY_HOSTNAME, GIT_MAX_REF_LENGTH, HTTP_STATUS_ACCEPTED, HTTP_STATUS_BAD_REQUEST, HTTP_STATUS_CONFLICT, HTTP_STATUS_CREATED, HTTP_STATUS_NOT_FOUND, MAX_AUTOMATIONS, MAX_PROCESSES, MAX_SECRETS, MS_PER_MINUTE, PROCESSES_FILENAME, SECRETS_FILENAME, SECRETS_SHIMS_DIRNAME, SERVER_STOP_GRACE_MS, SESSION_ID_QUERY_PARAM, WS_BACKPRESSURE_THRESHOLD_BYTES, WS_CLOSE_BACKPRESSURE, WS_CLOSE_CAPACITY_REACHED, WS_CLOSE_POLICY_VIOLATION, WS_HEARTBEAT_GRACE_MS, WS_HEARTBEAT_INTERVAL_MS, WS_HEARTBEAT_TIMEOUT_MS, WS_READY_STATE_OPEN, } from "./constants.js";
+import { z } from "zod";
+import { ACTIVITY_DIRNAME, ACTIVITY_REFRESH_DEBOUNCE_MS, ACTIVITY_WATCHED_PROGRAMS, AUTOMATION_EVENT_DEBOUNCE_MS, AUTOMATION_RECONCILE_MIN_DOWNTIME_MS, AUTOMATION_RUN_QUERY_PARAM, AUTOMATION_WATCH_DEBOUNCE_MS, AUTOMATION_WATCH_POST_RUN_GRACE_MS, AUTOMATION_WEBHOOK_DEBOUNCE_MS, DEFAULT_HOST, DEFAULT_PORT, FRIENDLY_HOSTNAME, GIT_MAX_REF_LENGTH, HTTP_STATUS_ACCEPTED, HTTP_STATUS_BAD_REQUEST, HTTP_STATUS_CONFLICT, HTTP_STATUS_CREATED, HTTP_STATUS_NOT_FOUND, MAX_AUTOMATIONS, MAX_PROCESSES, MAX_SECRETS, MS_PER_MINUTE, PROCESSES_FILENAME, SECRETS_FILENAME, SECRETS_SHIMS_DIRNAME, SERVER_STOP_GRACE_MS, SESSION_ID_QUERY_PARAM, SESSION_ACTIVITY_WINDOW_MS, WAIT_DEFAULT_TIMEOUT_MS, WS_BACKPRESSURE_THRESHOLD_BYTES, WS_CLOSE_BACKPRESSURE, WS_CLOSE_CAPACITY_REACHED, WS_CLOSE_POLICY_VIOLATION, WS_HEARTBEAT_GRACE_MS, WS_HEARTBEAT_INTERVAL_MS, WS_HEARTBEAT_TIMEOUT_MS, WS_READY_STATE_OPEN, } from "./constants.js";
 import { getDefaultShell } from "./default-shell.js";
 import { shellPathForUserShell } from "./utils/shell-path.js";
+import { openChromeInspect } from "./utils/open-chrome-inspect.js";
 import { ServerErrorException, serverError } from "./errors.js";
 import { FolderWatchManager } from "./folder-watch-manager.js";
 import { SessionEventManager } from "./session-event-manager.js";
@@ -30,12 +32,15 @@ import { createDefaultSecretBackend } from "./secret-backend.js";
 import { SecretStore } from "./secret-store.js";
 import { ProcessStore } from "./process-store.js";
 import { regenerateShims } from "./secret-shims.js";
+import { ProcessActivityWatcher } from "./process-activity-watcher.js";
 import { parseCronExpression } from "./cron-expression.js";
 import { createGitWorktree, listGitWorktrees, removeGitWorktree } from "./git-worktrees.js";
 import { defaultSnapshotListeners, isSessionDescendantPid, listSessionListeningPorts, } from "./listening-ports.js";
-import { clientToServerMessageSchema, createAutomationInputSchema, createSessionInputSchema, createWorktreeInputSchema, execInputSchema, execOneShotInputSchema, launchInputSchema, resetAutomationInputSchema, secretEntrySchema, secretSetInputSchema, sessionInputSchema, sessionResizeSchema, processNameSchema, processSetInputSchema, updateAutomationInputSchema, updateDaemonConfigInputSchema, updateSessionInputSchema, updateWorktreeConfigInputSchema, worktreeIncludeFileInputSchema, } from "./schemas.js";
+import { clientToServerMessageSchema, createAutomationInputSchema, createSessionInputSchema, createWorktreeInputSchema, execInputSchema, execOneShotInputSchema, launchInputSchema, resetAutomationInputSchema, secretEntrySchema, secretSetInputSchema, sessionInputSchema, sessionResizeSchema, processNameSchema, processSetInputSchema, updateAutomationInputSchema, updateDaemonConfigInputSchema, updateSessionInputSchema, updateWorktreeConfigInputSchema, worktreeIncludeFileInputSchema, waitInputSchema, mouseInputSchema, } from "./schemas.js";
 import { createNetworkPolicyMiddleware, isAllowedSourceIp, isLoopbackHost } from "./security.js";
 import { SessionManager, } from "./session-manager.js";
+import { capturePanePng, sendMouse } from "./session-automation.js";
+import { encodeClick, encodeDrag, encodeMove, encodeScroll } from "./utils/sgr-mouse.js";
 import { getBufferedAmount } from "./utils/ws-socket.js";
 import { resolveStaticAsset } from "./static-resolver.js";
 import { resolveImageAsset } from "./utils/resolve-image-asset.js";
@@ -103,9 +108,86 @@ const safeSend = (ws, payload) => {
         /* socket closed between readyState check and send */
     }
 };
+// Build the predicate the session manager polls against the flushed capture
+// renderer. Text matches substring (case-insensitive by default); regex compiles
+// (a bad pattern yields invalid_body); idle returns a no-op test since the
+// manager resolves it from output recency, not the pane text.
+const buildWaitPredicate = (input) => {
+    if (input.mode === "text") {
+        const needle = input.text;
+        const caseSensitive = input.caseSensitive ?? false;
+        return {
+            kind: "text",
+            test: caseSensitive
+                ? (text) => text.includes(needle)
+                : (text) => text.toLowerCase().includes(needle.toLowerCase()),
+        };
+    }
+    if (input.mode === "regex") {
+        let pattern;
+        try {
+            pattern = new RegExp(input.regex);
+        }
+        catch {
+            return null;
+        }
+        return { kind: "regex", test: (text) => pattern.test(text) };
+    }
+    return { kind: "idle", test: () => false };
+};
+// Normalize the parsed mouse schema into the MouseAction union the automation
+// layer consumes, applying defaults (left button, 1 click, 3 scroll lines).
+const normalizeMouseAction = (input) => {
+    if (input.action === "click") {
+        const button = input.button ?? "left";
+        const clicks = input.clicks ?? 1;
+        if (input.onText !== undefined)
+            return { action: "click", onText: input.onText, button, clicks };
+        if (input.col !== undefined && input.row !== undefined)
+            return { action: "click", col: input.col, row: input.row, button, clicks };
+        return null;
+    }
+    if (input.action === "drag")
+        return {
+            action: "drag",
+            fromCol: input.fromCol,
+            fromRow: input.fromRow,
+            toCol: input.toCol,
+            toRow: input.toRow,
+            button: input.button ?? "left",
+        };
+    if (input.action === "move")
+        return { action: "move", col: input.col, row: input.row };
+    return {
+        action: "scroll",
+        direction: input.direction,
+        amount: input.amount ?? 3,
+        col: input.col ?? 0,
+        row: input.row ?? 0,
+    };
+};
 const buildApiRoutes = (ctx) => {
     const api = new Hono();
-    const { registry, cdpClient, secretBackend, secretStore, shimsDir, processStore, syncSecretShims, automationStore, broadcastAutomations, syncFolderWatchers, syncSessionEventListeners, webhookTriggerManager, worktreeConfigStore, portsSnapshotProcesses, portsSnapshotListeners, toAutomationWithNextRun, listAutomationsWithNextRun, tryLaunch, getCdpPort, applyCdpPort, getGraceSeconds, applyGraceSeconds, connectCdpNow, } = ctx;
+    const { registry, cdpClient, secretBackend, secretStore, shimsDir, processStore, syncSecretShims, automationStore, broadcastAutomations, syncFolderWatchers, syncSessionEventListeners, webhookTriggerManager, worktreeConfigStore, portsSnapshotProcesses, portsSnapshotListeners, toAutomationWithNextRun, listAutomationsWithNextRun, tryLaunch, getCdpPort, applyCdpPort, getGraceSeconds, applyGraceSeconds, connectCdpNow, buildTabUrl, } = ctx;
+    // Headless SGR-1006 fallback for `mouse` when no CDP tab is reachable:
+    // encode the gesture as SGR bytes and write them straight to the PTY. Closes
+    // over `registry` so the automation layer stays CDP-agnostic. Coords arrive
+    // 0-indexed (viewport cells); SGR is 1-indexed.
+    const writeSgrMouseFallback = (id, action, col, row) => {
+        const c = col + 1;
+        const r = row + 1;
+        const button = action.action === "click" || action.action === "drag" ? action.button : "left";
+        let bytes;
+        if (action.action === "click")
+            bytes = encodeClick(c, r, button, action.clicks);
+        else if (action.action === "drag")
+            bytes = encodeDrag(action.fromCol + 1, action.fromRow + 1, action.toCol + 1, action.toRow + 1, button);
+        else if (action.action === "move")
+            bytes = encodeMove(c, r);
+        else
+            bytes = encodeScroll(c, r, action.direction, action.amount);
+        return registry.writeInputById(id, bytes);
+    };
     api.get("/health", (context) => context.json({
         ok: true,
         sessions: registry.size(),
@@ -186,15 +268,19 @@ const buildApiRoutes = (ctx) => {
             return context.json({ error: "not_found" }, HTTP_STATUS_NOT_FOUND);
         return context.json({ session });
     });
-    // send-keys: write raw input to a session by id. Bytes go straight to the
-    // PTY (no pending handshake — there's no WebSocket client). To execute a
+    // send-keys / press: write input to a session by id. Bytes go straight to
+    // the PTY (no pending handshake — there's no WebSocket client). To execute a
     // command, include a trailing newline; for a blocking command+output+exit
-    // in one call, use `exec` instead.
+    // in one call, use `exec` instead. `named:true` resolves space-separated key
+    // names (`F2`, `Ctrl-C`, literal text) to xterm bytes — the `press` path.
     api.post("/sessions/:id/input", async (context) => {
         const parsed = sessionInputSchema.safeParse(await readJsonBody(context));
         if (!parsed.success)
             return context.json({ error: "invalid_body" }, HTTP_STATUS_BAD_REQUEST);
-        const written = registry.writeInputById(context.req.param("id"), parsed.data.data);
+        const id = context.req.param("id");
+        const written = parsed.data.named
+            ? registry.pressKeysById(id, parsed.data.data)
+            : registry.writeInputById(id, parsed.data.data);
         if (!written)
             return context.json({ error: "not_found" }, HTTP_STATUS_NOT_FOUND);
         return context.json({ ok: true });
@@ -208,20 +294,76 @@ const buildApiRoutes = (ctx) => {
             return context.json({ error: "not_found" }, HTTP_STATUS_NOT_FOUND);
         return context.json({ ok: true });
     });
-    // capture-pane: the session's rendered screen as clean text (ANSI processed by
-    // the headless emulator). `lines` defaults to the viewport and may extend into
-    // scrollback. Returns the tmux `capture-pane -p` equivalent.
+    // capture-pane: the session's rendered screen. `format=png` returns the
+    // terminal rasterized to a PNG by the browser over the daemon's existing
+    // CDP socket (the viewer is reused, or an ephemeral background tab is
+    // opened and closed) — no new image dependency. Text (the default) is the
+    // headless capture renderer's grid, which works with no browser at all.
     api.get("/sessions/:id/pane", async (context) => {
+        const id = context.req.param("id");
+        const format = context.req.query("format");
+        if (format === "png") {
+            const png = await capturePanePng({ cdpClient, buildTabUrl }, registry, id);
+            if (!png)
+                return context.json({ error: "no_browser" }, HTTP_STATUS_CONFLICT);
+            return new Response(png, { headers: { "content-type": "image/png" } });
+        }
         const linesParam = context.req.query("lines");
         const lines = linesParam ? Number(linesParam) : undefined;
         if (lines !== undefined && (!Number.isInteger(lines) || lines <= 0)) {
             return context.json({ error: "invalid_lines" }, HTTP_STATUS_BAD_REQUEST);
         }
-        const text = await registry.capturePane(context.req.param("id"), lines);
+        const text = await registry.capturePane(id, lines);
         if (text === null)
             return context.json({ error: "not_found" }, HTTP_STATUS_NOT_FOUND);
         return context.json({ text });
     });
+    // wait: block until the session's rendered pane matches a text/regex
+    // predicate or goes idle for a window. The blocking `wait` primitive for
+    // interactive apps so an agent doesn't poll. Reuses the capture renderer as
+    // the source of truth (flushed per frame). Exits on match, timeout, or exit.
+    api.post("/sessions/:id/wait", async (context) => {
+        const parsed = waitInputSchema.safeParse(await readJsonBody(context));
+        if (!parsed.success)
+            return context.json({ error: "invalid_body" }, HTTP_STATUS_BAD_REQUEST);
+        const id = context.req.param("id");
+        const timeoutMs = parsed.data.timeoutMs ?? WAIT_DEFAULT_TIMEOUT_MS;
+        const predicate = buildWaitPredicate(parsed.data);
+        if (!predicate)
+            return context.json({ error: "invalid_body" }, HTTP_STATUS_BAD_REQUEST);
+        const idleMs = parsed.data.mode === "idle" ? (parsed.data.idleMs ?? SESSION_ACTIVITY_WINDOW_MS) : undefined;
+        const result = await registry.waitFor(id, predicate, timeoutMs, idleMs);
+        if (!result)
+            return context.json({ error: "not_found" }, HTTP_STATUS_NOT_FOUND);
+        return context.json(result);
+    });
+    // mouse: drive a TUI with the mouse. Dispatches a real event through the
+    // tab's xterm.js (SGR generated natively) over the existing CDP socket, or
+    // falls back to direct SGR-1006 bytes when no browser is reachable.
+    api.post("/sessions/:id/mouse", async (context) => {
+        const parsed = mouseInputSchema.safeParse(await readJsonBody(context));
+        if (!parsed.success)
+            return context.json({ error: "invalid_body" }, HTTP_STATUS_BAD_REQUEST);
+        const id = context.req.param("id");
+        const action = normalizeMouseAction(parsed.data);
+        if (!action)
+            return context.json({ error: "invalid_body" }, HTTP_STATUS_BAD_REQUEST);
+        const result = await sendMouse({ cdpClient, buildTabUrl }, registry, id, action, writeSgrMouseFallback);
+        return context.json(result);
+    });
+    // mouse state: whether the session's foreground app enabled mouse tracking
+    // (gates the SGR fallback) plus the viewport size.
+    api.get("/sessions/:id/mouse/state", (context) => {
+        const id = context.req.param("id");
+        const managed = registry.list().find((session) => session.id === id);
+        if (!managed)
+            return context.json({ error: "not_found" }, HTTP_STATUS_NOT_FOUND);
+        return context.json({
+            enabled: registry.mouseEnabledFor(id),
+            cols: registry.sessionSizeFor(id).cols,
+            rows: registry.sessionSizeFor(id).rows,
+        });
+    });
     // In-session exec: run a single command line inside a persistent session,
     // capture its rendered output, and return its exit code. The session's
     // cwd/env/history survive across calls (the tmux send-keys+capture-pane
@@ -885,6 +1027,16 @@ const buildApiRoutes = (ctx) => {
     // or the error that explains a failure), unlike the fire-and-forget connect
     // kicked by `PUT /api/config` and daemon start.
     api.post("/cdp/connect", async (context) => context.json(await connectCdpNow()));
+    // Open chrome://inspect in the user's browser. This is the bootstrap path
+    // for users who haven't enabled remote debugging yet — they open the inspect
+    // page to toggle "Discover network targets" — so it must NOT go through CDP
+    // (CDP isn't available to those users). chrome:// URLs can't be navigated to
+    // from a web page, so the daemon opens it (AppleScript `open location` on
+    // macOS to reuse the running profile; OS opener elsewhere).
+    api.post("/cdp/open-inspect", async (context) => {
+        await openChromeInspect();
+        return context.json({ ok: true });
+    });
     // Fire a webhook-triggered automation. The :id is the automation's webhook
     // capability token (Discord-style: anyone with the URL can fire it). The body
     // is intentionally ignored — the command/cwd are fixed at create time, so a
@@ -1016,8 +1168,39 @@ export const createServer = async (options = {}) => {
         shimsDir,
     });
     const processStore = new ProcessStore(path.join(stateDirectory, PROCESSES_FILENAME));
-    const syncSecretShims = () => regenerateShims(processStore.list(), secretStore.envVarByName(), shimsDir, secretBackend);
+    const activityDir = path.join(stateDirectory, ACTIVITY_DIRNAME);
+    const syncSecretShims = () => regenerateShims(processStore.list(), secretStore.envVarByName(), shimsDir, secretBackend, activityDir);
     syncSecretShims();
+    // Detect short-lived CLI invocations the process-tree walker can't catch
+    // (they exit before a `ps` snapshot observes them). Each activity-watched
+    // program's PATH shim overwrites <activityDir>/<program> with $PWD after the
+    // real binary exits; this watcher reacts via fs.watch (no polling). The
+    // built-in set starts with `gh` so running it in a viewed repo refreshes the
+    // PR lease for that cwd without the user manually refreshing — the same role
+    // the working-tree git-dirty signal plays for the diff summary. Gated on
+    // the secret backend because the activity shim is only generated where the
+    // shim feature is supported (darwin); elsewhere there is nothing to watch.
+    let processActivityWatcher = null;
+    if (secretBackend.supported && ACTIVITY_WATCHED_PROGRAMS.length > 0) {
+        processActivityWatcher = new ProcessActivityWatcher({
+            activityDir,
+            programs: ACTIVITY_WATCHED_PROGRAMS,
+            debounceMs: ACTIVITY_REFRESH_DEBOUNCE_MS,
+        });
+        processActivityWatcher.on("activity", (program, cwd) => {
+            if (program !== "gh")
+                return;
+            // No subscribers in this cwd → no toolbar to update, so skip the GitHub
+            // call. getGitBranchPr's own per-(cwd, branch) in-flight dedup handles
+            // any overlap with a concurrent manual refresh.
+            if (!registry.hasCoordinatorFor(cwd))
+                return;
+            void (async () => {
+                const pr = await getGitBranchPr(cwd);
+                registry.broadcastGitBranchPr(cwd, pr);
+            })();
+        });
+    }
     const caffeinateManager = new CaffeinateManager({
         controller: caffeinateController,
         store: caffeinatePreferencesStore,
@@ -1353,6 +1536,11 @@ export const createServer = async (options = {}) => {
         getGraceSeconds,
         applyGraceSeconds,
         connectCdpNow,
+        buildTabUrl: (sessionId) => {
+            const url = new URL(localOrigin ?? publicOrigin ?? `http://${FRIENDLY_HOSTNAME}:${actualPort}`);
+            url.searchParams.set(SESSION_ID_QUERY_PARAM, sessionId);
+            return url.toString();
+        },
     };
     const api = buildApiRoutes(ctx);
     app.route("/api", api);
@@ -1730,6 +1918,7 @@ export const createServer = async (options = {}) => {
         folderWatchManager.dispose();
         webhookTriggerManager.dispose();
         caffeinateManager.dispose();
+        processActivityWatcher?.dispose();
         cdpClient?.close();
         registry.disposeAll();
         // Forcibly tear down every WS first. node-pty + ws upgraded sockets