@prohost/cli 0.15.0 → 0.16.1

package/dist/host/service.d.ts

@@ -0,0 +1,114 @@
+/**
+ * `prohost host run` — one service for every AI employee placed on this computer.
+ *
+ * It holds one event stream, authenticated as the computer. For each
+ * `agent.run_requested` frame it:
+ *
+ * 1. verifies the signature and queues the run (see `scheduler.ts` for the order);
+ * 2. when a slot is free and the run's AI login has room, **claims** it
+ *    (`POST /v1/computers/{id}/runs/{run_id}/claim`) — exactly one computer
+ *    gets it; a 409 means another did, and it is skipped;
+ * 3. writes the employee's skills into its workspace and runs it the way
+ *    `agent run` would (`executeHostedRun`), as the employee, with the run's
+ *    own token for the heartbeat, tool events, reply and completion.
+ *
+ * Every 30 s (and on any change) it reports the machine — memory, CPU,
+ * pressure, battery, slots, AI logins, what's running — and the answer is the
+ * computer's config: capacity, holds, sharing between logins, placements.
+ *
+ * Terminal sessions (Code threads) are hosted by the same service with the
+ * computer credential, when hosting is on for the code-host home.
+ *
+ * Stopping drains: no new run starts, runs going finish, then it returns. A
+ * newer CLI on disk (an update) drains the same way and exits for the service
+ * manager to restart it.
+ */
+import type { spawn } from 'node:child_process';
+import WebSocket from 'ws';
+import type { CommandRunner } from '../agent/accounts.js';
+import { executeHostedRun } from '../agent/run.js';
+import type { AgentRunOptions } from '../agent/run.js';
+import type { CodeHostLike } from '../codehost/host.js';
+import type { HostStats } from '../codehost/host_stats.js';
+import type { Workload } from './capacity.js';
+import type { ComputerCredentials } from './computer.js';
+import type { LoginInfo } from './logins.js';
+import { PeakMemory } from './peak_memory.js';
+import type { ComputerConfig } from './status.js';
+/** Set by a dedicated install (`host install --dedicated`): reported as `dedicated` in the status. */
+export declare const DEDICATED_ENV = "PROHOST_HOST_DEDICATED";
+/** What a terminal start is answered with while the computer is paused. */
+export declare const PAUSED_START_REASON = "This computer is paused: it opens no new terminal sessions until it is resumed.";
+/** Declared in every status body: this is a `prohost host` service. */
+export declare const COMPUTER_HOST_CAPABILITY = "computer_host_v1";
+export declare const STATUS_INTERVAL_MS = 30000;
+/** Status on change goes out at most this often. */
+export declare const STATUS_MIN_SPACING_MS = 3000;
+export declare const LOGIN_REFRESH_MS: number;
+export declare const CONTROL_POLL_MS = 2000;
+export declare const UPDATE_CHECK_MS = 60000;
+/** A claim with no answer is tried again this many times before the run is left to the server. */
+export declare const MAX_CLAIM_ATTEMPTS = 5;
+/** How many times one run may move to another login after a usage limit. */
+export declare const MAX_LOGIN_MOVES = 3;
+/** Exit code that asks a service manager to restart (a newer CLI is installed). */
+export declare const RESTART_EXIT_CODE = 75;
+export interface HostServiceOptions {
+    computer: ComputerCredentials;
+    env?: NodeJS.ProcessEnv;
+    machine?: string;
+    log?: (line: string) => void;
+    /** Aborting it drains the service. */
+    signal?: AbortSignal;
+    /** Aborting it stops runs going too (a second Ctrl-C). */
+    hardStop?: AbortSignal;
+    /** Per-run wall clock (0 = none) and silence watchdog, as `agent run`. */
+    timeoutMs?: number;
+    idleTimeoutMs?: number;
+    allowUnverified?: boolean;
+    workload?: Workload;
+    /**
+     * An adopted employee's old working directory (`host migrate`): its
+     * sessions are filed under it, so its runs keep working there.
+     */
+    workdirFor?: (agentId: string) => string | undefined;
+    /** Called with each config the server sends (placements decide which adopted homes still run on their own). */
+    onConfig?: (config: ComputerConfig) => void;
+    webSocketCtor?: typeof WebSocket;
+    fetchImpl?: typeof fetch;
+    spawnImpl?: typeof spawn;
+    probeImpl?: AgentRunOptions['probeImpl'];
+    accountCommandRunner?: CommandRunner;
+    capabilityProbe?: AgentRunOptions['capabilityProbe'];
+    sleepImpl?: (ms: number) => Promise<void>;
+    stats?: {
+        sample(): Promise<HostStats>;
+        latest(): HostStats | undefined;
+    };
+    hardware?: {
+        memoryGb: number;
+        cores: number;
+    };
+    peak?: PeakMemory;
+    detectLogins?: () => Promise<LoginInfo[]>;
+    codeHost?: CodeHostLike | null;
+    executeRun?: typeof executeHostedRun;
+    updateAvailable?: () => boolean;
+    statusIntervalMs?: number;
+    updateCheckMs?: number;
+    heartbeatIntervalMs?: number;
+    livenessTimeoutMs?: number;
+    maxConnections?: number;
+    now?: () => number;
+}
+export interface HostServiceResult {
+    /** A newer CLI is on disk: exit with {@link RESTART_EXIT_CODE} so the service manager restarts it. */
+    restart: boolean;
+    /** Stopped for a reason retrying can't fix (the computer was removed, the key revoked). */
+    fatal?: string;
+    runsStarted: number;
+    runsSkipped: number;
+}
+/** The CLI's own entry file: when it changes on disk, an update was installed. */
+export declare function entrypointStamp(entry?: string): () => boolean;
+export declare function runHostService(options: HostServiceOptions): Promise<HostServiceResult>;