@prohost/cli 0.13.3 → 0.14.0

package/dist/codehost/terminals.d.ts

@@ -0,0 +1,390 @@
+/**
+ * The Mac's Code-thread terminals: one tmux window per thread, attached
+ * through a pty per viewer.
+ *
+ * - {@link CodeTerminals.start} handles `code_thread.start_requested`: a
+ *   worktree for the thread, then a window running the agent (`claude`,
+ *   `codex` or a shell) with `PROHOST_TERMINAL_ID` / `PROHOST_CODE_THREAD_ID`
+ *   in its environment — what makes the hooks fire for it and for nothing
+ *   else. When the agent exits, the window becomes a shell in the worktree; it
+ *   never just disappears under a viewer.
+ * - {@link CodeTerminals.input} handles `code_thread.input_requested`: the text
+ *   typed into a composer that isn't attached to the terminal, sent to the
+ *   pane as one paste plus Enter.
+ * - {@link CodeTerminals.attach} gives a viewer (relay or desktop) a byte
+ *   stream to one of a thread's windows.
+ * - {@link CodeTerminals.adopt} finds the threads a previous daemon started:
+ *   tmux owns their processes, so a daemon restart costs nothing.
+ *
+ * Every start and input is idempotent under redelivery: a window that exists
+ * is the thread already started.
+ */
+import { execFile } from 'node:child_process';
+import type { InstalledAgent } from './agents.js';
+import type { CheckoutResult } from './checkouts.js';
+import type { CodeThreadEventSink } from './events.js';
+import type { PtySpawn } from './pty.js';
+import { TerminalSizing } from './sizing.js';
+import type { SizerFrame, ViewerClient } from './sizing.js';
+import type { ApprovalDecision, TerminalWindow } from './tmux.js';
+export declare const CODE_AGENTS: readonly ["claude_code", "codex", "shell"];
+export type CodeAgent = (typeof CODE_AGENTS)[number];
+export declare const GOAL_ENV = "PROHOST_CODE_THREAD_GOAL";
+/** Window option set when the agent exits and its window becomes a shell. */
+export declare const EXITED_OPTION = "@prohost_exited";
+/**
+ * Window option that marks a relayed reply as possibly sitting in the agent's
+ * input unsubmitted. It is set before the reply's first keystroke reaches the
+ * pane and cleared only once its Enter went through, so a reply stopped half
+ * way — a revocation or `remote off` between the steps, a tmux error, the
+ * daemon dying — leaves it set. Relayed text is refused while it is set, so
+ * the next reply can't append to the leftover and submit both; the owner
+ * typing in a terminal attached to that window (where they see the input box)
+ * clears it.
+ */
+export declare const STAGED_OPTION = "@prohost_staged";
+export interface TmuxResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    /**
+     * Failed with an unknown outcome: the command was killed (a timeout) after it
+     * started, so it may have done its work. A clean failure (tmux exited with an
+     * error, or never started) did nothing.
+     */
+    uncertain?: boolean;
+}
+/** Runs `tmux <args>` (the base args are added by the caller); optional stdin, and a per-call timeout. */
+export type TmuxRunner = (args: string[], stdin?: string, timeoutMs?: number) => Promise<TmuxResult>;
+export declare function execTmux(binary?: string): TmuxRunner;
+/** The login a thread's agent runs on, or why it can't run here. */
+export type AccountEnvResult = {
+    ok: true;
+    env: NodeJS.ProcessEnv;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface StartRequest {
+    codeThreadId: string;
+    terminalId: string;
+    goal: string;
+    repo: string;
+    branch?: string;
+    agent: CodeAgent;
+    /**
+     * A folder start: the folder the thread runs in (absolute or `~/…`, as the server was sent it).
+     * Absent for a repository thread. Only a folder this Mac has opened, or one inside it, starts.
+     */
+    folder?: string;
+    /** With {@link folder}: a worktree and branch of the folder's git checkout instead of in place. */
+    separateCopy?: boolean;
+}
+/**
+ * Why `input` did not get a reply through, when the server should hear it (it
+ * hands the reply back on the thread):
+ * - `remote_terminal_disabled`: nothing typed; the owner's switch was off by
+ *   the time the queued job ran.
+ * - `reply_interrupted`: a reply stopped partway (some of it may sit in the
+ *   input box, unsent), or one refused because an earlier one did.
+ *
+ * A decision is never typed: the prompt's own hook answers it (`decision.ts`).
+ */
+export interface TypingOutcome {
+    /**
+     * `shell_window`: the thread's window is a shell (a shell thread, or an agent that exited into
+     * one), which composer text is never typed into: it would run as a command.
+     */
+    refused?: 'remote_terminal_disabled' | 'reply_interrupted' | 'terminal_gone' | 'trust_prompt' | 'shell_window';
+    /**
+     * Nothing reached the pane, and the failure was local and may pass (a tmux
+     * command failed): the delivery is worth sending again, not handing back.
+     */
+    retry?: boolean;
+}
+export interface InputRequest {
+    codeThreadId: string;
+    terminalId: string;
+    text: string;
+}
+export interface ApprovalRequest {
+    codeThreadId: string;
+    terminalId: string;
+    approvalId: string;
+    decision: ApprovalDecision;
+}
+export interface TerminalRecord {
+    terminalId: string;
+    codeThreadId: string;
+    agent: string;
+    cwd: string;
+    windows: TerminalWindow[];
+    /** Started by a build with the ready mark (`WindowMeta.readyMark`): never adopted past trust. */
+    readyMark?: boolean;
+}
+export type AttachFailure = 'unknown_terminal' | 'pty_unavailable' | 'busy' | 'invalid_window';
+export interface AttachRequest {
+    terminalId: string;
+    window: TerminalWindow;
+    cols?: number;
+    rows?: number;
+    /** `watch` streams output and drops every keystroke. */
+    mode?: 'type' | 'watch';
+}
+/** One viewer's live connection to one window. */
+export interface TerminalStream {
+    onData(listener: (chunk: Buffer) => void): void;
+    onExit(listener: () => void): void;
+    write(data: Uint8Array): void;
+    resize(cols: number, rows: number): void;
+    close(): void;
+    /** The viewer said what it is (`hello`): from now on it is told who sizes the window (`sizing.ts`). */
+    hello?(client: ViewerClient): void;
+    /** Size the window to this viewer (`claim`). */
+    claim?(): void;
+    /** Who sizes the window, for a viewer that said hello. */
+    onSizer?(listener: (frame: SizerFrame) => void): void;
+}
+export type AttachResult = {
+    ok: true;
+    stream: TerminalStream;
+} | {
+    ok: false;
+    reason: AttachFailure;
+};
+/**
+ * `reported`: the server answered the start / failed event definitively
+ * (2xx, or a 4xx it will keep giving). False means no answer — no token yet,
+ * offline, a 5xx — and the harness asks for the delivery again instead of
+ * acknowledging an outcome the server never heard.
+ */
+export type StartResult = {
+    ok: true;
+    adopted: boolean;
+    reported: boolean;
+} | {
+    ok: false;
+    reason: string;
+    reported: boolean;
+};
+/**
+ * Whether an event post's status settles it (see {@link StartResult}): the
+ * server applied it (2xx) or will refuse it the same way every time (404, 409,
+ * 422…). A 401 / 403 is the token — expired, or minted before a reconnect —
+ * and the next control-socket connect brings a fresh one, so like no answer
+ * at all (0, 408, 429, 5xx) it is retried.
+ */
+export declare function isDefinitive(status: number): boolean;
+/** The shell command line a thread's agent window runs. */
+export declare function agentCommandLine(agent: CodeAgent, options: {
+    claudeSettings: string;
+    claudeInvocationSettings?: string;
+    hookShim?: string;
+    codexNotify: string;
+    hasGoal: boolean;
+}): string;
+export interface CodeTerminalsOptions {
+    /** `$PROHOST_HOME` for this host; exported to every window. */
+    home: string;
+    socket: string;
+    confPath: string;
+    tmux: TmuxRunner;
+    spawnPty: () => PtySpawn | undefined;
+    checkouts: {
+        prepare(repo: string, terminalId: string, branch?: string): Promise<CheckoutResult>;
+        /** A folder start (`CodeThreadCheckouts.prepareFolder`); without it, folder starts are refused. */
+        prepareFolder?(folder: string, terminalId: string, options: {
+            separateCopy?: boolean;
+            branch?: string;
+        }): Promise<CheckoutResult>;
+        /** The folder start's window is open (`CodeThreadCheckouts.folderStarted`). */
+        folderStarted?(folder: string): void;
+    };
+    events: CodeThreadEventSink;
+    hookFiles: {
+        claudeSettings: string;
+        claudeInvocationSettings?: string;
+        hookShim?: string;
+        codexNotify: string;
+    };
+    /**
+     * The login this agent runs on (`CLAUDE_CONFIG_DIR` / `CODEX_HOME` of the
+     * account picked for it), read at each start — the same environment its
+     * ordinary runs get, so a thread spends the subscription the agent reports.
+     */
+    accountEnv?: (agent: CodeAgent) => AccountEnvResult;
+    /**
+     * Whether this machine may act on ProhostAI's behalf right now (the relay
+     * has not refused the pairing; the host is running). Read immediately
+     * before every side effect — opening a window, typing, pressing keys — so
+     * a delivery that arrives after a revocation does nothing.
+     */
+    authorized?: () => boolean;
+    /**
+     * Whether typing into a terminal on ProhostAI's behalf is allowed right now
+     * (the owner's remote-terminal switch, read from disk). Checked inside the
+     * queued job and before every step of it — a reply or decision that waited
+     * behind another never types after `remote off`.
+     */
+    remoteControlAllowed?: () => boolean;
+    log?: (line: string) => void;
+    now?: () => number;
+    tmuxBinary?: string;
+    sleep?: (ms: number) => Promise<void>;
+    /** Seams for tests: Claude Code's workspace trust (`claude_trust.ts`). */
+    trustWorkspace?: (workspace: string, env: NodeJS.ProcessEnv) => boolean | Promise<boolean>;
+    trusts?: (workspace: string, env: NodeJS.ProcessEnv) => boolean;
+    /** How many times (a second apart) to look for Claude Code's trust dialog after launch. */
+    trustWatchAttempts?: number;
+    /** Seam for tests: whether a terminal's Claude Code is past its trust dialog (`ready.ts`). */
+    ready?: (terminalId: string) => boolean | undefined;
+    /** Seams for tests: an older window's Claude session (`ready.ts`) and its pane's process. */
+    claudeSessionSince?: (cwd: string, configDir: string, sinceMs: number) => boolean;
+    paneStarts?: (pids: number[]) => Promise<Map<number, number>>;
+    /** Seam for tests: the daemon's own environment, under the launch env (`claudeLaunchEnv`). */
+    processEnv?: NodeJS.ProcessEnv;
+    /**
+     * Whether the agent's binary resolves here (`agents.ts`): a start for one that doesn't is
+     * refused with why, rather than opening a window that says `command not found`. Unset: not checked.
+     */
+    agentInstalled?: (agent: InstalledAgent) => boolean;
+    /** Seam for tests: the timers who-sizes-the-window settles with (`sizing.ts`). */
+    setTimer?: (fn: () => void, ms: number) => () => void;
+}
+/** What the thread says while Claude Code waits on its trust dialog. */
+export declare const TRUST_PROMPT_NOTE = "Claude Code is asking whether to trust this folder before it starts. Answer in the terminal.";
+export declare class CodeTerminals {
+    private readonly options;
+    private readonly records;
+    private readonly starting;
+    /**
+     * Older windows are adopted past trust by one pass that succeeds once per daemon start
+     * (`adoptReadiness`); a failed pass is forgotten and tried again by the next `adopt()`, or by a
+     * reply it would have let through. The pass in flight or done, so every `adopt()` (a concurrent
+     * one too) returns only once it has finished.
+     */
+    private readinessAdoption;
+    private readonly lastInterrupt;
+    /** Per terminal: the tail of its typing queue (see {@link serialize}). */
+    private readonly typing;
+    private openPtys;
+    /** Who sizes each window, and what its viewers are told (`sizing.ts`). */
+    readonly sizing: TerminalSizing;
+    private readonly log;
+    private readonly now;
+    private readonly sleep;
+    constructor(options: CodeTerminalsOptions);
+    private isReady;
+    private isAuthorized;
+    private canType;
+    private tmux;
+    /** Threads this host knows about right now. */
+    list(): TerminalRecord[];
+    /** Ptys open right now. Exposed for assertions. */
+    openPtyCount(): number;
+    /** Re-read the windows tmux holds. Returns how many threads are known after. */
+    /**
+     * Run `work` after every earlier typing job for this terminal. A paste and
+     * its Enter (or an approval's keys) are one unit: two deliveries for one
+     * terminal never interleave into "first, second, Enter, Enter".
+     */
+    private serialize;
+    /**
+     * Mark a thread's worktree lane as in use (`.last-used`, the marker every
+     * {@link WorktreeManager} prunes by), so a long-lived terminal's checkout is
+     * never removed as idle while its window lives — whichever lane's prepare
+     * happens to run the prune.
+     */
+    private touchLane;
+    /** Refresh the lanes of threads whose windows tmux still has (adopt reconciles first). */
+    private touchLiveLanes;
+    /**
+     * The hourly keeper: re-read tmux, then mark only the threads it still holds
+     * as in use. A window or server that went away is dropped by the re-read, so
+     * its lane is left to age out and be pruned as usual.
+     */
+    refreshLiveLanes(): Promise<void>;
+    /**
+     * Apply the config just written to a server that is already running: tmux
+     * reads `-f` only when a server starts, and the persistent session keeps an
+     * upgraded host's old server (and its old settings) alive. With no server
+     * there is nothing to apply, and the next one starts with the file.
+     */
+    reloadConfig(): Promise<boolean>;
+    adopt(): Promise<number>;
+    /**
+     * The environment a Claude Code thread starts with: what `startOnce` hands its window, and so
+     * the only source of where that window's Claude Code keeps its sessions (`adoptReadiness`).
+     */
+    private claudeLaunchEnv;
+    /**
+     * Older windows, all at once: one `ps` for every candidate's start (bounded, never one call per
+     * window), then the evidence check for each (`adoptReadiness`).
+     */
+    private adoptReadinessAll;
+    /**
+     * A Claude window from a build before the ready mark (an upgrade): its Claude Code may be long
+     * past trust, but no hook runs to say so until a reply types, which the missing mark refuses.
+     * Only such a window (no `readyMark` in its meta: this build's windows get the mark from their
+     * first hook, never from here), by a pass that succeeds once per daemon start (and is tried
+     * again after a failure; each try judges afresh), and only on evidence tied to it: a
+     * transcript in that window's Claude config dir (`claudeLaunchEnv`), naming its exact folder,
+     * written since the window's process started (`claudeSessionSince`). A window still at its
+     * trust dialog has none and stays refused. Never judged from the screen.
+     */
+    private adoptReadiness;
+    private ensureSession;
+    start(request: StartRequest): Promise<StartResult>;
+    private startOnce;
+    /**
+     * A worktree this host made for the thread opens without Claude Code's trust dialog: no hook
+     * fires for it, so the thread would read `Working` while it waits for someone at the Mac.
+     * Only a worktree under this home's own `worktrees/`, never a checkout it was handed.
+     */
+    private trustOwnWorktree;
+    /**
+     * Watch a new Claude Code window for its trust dialog, only to tell the thread it waits on it
+     * (needs-you, not Working). It never decides whether a reply types: the ready mark does.
+     */
+    private watchTrustPrompt;
+    private known;
+    /**
+     * Whether the thread's agent window runs an agent that composer text and
+     * approval keys may reach. A Claude Code or Codex that exited left a shell
+     * behind (see {@link agentCommandLine}); a `shell` thread is a shell from
+     * the start. Neither ever takes relayed text.
+     */
+    private agentRunning;
+    /** Send composer text to the thread's agent. False when the thread isn't here or its agent has exited. */
+    input(request: InputRequest, outcome?: TypingOutcome): Promise<boolean>;
+    private inputNow;
+    /**
+     * A reply stopped after a step that can reach the agent's input box, before
+     * its Enter went through. Nothing is pressed to take it back: no keystroke
+     * from out here can tell the reply apart from what was in the box already —
+     * a draft typed before, or one the agent put back — so clearing it would
+     * erase that too. The window stays staged until the owner types in a
+     * terminal attached to it, where they see the input box. The delivery is reported unhandled (acked 204), never
+     * retried blind.
+     */
+    private leaveStaged;
+    /**
+     * Mark a window just created with {@link holdCommand} as held, so its release signals it. When
+     * the mark can't be set, nothing would ever signal it: its shell is released now, unheld.
+     */
+    private markHeld;
+    /** The thread's shell window, made at `size` (its first viewer's) the first time someone asks. */
+    private ensureShellWindow;
+    private noteInterrupt;
+    attach(request: AttachRequest): Promise<AttachResult>;
+}
+/**
+ * When each of `pids` started, from one `ps -o pid=,etime=` (bounded, asynchronous: the daemon
+ * keeps serving meanwhile). From elapsed time, which no timezone can shift, a second early since
+ * `etime` drops the part of the current second already gone. A pid `ps` doesn't list is left out
+ * (`ps` exits 1 with nothing on stderr when none of them run). Rejects on any other outcome (it
+ * timed out, was killed, couldn't start, exited with another status, or wrote an error such as a
+ * bad option's usage, which also exits 1), so the caller tries again rather than taking "none
+ * started".
+ */
+export declare function paneStarts(pids: number[], now?: number, run?: typeof execFile): Promise<Map<number, number>>;