@prohost/cli 0.14.0 → 0.16.0

package/dist/host/migrate.d.ts

@@ -0,0 +1,165 @@
+/**
+ * `prohost host migrate` — bring this machine's existing agent homes and the
+ * desktop app's terminal-hosting home under the host service, keeping their
+ * credentials: nothing is paired again.
+ *
+ * What it adopts:
+ *
+ * - **Agent homes** (`agent.json` + `sessions.json`): every home a launchd
+ *   agent `ai.prohost.agent.*` or the desktop app's `ai.prohost.desktop[.dev].code-host`
+ *   runs (macOS; its `--exec`, `--workdir`,
+ *   `--concurrency`, `--repos`, timeouts and `--safe-tools` are read from the
+ *   plist), `$PROHOST_HOME` itself, and each `--home` given. Each one's
+ *   conversation sessions are copied into the employee's host home, so
+ *   conversations continue where they were. Until ProhostAI places that
+ *   employee on this computer, `host run` keeps serving it with its own
+ *   credential exactly as `agent run` did; once it is placed, the computer
+ *   serves it and the old connection goes quiet.
+ * - **The terminal-hosting home** — a home whose daemon runs `--host-only`,
+ *   or whose Code-thread hosting is on (`code-host/settings.json`). The host
+ *   service hosts terminal sessions from that home, so its open terminals,
+ *   opened folders and switches carry over (`code_host_home`).
+ * - **Old launchd agents** it adopted are stopped and removed (`--keep-services`
+ *   leaves them), so one service — not two — answers for each employee.
+ *
+ * What it cannot adopt:
+ *
+ * - A systemd unit or Windows task written by hand from `agent install-daemon`
+ *   (only launchd agents are found by themselves): pass `--home <dir>`, and
+ *   stop the old unit yourself.
+ * - An agent the desktop app supervises itself: the desktop stops it.
+ * - Its `--exec` when it isn't Claude Code or Codex: such a home keeps running
+ *   under its own credential, and is never served as the computer.
+ * - A home whose `agent.json` is missing or unreadable, or whose pairing was
+ *   revoked (it is listed, not adopted).
+ * - Sessions of a home that ran in a custom `--workdir` (a code checkout),
+ *   once the computer serves it: Claude Code files sessions by working
+ *   directory, and the host never writes skills into a checkout, so those
+ *   conversations start a fresh session there. (Until it is placed, its own
+ *   connection keeps running in that `--workdir`.)
+ *
+ * Running it again keeps what an earlier run adopted (including settings read
+ * from a plist it has since removed) and adds what is new.
+ * - `prohost listen` and `prohost usage` daemons, which are not agents.
+ */
+import type { MachineFacts } from './computer.js';
+import type { ServiceRunner } from './install.js';
+export interface AdoptedHome {
+    home: string;
+    agent_id: string;
+    agent_name: string;
+    /** The `--exec` it ran with, when known; `null` for a host-only home. */
+    exec: string | null;
+    host_only: boolean;
+    /** The working directory it ran in (`--workdir`, else its own workspace): its own connection keeps it. */
+    workdir?: string;
+    /**
+     * Where the computer runs it once placed: the old workspace, when that was
+     * the home's own (its sessions are filed under it). Never a code checkout.
+     */
+    hosted_workdir?: string;
+    concurrency?: number;
+    repos?: string[];
+    timeout_seconds?: number;
+    idle_timeout_seconds?: number;
+    safe_tools?: boolean;
+    /** The launchd agent it ran under, if any. */
+    launchd?: {
+        label: string;
+        plist: string;
+    };
+    sessions_copied: number;
+}
+export interface Adopted {
+    v: 1;
+    adopted_at: string;
+    homes: AdoptedHome[];
+    code_host_home: string | null;
+}
+export declare function loadAdopted(env?: NodeJS.ProcessEnv): Adopted | undefined;
+/** `ProgramArguments` and `EnvironmentVariables` out of an agent plist this CLI wrote. */
+export declare function parseAgentPlist(xml: string): {
+    args: string[];
+    env: Record<string, string>;
+};
+/** The `agent run` flags out of a daemon's arguments. */
+export declare function harnessFlags(args: readonly string[]): {
+    exec?: string;
+    hostOnly: boolean;
+    workdir?: string;
+    concurrency?: number;
+    repos?: string[];
+    timeoutSeconds?: number;
+    idleTimeoutSeconds?: number;
+    safeTools: boolean;
+};
+interface Candidate {
+    home: string;
+    /** Named by the caller (`--home` / `--from`), not found by discovery. */
+    explicit?: boolean;
+    args?: string[];
+    launchd?: {
+        label: string;
+        plist: string;
+    };
+}
+/** Homes worth looking at: launchd agents' homes, `$PROHOST_HOME`, and each `--home`. */
+export declare function findCandidates(options: {
+    env?: NodeJS.ProcessEnv;
+    homes?: string[];
+    /** `--from`: only these homes (and earlier adoptions) — no discovery. */
+    only?: string[];
+    launchAgentsDir?: string;
+    platform?: NodeJS.Platform;
+}): Candidate[];
+export interface MigrateReport {
+    /** Set when nothing was done: the host service is running (it owns the ledger). */
+    refused?: string;
+    adopted: AdoptedHome[];
+    skipped: Array<{
+        home: string;
+        reason: string;
+    }>;
+    codeHostHome: string | null;
+    servicesStopped: string[];
+    notes: string[];
+}
+export declare function runMigrate(options: {
+    env?: NodeJS.ProcessEnv;
+    homes?: string[];
+    /** `--from`: adopt only these homes (repeatable); nothing is discovered. */
+    only?: string[];
+    keepServices?: boolean;
+    dryRun?: boolean;
+    launchAgentsDir?: string;
+    platform?: NodeJS.Platform;
+    uid?: number;
+    run?: ServiceRunner;
+}): MigrateReport;
+export type ComputerAdoption = {
+    status: 'already_paired';
+} | {
+    status: 'adopted';
+    computer_id: string;
+    account: {
+        id: string;
+        name: string | null;
+    };
+} | {
+    status: 'not_adopted';
+    reason: string;
+};
+/**
+ * Get this machine's computer credential from one of the adopted homes' agent
+ * keys (`POST /v1/computers/pairing/adopt`) — no pairing code, no approval:
+ * the pairing's creator already owns the machine. Tried home by home until one
+ * is accepted; nothing is saved unless one is.
+ */
+export declare function adoptComputer(options: {
+    env?: NodeJS.ProcessEnv;
+    report: MigrateReport;
+    fetchImpl?: typeof fetch;
+    facts?: MachineFacts;
+    name?: string;
+}): Promise<ComputerAdoption>;
+export {};

