@prohost/cli 0.13.3 → 0.14.0

package/dist/codehost/host.d.ts

@@ -0,0 +1,290 @@
+/**
+ * The Code-thread host inside `prohost agent run`: one object the harness
+ * starts when this machine's owner has turned hosting on
+ * (`prohost agent code-host enable`), and hands the three events it serves —
+ * `code_thread.start_requested`, `.input_requested` and `.approval_decided`.
+ *
+ * Off — the default — the harness never builds one: no tmux, no relay socket,
+ * no local server, no host stats, and the events are acknowledged as ignored.
+ */
+import type { CodeThreadEventSink } from './events.js';
+import type { ReportedFolder } from './folders.js';
+import type { HostStats } from './host_stats.js';
+import type { PtySpawn } from './pty.js';
+import type { PairingIdentity } from './relay.js';
+import type { CodeHostSettings } from './settings.js';
+import { CodeTerminals } from './terminals.js';
+import type { AccountEnvResult, ApprovalRequest, CodeAgent, InputRequest, StartRequest, TmuxRunner } from './terminals.js';
+export declare const EVENT_CODE_THREAD_START_REQUESTED = "code_thread.start_requested";
+export declare const EVENT_CODE_THREAD_INPUT_REQUESTED = "code_thread.input_requested";
+export declare const EVENT_CODE_THREAD_APPROVAL_DECIDED = "code_thread.approval_decided";
+/**
+ * Declared in `runtime_status.capabilities` while this harness hosts threads.
+ * Versioned with the contract the server relies on (`remote_terminal`, 409
+ * refusals; a prompt's own `hook_decision` capability says how its decision is
+ * answered): an older CLI's `code_threads` is not listed.
+ */
+export declare const CODE_THREADS_CAPABILITY = "code_threads_v2";
+/**
+ * Declared beside {@link CODE_THREADS_CAPABILITY} while the owner allows remote
+ * terminals. It rides the `/ws/webhooks` socket into the pairing's row in
+ * Postgres, where the backend API reads it (hosts listing, shell create,
+ * terminal-token) whatever fleet and Redis it runs against.
+ */
+export declare const REMOTE_TERMINAL_CAPABILITY = "remote_terminal";
+/**
+ * Declared with the instance id appended (`host_instance_<32 hex>`) beside
+ * {@link CODE_THREADS_CAPABILITY}: the server binds each thread to the
+ * instance that accepted its start and routes its frames only there.
+ */
+export declare const HOST_INSTANCE_CAPABILITY_PREFIX = "host_instance_";
+/**
+ * Declared beside {@link CODE_THREADS_CAPABILITY} by a host that starts threads
+ * in a folder (`folder` / `separateCopy` in `code_thread.start_requested`, the
+ * opened-folders list, `code_host_folders` on the status frame). The server
+ * sends a folder start only to a socket that declared it.
+ */
+export declare const CODE_THREAD_FOLDERS_CAPABILITY = "code_thread_folders";
+/** `code_thread.start_requested` data (camelCase per the contract), or `null`. */
+export declare function parseStartRequest(data: Record<string, unknown>): StartRequest | null;
+/** `code_thread.input_requested` data, or `null`. */
+export declare function parseInputRequest(data: Record<string, unknown>): InputRequest | null;
+/** What the harness needs from a host; tests fake it. */
+export interface CodeHostLike {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Whether this Mac takes the event now (the owner's switches); a refusal is acked 204. */
+    admits(event: string, data: Record<string, unknown>): boolean;
+    /** Why `event` is refused when it is only the owner's remote switch: the server hands it back. */
+    refusal(event: string): RefusedDeliveryError['reason'] | undefined;
+    handleStart(data: Record<string, unknown>): Promise<boolean>;
+    /** `deliveryId`: a redelivery of one already acted on is acknowledged without typing again. */
+    handleInput(data: Record<string, unknown>, deliveryId?: string): Promise<boolean>;
+    handleApproval(data: Record<string, unknown>, deliveryId?: string): Promise<boolean>;
+    latestStats(): HostStats | undefined;
+    /** The owner's remote-terminal switch as it is on disk now. */
+    remoteTerminalAllowed(): boolean;
+    /** This home's instance capability (`host_instance_<id>`). */
+    instanceCapability(): string;
+    /**
+     * The repositories this Mac offers Code threads (`--repos`, by `origin`), once
+     * known; `undefined` until then. Declared on every status frame.
+     */
+    offeredRepos?(): string[] | undefined;
+    /**
+     * The folders this Mac has opened (`folders.ts`) and its home directory, for the status frame
+     * (`code_host_folders`, `code_host_home`). Read for every frame.
+     */
+    openedFolders?(): {
+        folders: ReportedFolder[];
+        home: string;
+    } | undefined;
+    /** Whether this host may act for ProhostAI now (the relay hasn't refused the pairing). */
+    authorized(): boolean;
+    /**
+     * `code_thread_agent_<agent>` for each agent whose binary resolves on this daemon's `PATH`
+     * (`agents.ts`), re-checked on every status frame: what the server offers for this Mac.
+     */
+    agentCapabilities?(): string[];
+}
+/** `code_thread.approval_decided` data, or `null`. */
+export declare function parseApprovalDecision(data: Record<string, unknown>): ApprovalRequest | null;
+/** A start ran (or failed) but ProhostAI hasn't heard: redeliver, don't ack. */
+/**
+ * A reply or decision this Mac refuses before typing anything, with the reason
+ * the server shows on the thread (the harness acks it 409 + `reason`, and the
+ * server hands the reply or decision back instead of counting it delivered).
+ */
+export declare class RefusedDeliveryError extends Error {
+    readonly reason: 'remote_terminal_disabled' | 'reply_interrupted' | 'terminal_gone' | 'shell_window' | 'decision_unconfirmed' | 'trust_prompt' | 'prompt_local' | 'prompt_open';
+    constructor(reason: 'remote_terminal_disabled' | 'reply_interrupted' | 'terminal_gone' | 'shell_window' | 'decision_unconfirmed' | 'trust_prompt' | 'prompt_local' | 'prompt_open');
+}
+export declare class UnreportedOutcomeError extends Error {
+    constructor(codeThreadId: string);
+}
+export interface CodeHostOptions {
+    env?: NodeJS.ProcessEnv;
+    baseUrl: string;
+    apiKey: string;
+    machineId: string;
+    machine: string;
+    clientVersion: string;
+    /** The ProhostAI workspace this machine is paired with (`agent.json` `prohost_account.id`). */
+    accountId?: string;
+    repos: string[];
+    /** Absolute path of this CLI's entrypoint, for the hook shim. */
+    cliEntrypoint: string;
+    nodePath?: string;
+    log?: (line: string) => void;
+    slots?: () => {
+        busy: number;
+        total: number;
+    } | undefined;
+    /**
+     * What this host declares changed (the remote switch flipped, the relay
+     * authorized or refused the pairing, or the opened folders changed): the
+     * harness re-declares its capabilities now, and its status frame as soon as
+     * the server takes one, not in five minutes.
+     */
+    onRemoteChanged?: () => void;
+    /** The opened folders changed (`folders.json`): the status frame goes out as soon as the server takes one. */
+    onCodeHostChanged?: () => void;
+    /** The selected account's environment (see `CodeTerminalsOptions.accountEnv`). */
+    accountEnv?: (agent: CodeAgent) => AccountEnvResult;
+    tmux?: TmuxRunner;
+    spawnPty?: () => PtySpawn | undefined;
+    events?: CodeThreadEventSink;
+    relay?: boolean;
+    localServer?: boolean;
+    /** How often the owner's switches are re-read to close what they no longer allow. */
+    settingsPollMs?: number;
+    /** Seams for tests: whether a hook's process still runs, and the wait between looks. */
+    alive?: (pid: number) => boolean;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * How long a reply waits for a hook to apply the decision it was handed (it prints it and exits
+ * within a poll, 100 ms) before it is sent again later instead of typed.
+ */
+export declare const DECISION_APPLY_WAIT_MS = 2000;
+/** A `remote off` ends open terminals within this long. */
+export declare const SETTINGS_POLL_MS = 2000;
+/** How often live terminals' worktree lanes are marked in use (pruning is after 14 idle days). */
+export declare const LANE_REFRESH_MS = 3600000;
+export declare class CodeHost implements CodeHostLike {
+    private readonly options;
+    readonly terminals: CodeTerminals;
+    private readonly env;
+    private readonly stats;
+    private readonly deliveries;
+    private relay;
+    private local;
+    private watcher;
+    private laneKeeper;
+    private remoteAllowed;
+    private recoveringPermissions;
+    private readonly events;
+    /** Set while the relay refuses this pairing (revoked key, inactive pairing). */
+    private pairingRefused;
+    /** Whose pairing this is, from the relay's last `auth_ok`; the desktop socket is bound to it. */
+    private identity;
+    private stopped;
+    private readonly instanceId;
+    private readonly log;
+    private readonly checkouts;
+    /** What {@link offeredRepos} answers, read at {@link start}. */
+    private offered;
+    /** `folders.json` as last seen by the settings poll: a change re-sends the status frame. */
+    private foldersSeen;
+    /** Hosting (`enabled`) as last seen on disk: `code-host disable` closes the desktop socket at once. */
+    private enabledSeen;
+    /** `code-host/activity.json`, for the desktop app's keep-awake (`activity.ts`). */
+    private readonly activity;
+    constructor(options: CodeHostOptions);
+    settings(): CodeHostSettings;
+    remoteTerminalAllowed(): boolean;
+    instanceCapability(): string;
+    /**
+     * Only the agents a start would accept: installed here, and runnable on this harness's login
+     * (`accountEnv`: a Claude Code harness hosts no Codex thread). A host-only daemon has no login of
+     * its own and runs whichever is installed.
+     */
+    agentCapabilities(): string[];
+    offeredRepos(): string[] | undefined;
+    openedFolders(): {
+        folders: ReportedFolder[];
+        home: string;
+    };
+    /** The latest host stats, for the heartbeat. Sampled by the relay loop and on demand. */
+    latestStats(): HostStats | undefined;
+    sampleStats(): Promise<HostStats>;
+    start(): Promise<void>;
+    /**
+     * Whether an agent here is mid-turn, written for the desktop app's keep-awake (`activity.ts`) —
+     * only while hosting is on; turned off, the file goes.
+     */
+    reportActivity(): void;
+    /** The daemon outlives timed-out/killed hooks and retries recovery after reconnect or restart. */
+    recoverCompletedPermissions(): Promise<void>;
+    /**
+     * The switches as the desktop socket must see them: no remote terminal while
+     * the relay refuses this pairing, whatever the file says — a revoked
+     * pairing closes every way in, not only the relay's.
+     */
+    private desktopSettings;
+    /**
+     * Whether this host may act for ProhostAI now: running, and the relay has
+     * not refused the pairing. A refusal holds until the next `auth_ok`, and
+     * gates everything the event socket asks for as well as every attach.
+     */
+    authorized(): boolean;
+    /** The relay authorized or refused this machine (see `CodeHostRelayOptions.onAuthorization`). */
+    onAuthorization(authorized: boolean, reason?: string, identity?: PairingIdentity): Promise<void>;
+    /**
+     * The relay went away. Whether this pairing is still authorized can't be
+     * known until it answers again, so the desktop socket closes now (its
+     * identity is forgotten) and reopens only on a fresh `auth_ok`. The event
+     * socket's work is not paused: that socket authenticates on its own, and
+     * an explicit refusal (`auth_error`) is what gates it.
+     */
+    onRelayDisconnected(): Promise<void>;
+    private closeLocal;
+    /**
+     * The desktop app's socket on 127.0.0.1, served whenever hosting is on — with
+     * the remote switch off as well: then it admits only attaches the relay
+     * vouches for as local (`local_server.ts`).
+     */
+    private startLocal;
+    /**
+     * The owner's switches, re-read: a terminal attached while remote access was
+     * allowed must not outlive it. Turning it off closes every relay viewer and
+     * every desktop viewer that was admitted as remote; the desktop socket stays
+     * up for local attaches. Turning hosting off (`code-host disable`) closes the
+     * desktop socket (and its `local.json`) too. The opened folders changing
+     * re-sends the status frame.
+     */
+    applySettings(): Promise<void>;
+    /** Every closer is attempted, whatever the one before it did; never rejects. */
+    stop(): Promise<void>;
+    /**
+     * Whether this Mac takes `event` at all, read from the owner's switches on
+     * disk now — never cached. Anything that types into a terminal from
+     * ProhostAI (a reply, an approval) or opens a raw shell is remote control of
+     * this machine, so it needs the remote-terminal switch as well as hosting.
+     * The harness answers a refusal 204, as for a machine that doesn't host.
+     *
+     * Hosting itself (`enabled`) is latched for the process: this host exists only
+     * because it was on at startup, and `code-host disable` takes effect when the
+     * agent restarts, as the command says. Never re-read here: the runtime keeps
+     * advertising `code_threads_v2` until then, so a start refused for it would be
+     * acked 204 and leave its thread `starting` for good.
+     */
+    admits(event: string, data: Record<string, unknown>): boolean;
+    refusal(event: string): RefusedDeliveryError['reason'] | undefined;
+    /**
+     * Throws {@link UnreportedOutcomeError} when the outcome never reached the
+     * server, so the harness asks for the delivery again rather than ack it.
+     */
+    handleStart(data: Record<string, unknown>): Promise<boolean>;
+    handleInput(data: Record<string, unknown>, deliveryId?: string): Promise<boolean>;
+    handleApproval(data: Record<string, unknown>, deliveryId?: string): Promise<boolean>;
+    /** The terminal's menu state (`menuState`) once a hook that is still deciding has had a moment to finish. */
+    private menuSettled;
+    /**
+     * A refusal the server hands back. Nothing typed (the switch): the claim is
+     * released, so a redelivery after a lost ack is judged afresh rather than
+     * answered "done". Possibly typed (`reply_interrupted`): the claim stays, so it
+     * is never typed twice, and a redelivery is refused the same way.
+     */
+    private refuse;
+    /**
+     * A local failure before anything reached the pane: the claim is released and
+     * the harness acks 503, so the outbox sends it again and it is typed once.
+     */
+    private retryLater;
+    /**
+     * A delivery already acted on: done, unless it ended in a refusal, which is said again
+     * (`decision_unconfirmed`: a decision an older CLI pressed keys for, which may have landed).
+     */
+    private repeat;
+}