@prohost/cli 0.13.2 → 0.14.0

package/dist/codehost/local_server.js

@@ -0,0 +1,339 @@
+/**
+ * The desktop app's fast path to this machine's Code-thread terminals.
+ *
+ * The ProhostAI desktop app runs this CLI with its own `$PROHOST_HOME`, so it
+ * can read `code-host/local.json` and attach over loopback instead of a round
+ * trip through the relay. Served whenever this Mac hosts Code threads, with the
+ * remote switch on or off — the desktop app on this Mac is how its owner opens
+ * the terminals here at all. What the switch decides is which attaches it
+ * admits:
+ *
+ * - **Remote on:** any attach whose viewer token the relay vouches for.
+ * - **Remote off:** only one the relay vouches for as `local: true` — a token
+ *   minted for this Mac's own desktop app (`loc`), which the relay refuses for
+ *   any relayed attach. A verdict without `local` (an older server) is not
+ *   local. Turning the switch off ends every viewer admitted as remote.
+ *
+ * Who can connect:
+ *
+ * - **Loopback only** (`127.0.0.1`, ephemeral port), and the `Host` header must
+ *   name it — a DNS-rebinding page can't pass for it.
+ * - **Never a browser:** any request carrying an `Origin` header is refused.
+ *   Browsers always send one on a WebSocket handshake; Electron's main
+ *   process (Node's WebSocket) sends none.
+ * - **The token in `local.json`** (0600, owner-only, new every start), in the
+ *   first frame, compared in constant time.
+ *
+ * After `ready` it speaks the relay's viewer protocol: binary frames both
+ * ways, `{"type":"input"}`, `{"type":"resize"}`, ping/pong, and who sizes the
+ * window (`{"type":"hello"}` / `{"type":"claim"}` in, `{"type":"sizer"}` out to
+ * a viewer that said hello; `sizing.ts`).
+ */
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { rmSync } from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import WebSocket, { WebSocketServer } from 'ws';
+import { pipeStream } from './relay.js';
+import { codeHostDir, writePrivateJson } from './settings.js';
+import { clampDim, DEFAULT_COLS, DEFAULT_ROWS, isValidId, parseControl, TERMINAL_WINDOWS } from './tmux.js';
+export const LOCAL_TERMINAL_PATH = '/code-host/terminal';
+export const LOCAL_TERMINALS_PATH = '/code-host/terminals';
+const AUTH_TIMEOUT_MS = 10_000;
+const PING_INTERVAL_MS = 30_000;
+const PONG_TIMEOUT_MS = 60_000;
+const STOP_GRACE_MS = 1_000;
+async function closeServer(server) {
+    const closed = new Promise((resolve) => server.close(() => resolve()));
+    // Upgraded sockets must not hold the daemon's shutdown open.
+    server.closeAllConnections();
+    await Promise.race([closed, new Promise((resolve) => setTimeout(resolve, STOP_GRACE_MS).unref?.())]);
+}
+export function localConfigPath(env = process.env) {
+    return path.join(codeHostDir(env), 'local.json');
+}
+export function tokensMatch(expected, given) {
+    if (typeof given !== 'string' || !given || !expected)
+        return false;
+    const a = Buffer.from(expected, 'utf8');
+    const b = Buffer.from(given, 'utf8');
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/** Why a handshake must be refused, or `undefined` to accept it. */
+export function refuseHandshake(headers, url, port) {
+    if (headers.origin !== undefined)
+        return { status: 403, reason: 'origin_not_allowed' };
+    const host = headers.host;
+    if (host !== `127.0.0.1:${port}` && host !== `localhost:${port}`)
+        return { status: 403, reason: 'bad_host' };
+    let pathname;
+    try {
+        pathname = new URL(url ?? '/', 'http://127.0.0.1').pathname;
+    }
+    catch {
+        return { status: 400, reason: 'bad_url' };
+    }
+    if (pathname !== LOCAL_TERMINAL_PATH)
+        return { status: 404, reason: 'not_found' };
+    return undefined;
+}
+export function parseLocalAuth(text, token) {
+    let frame;
+    try {
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== 'object')
+            return { error: 'expected_auth_frame' };
+        frame = parsed;
+    }
+    catch {
+        return { error: 'invalid_json' };
+    }
+    if (frame.type !== 'auth')
+        return { error: 'expected_auth_frame' };
+    if (!tokensMatch(token, frame.token))
+        return { error: 'invalid_token' };
+    if (!isValidId(frame.terminal_id))
+        return { error: 'unknown_terminal' };
+    const window = frame.window === undefined ? 'agent' : frame.window;
+    if (typeof window !== 'string' || !TERMINAL_WINDOWS.has(window))
+        return { error: 'invalid_window' };
+    if (typeof frame.viewer_token !== 'string' || !frame.viewer_token)
+        return { error: 'viewer_token_required' };
+    return {
+        terminalId: frame.terminal_id,
+        window: window,
+        cols: clampDim(frame.cols, DEFAULT_COLS),
+        rows: clampDim(frame.rows, DEFAULT_ROWS),
+        viewerToken: frame.viewer_token,
+    };
+}
+export class LocalTerminalServer {
+    options;
+    server;
+    wss;
+    token = '';
+    port = 0;
+    env;
+    /** Viewers admitted on a verdict that was not `local`: the ones `remote off` ends. */
+    remoteClients = new Set();
+    constructor(options) {
+        this.options = options;
+        this.env = options.env ?? process.env;
+    }
+    /** The bound port, once listening. */
+    boundPort() {
+        return this.port;
+    }
+    /** The current token. Exposed for tests; never logged. */
+    currentToken() {
+        return this.token;
+    }
+    async start() {
+        if (this.server)
+            return;
+        this.token = randomBytes(32).toString('hex');
+        const wss = new WebSocketServer({ noServer: true, maxPayload: 1024 * 1024 });
+        this.wss = wss;
+        const server = http.createServer((req, res) => this.onRequest(req, res));
+        server.on('upgrade', (req, socket, head) => this.onUpgrade(req, socket, head));
+        // Own the listener before awaiting it, so stop() can invalidate this start.
+        this.server = server;
+        try {
+            await new Promise((resolve, reject) => {
+                const complete = () => {
+                    server.off('error', failed);
+                    server.off('close', complete);
+                    resolve();
+                };
+                const failed = (error) => {
+                    server.off('close', complete);
+                    reject(error);
+                };
+                server.once('error', failed);
+                server.once('close', complete);
+                server.listen(0, '127.0.0.1', complete);
+            });
+            if (this.server !== server) {
+                await closeServer(server);
+                return;
+            }
+            const address = server.address();
+            this.port = typeof address === 'object' && address ? address.port : 0;
+            writePrivateJson(localConfigPath(this.env), {
+                // v2: every attach's viewer token is verified through the relay (a v1
+                // desktop, which never sends one, gets `viewer_token_required`).
+                version: 2,
+                port: this.port,
+                token: this.token,
+                pid: process.pid,
+                account_id: this.options.accountId.toLowerCase(),
+                owner_user_id: this.options.ownerUserId.toLowerCase(),
+            });
+        }
+        catch (error) {
+            if (this.server === server)
+                await this.stop();
+            else
+                await closeServer(server);
+            throw error;
+        }
+    }
+    /** End every attached desktop viewer now (the pairing refused, the host stopping). */
+    dropClients() {
+        for (const client of this.wss?.clients ?? [])
+            client.terminate();
+    }
+    /** End every viewer admitted as remote (the remote switch turned off); local ones stay. */
+    dropRemoteClients() {
+        for (const client of this.remoteClients)
+            client.terminate();
+        this.remoteClients.clear();
+    }
+    /** Whether `verdict` may attach now: the remote switch, or a token the relay vouched for as local. */
+    admits(verdict) {
+        return verdict.local || this.options.settings().allowRemoteTerminal;
+    }
+    async stop() {
+        // Clients first: a file that can't be removed must not keep a viewer attached.
+        for (const client of this.wss?.clients ?? [])
+            client.terminate();
+        try {
+            rmSync(localConfigPath(this.env), { force: true });
+        }
+        catch {
+            /* the port and token in it are dead once the server closes below */
+        }
+        this.wss?.close();
+        const server = this.server;
+        this.server = undefined;
+        this.wss = undefined;
+        if (server)
+            await closeServer(server);
+    }
+    /** Every WebSocket handshake comes through here; a refused one never reaches `ws`. */
+    onUpgrade(req, socket, head) {
+        const refusal = refuseHandshake(req.headers, req.url, this.port);
+        if (refusal || !this.wss) {
+            const { status, reason } = refusal ?? { status: 503, reason: 'stopping' };
+            socket.write(`HTTP/1.1 ${status} ${reason}\r\nConnection: close\r\n\r\n`);
+            socket.destroy();
+            return;
+        }
+        this.wss.handleUpgrade(req, socket, head, (ws) => this.onSocket(ws));
+    }
+    onRequest(req, res) {
+        const refuse = (status) => {
+            res.writeHead(status, { 'content-type': 'application/json' });
+            res.end('{}');
+        };
+        if (req.headers.origin !== undefined)
+            return refuse(403);
+        if (req.headers.host !== `127.0.0.1:${this.port}` && req.headers.host !== `localhost:${this.port}`)
+            return refuse(403);
+        if (req.method !== 'GET' || new URL(req.url ?? '/', 'http://127.0.0.1').pathname !== LOCAL_TERMINALS_PATH) {
+            return refuse(404);
+        }
+        const auth = req.headers.authorization ?? '';
+        if (!auth.startsWith('Bearer ') || !tokensMatch(this.token, auth.slice('Bearer '.length)))
+            return refuse(401);
+        const terminals = this.options.settings().allowRemoteTerminal
+            ? this.options.terminals.list().map((t) => ({
+                terminalId: t.terminalId,
+                codeThreadId: t.codeThreadId,
+                agent: t.agent,
+                windows: t.windows,
+            }))
+            : [];
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ terminals }));
+    }
+    onSocket(ws) {
+        const fail = (reason, code = 1008) => {
+            try {
+                ws.send(JSON.stringify({ type: 'error', reason }));
+                ws.close(code, reason);
+            }
+            catch {
+                ws.terminate();
+            }
+        };
+        const timer = setTimeout(() => fail('auth_timeout'), AUTH_TIMEOUT_MS);
+        timer.unref?.();
+        ws.once('message', (data, isBinary) => {
+            clearTimeout(timer);
+            if (isBinary)
+                return fail('expected_auth_frame');
+            const parsed = parseLocalAuth(data.toString(), this.token);
+            if ('error' in parsed)
+                return fail(parsed.error);
+            void this.options
+                .verifyViewer(parsed.viewerToken)
+                .then((verdict) => {
+                if (!verdict.ok)
+                    return fail(verdict.reason);
+                // Remote off: only a token minted for this Mac's own desktop app opens anything.
+                if (!this.admits(verdict))
+                    return fail('remote_terminal_disabled');
+                // The token names one terminal (and maybe one window); it opens nothing else.
+                if (verdict.terminalId !== parsed.terminalId)
+                    return fail('not_allowed');
+                if (verdict.window !== null && verdict.window !== parsed.window)
+                    return fail('invalid_window');
+                return this.options.terminals
+                    .attach({
+                    terminalId: parsed.terminalId,
+                    window: parsed.window,
+                    cols: parsed.cols,
+                    rows: parsed.rows,
+                    mode: verdict.mode,
+                })
+                    .then((attached) => this.serve(ws, attached, fail, verdict.local, `${parsed.terminalId.slice(0, 12)} (${parsed.window}, ${verdict.mode}${verdict.local ? ', local' : ''})`));
+            })
+                // Fail closed on anything unexpected: no verdict, no terminal.
+                .catch(() => fail('relay_unavailable', 1011));
+        });
+    }
+    /** Hand a verified attach to its socket, re-checking what may have changed while it opened. */
+    serve(ws, attached, fail, local, what = '') {
+        if (!attached.ok)
+            return fail(attached.reason, 1011);
+        // Re-checked after the attach: the switch may have turned off, or the server stopped, meanwhile.
+        if (!this.wss || !this.admits({ local })) {
+            attached.stream.close();
+            return fail('remote_terminal_disabled');
+        }
+        if (ws.readyState !== WebSocket.OPEN) {
+            attached.stream.close();
+            return;
+        }
+        if (!local) {
+            this.remoteClients.add(ws);
+            ws.on('close', () => this.remoteClients.delete(ws));
+        }
+        ws.send(JSON.stringify({ type: 'ready' }));
+        // The desktop fast path, not the relay: the one line that tells the two apart on this side.
+        this.options.log?.(`    ⇄ terminal ${what} attached by the desktop app on this Mac (no relay)`);
+        this.heartbeat(ws);
+        pipeStream(ws, attached.stream, () => { });
+    }
+    /** Same heartbeat as the relay: a ping every 30 s, closed after 60 s without a pong. */
+    heartbeat(ws) {
+        let lastPong = Date.now();
+        ws.on('message', (data, isBinary) => {
+            if (isBinary)
+                return;
+            if (parseControl(data.toString())?.type === 'pong')
+                lastPong = Date.now();
+        });
+        const interval = setInterval(() => {
+            if (Date.now() - lastPong >= PONG_TIMEOUT_MS) {
+                ws.close(1011, 'heartbeat_timeout');
+                return;
+            }
+            if (ws.readyState === WebSocket.OPEN)
+                ws.send(JSON.stringify({ type: 'ping' }));
+        }, PING_INTERVAL_MS);
+        interval.unref?.();
+        ws.on('close', () => clearInterval(interval));
+    }
+}