package/dist/host/migrate.js

@@ -0,0 +1,364 @@
+/**
+ * `prohost host migrate` — bring this machine's existing agent homes and the
+ * desktop app's terminal-hosting home under the host service, keeping their
+ * credentials: nothing is paired again.
+ *
+ * What it adopts:
+ *
+ * - **Agent homes** (`agent.json` + `sessions.json`): every home a launchd
+ *   agent `ai.prohost.agent.*` or the desktop app's `ai.prohost.desktop[.dev].code-host`
+ *   runs (macOS; its `--exec`, `--workdir`,
+ *   `--concurrency`, `--repos`, timeouts and `--safe-tools` are read from the
+ *   plist), `$PROHOST_HOME` itself, and each `--home` given. Each one's
+ *   conversation sessions are copied into the employee's host home, so
+ *   conversations continue where they were. Until ProhostAI places that
+ *   employee on this computer, `host run` keeps serving it with its own
+ *   credential exactly as `agent run` did; once it is placed, the computer
+ *   serves it and the old connection goes quiet.
+ * - **The terminal-hosting home** — a home whose daemon runs `--host-only`,
+ *   or whose Code-thread hosting is on (`code-host/settings.json`). The host
+ *   service hosts terminal sessions from that home, so its open terminals,
+ *   opened folders and switches carry over (`code_host_home`).
+ * - **Old launchd agents** it adopted are stopped and removed (`--keep-services`
+ *   leaves them), so one service — not two — answers for each employee.
+ *
+ * What it cannot adopt:
+ *
+ * - A systemd unit or Windows task written by hand from `agent install-daemon`
+ *   (only launchd agents are found by themselves): pass `--home <dir>`, and
+ *   stop the old unit yourself.
+ * - An agent the desktop app supervises itself: the desktop stops it.
+ * - Its `--exec` when it isn't Claude Code or Codex: such a home keeps running
+ *   under its own credential, and is never served as the computer.
+ * - A home whose `agent.json` is missing or unreadable, or whose pairing was
+ *   revoked (it is listed, not adopted).
+ * - Sessions of a home that ran in a custom `--workdir` (a code checkout),
+ *   once the computer serves it: Claude Code files sessions by working
+ *   directory, and the host never writes skills into a checkout, so those
+ *   conversations start a fresh session there. (Until it is placed, its own
+ *   connection keeps running in that `--workdir`.)
+ *
+ * Running it again keeps what an earlier run adopted (including settings read
+ * from a plist it has since removed) and adds what is new.
+ * - `prohost listen` and `prohost usage` daemons, which are not agents.
+ */
+import { existsSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { loadCredentials, prohostHome } from '../agent/credentials.js';
+import { LAUNCHD_LABEL_PREFIX } from '../agent/daemon.js';
+import { resolveAgentAccount } from '../agent/accounts.js';
+import { PAIRING_ADOPT_PATH, callJson } from './api.js';
+import { machineFacts } from './computer.js';
+import { credentialsFrom } from './pair.js';
+import { isCodexExec } from '../agent/codex.js';
+import { SessionStore } from '../agent/sessionstore.js';
+import { HostLedger } from './ledger.js';
+import { loadSettings as loadCodeHostSettings } from '../codehost/settings.js';
+import { acquireHostLock, adoptedPath, employeeHome, readObject, saveComputer, tryLoadComputer, writePrivateFile, } from './computer.js';
+import { defaultServiceRunner } from './install.js';
+export function loadAdopted(env = process.env) {
+    const raw = readObject(adoptedPath(env));
+    if (!raw || raw.v !== 1 || !Array.isArray(raw.homes))
+        return undefined;
+    return raw;
+}
+function unescapeXml(value) {
+    return value
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, '&');
+}
+/** `ProgramArguments` and `EnvironmentVariables` out of an agent plist this CLI wrote. */
+export function parseAgentPlist(xml) {
+    const argsBlock = /<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/.exec(xml)?.[1] ?? '';
+    const args = [...argsBlock.matchAll(/<string>([\s\S]*?)<\/string>/g)].map((m) => unescapeXml(m[1]));
+    const envBlock = /<key>EnvironmentVariables<\/key>\s*<dict>([\s\S]*?)<\/dict>/.exec(xml)?.[1] ?? '';
+    const env = {};
+    for (const m of envBlock.matchAll(/<key>([\s\S]*?)<\/key>\s*<string>([\s\S]*?)<\/string>/g)) {
+        env[unescapeXml(m[1])] = unescapeXml(m[2]);
+    }
+    return { args, env };
+}
+/** The `agent run` flags out of a daemon's arguments. */
+export function harnessFlags(args) {
+    const value = (flag) => {
+        const index = args.indexOf(flag);
+        return index >= 0 && index + 1 < args.length ? args[index + 1] : undefined;
+    };
+    const number = (flag) => {
+        const raw = value(flag);
+        const parsed = raw === undefined ? Number.NaN : Number(raw);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    };
+    const repos = value('--repos');
+    return {
+        ...(value('--exec') !== undefined ? { exec: value('--exec') } : {}),
+        hostOnly: args.includes('--host-only'),
+        ...(value('--workdir') !== undefined ? { workdir: value('--workdir') } : {}),
+        ...(number('--concurrency') !== undefined ? { concurrency: number('--concurrency') } : {}),
+        ...(repos ? { repos: repos.split(',').filter(Boolean) } : {}),
+        ...(number('--timeout') !== undefined ? { timeoutSeconds: number('--timeout') } : {}),
+        ...(number('--idle-timeout') !== undefined ? { idleTimeoutSeconds: number('--idle-timeout') } : {}),
+        safeTools: args.includes('--safe-tools') || args.includes('--no-skip-permissions'),
+    };
+}
+/** The desktop app's terminal-hosting agent: `ai.prohost.desktop[.dev].code-host`. */
+const DESKTOP_CODE_HOST_PLIST = /^ai\.prohost\.desktop(\.dev)?\.code-host\.plist$/;
+function isAgentPlist(name) {
+    return (name.startsWith(`${LAUNCHD_LABEL_PREFIX}.`) && name.endsWith('.plist')) || DESKTOP_CODE_HOST_PLIST.test(name);
+}
+/** Homes worth looking at: launchd agents' homes, `$PROHOST_HOME`, and each `--home`. */
+export function findCandidates(options) {
+    const env = options.env ?? process.env;
+    const out = [];
+    const seen = new Set();
+    const add = (candidate) => {
+        const key = path.resolve(candidate.home);
+        const existing = out.find((c) => path.resolve(c.home) === key);
+        if (existing) {
+            if (!existing.args && candidate.args)
+                Object.assign(existing, candidate);
+            return;
+        }
+        seen.add(key);
+        out.push(candidate);
+    };
+    if (options.only) {
+        for (const home of options.only)
+            add({ home: path.resolve(home), explicit: true });
+        for (const home of options.homes ?? [])
+            add({ home: path.resolve(home), explicit: true });
+        return out;
+    }
+    if ((options.platform ?? process.platform) === 'darwin') {
+        const dir = options.launchAgentsDir ?? path.join(env.HOME || os.homedir(), 'Library', 'LaunchAgents');
+        let names = [];
+        try {
+            names = readdirSync(dir).sort();
+        }
+        catch {
+            names = [];
+        }
+        for (const name of names) {
+            if (!isAgentPlist(name))
+                continue;
+            const plist = path.join(dir, name);
+            let parsed;
+            try {
+                parsed = parseAgentPlist(readFileSync(plist, 'utf8'));
+            }
+            catch {
+                continue;
+            }
+            if (!parsed.args.includes('agent') || !parsed.args.includes('run'))
+                continue;
+            add({
+                home: parsed.env.PROHOST_HOME || path.join(env.HOME || os.homedir(), '.prohost'),
+                args: parsed.args,
+                launchd: { label: name.slice(0, -'.plist'.length), plist },
+            });
+        }
+    }
+    add({ home: prohostHome(env) });
+    for (const home of options.homes ?? [])
+        add({ home: path.resolve(home), explicit: true });
+    return out;
+}
+/** The AI login an adopted agent ran on (its `account`, else the default), for a Claude or Codex `--exec`. */
+function loginKeyFor(exec, account, env) {
+    if (!exec)
+        return undefined;
+    try {
+        return resolveAgentAccount(account, isCodexExec(exec) ? 'codex' : 'claude_code', env)?.key;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Copy a home's conversation sessions into the employee's host home; the
+ * host's own entries win. Each copied conversation sticks to the login it ran
+ * on (`login`), so its first hosted turn resumes where the transcript is.
+ */
+function copySessions(fromHome, agentId, env, login) {
+    const from = path.join(fromHome, 'sessions.json');
+    let entries = [];
+    try {
+        const parsed = JSON.parse(readFileSync(from, 'utf8'));
+        entries = Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return 0;
+    }
+    const target = SessionStore.load({ ...env, PROHOST_HOME: employeeHome(agentId, env) });
+    const ledger = login ? HostLedger.load(env) : undefined;
+    let copied = 0;
+    for (const entry of entries) {
+        if (typeof entry?.key !== 'string' || typeof entry.session_id !== 'string')
+            continue;
+        if (!entry.key.startsWith(`${agentId}/`))
+            continue;
+        if (target.get(entry.key))
+            continue;
+        target.remember(entry.key, entry.session_id);
+        if (ledger && login && !ledger.conversationLogin(entry.key))
+            ledger.setConversationLogin(entry.key, login);
+        copied += 1;
+    }
+    return copied;
+}
+export function runMigrate(options) {
+    const env = options.env ?? process.env;
+    const run = options.run ?? defaultServiceRunner;
+    const report = { adopted: [], skipped: [], codeHostHome: null, servicesStopped: [], notes: [] };
+    // The running service is the ledger's only writer: migrating beside it could
+    // drop a run it just claimed. Stop it first (a dry run changes nothing).
+    const lock = options.dryRun ? undefined : acquireHostLock(env);
+    if (lock && !lock.ok) {
+        report.refused = `the host service is running (pid ${lock.heldBy}); stop it first (prohost host uninstall, or quit it), then migrate`;
+        return report;
+    }
+    try {
+        return migrateLocked(options, env, run, report);
+    }
+    finally {
+        if (lock?.ok)
+            lock.release();
+    }
+}
+function migrateLocked(options, env, run, report) {
+    const earlier = loadAdopted(env);
+    const previous = new Map((earlier?.homes ?? []).map((home) => [path.resolve(home.home), home]));
+    // Homes adopted before are looked at again, so their settings are kept.
+    const candidates = findCandidates({ ...options, homes: [...(options.homes ?? []), ...[...previous.values()].map((h) => h.home)] });
+    for (const candidate of candidates) {
+        if (!existsSync(path.join(candidate.home, 'agent.json'))) {
+            if (candidate.args)
+                report.skipped.push({ home: candidate.home, reason: 'no agent.json' });
+            continue;
+        }
+        let credentials;
+        try {
+            credentials = loadCredentials({ ...env, PROHOST_HOME: candidate.home });
+        }
+        catch (err) {
+            report.skipped.push({ home: candidate.home, reason: err instanceof Error ? err.message : String(err) });
+            continue;
+        }
+        const agentId = credentials.agent?.id;
+        if (typeof agentId !== 'string' || !/^[A-Za-z0-9-]{1,64}$/.test(agentId)) {
+            report.skipped.push({ home: candidate.home, reason: 'agent.json names no employee' });
+            continue;
+        }
+        const flags = harnessFlags(candidate.args ?? []);
+        const codeHosting = loadCodeHostSettings({ ...env, PROHOST_HOME: candidate.home }).enabled;
+        // A home that hosts terminals and runs no known agent is the terminal-hosting home.
+        const hostOnly = flags.hostOnly || (!flags.exec && codeHosting && (candidate.args !== undefined || candidate.explicit === true));
+        const ownWorkspace = path.join(candidate.home, 'workspace');
+        // Read from the plist this run, else kept from an earlier adoption (whose plist is gone).
+        const before = candidate.args ? undefined : previous.get(path.resolve(candidate.home));
+        const workdir = flags.workdir ?? before?.workdir ?? ownWorkspace;
+        const ownOnly = path.resolve(workdir) === path.resolve(ownWorkspace);
+        if (!ownOnly && !before) {
+            report.notes.push(`${credentials.agent.name}: ran in ${workdir}; once placed on this computer its conversations start fresh sessions`);
+        }
+        const adopted = before
+            ? { ...before, agent_id: agentId, agent_name: credentials.agent.name, sessions_copied: 0 }
+            : {
+                home: candidate.home,
+                agent_id: agentId,
+                agent_name: credentials.agent.name,
+                exec: hostOnly ? null : (flags.exec ?? null),
+                host_only: hostOnly,
+                workdir,
+                ...(ownOnly ? { hosted_workdir: ownWorkspace } : {}),
+                ...(flags.concurrency !== undefined ? { concurrency: flags.concurrency } : {}),
+                ...(flags.repos ? { repos: flags.repos } : {}),
+                ...(flags.timeoutSeconds !== undefined ? { timeout_seconds: flags.timeoutSeconds } : {}),
+                ...(flags.idleTimeoutSeconds !== undefined ? { idle_timeout_seconds: flags.idleTimeoutSeconds } : {}),
+                ...(flags.safeTools ? { safe_tools: true } : {}),
+                ...(candidate.launchd ? { launchd: candidate.launchd } : {}),
+                sessions_copied: 0,
+            };
+        if ((adopted.host_only || codeHosting) && report.codeHostHome === null)
+            report.codeHostHome = candidate.home;
+        if (!adopted.host_only && !options.dryRun) {
+            adopted.sessions_copied = copySessions(candidate.home, agentId, env, loginKeyFor(adopted.exec, credentials.account, env));
+        }
+        if (!adopted.host_only && !adopted.exec) {
+            report.notes.push(`${credentials.agent.name}: no --exec found; it is served only once placed on this computer`);
+        }
+        report.adopted.push(adopted);
+    }
+    report.codeHostHome ??= earlier?.code_host_home ?? null;
+    if (options.dryRun)
+        return report;
+    if (!options.keepServices) {
+        const uid = options.uid ?? process.getuid?.() ?? 0;
+        for (const home of report.adopted) {
+            if (!home.launchd)
+                continue;
+            run('launchctl', ['bootout', `gui/${uid}/${home.launchd.label}`]);
+            rmSync(home.launchd.plist, { force: true });
+            report.servicesStopped.push(home.launchd.label);
+        }
+    }
+    writePrivateFile(adoptedPath(env), {
+        v: 1,
+        adopted_at: new Date().toISOString(),
+        homes: report.adopted,
+        code_host_home: report.codeHostHome,
+    });
+    const computer = tryLoadComputer(env);
+    if (computer && report.codeHostHome && computer.code_host_home !== report.codeHostHome) {
+        saveComputer({ ...computer, code_host_home: report.codeHostHome }, env);
+    }
+    return report;
+}
+/**
+ * Get this machine's computer credential from one of the adopted homes' agent
+ * keys (`POST /v1/computers/pairing/adopt`) — no pairing code, no approval:
+ * the pairing's creator already owns the machine. Tried home by home until one
+ * is accepted; nothing is saved unless one is.
+ */
+export async function adoptComputer(options) {
+    const env = options.env ?? process.env;
+    if (tryLoadComputer(env))
+        return { status: 'already_paired' };
+    let facts;
+    try {
+        facts = options.facts ?? machineFacts({ env, name: options.name });
+    }
+    catch (err) {
+        return { status: 'not_adopted', reason: err instanceof Error ? err.message : String(err) };
+    }
+    const homes = [...options.report.adopted].sort((a, b) => Number(a.host_only) - Number(b.host_only));
+    let reason = 'no adopted home holds an agent key';
+    for (const home of homes) {
+        let credentials;
+        try {
+            credentials = loadCredentials({ ...env, PROHOST_HOME: home.home });
+        }
+        catch {
+            continue;
+        }
+        const response = await callJson({ baseUrl: credentials.base_url, apiKey: credentials.api_key, fetchImpl: options.fetchImpl }, PAIRING_ADOPT_PATH, facts);
+        if (response.status === 200 || response.status === 201) {
+            const stored = credentialsFrom(response.body, credentials.base_url, facts);
+            if (typeof stored === 'string')
+                return { status: 'not_adopted', reason: stored };
+            saveComputer({ ...stored, ...(options.report.codeHostHome ? { code_host_home: options.report.codeHostHome } : {}) }, env);
+            return { status: 'adopted', computer_id: stored.computer_id, account: stored.account };
+        }
+        reason =
+            response.status === 0
+                ? `could not reach ProhostAI (${response.error ?? 'no answer'})`
+                : response.status === 404
+                    ? 'ProhostAI did not adopt this machine from these pairings (already has a key, or not yours to manage) — add it with: prohost host pair'
+                    : `adopt answered HTTP ${response.status}`;
+    }
+    return { status: 'not_adopted', reason };
+}

package/dist/host/pair.d.ts

@@ -0,0 +1,62 @@
+/**
+ * `prohost host pair` — add this computer to a workspace.
+ *
+ * Two ways in:
+ *
+ * - **Device code** (default). The CLI asks for a code, prints it with the
+ *   page to enter it on, and polls until someone in the workspace approves it
+ *   (`/v1/computers/pairing/start` then `/poll`). Nothing secret is printed:
+ *   the code is only good for the person who approves it, for 15 minutes.
+ * - **Redeem token** (`--token`). The signed-in desktop app asks the server
+ *   for a one-time token and hands it here (`/v1/computers/pairing/redeem`).
+ *   The token is a secret and is never printed.
+ *
+ * Either way the answer is the computer credential, stored in
+ * `$PROHOST_HOME/host/computer.json` (0600). `--expect-account` refuses — and
+ * does not store — a credential for any other workspace.
+ *
+ * A program that runs this reads `$PROHOST_PAIR_RESULT_FILE` (the same
+ * variable `agent pair` writes), never the output: `{version: 1, outcome,
+ * computer_id, account: {id, name}, message}`.
+ */
+import type { ProhostAccount } from '../agent/credentials.js';
+import type { ComputerCredentials, MachineFacts } from './computer.js';
+export declare const HOST_PAIR_OUTCOMES: readonly ["paired", "expired", "token_rejected", "workspace_unconfirmed", "declined", "rate_limited", "unreachable", "invalid_arguments", "failed"];
+export type HostPairOutcome = (typeof HOST_PAIR_OUTCOMES)[number];
+export interface HostPairResult {
+    version: 1;
+    outcome: HostPairOutcome;
+    computer_id: string | null;
+    account: ProhostAccount | null;
+    /** For display only; may hold server-chosen text (the workspace name). */
+    message: string;
+}
+export interface HostPairOptions {
+    baseUrl: string;
+    name?: string;
+    token?: string;
+    expectAccount?: string;
+    env?: NodeJS.ProcessEnv;
+    fetchImpl?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    log?: (line: string) => void;
+    /** Tests pin what pairing reports about the machine. */
+    facts?: MachineFacts;
+    signal?: AbortSignal;
+    /**
+     * Asked before anything is saved when no `--expect-account` vouched for the
+     * workspace (an interactive terminal): "Add this computer to <workspace>?".
+     * Unset (a program running it), only `--expect-account` decides.
+     */
+    confirm?: (account: ProhostAccount) => Promise<boolean>;
+}
+/** Write the result file, atomically and 0600, when `$PROHOST_PAIR_RESULT_FILE` asks for one. */
+export declare function writeHostPairResult(value: HostPairResult, env?: NodeJS.ProcessEnv, warn?: (line: string) => void): void;
+/** Turn a 200 pairing answer into what is stored, or say what is missing. */
+export declare function credentialsFrom(body: Record<string, unknown> | undefined, baseUrl: string, facts: MachineFacts): ComputerCredentials | string;
+/**
+ * Pair this computer. Never throws for an outcome; the result says what
+ * happened and is what the command prints and writes to the result file.
+ */
+export declare function runHostPair(options: HostPairOptions): Promise<HostPairResult>;