@prohost/cli 0.1.0

package/dist/agent/contract.js

@@ -0,0 +1,125 @@
+/**
+ * The wire contract between this CLI and ProhostAI's agent-run loop.
+ *
+ * Everything the server owns — event names, HTTP paths, run-status values —
+ * lives here and nowhere else, so a server-side rename is a one-line change
+ * in this file rather than a hunt through the runner.
+ *
+ * The `agent.run_requested` payload spells out its own reply and completion
+ * paths precisely so a harness doesn't hand-derive them, and this module
+ * prefers those server-supplied paths. The constants below are the fallback
+ * for a payload that omits them.
+ *
+ * Server-side sources of truth:
+ *   - payload shape — `shared/events/payloads/agent_runs.py`
+ *   - `POST /v1/agent-runs/{id}/complete` — `api_public/routers/agent_runs.py`
+ *   - `POST /v1/agent-pairing/redeem` — `api_public/routers/agent_pairing.py`
+ *   - `POST /v1/conversations/{id}/messages` — `api_public/routers/conversations.py`
+ */
+/** Default host for the public API (`api_public`, mounted under `/v1`). */
+export const DEFAULT_API_BASE_URL = 'https://connect.prohost.ai';
+/** Fired when a paired agent is given work — the trigger to run. */
+export const EVENT_AGENT_RUN_REQUESTED = 'agent.run_requested';
+/** Informational events the harness logs but does not act on. */
+export const EVENT_MENTION_CREATED = 'mention.created';
+export const EVENT_MESSAGE_TEAM_CHAT = 'message.team_chat';
+/** Terminal statuses accepted by the run-completion endpoint. */
+export const RUN_STATUS_SUCCEEDED = 'succeeded';
+export const RUN_STATUS_FAILED = 'failed';
+/** Server-side cap on the `error` field of a completion (`MAX_ERROR_CHARS`). */
+export const MAX_ERROR_CHARS = 1000;
+/** `POST` — exchange a one-time pairing code for a scoped credential. */
+export const REDEEM_PATH = '/v1/agent-pairing/redeem';
+/** `POST` — send a message into a conversation as the paired agent. */
+export function conversationMessagesPath(conversationId) {
+    return `/v1/conversations/${encodeURIComponent(conversationId)}/messages`;
+}
+/** `POST` — close out a run. Must be called for every run, success or not. */
+export function agentRunCompletePath(runId) {
+    return `/v1/agent-runs/${encodeURIComponent(runId)}/complete`;
+}
+/**
+ * Fallback for a server that predates `reply_instructions.body_field`.
+ *
+ * Comment endpoints and message endpoints disagree on the field name, so before
+ * the server named it a harness had to encode the mapping itself. The event is
+ * authoritative when it says — this is only the older-server path.
+ */
+function legacyBodyKeyFor(surface) {
+    if (surface === 'conversation')
+        return 'message';
+    if (surface === 'task' || surface === 'cleaning')
+        return 'content';
+    return undefined;
+}
+function str(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function obj(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+/**
+ * Extract the event body from a websocket frame's payload.
+ *
+ * Deliveries arrive wrapped in the outbound-webhook envelope
+ * (`{id, event, created_at, schema_version, data}`); the fields we want live
+ * in `data`. Frames without an envelope (the server's `echo` test frame) are
+ * passed through unchanged.
+ */
+export function eventData(payload) {
+    const data = payload.data;
+    if (data && typeof data === 'object' && !Array.isArray(data)) {
+        return data;
+    }
+    return payload;
+}
+/**
+ * Validate an `agent.run_requested` body. Returns ``null`` when the frame is
+ * missing a ``run_id`` — without one there is no run to complete, so the only
+ * safe move is to ignore it rather than execute an unattributable prompt.
+ */
+export function parseRunRequest(data) {
+    const runId = str(data.run_id);
+    if (!runId)
+        return null;
+    const trigger = obj(data.trigger);
+    const replyInstructions = obj(data.reply_instructions);
+    const completion = obj(data.completion);
+    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);
+    const cleaningId = str(data.cleaning_id) ?? str(replyInstructions.cleaning_id);
+    const serverPath = str(replyInstructions.path);
+    // Keep the surface the server declared, even when it gave no path. A task run
+    // whose reply can't be posted is still a task run, and the prompt has to say
+    // so or the agent answers as if it were a chat message.
+    const surface = declaredSurface ?? (conversationId ? 'conversation' : 'none');
+    return {
+        run_id: runId,
+        agent_id: str(data.agent_id),
+        agent_user_id: str(data.agent_user_id),
+        agent_name: str(data.agent_name),
+        account_id: str(data.account_id),
+        kind: str(data.kind),
+        conversation_id: conversationId,
+        task_id: taskId,
+        cleaning_id: cleaningId,
+        trigger_source: str(trigger.source) ?? str(data.trigger_source),
+        trigger_message_id: str(trigger.message_id),
+        trigger_text: str(trigger.text_excerpt),
+        trigger_user_id: str(trigger.user_id),
+        trigger_type: str(trigger.type),
+        trigger_entity_id: str(trigger.entity_id),
+        reply_surface: surface,
+        // Prefer the server's path; fall back to the documented conversation path
+        // rather than drop a reply that plainly has somewhere to go.
+        reply_path: serverPath ?? (conversationId ? conversationMessagesPath(conversationId) : undefined),
+        // New events spell this out, which also makes future surfaces postable
+        // 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),
+        completion_path: str(completion.path) ?? agentRunCompletePath(runId),
+    };
+}

package/dist/agent/credentials.d.ts

@@ -0,0 +1,72 @@
+/**
+ * On-disk credential store for a paired agent (`~/.prohost/agent.json`).
+ *
+ * The file holds a live API key and a webhook signing secret, so it is written
+ * ``0600`` inside a ``0700`` directory and never echoed back to the terminal —
+ * :func:`maskSecret` is the only way this CLI prints any part of it.
+ */
+export interface StoredAgent {
+    id: string;
+    name: string;
+    user_id: string;
+}
+export interface AgentCredentials {
+    /** Schema version, so a future format change can migrate rather than crash. */
+    version: number;
+    /** Base URL of the public API these credentials belong to. */
+    base_url: string;
+    /** Websocket endpoint events stream over. */
+    ws_url: string;
+    api_key: string;
+    /** ``null`` when pairing did not provision a webhook subscription. */
+    webhook_secret: string | null;
+    /**
+     * The subscription provisioned for this connection. Sent on the websocket
+     * auth frame so the connection's ``connected_from`` is stamped with this
+     * machine's name — a presence signal, not a scoping one: the server derives
+     * which subscription's events a paired socket receives from the connection
+     * itself (`api_public/websockets/webhooks.py`).
+     */
+    subscription_id: string | null;
+    /**
+     * ``true`` when pairing carried no ``webhook_url``. Events arrive over the
+     * websocket only; nothing is ever POSTed anywhere. This is the normal path
+     * for an agent on a laptop, which has no public HTTPS endpoint to offer.
+     */
+    stream_only: boolean;
+    mcp_url: string;
+    events: string[];
+    agent: StoredAgent;
+    paired_at: string;
+}
+export declare const CREDENTIALS_VERSION = 1;
+/** 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;
+/**
+ * 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
+ * malformed value can't leak in full.
+ */
+export declare function maskSecret(secret: string, keep?: number): string;
+/** Persist credentials with owner-only permissions. Returns the path written. */
+export declare function saveCredentials(credentials: AgentCredentials, env?: NodeJS.ProcessEnv): string;
+export declare class CredentialsMissingError extends Error {
+}
+/** Read stored credentials, or ``null`` when there aren't any usable ones. */
+export declare function tryLoadCredentials(env?: NodeJS.ProcessEnv): AgentCredentials | null;
+/**
+ * Delete the stored credentials. Returns whether a file was removed.
+ *
+ * Used when the server has already revoked what's on disk, so keeping it would
+ * only produce a misleading error later.
+ */
+export declare function clearCredentials(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Read stored credentials.
+ *
+ * @throws CredentialsMissingError when the file is absent, unreadable, or
+ *   doesn't contain an API key — all of which mean "run `prohost agent pair`".
+ */
+export declare function loadCredentials(env?: NodeJS.ProcessEnv): AgentCredentials;

package/dist/agent/credentials.js

@@ -0,0 +1,92 @@
+/**
+ * On-disk credential store for a paired agent (`~/.prohost/agent.json`).
+ *
+ * The file holds a live API key and a webhook signing secret, so it is written
+ * ``0600`` inside a ``0700`` directory and never echoed back to the terminal —
+ * :func:`maskSecret` is the only way this CLI prints any part of it.
+ */
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export const CREDENTIALS_VERSION = 1;
+/** 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');
+}
+/** Absolute path of the credential file. */
+export function credentialsPath(env = process.env) {
+    return path.join(prohostHome(env), 'agent.json');
+}
+/**
+ * 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
+ * malformed value can't leak in full.
+ */
+export function maskSecret(secret, keep = 11) {
+    if (secret.length <= keep)
+        return '***';
+    return `${secret.slice(0, keep)}…`;
+}
+/** Persist credentials with owner-only permissions. Returns the path written. */
+export function saveCredentials(credentials, env = process.env) {
+    const dir = prohostHome(env);
+    const file = credentialsPath(env);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // mkdirSync's mode is masked by the process umask and is a no-op when the
+    // directory already exists, so tighten it explicitly.
+    chmodSync(dir, 0o700);
+    writeFileSync(file, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(file, 0o600);
+    return file;
+}
+export class CredentialsMissingError extends Error {
+}
+/** Read stored credentials, or ``null`` when there aren't any usable ones. */
+export function tryLoadCredentials(env = process.env) {
+    try {
+        return loadCredentials(env);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Delete the stored credentials. Returns whether a file was removed.
+ *
+ * Used when the server has already revoked what's on disk, so keeping it would
+ * only produce a misleading error later.
+ */
+export function clearCredentials(env = process.env) {
+    const file = credentialsPath(env);
+    const existed = tryLoadCredentials(env) !== null;
+    rmSync(file, { force: true });
+    return existed;
+}
+/**
+ * Read stored credentials.
+ *
+ * @throws CredentialsMissingError when the file is absent, unreadable, or
+ *   doesn't contain an API key — all of which mean "run `prohost agent pair`".
+ */
+export function loadCredentials(env = process.env) {
+    const file = credentialsPath(env);
+    let raw;
+    try {
+        raw = readFileSync(file, 'utf8');
+    }
+    catch {
+        throw new CredentialsMissingError(`No paired agent found at ${file}. Run: prohost agent pair --code <pairing-code>`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CredentialsMissingError(`Credential file is not valid JSON: ${file}`);
+    }
+    const c = parsed;
+    if (!c || typeof c !== 'object' || typeof c.api_key !== 'string' || !c.api_key) {
+        throw new CredentialsMissingError(`Credential file is missing an api_key: ${file}`);
+    }
+    return c;
+}

package/dist/agent/exec.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Runs the user's agent command and captures its answer.
+ *
+ * Deliberately agent-agnostic: the command is whatever the host passed to
+ * ``--exec`` (``claude -p``, ``codex exec -``, ``goose run -i -``, a shell
+ * script). The contract is the lowest common denominator every CLI agent
+ * already speaks — prompt in on stdin, reply out on stdout.
+ *
+ * The prompt goes in over **stdin, never the command line**. ``shell: true``
+ * is what makes ``--exec 'claude -p'`` work as typed, and the command string
+ * comes from the host's own flag — but event-derived text never reaches the
+ * shell, so a crafted mention cannot inject a command.
+ */
+import { spawn } from 'node:child_process';
+export interface ExecOptions {
+    /** Shell command to run, exactly as the host typed it after ``--exec``. */
+    command: string;
+    /** Prompt written to the child's stdin. */
+    prompt: string;
+    /** Hard cap on wall-clock runtime. */
+    timeoutMs: number;
+    /** Working directory for the child. Defaults to the CLI's cwd. */
+    cwd?: string;
+    /** Extra environment for the child, merged over ``process.env``. */
+    env?: NodeJS.ProcessEnv;
+    /** Injectable spawn — tests substitute a fake process. */
+    spawnImpl?: typeof spawn;
+}
+export interface ExecResult {
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+    /** Populated when the process could not be started at all. */
+    error?: string;
+    durationMs: number;
+}
+/** Cap on captured output (in characters) so a runaway agent can't exhaust memory. */
+export declare const MAX_OUTPUT_CHARS: number;
+/**
+ * Execute the agent command with ``prompt`` on stdin and return its stdout.
+ *
+ * Never throws: a spawn failure, a non-zero exit, and a timeout all come back
+ * as ``ok: false`` with the detail filled in, because the caller must report
+ * *some* outcome to the server for every run.
+ */
+export declare function execAgent(options: ExecOptions): Promise<ExecResult>;

package/dist/agent/exec.js

@@ -0,0 +1,151 @@
+/**
+ * Runs the user's agent command and captures its answer.
+ *
+ * Deliberately agent-agnostic: the command is whatever the host passed to
+ * ``--exec`` (``claude -p``, ``codex exec -``, ``goose run -i -``, a shell
+ * script). The contract is the lowest common denominator every CLI agent
+ * already speaks — prompt in on stdin, reply out on stdout.
+ *
+ * The prompt goes in over **stdin, never the command line**. ``shell: true``
+ * is what makes ``--exec 'claude -p'`` work as typed, and the command string
+ * comes from the host's own flag — but event-derived text never reaches the
+ * shell, so a crafted mention cannot inject a command.
+ */
+import { spawn } from 'node:child_process';
+/** Cap on captured output (in characters) so a runaway agent can't exhaust memory. */
+export const MAX_OUTPUT_CHARS = 512 * 1024;
+/** Grace period between SIGTERM and SIGKILL when a run overruns its timeout. */
+const KILL_GRACE_MS = 5_000;
+function clamp(text) {
+    if (text.length <= MAX_OUTPUT_CHARS)
+        return text;
+    return `${text.slice(0, MAX_OUTPUT_CHARS)}\n…[truncated]`;
+}
+/**
+ * Execute the agent command with ``prompt`` on stdin and return its stdout.
+ *
+ * Never throws: a spawn failure, a non-zero exit, and a timeout all come back
+ * as ``ok: false`` with the detail filled in, because the caller must report
+ * *some* outcome to the server for every run.
+ */
+export async function execAgent(options) {
+    const spawnImpl = options.spawnImpl ?? spawn;
+    const started = Date.now();
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        let settled = false;
+        const spawnOptions = {
+            shell: true,
+            cwd: options.cwd,
+            env: options.env ? { ...process.env, ...options.env } : process.env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            // Own process group. `--exec 'foo | bar'` runs under a shell, and
+            // signalling the shell alone leaves its children holding our stdio
+            // pipes — `close` then never fires and the run queue wedges past the
+            // timeout. With a group we can signal the whole tree.
+            detached: process.platform !== 'win32',
+        };
+        let child;
+        try {
+            child = spawnImpl(options.command, spawnOptions);
+        }
+        catch (err) {
+            resolve({
+                ok: false,
+                stdout: '',
+                stderr: '',
+                exitCode: null,
+                timedOut: false,
+                error: err instanceof Error ? err.message : String(err),
+                durationMs: Date.now() - started,
+            });
+            return;
+        }
+        let killTimer;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (killTimer !== undefined)
+                clearTimeout(killTimer);
+            resolve({ ...result, durationMs: Date.now() - started });
+        };
+        /**
+         * Signal the child's whole process group, falling back to the child alone
+         * when there is no group (Windows, or a spawn that never got a pid).
+         */
+        const signalTree = (signal) => {
+            const pid = child.pid;
+            try {
+                if (pid !== undefined && spawnOptions.detached)
+                    process.kill(-pid, signal);
+                else
+                    child.kill(signal);
+            }
+            catch {
+                // ESRCH — the group is already gone, which is the outcome we wanted.
+            }
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            signalTree('SIGTERM');
+            // Escalate if the agent ignores SIGTERM, so a wedged child can't hold
+            // the harness open past its timeout.
+            killTimer = setTimeout(() => {
+                signalTree('SIGKILL');
+                // A descendant can still hold the pipes open after the group is
+                // killed; don't wait on `close` forever for a run we already gave up
+                // on.
+                finish({
+                    ok: false,
+                    stdout: clamp(stdout),
+                    stderr: clamp(stderr),
+                    exitCode: null,
+                    timedOut: true,
+                    error: `timed out after ${options.timeoutMs}ms`,
+                });
+            }, KILL_GRACE_MS);
+        }, options.timeoutMs);
+        child.stdout?.on('data', (chunk) => {
+            if (stdout.length < MAX_OUTPUT_CHARS)
+                stdout += chunk.toString();
+        });
+        child.stderr?.on('data', (chunk) => {
+            if (stderr.length < MAX_OUTPUT_CHARS)
+                stderr += chunk.toString();
+        });
+        child.on('error', (err) => {
+            finish({
+                ok: false,
+                stdout: clamp(stdout),
+                stderr: clamp(stderr),
+                exitCode: null,
+                timedOut,
+                error: err.message,
+            });
+        });
+        child.on('close', (code) => {
+            finish({
+                ok: !timedOut && code === 0,
+                stdout: clamp(stdout),
+                stderr: clamp(stderr),
+                exitCode: code,
+                timedOut,
+                error: timedOut ? `timed out after ${options.timeoutMs}ms` : undefined,
+            });
+        });
+        // stdin may already be closed if the command failed to start.
+        try {
+            child.stdin?.on('error', () => {
+                /* the close/error handlers above report the real failure */
+            });
+            child.stdin?.end(options.prompt);
+        }
+        catch {
+            /* ignore — reported via 'error'/'close' */
+        }
+    });
+}

package/dist/agent/pair.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `prohost agent pair` — redeem a one-time pairing code.
+ *
+ * The host generates the code in ProhostAI ("Hire an AI employee" → "Bring your
+ * own agent"); this exchanges it for a scoped API key, the webhook signing
+ * secret, and the MCP URL, then writes them to `~/.prohost/agent.json`.
+ *
+ * Codes are single-use and expire after 15 minutes. Every redeem failure comes
+ * back as one generic 404 by design, so the error text here can't be more
+ * specific than "invalid, expired, or already used".
+ */
+import type { AgentCredentials } from './credentials.js';
+export interface PairOptions {
+    /** The one-time code from the hire modal. */
+    code: string;
+    /** Public API base. Defaults to production. */
+    baseUrl?: string;
+    /** Websocket endpoint stored for `prohost agent run`. */
+    wsUrl?: string;
+    /**
+     * HTTPS endpoint to ALSO deliver agent events to. Optional and rarely
+     * wanted: omitting it gives a stream-only pairing, which is the normal path
+     * for an agent on a laptop. Supply one only if something else of yours also
+     * needs the events pushed over HTTPS.
+     */
+    webhookUrl?: string;
+    fetchImpl?: typeof fetch;
+    /** Line-oriented output sink. Defaults to stdout. */
+    onLine?: (line: string) => void;
+    /** Environment used to resolve the credential path (tests override this). */
+    env?: NodeJS.ProcessEnv;
+}
+export interface PairResult {
+    credentials: AgentCredentials;
+    path: string;
+}
+export declare class PairError extends Error {
+}
+/**
+ * Redeem ``code`` and persist the resulting credentials.
+ *
+ * @throws PairError when the code is rejected or the response is malformed.
+ */
+export declare function runPair(options: PairOptions): Promise<PairResult>;