package/dist/codehost/pty.d.ts

@@ -0,0 +1,38 @@
+/**
+ * node-pty, loaded only when a terminal is attached.
+ *
+ * It is a native module, so it is an *optional* dependency: a CLI installed
+ * where its prebuilt binary doesn't load still pairs, runs agents and hosts
+ * threads — only attaching a viewer answers `pty_unavailable`. Pinned to the
+ * version the cloud sandbox's terminal server uses (1.1.0); 1.2 is still beta.
+ *
+ * Each attach owns exactly one pty, killed when its viewer goes. node-pty 1.1
+ * has been seen to leak `/dev/ptmx` descriptors in hosts that churn ptys
+ * without killing them, so the host caps how many are open at once
+ * ({@link MAX_OPEN_PTYS}) and always kills on close.
+ */
+export declare const MAX_OPEN_PTYS = 16;
+export interface PtyDisposable {
+    dispose(): void;
+}
+/** The slice of node-pty's `IPty` the host uses. */
+export interface PtyProcess {
+    onData(listener: (data: string) => void): PtyDisposable | void;
+    onExit(listener: (event: {
+        exitCode: number;
+        signal?: number;
+    }) => void): PtyDisposable | void;
+    write(data: string): void;
+    resize(cols: number, rows: number): void;
+    kill(signal?: string): void;
+}
+export interface PtySpawnOptions {
+    name: string;
+    cols: number;
+    rows: number;
+    cwd: string;
+    env: Record<string, string>;
+}
+export type PtySpawn = (file: string, args: string[], options: PtySpawnOptions) => PtyProcess;
+/** node-pty's `spawn`, or `undefined` when the module is not installed or won't load. */
+export declare function loadNodePty(): PtySpawn | undefined;

