@prohost/cli 0.14.0 → 0.16.0

package/dist/host/api.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The public API `prohost host` speaks: `/v1/computers/*`.
+ *
+ * Pairing is unauthenticated (the device code or redeem token is the proof);
+ * everything else carries the computer key as `X-API-Key`, the header every
+ * public-API call from this CLI uses. A run's own token replaces it for that
+ * run's heartbeat, events and completion (see `service.ts`).
+ */
+export interface ComputerApiOptions {
+    baseUrl: string;
+    apiKey?: string;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+export interface JsonResponse {
+    /** HTTP status, or `0` when no answer arrived. */
+    status: number;
+    /** The parsed body, when it was a JSON object. */
+    body?: Record<string, unknown>;
+    /** Why no answer arrived, or a short excerpt of a refusal. */
+    error?: string;
+}
+export declare function callJson(options: ComputerApiOptions, path: string, body: unknown, method?: 'POST' | 'GET' | 'DELETE'): Promise<JsonResponse>;
+export declare const PAIRING_START_PATH = "/v1/computers/pairing/start";
+export declare const PAIRING_POLL_PATH = "/v1/computers/pairing/poll";
+export declare const PAIRING_REDEEM_PATH = "/v1/computers/pairing/redeem";
+export declare const PAIRING_ADOPT_PATH = "/v1/computers/pairing/adopt";
+export declare function computerPath(computerId: string): string;
+export type RevokeResult = 'revoked' | 'already_gone' | 'failed';
+/**
+ * Remove this computer from its workspace, as the computer (`DELETE
+ * /v1/computers/{id}`): its key stops working. A key the server no longer
+ * knows (401) or a computer already removed (404 / 410) is already done.
+ */
+export declare function revokeComputer(options: ComputerApiOptions, computerId: string): Promise<{
+    result: RevokeResult;
+    status: number;
+    error?: string;
+}>;
+export declare function statusPath(computerId: string): string;
+export declare function eventsPath(computerId: string): string;
+export declare function claimPath(computerId: string, runId: string): string;
+/** One skill file the claim hands over, written into the run's workspace. */
+export interface SkillFile {
+    path: string;
+    content: string;
+}
+export interface ClaimedSkill {
+    key: string;
+    version?: string | number;
+    files: SkillFile[];
+}
+export type ClaimResult = {
+    kind: 'claimed';
+    runToken: string;
+    expiresAt?: string;
+    payload: Record<string, unknown>;
+    skills: ClaimedSkill[];
+}
+/** Another computer has it (409): skip it, never run it. */
+ | {
+    kind: 'elsewhere';
+}
+/** Gone server-side (404 / 410): nothing to run. */
+ | {
+    kind: 'gone';
+    status: number;
+}
+/** No answer, or one worth asking again (429 / 5xx). */
+ | {
+    kind: 'retry';
+    status: number;
+    error?: string;
+}
+/** Any other refusal. */
+ | {
+    kind: 'refused';
+    status: number;
+    error?: string;
+};
+/** Claim a run for this computer. Exactly one computer ever gets a 200. */
+export declare function claimRun(options: ComputerApiOptions, computerId: string, runId: string): Promise<ClaimResult>;

package/dist/host/api.js

@@ -0,0 +1,122 @@
+/**
+ * The public API `prohost host` speaks: `/v1/computers/*`.
+ *
+ * Pairing is unauthenticated (the device code or redeem token is the proof);
+ * everything else carries the computer key as `X-API-Key`, the header every
+ * public-API call from this CLI uses. A run's own token replaces it for that
+ * run's heartbeat, events and completion (see `service.ts`).
+ */
+import { USER_AGENT } from '../version.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+export async function callJson(options, path, body, method = 'POST') {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetchImpl(`${options.baseUrl.replace(/\/+$/, '')}${path}`, {
+            method,
+            redirect: 'error',
+            headers: {
+                'Content-Type': 'application/json',
+                'User-Agent': USER_AGENT,
+                ...(options.apiKey ? { 'X-API-Key': options.apiKey } : {}),
+            },
+            ...(method === 'POST' ? { body: JSON.stringify(body ?? {}) } : {}),
+            signal: controller.signal,
+        });
+        const text = await response.text().catch(() => '');
+        let parsed;
+        try {
+            const value = text ? JSON.parse(text) : undefined;
+            if (value && typeof value === 'object' && !Array.isArray(value))
+                parsed = value;
+        }
+        catch {
+            parsed = undefined;
+        }
+        const ok = response.status >= 200 && response.status < 300;
+        return { status: response.status, body: parsed, ...(ok ? {} : { error: text.slice(0, 300) }) };
+    }
+    catch (err) {
+        if (controller.signal.aborted)
+            return { status: 0, error: `timed out after ${Math.round(timeoutMs / 1000)}s` };
+        return { status: 0, error: err instanceof Error ? err.message : String(err) };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export const PAIRING_START_PATH = '/v1/computers/pairing/start';
+export const PAIRING_POLL_PATH = '/v1/computers/pairing/poll';
+export const PAIRING_REDEEM_PATH = '/v1/computers/pairing/redeem';
+export const PAIRING_ADOPT_PATH = '/v1/computers/pairing/adopt';
+export function computerPath(computerId) {
+    return `/v1/computers/${encodeURIComponent(computerId)}`;
+}
+/**
+ * Remove this computer from its workspace, as the computer (`DELETE
+ * /v1/computers/{id}`): its key stops working. A key the server no longer
+ * knows (401) or a computer already removed (404 / 410) is already done.
+ */
+export async function revokeComputer(options, computerId) {
+    const response = await callJson(options, computerPath(computerId), undefined, 'DELETE');
+    if (response.status >= 200 && response.status < 300)
+        return { result: 'revoked', status: response.status };
+    if ([401, 404, 410].includes(response.status))
+        return { result: 'already_gone', status: response.status };
+    return { result: 'failed', status: response.status, ...(response.error ? { error: response.error } : {}) };
+}
+export function statusPath(computerId) {
+    return `/v1/computers/${encodeURIComponent(computerId)}/status`;
+}
+export function eventsPath(computerId) {
+    return `/v1/computers/${encodeURIComponent(computerId)}/events`;
+}
+export function claimPath(computerId, runId) {
+    return `/v1/computers/${encodeURIComponent(computerId)}/runs/${encodeURIComponent(runId)}/claim`;
+}
+function parseSkills(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((raw) => {
+        const skill = raw;
+        if (!skill || typeof skill.key !== 'string' || !Array.isArray(skill.files))
+            return [];
+        const files = skill.files.flatMap((f) => {
+            const file = f;
+            return file && typeof file.path === 'string' && typeof file.content === 'string'
+                ? [{ path: file.path, content: file.content }]
+                : [];
+        });
+        const version = typeof skill.version === 'string' || typeof skill.version === 'number' ? skill.version : undefined;
+        return [{ key: skill.key, ...(version !== undefined ? { version } : {}), files }];
+    });
+}
+/** Claim a run for this computer. Exactly one computer ever gets a 200. */
+export async function claimRun(options, computerId, runId) {
+    const response = await callJson(options, claimPath(computerId, runId), {});
+    if (response.status === 200 || response.status === 201) {
+        const body = response.body ?? {};
+        const token = body.run_token;
+        const payload = body.payload;
+        if (typeof token !== 'string' || !token || !payload || typeof payload !== 'object' || Array.isArray(payload)) {
+            return { kind: 'refused', status: response.status, error: 'claim answer carried no run token or payload' };
+        }
+        return {
+            kind: 'claimed',
+            runToken: token,
+            ...(typeof body.expires_at === 'string' ? { expiresAt: body.expires_at } : {}),
+            payload: payload,
+            skills: parseSkills(body.skills),
+        };
+    }
+    if (response.status === 409)
+        return { kind: 'elsewhere' };
+    if (response.status === 404 || response.status === 410)
+        return { kind: 'gone', status: response.status };
+    if (response.status === 0 || response.status === 429 || response.status >= 500) {
+        return { kind: 'retry', status: response.status, error: response.error };
+    }
+    return { kind: 'refused', status: response.status, error: response.error };
+}

package/dist/host/capacity.d.ts

@@ -0,0 +1,41 @@
+/**
+ * How many things this computer works on at once, and when it takes no new work.
+ */
+import type { MemoryPressure } from '../codehost/host_stats.js';
+export type Workload = 'coding' | 'chat';
+/** Memory one run takes, by what the employees here mostly do. */
+export declare const RUN_MEMORY_GB: Record<Workload, number>;
+/** Never recommend more than this, however big the machine. */
+export declare const MAX_RECOMMENDED_CAPACITY = 16;
+/** Memory kept for the person using the computer: the larger of these. */
+export declare const RESERVE_MIN_GB = 8;
+export declare const RESERVE_SHARE = 0.25;
+/**
+ * The recommended capacity: memory after the reserve, divided by what one run
+ * takes; at most half the cores (a run is a CLI plus the tools it starts); at
+ * least 1, at most {@link MAX_RECOMMENDED_CAPACITY}.
+ */
+export declare function recommendCapacity(hardware: {
+    memoryGb: number;
+    cores: number;
+    workload?: Workload;
+}): number;
+/** What the server's `capacity` (null = use recommended) and the local recommendation come to. */
+export declare function effectiveCapacity(configured: number | null | undefined, recommended: number): number;
+export type HeldReason = 'paused' | 'pressure' | 'battery';
+export interface HoldInputs {
+    paused: boolean;
+    holdOnPressure: boolean;
+    holdOnBattery: boolean;
+    memoryPressure: MemoryPressure | null;
+    onBattery: boolean | null;
+}
+/**
+ * Why new work waits, or `null`. Work already running is never stopped by a
+ * hold; it only keeps the next run from starting.
+ *
+ * Pressure holds only at `critical`: `elevated` is routine on a busy Mac
+ * (the compressor is working), and holding on it would idle a computer that is
+ * coping. A battery hold needs the OS to say it is on battery — unknown is not.
+ */
+export declare function holdReason(inputs: HoldInputs): HeldReason | null;

package/dist/host/capacity.js

@@ -0,0 +1,48 @@
+/**
+ * How many things this computer works on at once, and when it takes no new work.
+ */
+/** Memory one run takes, by what the employees here mostly do. */
+export const RUN_MEMORY_GB = { coding: 4, chat: 1.5 };
+/** Never recommend more than this, however big the machine. */
+export const MAX_RECOMMENDED_CAPACITY = 16;
+/** Memory kept for the person using the computer: the larger of these. */
+export const RESERVE_MIN_GB = 8;
+export const RESERVE_SHARE = 0.25;
+/**
+ * The recommended capacity: memory after the reserve, divided by what one run
+ * takes; at most half the cores (a run is a CLI plus the tools it starts); at
+ * least 1, at most {@link MAX_RECOMMENDED_CAPACITY}.
+ */
+export function recommendCapacity(hardware) {
+    const memory = Number.isFinite(hardware.memoryGb) ? Math.max(0, hardware.memoryGb) : 0;
+    const cores = Number.isFinite(hardware.cores) ? Math.max(1, Math.floor(hardware.cores)) : 1;
+    const perRun = RUN_MEMORY_GB[hardware.workload ?? 'chat'];
+    const reserve = Math.max(RESERVE_MIN_GB, memory * RESERVE_SHARE);
+    const byMemory = Math.floor((memory - reserve) / perRun);
+    const byCores = Math.floor(cores / 2);
+    return Math.max(1, Math.min(MAX_RECOMMENDED_CAPACITY, byMemory, byCores));
+}
+/** What the server's `capacity` (null = use recommended) and the local recommendation come to. */
+export function effectiveCapacity(configured, recommended) {
+    if (typeof configured === 'number' && Number.isInteger(configured) && configured >= 1) {
+        return Math.min(configured, 64);
+    }
+    return recommended;
+}
+/**
+ * Why new work waits, or `null`. Work already running is never stopped by a
+ * hold; it only keeps the next run from starting.
+ *
+ * Pressure holds only at `critical`: `elevated` is routine on a busy Mac
+ * (the compressor is working), and holding on it would idle a computer that is
+ * coping. A battery hold needs the OS to say it is on battery — unknown is not.
+ */
+export function holdReason(inputs) {
+    if (inputs.paused)
+        return 'paused';
+    if (inputs.holdOnPressure && inputs.memoryPressure === 'critical')
+        return 'pressure';
+    if (inputs.holdOnBattery && inputs.onBattery === true)
+        return 'battery';
+    return null;
+}

package/dist/host/command.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `prohost host …` — one background service per computer, serving every AI
+ * employee placed on it, plus the terminal sessions opened on it.
+ *
+ *     prohost host pair [--name <n>] [--token <redeem_token>|-] [--expect-account <id>]
+ *     prohost host unpair
+ *     prohost host run
+ *     prohost host install [--label <id>] [--dedicated --service-user <name> [--service-home <dir>]
+ *                          [--claude-token-file <path>]] | uninstall [--label <id>]
+ *     prohost host status [--json] [--label <id>] | logins [--json] | logins add --runtime claude_code|codex
+ *     prohost host pause | resume
+ *     prohost host migrate [--from <home>]… [--home <dir,…>] [--keep-services] [--dry-run] [--json]
+ */
+import type { InstallIo } from './install.js';
+import type { LoginInfo } from './logins.js';
+import { runMigrate } from './migrate.js';
+type Flags = Record<string, string | boolean>;
+export interface HostIo {
+    env?: NodeJS.ProcessEnv;
+    out?: (line: string) => void;
+    err?: (line: string) => void;
+    stdin?: AsyncIterable<string | Buffer>;
+    now?: () => number;
+    fetchImpl?: typeof fetch;
+    detectLogins?: () => Promise<LoginInfo[]>;
+    platform?: NodeJS.Platform;
+    /** Seams for `install` / `uninstall` (service manager calls, files). */
+    serviceIo?: InstallIo;
+    /** Seams for `migrate`. */
+    migrate?: Partial<Parameters<typeof runMigrate>[0]>;
+    /** Positionals after the subcommand (`logins add`). */
+    args?: string[];
+    /** Every value of a repeated flag (`--from a --from b`). */
+    repeated?: Record<string, string[]>;
+    /** Is this an interactive terminal (asks before adding a computer to a workspace)? */
+    interactive?: boolean;
+    /** Answers a yes/no question on the terminal. */
+    ask?: (question: string) => Promise<boolean>;
+    /** Runs a sign-in in this terminal (`logins add`); resolves its exit code. */
+    signIn?: (command: string, args: string[], env: NodeJS.ProcessEnv) => Promise<number | null>;
+    /** Whether the CLI runs as Electron-as-Node (the desktop app's bundled CLI). */
+    electron?: boolean;
+    /** Where dedicated services publish their state (tests). */
+    sharedBase?: string;
+}
+export declare function hardwareFacts(): Record<string, unknown>;
+/**
+ * `host status --json`: what the desktop app and scripts read. Always an
+ * answer — `{paired: false, …}` before pairing. When this home runs no
+ * service but a dedicated one runs on the computer, that one is reported
+ * (`service.dedicated`), from the state it publishes for the logged-in user.
+ */
+export declare function statusJson(env: NodeJS.ProcessEnv, now?: number, options?: {
+    sharedBase?: string;
+    label?: string;
+    platform?: NodeJS.Platform;
+}): Record<string, unknown>;
+export declare function runHost(subcommand: string | undefined, flags: Flags, printHelp: () => void, io?: HostIo): Promise<number>;
+export {};