@prohost/cli 0.1.0

package/dist/agent/pair.js

@@ -0,0 +1,149 @@
+/**
+ * `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 { USER_AGENT } from '../version.js';
+import { DEFAULT_API_BASE_URL, REDEEM_PATH } from './contract.js';
+import { CREDENTIALS_VERSION, clearCredentials, maskSecret, saveCredentials, tryLoadCredentials, } from './credentials.js';
+import { DEFAULT_WS_URL } from '../listen.js';
+export class PairError extends Error {
+}
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Whether a value is a UUID string, which is how the server types ids. */
+function isUuid(value) {
+    return typeof value === 'string' && UUID_PATTERN.test(value);
+}
+/** Derive the API base from the server-reported MCP URL, so the server wins. */
+function baseFromMcpUrl(mcpUrl, fallback) {
+    return mcpUrl.endsWith('/mcp') ? mcpUrl.slice(0, -'/mcp'.length) : fallback;
+}
+/**
+ * Redeem ``code`` and persist the resulting credentials.
+ *
+ * @throws PairError when the code is rejected or the response is malformed.
+ */
+export async function runPair(options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const onLine = options.onLine ?? ((line) => process.stdout.write(`${line}\n`));
+    const baseUrl = (options.baseUrl ?? DEFAULT_API_BASE_URL).replace(/\/+$/, '');
+    const wsUrl = options.wsUrl ?? DEFAULT_WS_URL;
+    if (options.webhookUrl && !options.webhookUrl.startsWith('https://')) {
+        throw new PairError('--webhook-url must be an https:// URL');
+    }
+    let response;
+    try {
+        response = await fetchImpl(`${baseUrl}${REDEEM_PATH}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'User-Agent': USER_AGENT },
+            body: JSON.stringify({
+                code: options.code,
+                ...(options.webhookUrl ? { webhook_url: options.webhookUrl } : {}),
+            }),
+        });
+    }
+    catch (err) {
+        throw new PairError(`Could not reach ${baseUrl}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (response.status === 404) {
+        throw new PairError('Pairing code is invalid, expired, or already used. Codes are single-use and ' +
+            'expire 15 minutes after they are generated — generate a fresh one.');
+    }
+    if (response.status === 429) {
+        throw new PairError('Too many pairing attempts from this IP. Wait an hour and retry.');
+    }
+    if (!response.ok) {
+        throw new PairError(`Pairing failed with HTTP ${response.status}.`);
+    }
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        throw new PairError('Pairing succeeded but the response was not valid JSON.');
+    }
+    if (!body || typeof body.api_key !== 'string' || !body.agent) {
+        throw new PairError('Pairing response was missing an api_key or agent.');
+    }
+    // The response is JSON off the wire, so the TypeScript cast proves nothing.
+    // Check the two fields that decide how this pairing behaves, rather than
+    // coercing them and reporting the consequences much later as a websocket
+    // failure or an "also POSTed to undefined" line.
+    if (typeof body.stream_only !== 'boolean') {
+        throw new PairError('Pairing response had no usable `stream_only` flag. The server may predate ' +
+            'stream-only pairing — check that it is running a current build.');
+    }
+    // The server types this `UUID | None`, so anything present that isn't a UUID
+    // is a malformed response. A looser "non-empty string" check would let a
+    // truncated or placeholder id through to be stored, and it would only fail
+    // later at the websocket where nothing points back to pairing.
+    if (body.subscription_id !== null &&
+        body.subscription_id !== undefined &&
+        !isUuid(body.subscription_id)) {
+        throw new PairError(`Pairing response contained an invalid subscription_id: ${JSON.stringify(body.subscription_id)}`);
+    }
+    // Redeem provisions a subscription on every path, stream-only included. A
+    // missing one means provisioning failed after the code was already spent
+    // (`shared/agents/connections.py` degrades rather than re-minting), and both
+    // the run dispatcher and the websocket auth gate refuse a connection that
+    // has none — so this credential can never receive a run. Fail here instead
+    // of storing it and letting the operator meet it later as an auth error
+    // with no obvious cause.
+    if (!body.subscription_id) {
+        // Redeem revokes the previously paired credential unconditionally, even on
+        // this path (`connections.py` step 6 runs after the provisioning failure is
+        // swallowed). So on a re-pair of the same agent, whatever is on disk is
+        // already dead — leaving it would send the operator chasing an
+        // `invalid_api_key` at `agent run` instead of the real cause.
+        const stored = tryLoadCredentials(options.env);
+        const staleRevoked = stored?.agent?.id === body.agent.id && clearCredentials(options.env);
+        throw new PairError('Pairing completed but no event subscription was provisioned, so this agent ' +
+            'would never receive a run.\n' +
+            '  The pairing code is spent either way — generate a fresh one and pair again.\n' +
+            (staleRevoked
+                ? '  The previously stored credential for this agent was revoked by this ' +
+                    'redeem and has been removed.'
+                : '  Nothing was saved.'));
+    }
+    const credentials = {
+        version: CREDENTIALS_VERSION,
+        base_url: baseFromMcpUrl(body.mcp_url ?? '', baseUrl),
+        ws_url: wsUrl,
+        api_key: body.api_key,
+        webhook_secret: body.webhook_secret ?? null,
+        subscription_id: body.subscription_id ?? null,
+        stream_only: body.stream_only,
+        mcp_url: body.mcp_url,
+        events: body.events ?? [],
+        agent: body.agent,
+        paired_at: new Date().toISOString(),
+    };
+    const file = saveCredentials(credentials, options.env);
+    onLine(`✓ Paired as "${body.agent.name}" (agent ${body.agent.id})`);
+    onLine(`  API key      ${maskSecret(body.api_key)}  (stored, never printed in full)`);
+    onLine(`  Credentials  ${file}  (chmod 600)`);
+    onLine(`  MCP URL      ${body.mcp_url}`);
+    onLine(`  Events       ${credentials.events.join(', ') || '(none)'}`);
+    onLine(`  Delivery     ${credentials.stream_only
+        ? 'stream-only — events arrive over the websocket, nothing is POSTed to you'
+        : `over the websocket, and POSTed to ${options.webhookUrl ?? 'your registered endpoint'}`}`);
+    if (!credentials.webhook_secret) {
+        // Without a secret the runner can't prove an event came from ProhostAI,
+        // and a run event makes this machine execute a command — so it refuses to
+        // run rather than trusting it.
+        onLine('');
+        onLine('  ! No signing secret was issued, so incoming events cannot be verified');
+        onLine('    and runs will be refused. Re-pair, or pass --allow-unverified if you');
+        onLine('    accept unauthenticated triggers.');
+    }
+    onLine('');
+    onLine('Next: start your agent and leave it running.');
+    onLine("  prohost agent run --exec 'claude -p'");
+    return { credentials, path: file };
+}

package/dist/agent/prompt.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Turns an `agent.run_requested` event into the prompt handed to the local agent.
+ *
+ * Kept plain and self-describing because we have no idea what is on the other
+ * end of ``--exec``: the text has to make sense to Claude Code, Codex, goose, or
+ * a shell script that greps it. The reply contract is stated explicitly so an
+ * agent that would otherwise narrate its reasoning returns something sendable.
+ */
+import type { AgentRunRequest } from './contract.js';
+export interface PromptContext {
+    /** Display name of the paired AI employee, e.g. "Ada". */
+    agentName: string;
+    /** MCP endpoint the agent can use to act back into the account. */
+    mcpUrl?: string;
+}
+/** Build the stdin prompt for one run. */
+export declare function buildPrompt(run: AgentRunRequest, context: PromptContext): string;
+/**
+ * Normalize an agent's stdout into a postable message.
+ *
+ * Only trims surrounding whitespace: everything else the agent wrote is the
+ * host's message to send, and second-guessing it here would be surprising.
+ */
+export declare function replyFromStdout(stdout: string): string;

package/dist/agent/prompt.js

@@ -0,0 +1,77 @@
+/**
+ * Turns an `agent.run_requested` event into the prompt handed to the local agent.
+ *
+ * Kept plain and self-describing because we have no idea what is on the other
+ * end of ``--exec``: the text has to make sense to Claude Code, Codex, goose, or
+ * a shell script that greps it. The reply contract is stated explicitly so an
+ * agent that would otherwise narrate its reasoning returns something sendable.
+ */
+/** Build the stdin prompt for one run. */
+export function buildPrompt(run, context) {
+    const name = run.agent_name ?? context.agentName;
+    const canReply = Boolean(run.reply_surface !== 'none' && run.reply_path && run.reply_body_key);
+    const lines = [
+        `You are "${name}", an AI teammate in a ProhostAI workspace.`,
+        canReply && run.reply_surface === 'conversation'
+            ? 'You were mentioned in a conversation and someone is waiting on a reply.'
+            : run.reply_surface === 'none'
+                ? 'You have been given work to do. There is nowhere to reply.'
+                : canReply
+                    ? `You were mentioned on a ${run.reply_surface} and someone is waiting on a reply.`
+                    : `You have been given work on a ${run.reply_surface}. There is nowhere to post a reply.`,
+        '',
+    ];
+    const facts = [];
+    if (run.kind)
+        facts.push(`Why you woke up: ${run.kind}`);
+    if (run.trigger_source)
+        facts.push(`Surface: ${run.trigger_source}`);
+    // The entity the run is about, so the agent can look it up over MCP rather
+    // than guess at what "this" refers to.
+    if (run.conversation_id)
+        facts.push(`Conversation: ${run.conversation_id}`);
+    if (run.task_id)
+        facts.push(`Task: ${run.task_id}`);
+    if (run.cleaning_id)
+        facts.push(`Cleaning: ${run.cleaning_id}`);
+    if (run.trigger_type)
+        facts.push(`Triggering event: ${run.trigger_type}`);
+    if (run.trigger_entity_id)
+        facts.push(`Event subject: ${run.trigger_entity_id}`);
+    // Comment surfaces carry no inline text excerpt, so the comment id is the
+    // only handle the agent has on what was actually said.
+    if (run.trigger_message_id)
+        facts.push(`Comment/message id: ${run.trigger_message_id}`);
+    if (context.mcpUrl) {
+        facts.push(`ProhostAI MCP endpoint (for looking things up): ${context.mcpUrl}`);
+    }
+    if (facts.length > 0) {
+        lines.push('Context:', ...facts.map((f) => `- ${f}`), '');
+    }
+    if (run.trigger_text) {
+        // The server caps this excerpt, so say so rather than let an agent assume
+        // it has the whole message.
+        lines.push('Message that woke you (may be truncated by the server):', run.trigger_text, '');
+    }
+    else {
+        lines.push('The message text was not included in the event.', '');
+    }
+    // Postability is a separate question from what the run is about: a task run
+    // has no comment route in the external API yet, so the agent must be told its
+    // output won't be posted rather than left to assume it will.
+    lines.push(canReply
+        ? 'Write your reply to that message. Reply with the message text only — no'
+        : 'Summarize what you did, in one short message. Output the message only — no', 'preamble, no explanation of your reasoning, no surrounding quotes. Your', canReply
+        ? `entire stdout is posted verbatim as your reply on the ${run.reply_surface}.`
+        : 'stdout is recorded but not posted anywhere — act through your own tools.');
+    return `${lines.join('\n')}\n`;
+}
+/**
+ * Normalize an agent's stdout into a postable message.
+ *
+ * Only trims surrounding whitespace: everything else the agent wrote is the
+ * host's message to send, and second-guessing it here would be surprising.
+ */
+export function replyFromStdout(stdout) {
+    return stdout.trim();
+}

package/dist/agent/run.d.ts

@@ -0,0 +1,78 @@
+/**
+ * `prohost agent run` — the event loop that makes a local agent a teammate.
+ *
+ * Connects to the same authenticated `/ws/webhooks` stream `prohost listen`
+ * uses, and for every `agent.run_requested` frame: verifies the HMAC, builds a
+ * prompt, runs the host's ``--exec`` command with that prompt on stdin, posts
+ * stdout back into the conversation, and closes the run out. A run is *always*
+ * completed — a crashed or timed-out command reports ``failed`` rather than
+ * being left hanging.
+ *
+ * Two deliberate safety properties:
+ *
+ * * **Runs are serialized.** One local agent, one run at a time; concurrent
+ *   frames queue. Agents hold working directories and rate limits, and running
+ *   several at once is a good way to corrupt both.
+ * * **Runs are deduped on ``run_id``.** Webhook deliveries retry, and each
+ *   attempt is mirrored to this socket. Without dedupe a retry would execute
+ *   the command a second time and post a second reply.
+ */
+import type { spawn } from 'node:child_process';
+import WebSocket from 'ws';
+import type { AgentCredentials } from './credentials.js';
+/** Default ceiling on one agent invocation. */
+export declare const DEFAULT_EXEC_TIMEOUT_MS = 300000;
+export interface AgentRunOptions {
+    /** Shell command that runs the agent, e.g. ``claude -p``. */
+    exec: string;
+    credentials: AgentCredentials;
+    /** Websocket endpoint override. Defaults to the paired value. */
+    url?: string;
+    /** Machine name shown in the ProhostAI UI. Defaults to the OS hostname. */
+    machine?: string;
+    /** Per-run execution timeout. */
+    timeoutMs?: number;
+    /** Print the reply that would be posted and make no writes. */
+    dryRun?: boolean;
+    /** Execute runs whose signature could not be verified. Off by default. */
+    allowUnverified?: boolean;
+    /** Working directory for the agent command. */
+    cwd?: string;
+    onLine?: (line: string) => void;
+    webSocketCtor?: typeof WebSocket;
+    fetchImpl?: typeof fetch;
+    spawnImpl?: typeof spawn;
+    signal?: AbortSignal;
+    /** Stop after this many connection attempts. Unlimited when unset (tests set it). */
+    maxConnections?: number;
+    /** Injectable sleep so tests don't wait out the reconnect backoff. */
+    sleepImpl?: (ms: number) => Promise<void>;
+    /** Environment used to locate the run ledger (tests point this at a temp dir). */
+    env?: NodeJS.ProcessEnv;
+}
+export interface AgentRunMetrics {
+    connections: number;
+    eventsReceived: number;
+    runsStarted: number;
+    runsSucceeded: number;
+    runsFailed: number;
+    /** Frames dropped because the HMAC didn't verify (or couldn't be checked). */
+    signatureRejections: number;
+    /** Frames for events the harness doesn't act on. */
+    ignored: number;
+    /** Repeat deliveries of a run already handled this session. */
+    duplicates: number;
+    /**
+     * Set when the harness stopped for a reason retrying can't fix (a rejected
+     * credential). The CLI exits nonzero on it, so a service manager doesn't
+     * read "never connected" as success.
+     */
+    fatal?: string;
+}
+/**
+ * Run the harness until the abort signal fires (or ``maxConnections`` is hit).
+ *
+ * Reconnects on any drop with jittered exponential backoff; an ``auth_error``
+ * is fatal, because retrying a rejected credential just hammers the server.
+ */
+export declare function runAgentHarness(options: AgentRunOptions): Promise<AgentRunMetrics>;