package/dist/codehost/pty.js

@@ -0,0 +1,47 @@
+/**
+ * node-pty, loaded only when a terminal is attached.
+ *
+ * It is a native module, so it is an *optional* dependency: a CLI installed
+ * where its prebuilt binary doesn't load still pairs, runs agents and hosts
+ * threads — only attaching a viewer answers `pty_unavailable`. Pinned to the
+ * version the cloud sandbox's terminal server uses (1.1.0); 1.2 is still beta.
+ *
+ * Each attach owns exactly one pty, killed when its viewer goes. node-pty 1.1
+ * has been seen to leak `/dev/ptmx` descriptors in hosts that churn ptys
+ * without killing them, so the host caps how many are open at once
+ * ({@link MAX_OPEN_PTYS}) and always kills on close.
+ */
+import { chmodSync, existsSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+export const MAX_OPEN_PTYS = 16;
+let cached;
+/**
+ * npm sometimes unpacks node-pty's prebuilt `spawn-helper` without its execute
+ * bit, and every spawn then fails with `posix_spawnp failed`. Restore it.
+ */
+function ensureSpawnHelperExecutable(packageJsonPath) {
+    const helper = path.join(path.dirname(packageJsonPath), 'prebuilds', `${process.platform}-${process.arch}`, 'spawn-helper');
+    try {
+        if (existsSync(helper) && (statSync(helper).mode & 0o111) === 0)
+            chmodSync(helper, 0o755);
+    }
+    catch {
+        /* best effort — the spawn will say what is wrong */
+    }
+}
+/** node-pty's `spawn`, or `undefined` when the module is not installed or won't load. */
+export function loadNodePty() {
+    if (cached !== undefined)
+        return cached ?? undefined;
+    try {
+        const require = createRequire(import.meta.url);
+        ensureSpawnHelperExecutable(require.resolve('node-pty/package.json'));
+        const mod = require('node-pty');
+        cached = typeof mod.spawn === 'function' ? mod.spawn : null;
+    }
+    catch {
+        cached = null;
+    }
+    return cached ?? undefined;
+}

package/dist/codehost/ready.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Whether a thread's Claude Code is past its workspace trust dialog.
+ *
+ * Claude Code runs no hook until its folder is trusted (checked against
+ * 2.1.314: with the dialog up, not even `SessionStart` fires; once it is
+ * accepted, `SessionStart` comes first). So the first hook that runs in a
+ * thread's window writes `<state>/<terminal>.ready`, and that mark, never the
+ * screen, is what lets a relayed reply be typed: before it, the dialog may be
+ * up or about to be drawn, and an Enter would answer it. The mark is a file,
+ * so it outlives a daemon restart.
+ */
+export declare function readyPath(terminalId: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Mark the terminal's Claude Code past its trust dialog (a hook ran). Atomic (`writePrivateJson`).
+ * Returns whether it is marked afterwards; `false` means the write failed, and the caller says so.
+ */
+export declare function markReady(terminalId: string, env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Whether Claude Code ran a session in exactly `cwd`, under `configDir`, that it last wrote at or
+ * after `sinceMs`: a `projects/<key>/<session>.jsonl` modified since then whose entries name `cwd`
+ * itself (read from inside the file: the dash-encoded `<key>` is lossy, `/a-b` and `/a/b` share it).
+ *
+ * Claude Code writes that transcript only once the folder is trusted (checked against 2.1.314:
+ * nothing under `projects/` while the dialog is up; the transcript the moment it is accepted and
+ * the first prompt runs). With `sinceMs` the window's start, it is proof, from a file Claude Code
+ * owns, that this window's Claude Code got past its dialog. Used only for a window an older build
+ * started, which never had a ready mark.
+ */
+export declare function claudeSessionSince(cwd: string, configDir: string, sinceMs: number): boolean;
+/** `true` past the dialog, `false` not yet, `undefined` when the state can't be read. */
+export declare function isReady(terminalId: string, env?: NodeJS.ProcessEnv): boolean | undefined;

package/dist/codehost/ready.js

@@ -0,0 +1,109 @@
+/**
+ * Whether a thread's Claude Code is past its workspace trust dialog.
+ *
+ * Claude Code runs no hook until its folder is trusted (checked against
+ * 2.1.314: with the dialog up, not even `SessionStart` fires; once it is
+ * accepted, `SessionStart` comes first). So the first hook that runs in a
+ * thread's window writes `<state>/<terminal>.ready`, and that mark, never the
+ * screen, is what lets a relayed reply be typed: before it, the dialog may be
+ * up or about to be drawn, and an Enter would answer it. The mark is a file,
+ * so it outlives a daemon restart.
+ */
+import { closeSync, openSync, readdirSync, readSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { codeHostDir, writePrivateJson } from './settings.js';
+import { isValidId } from './tmux.js';
+export function readyPath(terminalId, env = process.env) {
+    if (!isValidId(terminalId))
+        throw new Error('invalid terminal id');
+    return path.join(codeHostDir(env), 'state', `${terminalId}.ready`);
+}
+/**
+ * Mark the terminal's Claude Code past its trust dialog (a hook ran). Atomic (`writePrivateJson`).
+ * Returns whether it is marked afterwards; `false` means the write failed, and the caller says so.
+ */
+export function markReady(terminalId, env = process.env) {
+    if (!isValidId(terminalId))
+        return false;
+    if (isReady(terminalId, env) === true)
+        return true;
+    try {
+        writePrivateJson(readyPath(terminalId, env), Date.now());
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** How much of a transcript is read looking for its folder (its first entries carry `cwd`). */
+const TRANSCRIPT_HEAD_BYTES = 256 * 1024;
+/**
+ * Whether Claude Code ran a session in exactly `cwd`, under `configDir`, that it last wrote at or
+ * after `sinceMs`: a `projects/<key>/<session>.jsonl` modified since then whose entries name `cwd`
+ * itself (read from inside the file: the dash-encoded `<key>` is lossy, `/a-b` and `/a/b` share it).
+ *
+ * Claude Code writes that transcript only once the folder is trusted (checked against 2.1.314:
+ * nothing under `projects/` while the dialog is up; the transcript the moment it is accepted and
+ * the first prompt runs). With `sinceMs` the window's start, it is proof, from a file Claude Code
+ * owns, that this window's Claude Code got past its dialog. Used only for a window an older build
+ * started, which never had a ready mark.
+ */
+export function claudeSessionSince(cwd, configDir, sinceMs) {
+    let real;
+    try {
+        real = realpathSync(cwd);
+    }
+    catch {
+        return false;
+    }
+    const dir = path.join(configDir, 'projects', real.replace(/[^a-zA-Z0-9]/g, '-'));
+    let names;
+    try {
+        names = readdirSync(dir).filter((name) => name.endsWith('.jsonl'));
+    }
+    catch {
+        return false;
+    }
+    return names.some((name) => {
+        const file = path.join(dir, name);
+        let fd;
+        try {
+            if (statSync(file).mtimeMs < sinceMs)
+                return false;
+            fd = openSync(file, 'r');
+            const buffer = Buffer.alloc(TRANSCRIPT_HEAD_BYTES);
+            const read = readSync(fd, buffer, 0, buffer.length, 0);
+            return buffer
+                .subarray(0, read)
+                .toString('utf8')
+                .split('\n')
+                .some((line) => {
+                if (!line.includes('"cwd"'))
+                    return false;
+                try {
+                    return JSON.parse(line).cwd === real;
+                }
+                catch {
+                    return false; // a line cut at the read's end
+                }
+            });
+        }
+        catch {
+            return false;
+        }
+        finally {
+            if (fd !== undefined)
+                closeSync(fd);
+        }
+    });
+}
+/** `true` past the dialog, `false` not yet, `undefined` when the state can't be read. */
+export function isReady(terminalId, env = process.env) {
+    try {
+        statSync(readyPath(terminalId, env));
+        return true;
+    }
+    catch (err) {
+        return err.code === 'ENOENT' ? false : undefined;
+    }
+}