@prohost/cli 0.1.0 → 0.2.0

package/dist/agent/contract.js

@@ -38,6 +38,16 @@ export function conversationMessagesPath(conversationId) {
 export function agentRunCompletePath(runId) {
     return `/v1/agent-runs/${encodeURIComponent(runId)}/complete`;
 }
+/**
+ * Ceiling on how many context entries are kept from one payload.
+ *
+ * The server bounds these, but the prompt is written to a child process's
+ * stdin and the harness is the last thing standing between a pathological
+ * payload and an agent's context window. Entries past the limit are dropped
+ * from the *front*, because both lists are oldest-first and the recent end is
+ * the part worth spending prompt on.
+ */
+export const MAX_CONTEXT_ENTRIES = 50;
 /**
  * Fallback for a server that predates `reply_instructions.body_field`.
  *
@@ -60,6 +70,60 @@ function obj(value) {
         ? value
         : {};
 }
+/**
+ * Keep the last {@link MAX_CONTEXT_ENTRIES} entries of a list the server sent.
+ *
+ * Everything about this is deliberately forgiving. The two context lists are
+ * additive fields on an event this CLI already had to parse without them, and
+ * they will keep changing shape after this build is published: a version that
+ * throws — or that drops the whole run — because a list arrived as `null`, held
+ * an entry with a new key, or carried one malformed row would turn a server-side
+ * improvement into a fleet-wide outage of laptops nobody can redeploy. A
+ * missing, null, or wrong-typed list degrades to "this server doesn't send it",
+ * and one bad entry costs that entry only.
+ */
+function contextList(value, parseEntry) {
+    if (!Array.isArray(value))
+        return undefined;
+    const entries = [];
+    for (const raw of value) {
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            continue;
+        const parsed = parseEntry(raw);
+        if (parsed !== null)
+            entries.push(parsed);
+    }
+    if (entries.length === 0)
+        return undefined;
+    return entries.slice(-MAX_CONTEXT_ENTRIES);
+}
+/**
+ * Validate ``reply_instructions.body_extra``.
+ *
+ * Anything that isn't a plain object is treated as absent rather than as an
+ * error: these fields are additive, and a malformed one must not cost the run
+ * its reply. Values are passed through untouched — the server owns their
+ * meaning, and coercing them here would be this CLI inventing a schema it does
+ * not have.
+ */
+function bodyExtra(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const entries = value;
+    return Object.keys(entries).length > 0 ? entries : undefined;
+}
+function parseMessage(entry) {
+    const text = str(entry.text);
+    if (!text)
+        return null;
+    return { text, author: str(entry.author), role: str(entry.role), at: str(entry.at) };
+}
+function parseMemory(entry) {
+    const content = str(entry.content);
+    if (!content)
+        return null;
+    return { content, scope: str(entry.scope) };
+}
 /**
  * Extract the event body from a websocket frame's payload.
  *
@@ -87,6 +151,7 @@ export function parseRunRequest(data) {
     const trigger = obj(data.trigger);
     const replyInstructions = obj(data.reply_instructions);
     const completion = obj(data.completion);
+    const context = obj(data.context);
     const declaredSurface = str(replyInstructions.surface);
     const conversationId = str(data.conversation_id) ?? str(replyInstructions.conversation_id);
     const taskId = str(data.task_id) ?? str(replyInstructions.task_id);
@@ -120,6 +185,12 @@ export function parseRunRequest(data) {
         // without a CLI release. A path with no nameable field is not postable;
         // keep the known-surface fallback only for old events.
         reply_body_key: str(replyInstructions.body_field) ?? legacyBodyKeyFor(surface),
+        reply_body_extra: bodyExtra(replyInstructions.body_extra),
         completion_path: str(completion.path) ?? agentRunCompletePath(runId),
+        // Accepted both at the top level and nested under `context`, because the
+        // server can move them without a CLI release either way — and a published
+        // CLI cannot be redeployed to follow.
+        recent_messages: contextList(data.recent_messages ?? context.recent_messages, parseMessage),
+        memories: contextList(data.memories ?? context.memories, parseMemory),
     };
 }

package/dist/agent/credentials.d.ts

@@ -39,11 +39,50 @@ export interface AgentCredentials {
     agent: StoredAgent;
     paired_at: string;
 }
-export declare const CREDENTIALS_VERSION = 1;
+/**
+ * On-disk credential schema version.
+ *
+ * ``2`` means "``ws_url`` is trustworthy". Version ``1`` files were written by
+ * a CLI that composed that URL from a hardcoded constant, and 0.1.0 shipped a
+ * constant naming the wrong host — so a v1 file may carry a socket URL that can
+ * only ever 403. Upgrading the CLI alone would not have helped those installs:
+ * {@link streamUrlFor} prefers the stored value, so the bad URL would keep
+ * being used until the operator re-paired. The version bump is what lets a new
+ * build recognise a stale file and re-derive instead.
+ */
+export declare const CREDENTIALS_VERSION = 2;
+/**
+ * Websocket URL to use for a stored credential.
+ *
+ * For a current (v2+) file this is just ``ws_url`` — the value the server
+ * reported at pair time. For a v1 file the stored URL is not trusted: it came
+ * from a client-side constant, and 0.1.0's was wrong. It is re-derived from
+ * ``base_url``, which the server did report (via ``mcp_url``) and which is
+ * therefore right even in a v1 file.
+ *
+ * @param credentials Stored credentials.
+ * @param fallback Used when neither the stored URL nor ``base_url`` is usable.
+ */
+export declare function streamUrlFor(credentials: AgentCredentials, fallback: string): string;
 /** Directory holding CLI state. Overridable with ``$PROHOST_HOME`` for tests. */
 export declare function prohostHome(env?: NodeJS.ProcessEnv): string;
 /** Absolute path of the credential file. */
 export declare function credentialsPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Default working directory for the agent command.
+ *
+ * A dedicated, boring directory — **not** whatever the operator happened to
+ * `cd` into. Coding agents read their working directory as configuration: a
+ * `CLAUDE.md`, a `.claude/settings.json` permission list, a project `.mcp.json`.
+ * Launched from a checkout of some unrelated service, the agent inherits that
+ * repo's instructions and denials and answers a customer's question as if it
+ * were working on that codebase — which is exactly what happened when this was
+ * first run in production from a dev checkout. Defaulting somewhere neutral
+ * makes the inherited-context case something you opt into with `--workdir`.
+ */
+export declare function workspacePath(env?: NodeJS.ProcessEnv): string;
+/** Create the workspace directory if it isn't there, and return its path. */
+export declare function ensureWorkspace(env?: NodeJS.ProcessEnv): string;
 /**
  * Show enough of a secret to identify it and no more — ``ph_live_ab…`` style.
  * Anything shorter than the prefix is reported as ``***`` so a short or

package/dist/agent/credentials.js

@@ -8,7 +8,61 @@
 import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-export const CREDENTIALS_VERSION = 1;
+/**
+ * On-disk credential schema version.
+ *
+ * ``2`` means "``ws_url`` is trustworthy". Version ``1`` files were written by
+ * a CLI that composed that URL from a hardcoded constant, and 0.1.0 shipped a
+ * constant naming the wrong host — so a v1 file may carry a socket URL that can
+ * only ever 403. Upgrading the CLI alone would not have helped those installs:
+ * {@link streamUrlFor} prefers the stored value, so the bad URL would keep
+ * being used until the operator re-paired. The version bump is what lets a new
+ * build recognise a stale file and re-derive instead.
+ */
+export const CREDENTIALS_VERSION = 2;
+/**
+ * Websocket URL to use for a stored credential.
+ *
+ * For a current (v2+) file this is just ``ws_url`` — the value the server
+ * reported at pair time. For a v1 file the stored URL is not trusted: it came
+ * from a client-side constant, and 0.1.0's was wrong. It is re-derived from
+ * ``base_url``, which the server did report (via ``mcp_url``) and which is
+ * therefore right even in a v1 file.
+ *
+ * @param credentials Stored credentials.
+ * @param fallback Used when neither the stored URL nor ``base_url`` is usable.
+ */
+export function streamUrlFor(credentials, fallback) {
+    if ((credentials.version ?? 1) >= 2 && credentials.ws_url)
+        return credentials.ws_url;
+    // Truthiness, not `??`: a hand-edited or truncated file can hold `""`, which
+    // is not a URL but is not nullish either, so `??` would return it.
+    return wsUrlFromBaseUrl(credentials.base_url) || credentials.ws_url || fallback;
+}
+/**
+ * Turn an API base URL into the websocket URL on the same host.
+ *
+ * Mirrors the server's derivation (`shared/agents/connections.py`
+ * ``pairing_endpoints``): only plain ``http`` maps to ``ws``, so a local dev
+ * base keeps working and nothing else can downgrade a socket that carries an
+ * API key. Returns ``undefined`` for anything not parseable as a URL.
+ */
+function wsUrlFromBaseUrl(baseUrl) {
+    if (!baseUrl)
+        return undefined;
+    let parsed;
+    try {
+        parsed = new URL(baseUrl);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+        return undefined;
+    const scheme = parsed.protocol === 'http:' ? 'ws' : 'wss';
+    const prefix = parsed.pathname.replace(/\/+$/, '');
+    return `${scheme}://${parsed.host}${prefix}/ws/webhooks`;
+}
 /** Directory holding CLI state. Overridable with ``$PROHOST_HOME`` for tests. */
 export function prohostHome(env = process.env) {
     return env.PROHOST_HOME ?? path.join(os.homedir(), '.prohost');
@@ -17,6 +71,27 @@ export function prohostHome(env = process.env) {
 export function credentialsPath(env = process.env) {
     return path.join(prohostHome(env), 'agent.json');
 }
+/**
+ * Default working directory for the agent command.
+ *
+ * A dedicated, boring directory — **not** whatever the operator happened to
+ * `cd` into. Coding agents read their working directory as configuration: a
+ * `CLAUDE.md`, a `.claude/settings.json` permission list, a project `.mcp.json`.
+ * Launched from a checkout of some unrelated service, the agent inherits that
+ * repo's instructions and denials and answers a customer's question as if it
+ * were working on that codebase — which is exactly what happened when this was
+ * first run in production from a dev checkout. Defaulting somewhere neutral
+ * makes the inherited-context case something you opt into with `--workdir`.
+ */
+export function workspacePath(env = process.env) {
+    return path.join(prohostHome(env), 'workspace');
+}
+/** Create the workspace directory if it isn't there, and return its path. */
+export function ensureWorkspace(env = process.env) {
+    const dir = workspacePath(env);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    return dir;
+}
 /**
  * Show enough of a secret to identify it and no more — ``ph_live_ab…`` style.
  * Anything shorter than the prefix is reported as ``***`` so a short or

package/dist/agent/daemon.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Keeping `agent run` alive across logouts, crashes, and reboots.
+ *
+ * A paired agent that only runs while a terminal window is open is not a
+ * teammate — it is a demo. Someone @-mentions it at 2am, the laptop had
+ * rebooted for an update, and the run times out server-side with no indication
+ * that anything is wrong on this end. So the harness ships a way to hand itself
+ * to the OS supervisor.
+ *
+ * On macOS that is a per-user launchd agent: a plist in `~/Library/LaunchAgents`
+ * with `KeepAlive`, bootstrapped into the `gui/$UID` domain so it starts at
+ * login and is restarted whenever it exits. On Linux there is no equivalent
+ * this CLI can write safely (systemd-user layouts differ per distro and per
+ * init), so we print a unit file to install by hand rather than guess.
+ *
+ * Only plist *generation* is unit-tested. Asserting on `launchctl` would be
+ * testing Apple's binary, and doing it for real in CI would install a live
+ * daemon on the runner.
+ */
+/** Reverse-DNS prefix every generated label starts with. */
+export declare const LAUNCHD_LABEL_PREFIX = "ai.prohost.agent";
+export interface DaemonSpec {
+    /** launchd label, also the plist filename stem. */
+    label: string;
+    /** argv[0] plus arguments, exactly as launchd will exec them. */
+    programArguments: string[];
+    /** Working directory for the harness process. */
+    workdir: string;
+    /** Combined stdout/stderr destination. */
+    logPath: string;
+    /** Extra environment launchd must set — launchd inherits almost nothing. */
+    env?: Record<string, string>;
+}
+/**
+ * Label for the daemon serving one `$PROHOST_HOME`.
+ *
+ * Keyed on the home directory rather than on the agent id, because the home
+ * directory is what actually scopes an install: there is exactly one
+ * `agent.json` in it, so every daemon pointed at the same home runs the *same*
+ * agent no matter which agent was paired when it was installed. An agent-keyed
+ * label got that backwards — re-pairing and re-installing produced a second
+ * label whose plist loaded the same single credential, so both jobs came up as
+ * the new agent (two harnesses, duplicate work) and `uninstall-daemon` could no
+ * longer name the first one to remove it.
+ *
+ * Running two agents at once is still supported, and this is what makes it
+ * honest: give each one its own `$PROHOST_HOME`, and they get separate
+ * credentials, separate ledgers, and separate daemons.
+ *
+ * A digest rather than the path itself — a label is a filename, and home
+ * directories contain spaces, `~`, and non-ASCII.
+ */
+export declare function launchdLabel(home: string): string;
+/** Where a label's plist lives. */
+export declare function launchdPlistPath(label: string, home?: string): string;
+/**
+ * Render the launchd property list for a daemon spec.
+ *
+ * `KeepAlive` is unconditional `true` rather than `SuccessfulExit: false`:
+ * `agent run` exits 0 on a clean shutdown *and* on a fatal auth error, and a
+ * daemon that stops restarting after a revoked-then-restored credential is
+ * exactly the silent-agent failure this whole feature exists to prevent.
+ * Restarting into a rejected credential is loud and cheap; not restarting is
+ * quiet and expensive.
+ */
+export declare function buildLaunchdPlist(spec: DaemonSpec): string;
+/**
+ * The systemd-user unit we print on Linux.
+ *
+ * Printed rather than installed. `systemctl --user` needs a running user
+ * manager and lingering enabled for it to survive logout, neither of which this
+ * CLI can arrange without making decisions about the machine that aren't its
+ * to make.
+ */
+export declare function buildSystemdUnit(spec: DaemonSpec): string;
+/** Reconstruct the `agent run` argv a daemon should launch. */
+export interface HarnessInvocation {
+    /** Interpreter to exec — normally the Node binary running this process. */
+    execPath: string;
+    /** Absolute path of the CLI entrypoint script. */
+    scriptPath: string;
+    /** The `--exec` command, verbatim. */
+    exec: string;
+    workdir: string;
+    timeoutSeconds?: number;
+    machine?: string;
+    url?: string;
+    allowUnverified?: boolean;
+    /** Gate tools behind permission prompts (the `--safe-tools` opt-out). */
+    safeTools?: boolean;
+}
+export declare function harnessArguments(invocation: HarnessInvocation): string[];
+/** Default log destination — alongside the credential and the run ledger. */
+export declare function agentLogPath(env?: NodeJS.ProcessEnv): string;
+export interface InstallResult {
+    ok: boolean;
+    /** Human-readable report, already formatted for the terminal. */
+    message: string;
+    /** Path written, when one was. */
+    plistPath?: string;
+}
+type Runner = (command: string, args: string[]) => {
+    status: number | null;
+    stderr: string;
+};
+/**
+ * Write the plist and hand it to launchd.
+ *
+ * `bootout` first, ignoring its result: bootstrapping a label that is already
+ * loaded fails outright, so a plain re-install of an agent whose `--exec`
+ * changed would otherwise keep running the old command and report success.
+ */
+export declare function installLaunchdDaemon(spec: DaemonSpec, options?: {
+    home?: string;
+    uid?: number;
+    run?: Runner;
+}): InstallResult;
+/**
+ * Unload the daemon and delete its plist. Missing pieces are not an error.
+ *
+ * Reports whether anything was actually there. "✓ Removed" printed over an
+ * empty home reads as confirmation that a daemon has been stopped — which is
+ * exactly the wrong thing to tell someone whose agent is still running from a
+ * *different* `$PROHOST_HOME` than the one they just pointed this at.
+ */
+export declare function uninstallLaunchdDaemon(label: string, options?: {
+    home?: string;
+    uid?: number;
+    run?: Runner;
+}): InstallResult;
+export {};

package/dist/agent/daemon.js

@@ -0,0 +1,274 @@
+/**
+ * Keeping `agent run` alive across logouts, crashes, and reboots.
+ *
+ * A paired agent that only runs while a terminal window is open is not a
+ * teammate — it is a demo. Someone @-mentions it at 2am, the laptop had
+ * rebooted for an update, and the run times out server-side with no indication
+ * that anything is wrong on this end. So the harness ships a way to hand itself
+ * to the OS supervisor.
+ *
+ * On macOS that is a per-user launchd agent: a plist in `~/Library/LaunchAgents`
+ * with `KeepAlive`, bootstrapped into the `gui/$UID` domain so it starts at
+ * login and is restarted whenever it exits. On Linux there is no equivalent
+ * this CLI can write safely (systemd-user layouts differ per distro and per
+ * init), so we print a unit file to install by hand rather than guess.
+ *
+ * Only plist *generation* is unit-tested. Asserting on `launchctl` would be
+ * testing Apple's binary, and doing it for real in CI would install a live
+ * daemon on the runner.
+ */
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { prohostHome } from './credentials.js';
+/** Reverse-DNS prefix every generated label starts with. */
+export const LAUNCHD_LABEL_PREFIX = 'ai.prohost.agent';
+/** Hex characters of the home-directory digest that go into the label. */
+const LABEL_DIGEST_CHARS = 8;
+/**
+ * Label for the daemon serving one `$PROHOST_HOME`.
+ *
+ * Keyed on the home directory rather than on the agent id, because the home
+ * directory is what actually scopes an install: there is exactly one
+ * `agent.json` in it, so every daemon pointed at the same home runs the *same*
+ * agent no matter which agent was paired when it was installed. An agent-keyed
+ * label got that backwards — re-pairing and re-installing produced a second
+ * label whose plist loaded the same single credential, so both jobs came up as
+ * the new agent (two harnesses, duplicate work) and `uninstall-daemon` could no
+ * longer name the first one to remove it.
+ *
+ * Running two agents at once is still supported, and this is what makes it
+ * honest: give each one its own `$PROHOST_HOME`, and they get separate
+ * credentials, separate ledgers, and separate daemons.
+ *
+ * A digest rather than the path itself — a label is a filename, and home
+ * directories contain spaces, `~`, and non-ASCII.
+ */
+export function launchdLabel(home) {
+    const digest = createHash('sha256').update(path.resolve(home)).digest('hex').slice(0, LABEL_DIGEST_CHARS);
+    return `${LAUNCHD_LABEL_PREFIX}.${digest}`;
+}
+/** Where a label's plist lives. */
+export function launchdPlistPath(label, home = os.homedir()) {
+    return path.join(home, 'Library', 'LaunchAgents', `${label}.plist`);
+}
+/**
+ * XML-escape a plist string value.
+ *
+ * Not optional politeness: an `--exec` command is arbitrary shell the operator
+ * typed, and `--exec 'sh -c "foo && bar"'` is a perfectly ordinary thing to
+ * want. Interpolated raw, its `&` alone produces a plist that `launchctl`
+ * rejects as malformed — with an error that points at the file, not at the
+ * flag that poisoned it.
+ */
+function xmlEscape(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+function stringEntries(values, indent) {
+    return Object.entries(values).flatMap(([key, value]) => [
+        `${indent}<key>${xmlEscape(key)}</key>`,
+        `${indent}<string>${xmlEscape(value)}</string>`,
+    ]);
+}
+/**
+ * Render the launchd property list for a daemon spec.
+ *
+ * `KeepAlive` is unconditional `true` rather than `SuccessfulExit: false`:
+ * `agent run` exits 0 on a clean shutdown *and* on a fatal auth error, and a
+ * daemon that stops restarting after a revoked-then-restored credential is
+ * exactly the silent-agent failure this whole feature exists to prevent.
+ * Restarting into a rejected credential is loud and cheap; not restarting is
+ * quiet and expensive.
+ */
+export function buildLaunchdPlist(spec) {
+    const lines = [
+        '<?xml version="1.0" encoding="UTF-8"?>',
+        '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" ' +
+            '"http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+        '<plist version="1.0">',
+        '<dict>',
+        '  <key>Label</key>',
+        `  <string>${xmlEscape(spec.label)}</string>`,
+        '  <key>ProgramArguments</key>',
+        '  <array>',
+        ...spec.programArguments.map((arg) => `    <string>${xmlEscape(arg)}</string>`),
+        '  </array>',
+        '  <key>WorkingDirectory</key>',
+        `  <string>${xmlEscape(spec.workdir)}</string>`,
+        '  <key>RunAtLoad</key>',
+        '  <true/>',
+        '  <key>KeepAlive</key>',
+        '  <true/>',
+        // Without this a crash-looping harness would be restarted as fast as it can
+        // fail, which on a bad credential means hammering the pairing endpoint.
+        '  <key>ThrottleInterval</key>',
+        '  <integer>10</integer>',
+        '  <key>StandardOutPath</key>',
+        `  <string>${xmlEscape(spec.logPath)}</string>`,
+        '  <key>StandardErrorPath</key>',
+        `  <string>${xmlEscape(spec.logPath)}</string>`,
+    ];
+    if (spec.env && Object.keys(spec.env).length > 0) {
+        lines.push('  <key>EnvironmentVariables</key>', '  <dict>', ...stringEntries(spec.env, '    '), '  </dict>');
+    }
+    lines.push('</dict>', '</plist>');
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Quote one `ExecStart` word for systemd.
+ *
+ * systemd re-splits `ExecStart` on whitespace, so joining argv with spaces
+ * silently corrupts any argument that contains one — and the very first thing
+ * this CLI passes is `--exec 'claude -p'`. Unquoted, systemd hands `--exec` the
+ * value `claude` and treats `-p` as a flag of its own; `codex exec -` loses two
+ * words the same way. Quoting is not decoration here, it is the difference
+ * between a working unit and one that starts the wrong process.
+ */
+function systemdQuote(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/**
+ * The systemd-user unit we print on Linux.
+ *
+ * Printed rather than installed. `systemctl --user` needs a running user
+ * manager and lingering enabled for it to survive logout, neither of which this
+ * CLI can arrange without making decisions about the machine that aren't its
+ * to make.
+ */
+export function buildSystemdUnit(spec) {
+    const environment = Object.entries(spec.env ?? {})
+        .map(([key, value]) => `Environment=${key}=${systemdQuote(value)}`)
+        .join('\n');
+    return [
+        '[Unit]',
+        'Description=ProhostAI paired agent',
+        'After=network-online.target',
+        '',
+        '[Service]',
+        'Type=simple',
+        `WorkingDirectory=${systemdQuote(spec.workdir)}`,
+        `ExecStart=${spec.programArguments.map(systemdQuote).join(' ')}`,
+        'Restart=always',
+        'RestartSec=10',
+        ...(environment ? [environment] : []),
+        '',
+        '[Install]',
+        'WantedBy=default.target',
+        '',
+    ].join('\n');
+}
+export function harnessArguments(invocation) {
+    const args = [
+        invocation.execPath,
+        invocation.scriptPath,
+        'agent',
+        'run',
+        '--exec',
+        invocation.exec,
+        '--workdir',
+        invocation.workdir,
+    ];
+    if (invocation.timeoutSeconds !== undefined)
+        args.push('--timeout', String(invocation.timeoutSeconds));
+    if (invocation.machine)
+        args.push('--machine', invocation.machine);
+    if (invocation.url)
+        args.push('--url', invocation.url);
+    if (invocation.allowUnverified)
+        args.push('--allow-unverified');
+    if (invocation.safeTools)
+        args.push('--safe-tools');
+    return args;
+}
+/** Default log destination — alongside the credential and the run ledger. */
+export function agentLogPath(env = process.env) {
+    return path.join(prohostHome(env), 'agent.log');
+}
+const defaultRunner = (command, args) => {
+    const result = spawnSync(command, args, { encoding: 'utf8' });
+    return { status: result.status, stderr: result.stderr ?? '' };
+};
+/**
+ * Write the plist and hand it to launchd.
+ *
+ * `bootout` first, ignoring its result: bootstrapping a label that is already
+ * loaded fails outright, so a plain re-install of an agent whose `--exec`
+ * changed would otherwise keep running the old command and report success.
+ */
+export function installLaunchdDaemon(spec, options = {}) {
+    const home = options.home ?? os.homedir();
+    const uid = options.uid ?? process.getuid?.() ?? 0;
+    const run = options.run ?? defaultRunner;
+    const plistPath = launchdPlistPath(spec.label, home);
+    const domain = `gui/${uid}`;
+    mkdirSync(path.dirname(plistPath), { recursive: true });
+    // 0600 rather than the usual 0644 for a LaunchAgent: this plist carries the
+    // installing shell's environment, and while today that is only PATH and
+    // PROHOST_HOME, a file whose whole job is "environment for a credentialed
+    // process" should not be readable by other local accounts. launchd runs it as
+    // the owning user, so nothing needs wider access.
+    writeFileSync(plistPath, buildLaunchdPlist(spec), { mode: 0o600 });
+    chmodSync(plistPath, 0o600);
+    run('launchctl', ['bootout', `${domain}/${spec.label}`]);
+    const bootstrap = run('launchctl', ['bootstrap', domain, plistPath]);
+    if (bootstrap.status !== 0) {
+        return {
+            ok: false,
+            plistPath,
+            message: `Wrote ${plistPath}, but \`launchctl bootstrap ${domain}\` failed` +
+                `${bootstrap.stderr.trim() ? `: ${bootstrap.stderr.trim()}` : '.'}\n` +
+                `Load it by hand with: launchctl bootstrap ${domain} ${plistPath}`,
+        };
+    }
+    run('launchctl', ['enable', `${domain}/${spec.label}`]);
+    return {
+        ok: true,
+        plistPath,
+        message: `✓ Installed ${spec.label}\n` +
+            `  plist: ${plistPath}\n` +
+            `  logs:  ${spec.logPath}\n` +
+            `  The agent now starts at login and is restarted if it exits.\n` +
+            // Said at install time because the alternative is finding out from a
+            // crash-loop in a log nobody is watching: a supervised process does not
+            // inherit the shell you installed from, so an --exec that depends on an
+            // exported API key works interactively and fails here.
+            `  It runs with only PATH and PROHOST_HOME from this shell. If your\n` +
+            `  command needs other environment (an API key, a proxy setting), point\n` +
+            `  --exec at a wrapper script that sets it.\n` +
+            `  Stop it with: prohost agent uninstall-daemon`,
+    };
+}
+/**
+ * Unload the daemon and delete its plist. Missing pieces are not an error.
+ *
+ * Reports whether anything was actually there. "✓ Removed" printed over an
+ * empty home reads as confirmation that a daemon has been stopped — which is
+ * exactly the wrong thing to tell someone whose agent is still running from a
+ * *different* `$PROHOST_HOME` than the one they just pointed this at.
+ */
+export function uninstallLaunchdDaemon(label, options = {}) {
+    const home = options.home ?? os.homedir();
+    const uid = options.uid ?? process.getuid?.() ?? 0;
+    const run = options.run ?? defaultRunner;
+    const plistPath = launchdPlistPath(label, home);
+    const existed = existsSync(plistPath);
+    run('launchctl', ['bootout', `gui/${uid}/${label}`]);
+    rmSync(plistPath, { force: true });
+    return {
+        ok: true,
+        plistPath,
+        message: existed
+            ? `✓ Removed ${label} (${plistPath})`
+            : `No daemon was installed for this PROHOST_HOME (looked for ${plistPath}).\n` +
+                `  Nothing to remove. If an agent is still running, it belongs to a\n` +
+                `  different PROHOST_HOME — check with: launchctl list | grep ${LAUNCHD_LABEL_PREFIX}`,
+    };
+}

package/dist/agent/pair.d.ts

@@ -15,7 +15,11 @@ export interface PairOptions {
     code: string;
     /** Public API base. Defaults to production. */
     baseUrl?: string;
-    /** Websocket endpoint stored for `prohost agent run`. */
+    /**
+     * Explicit websocket endpoint to store for `prohost agent run` (`--url` /
+     * `$PROHOST_WS_URL`). An operator override, so it beats what the server
+     * reports; leave it unset and the server's `ws_url` is used.
+     */
     wsUrl?: string;
     /**
      * HTTPS endpoint to ALSO deliver agent events to. Optional and rarely