@prohost/cli 0.1.0

package/dist/agent/signature.js

@@ -0,0 +1,99 @@
+/**
+ * HMAC verification for events arriving over the websocket.
+ *
+ * A run event makes this CLI execute a local command, so the frame has to be
+ * proven to come from ProhostAI before it is acted on. HTTPS webhook receivers
+ * verify the HMAC over the raw request body; the websocket carries the payload
+ * as parsed JSON instead, so we re-serialize it in the exact form the server
+ * signed and compare.
+ *
+ * The server signs ``json.dumps(envelope, sort_keys=True, default=str)``
+ * (`shared/webhooks_outbound/signing.py::canonical_body`), which means:
+ * recursively sorted keys, Python's ``", "`` / ``": "`` separators, and
+ * ``ensure_ascii=True`` (every character outside ``0x20``–``0x7e`` escaped as
+ * ``\uXXXX``, non-BMP as a UTF-16 surrogate pair — which is what JS strings
+ * already hold). :func:`canonicalJson` reproduces that byte-for-byte.
+ *
+ * Known limit: JSON has one number type but Python does not. A float that
+ * round-trips through ``JSON.parse`` as an integer (``1.0`` → ``1``)
+ * re-serializes as ``1`` and fails verification. ProhostAI event payloads carry
+ * ids, timestamps, and text — no bare floats — so this has no practical effect;
+ * it is called out because the failure mode would otherwise look like tampering.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+const ESCAPES = {
+    '\\': '\\\\',
+    '"': '\\"',
+    '\b': '\\b',
+    '\f': '\\f',
+    '\n': '\\n',
+    '\r': '\\r',
+    '\t': '\\t',
+};
+/** Serialize a string the way Python's ``json.dumps(ensure_ascii=True)`` does. */
+function encodeString(value) {
+    let out = '"';
+    for (let i = 0; i < value.length; i += 1) {
+        const ch = value[i];
+        const escaped = ESCAPES[ch];
+        if (escaped !== undefined) {
+            out += escaped;
+            continue;
+        }
+        const code = value.charCodeAt(i);
+        if (code < 0x20 || code > 0x7e) {
+            out += `\\u${code.toString(16).padStart(4, '0')}`;
+            continue;
+        }
+        out += ch;
+    }
+    return `${out}"`;
+}
+/**
+ * Re-create the exact JSON bytes the server signed.
+ *
+ * Mirrors ``json.dumps(value, sort_keys=True, default=str)``: sorted keys,
+ * a space after every ``:`` and ``,``, and ASCII-escaped output.
+ */
+export function canonicalJson(value) {
+    if (value === null || value === undefined)
+        return 'null';
+    if (typeof value === 'string')
+        return encodeString(value);
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'number') {
+        // Non-finite numbers cannot appear in a JSON.parse result; treat them as
+        // null so a hand-constructed value can never throw here.
+        return Number.isFinite(value) ? String(value) : 'null';
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalJson(item)).join(', ')}]`;
+    }
+    if (typeof value === 'object') {
+        const entries = Object.entries(value)
+            // Python sorts by code point; JS's default sort compares UTF-16 code
+            // units, which agrees for every key in our payloads (ASCII field names).
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([key, item]) => `${encodeString(key)}: ${canonicalJson(item)}`);
+        return `{${entries.join(', ')}}`;
+    }
+    // Anything else (function/symbol) can't come out of JSON.parse.
+    return 'null';
+}
+/**
+ * Constant-time check that ``signature`` is the server's HMAC-SHA256 over
+ * ``payload``. Returns ``false`` for an empty signature or secret rather than
+ * throwing — the caller decides what an unverifiable frame means.
+ */
+export function verifySignature(secret, payload, signature) {
+    if (!secret || !signature)
+        return false;
+    const expected = createHmac('sha256', secret).update(canonicalJson(payload)).digest('hex');
+    // Strip the ``sha256=`` prefix the HTTP header carries, in case a future
+    // server sends the header form over the socket too.
+    const received = signature.startsWith('sha256=') ? signature.slice('sha256='.length) : signature;
+    if (received.length !== expected.length)
+        return false;
+    return timingSafeEqual(Buffer.from(expected), Buffer.from(received));
+}

package/dist/forward.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Webhook forwarding logic — pure functions, no CLI / websocket dependencies.
+ *
+ * Separated from the `listen` command so tests can exercise the forward-to
+ * behaviour against a mock websocket and a mock `fetch`.
+ */
+export interface WebhookEvent {
+    type: 'event';
+    event: string;
+    delivery_id: string;
+    signature: string;
+    payload: Record<string, unknown>;
+}
+export interface ForwardResult {
+    delivery_id: string;
+    status: number;
+    ok: boolean;
+    error?: string;
+    duration_ms: number;
+}
+export interface ForwardOptions {
+    /** Local URL to POST the payload to. */
+    forwardTo: string;
+    /** HTTP fetch implementation — defaults to the global `fetch`. Injectable for tests. */
+    fetchImpl?: typeof fetch;
+    /** Request timeout in milliseconds. Defaults to 10 seconds. */
+    timeoutMs?: number;
+}
+/**
+ * POST a webhook event's payload to the configured local URL, preserving the
+ * signature headers so local handlers see the same shape as a production
+ * webhook delivery.
+ */
+export declare function forwardEvent(event: WebhookEvent, options: ForwardOptions): Promise<ForwardResult>;
+/**
+ * Type guard — validates a raw JSON-decoded websocket frame as a
+ * :class:`WebhookEvent`. Anything that fails the guard is ignored by the CLI.
+ */
+export declare function isWebhookEvent(frame: unknown): frame is WebhookEvent;

package/dist/forward.js

@@ -0,0 +1,68 @@
+/**
+ * Webhook forwarding logic — pure functions, no CLI / websocket dependencies.
+ *
+ * Separated from the `listen` command so tests can exercise the forward-to
+ * behaviour against a mock websocket and a mock `fetch`.
+ */
+import { USER_AGENT } from './version.js';
+/**
+ * POST a webhook event's payload to the configured local URL, preserving the
+ * signature headers so local handlers see the same shape as a production
+ * webhook delivery.
+ */
+export async function forwardEvent(event, options) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const started = Date.now();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetchImpl(options.forwardTo, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-ProhostAI-Event': event.event,
+                'X-ProhostAI-Delivery': event.delivery_id,
+                'X-ProhostAI-Signature': event.signature,
+                'User-Agent': USER_AGENT,
+            },
+            body: JSON.stringify(event.payload),
+            signal: controller.signal,
+        });
+        const ok = response.status >= 200 && response.status < 300;
+        return {
+            delivery_id: event.delivery_id,
+            status: response.status,
+            ok,
+            duration_ms: Date.now() - started,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            delivery_id: event.delivery_id,
+            status: 0,
+            ok: false,
+            error: message,
+            duration_ms: Date.now() - started,
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Type guard — validates a raw JSON-decoded websocket frame as a
+ * :class:`WebhookEvent`. Anything that fails the guard is ignored by the CLI.
+ */
+export function isWebhookEvent(frame) {
+    if (!frame || typeof frame !== 'object')
+        return false;
+    const f = frame;
+    return (f.type === 'event' &&
+        typeof f.event === 'string' &&
+        typeof f.delivery_id === 'string' &&
+        typeof f.signature === 'string' &&
+        typeof f.payload === 'object' &&
+        f.payload !== null);
+}

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * `@prohost/cli` — entrypoint.
+ *
+ * Two commands:
+ *
+ *     npx @prohost/cli listen --forward-to http://localhost:3000/webhook
+ *     npx @prohost/cli agent pair --code <pairing-code>
+ *     npx @prohost/cli agent run --exec 'claude -p'
+ *
+ * Parses arguments with a zero-dep, zero-magic flag parser so the published
+ * binary stays small and starts fast.
+ */
+interface ParsedArgs {
+    command: string | undefined;
+    /** Second positional, e.g. the ``pair`` in ``prohost agent pair``. */
+    subcommand: string | undefined;
+    flags: Record<string, string | boolean>;
+}
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;
+declare function main(argv: readonly string[]): Promise<number>;
+export { main };
+/**
+ * True when this module is the process entrypoint rather than an import.
+ *
+ * ⚠️ Do NOT "simplify" this back to comparing `import.meta.url` against a
+ * hand-built `file://` + `process.argv[1]`. That looks equivalent and is not; it is
+ * the exact bug this function exists to fix, and it fails **silently** — the
+ * CLI exits 0 having printed nothing, so there is no error to search for.
+ * Two independent reasons the string form is wrong:
+ *
+ * 1. **Symlinks.** `npm i -g` (and `npx`) install a `bin` as a symlink, so
+ *    `process.argv[1]` is `<prefix>/bin/prohost` while `import.meta.url` is the
+ *    realpath inside `<prefix>/lib/node_modules/@prohost/cli/dist/`. Those never
+ *    match, so `main()` never runs for any user who installed the package —
+ *    i.e. every user. Resolving both sides through `realpathSync` is what makes
+ *    the symlinked and direct invocations agree.
+ *
+ * 2. **URL encoding.** A file URL percent-encodes characters that are legal in
+ *    a path, so concatenating `file://` onto a raw path diverges whenever the
+ *    path contains a space (`My Documents` → `My%20Documents`), non-ASCII, or a
+ *    Windows drive letter (`C:\…` → `file:///C:/…`). `fileURLToPath` decodes
+ *    properly and returns a real filesystem path, which is the only thing safe
+ *    to compare against another filesystem path.
+ *
+ * `src/index.test.ts` guards both: the resolver cases directly, and — the
+ * load-bearing one — by spawning the built `dist/index.js` through a real
+ * symlink and asserting on its **stdout**, because a no-op also exits 0 and
+ * exit status alone cannot tell working from broken.
+ */
+export declare function isEntrypointModule(moduleUrl: string, argv1: string | undefined, resolve?: (p: string) => string): boolean;

package/dist/index.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+/**
+ * `@prohost/cli` — entrypoint.
+ *
+ * Two commands:
+ *
+ *     npx @prohost/cli listen --forward-to http://localhost:3000/webhook
+ *     npx @prohost/cli agent pair --code <pairing-code>
+ *     npx @prohost/cli agent run --exec 'claude -p'
+ *
+ * Parses arguments with a zero-dep, zero-magic flag parser so the published
+ * binary stays small and starts fast.
+ */
+import { realpathSync } from 'node:fs';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { runAgent } from './agent/command.js';
+import { DEFAULT_WS_URL, runListen } from './listen.js';
+import { CLI_VERSION } from './version.js';
+function printHelp() {
+    const lines = [
+        'prohost — ProhostAI CLI',
+        '',
+        'Usage:',
+        '  prohost listen --forward-to <local-url> [--api-key <key>] [--url <ws-url>] [--machine <name>] [--subscription-id <id>]',
+        '  prohost agent pair --code <pairing-code> [--webhook-url <https-url>] [--base-url <url>]',
+        "  prohost agent run --exec '<command>' [--timeout <seconds>] [--dry-run] [--cwd <dir>]",
+        '',
+        'listen flags:',
+        '  --forward-to     Local URL to POST each webhook payload to (required)',
+        '  --api-key        ProhostAI API key. Defaults to $PROHOST_API_KEY.',
+        '  --url            Websocket endpoint. Defaults to wss://api.prohost.ai/ws/webhooks.',
+        '  --machine        Machine name displayed in the UI. Defaults to the OS hostname.',
+        '  --subscription-id  Stamp connected_from on a specific subscription row.',
+        '',
+        'agent pair flags:',
+        '  --code           One-time pairing code from the hire modal. Defaults to $PROHOST_PAIRING_CODE.',
+        '  --webhook-url    Also push events to this HTTPS endpoint. Omit it: stream-only is the normal setup.',
+        '  --base-url       Public API base. Defaults to https://connect.prohost.ai.',
+        '',
+        'agent run flags:',
+        '  --exec           Command to run for each mention; the prompt arrives on stdin (required)',
+        '  --timeout        Seconds one run may take before it is killed. Defaults to 300.',
+        '  --dry-run        Print the reply that would be posted; write nothing.',
+        '  --cwd            Working directory for the agent command.',
+        '  --machine        Machine name displayed in the UI. Defaults to the OS hostname.',
+        '  --url            Websocket endpoint. Defaults to the paired value.',
+        '  --allow-unverified  Run events whose signature could not be verified (not recommended).',
+        '',
+        'Global flags:',
+        '  --help, -h       Show this help and exit.',
+        '  --version, -v    Print the CLI version and exit.',
+        '',
+        'Environment:',
+        '  PROHOST_API_KEY       Used by `listen` when --api-key is not provided.',
+        '  PROHOST_WS_URL        Used when --url is not provided.',
+        '  PROHOST_PAIRING_CODE  Used by `agent pair` when --code is not provided.',
+        '  PROHOST_HOME          Credential directory. Defaults to ~/.prohost.',
+    ];
+    process.stdout.write(`${lines.join('\n')}\n`);
+}
+export function parseArgs(argv) {
+    const flags = {};
+    let command;
+    let subcommand;
+    let i = 0;
+    while (i < argv.length) {
+        const token = argv[i];
+        if (!token.startsWith('-')) {
+            if (!command)
+                command = token;
+            else if (!subcommand)
+                subcommand = token;
+            i += 1;
+            continue;
+        }
+        const key = token.replace(/^--?/, '');
+        const next = argv[i + 1];
+        if (key === 'help' || key === 'h') {
+            flags.help = true;
+            i += 1;
+            continue;
+        }
+        if (key === 'version' || key === 'v') {
+            flags.version = true;
+            i += 1;
+            continue;
+        }
+        if (next === undefined || next.startsWith('-')) {
+            flags[key] = true;
+            i += 1;
+        }
+        else {
+            flags[key] = next;
+            i += 2;
+        }
+    }
+    return { command, subcommand, flags };
+}
+async function main(argv) {
+    const { command, subcommand, flags } = parseArgs(argv);
+    // Checked before the help/no-command branch: `prohost --version` carries no
+    // command, which would otherwise print help and exit 1.
+    if (flags.version) {
+        process.stdout.write(`${CLI_VERSION}\n`);
+        return 0;
+    }
+    // An explicit `--help` is a successful request for help, so it exits 0 — the
+    // README opens with `npx @prohost/cli --help`, and a non-zero exit there
+    // fails any script or CI step that runs it. Bare `prohost` with no arguments
+    // is a usage error and still exits 1.
+    if (flags.help) {
+        printHelp();
+        return 0;
+    }
+    if (!command) {
+        printHelp();
+        return 1;
+    }
+    if (command === 'agent') {
+        return runAgent(subcommand, flags, printHelp);
+    }
+    if (command !== 'listen') {
+        process.stderr.write(`Unknown command: ${command}\n\n`);
+        printHelp();
+        return 1;
+    }
+    const forwardTo = typeof flags['forward-to'] === 'string' ? flags['forward-to'] : undefined;
+    if (!forwardTo) {
+        process.stderr.write('Missing required flag: --forward-to\n');
+        return 1;
+    }
+    const apiKey = (typeof flags['api-key'] === 'string' ? flags['api-key'] : undefined) ??
+        process.env.PROHOST_API_KEY;
+    if (!apiKey) {
+        process.stderr.write('Missing API key. Pass --api-key or set $PROHOST_API_KEY.\n');
+        return 1;
+    }
+    const url = (typeof flags['url'] === 'string' ? flags['url'] : undefined) ??
+        process.env.PROHOST_WS_URL ??
+        DEFAULT_WS_URL;
+    const machine = typeof flags['machine'] === 'string' ? flags['machine'] : undefined;
+    const subscriptionId = typeof flags['subscription-id'] === 'string' ? flags['subscription-id'] : undefined;
+    const controller = new AbortController();
+    const onSig = () => controller.abort();
+    process.on('SIGINT', onSig);
+    process.on('SIGTERM', onSig);
+    try {
+        await runListen({
+            forwardTo,
+            apiKey,
+            url,
+            machine,
+            subscriptionId,
+            signal: controller.signal,
+        });
+        process.stdout.write('\n');
+        return 0;
+    }
+    finally {
+        process.off('SIGINT', onSig);
+        process.off('SIGTERM', onSig);
+    }
+}
+// Export the entrypoint so tests can import `parseArgs` without running main.
+export { main };
+/**
+ * True when this module is the process entrypoint rather than an import.
+ *
+ * ⚠️ Do NOT "simplify" this back to comparing `import.meta.url` against a
+ * hand-built `file://` + `process.argv[1]`. That looks equivalent and is not; it is
+ * the exact bug this function exists to fix, and it fails **silently** — the
+ * CLI exits 0 having printed nothing, so there is no error to search for.
+ * Two independent reasons the string form is wrong:
+ *
+ * 1. **Symlinks.** `npm i -g` (and `npx`) install a `bin` as a symlink, so
+ *    `process.argv[1]` is `<prefix>/bin/prohost` while `import.meta.url` is the
+ *    realpath inside `<prefix>/lib/node_modules/@prohost/cli/dist/`. Those never
+ *    match, so `main()` never runs for any user who installed the package —
+ *    i.e. every user. Resolving both sides through `realpathSync` is what makes
+ *    the symlinked and direct invocations agree.
+ *
+ * 2. **URL encoding.** A file URL percent-encodes characters that are legal in
+ *    a path, so concatenating `file://` onto a raw path diverges whenever the
+ *    path contains a space (`My Documents` → `My%20Documents`), non-ASCII, or a
+ *    Windows drive letter (`C:\…` → `file:///C:/…`). `fileURLToPath` decodes
+ *    properly and returns a real filesystem path, which is the only thing safe
+ *    to compare against another filesystem path.
+ *
+ * `src/index.test.ts` guards both: the resolver cases directly, and — the
+ * load-bearing one — by spawning the built `dist/index.js` through a real
+ * symlink and asserting on its **stdout**, because a no-op also exits 0 and
+ * exit status alone cannot tell working from broken.
+ */
+export function isEntrypointModule(moduleUrl, argv1, resolve = realpathSync) {
+    if (argv1 === undefined)
+        return false;
+    try {
+        return resolve(argv1) === resolve(fileURLToPath(moduleUrl));
+    }
+    catch {
+        // A deleted or unreadable path is not the entrypoint; never throw out of
+        // module top-level, which would take the whole process down on import.
+        return false;
+    }
+}
+const isEntrypoint = isEntrypointModule(import.meta.url, process.argv[1]) ||
+    process.env.PROHOST_CLI_RUN === '1';
+if (isEntrypoint) {
+    main(process.argv.slice(2)).then((code) => {
+        process.exit(code);
+    }, (err) => {
+        process.stderr.write(`prohost: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(1);
+    });
+}

package/dist/listen.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `prohost listen --forward-to <url>` — connects to the authenticated
+ * websocket, forwards events to a local URL, and displays a live counter.
+ */
+import WebSocket from 'ws';
+export interface ListenOptions {
+    /** Local URL that each event is POSTed to. */
+    forwardTo: string;
+    /** ProhostAI API key (``ph_live_*``). Also accepted via ``PROHOST_API_KEY``. */
+    apiKey: string;
+    /** Websocket endpoint. Defaults to production. */
+    url?: string;
+    /** Machine name displayed in the UI. Defaults to ``os.hostname()``. */
+    machine?: string;
+    /** Stamp a specific webhook subscription with this connection. */
+    subscriptionId?: string;
+    /**
+     * Called with a one-line status string every time the counter changes.
+     * Defaults to stdout. Tests override this to capture output.
+     */
+    onStatus?: (line: string) => void;
+    /**
+     * Websocket constructor. Defaults to ``ws.WebSocket``. Tests pass a mock
+     * constructor that exposes a fake server.
+     */
+    webSocketCtor?: typeof WebSocket;
+    /** Injectable ``fetch`` for forwarding — defaults to the global. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Stop the listener when called. Resolves once the socket has been closed
+     * and the final status has been emitted.
+     */
+    signal?: AbortSignal;
+}
+export interface ListenMetrics {
+    connected: boolean;
+    eventsReceived: number;
+    eventsForwarded: number;
+    forwardErrors: number;
+}
+export declare const DEFAULT_WS_URL = "wss://api.prohost.ai/ws/webhooks";
+/**
+ * Run the listener until the abort signal fires or the socket closes.
+ *
+ * Exposed as a standalone async function (as opposed to the CLI ``main``)
+ * so tests can drive it with a fake websocket.
+ */
+export declare function runListen(options: ListenOptions): Promise<ListenMetrics>;

package/dist/listen.js

@@ -0,0 +1,113 @@
+/**
+ * `prohost listen --forward-to <url>` — connects to the authenticated
+ * websocket, forwards events to a local URL, and displays a live counter.
+ */
+import os from 'node:os';
+import WebSocket from 'ws';
+import { forwardEvent, isWebhookEvent } from './forward.js';
+export const DEFAULT_WS_URL = 'wss://api.prohost.ai/ws/webhooks';
+/**
+ * Run the listener until the abort signal fires or the socket closes.
+ *
+ * Exposed as a standalone async function (as opposed to the CLI ``main``)
+ * so tests can drive it with a fake websocket.
+ */
+export async function runListen(options) {
+    const url = options.url ?? DEFAULT_WS_URL;
+    const machine = options.machine ?? os.hostname();
+    const Ctor = options.webSocketCtor ?? WebSocket;
+    const onStatus = options.onStatus ?? ((line) => process.stdout.write(`${line}\r`));
+    const metrics = {
+        connected: false,
+        eventsReceived: 0,
+        eventsForwarded: 0,
+        forwardErrors: 0,
+    };
+    const ws = new Ctor(url);
+    return new Promise((resolve) => {
+        const status = () => {
+            const dot = metrics.connected ? '\u25CF' : '\u25CB';
+            onStatus(`${dot} prohost listen \u2192 ${options.forwardTo} | Events: ${metrics.eventsReceived} | Forwarded: ${metrics.eventsForwarded} | Errors: ${metrics.forwardErrors}`);
+        };
+        const closeWith = () => {
+            try {
+                ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+        };
+        if (options.signal) {
+            if (options.signal.aborted)
+                closeWith();
+            else
+                options.signal.addEventListener('abort', closeWith, { once: true });
+        }
+        ws.on('open', () => {
+            const authFrame = {
+                type: 'auth',
+                api_key: options.apiKey,
+                machine,
+                ...(options.subscriptionId ? { subscription_id: options.subscriptionId } : {}),
+            };
+            ws.send(JSON.stringify(authFrame));
+        });
+        ws.on('message', async (data) => {
+            let frame;
+            try {
+                frame = JSON.parse(data.toString());
+            }
+            catch {
+                return;
+            }
+            if (!frame || typeof frame !== 'object')
+                return;
+            const f = frame;
+            if (f.type === 'auth_ok') {
+                metrics.connected = true;
+                status();
+                return;
+            }
+            if (f.type === 'auth_error') {
+                onStatus(`\n\u2717 auth_error: ${String(f.reason ?? 'unknown')}\n`);
+                closeWith();
+                return;
+            }
+            if (f.type === 'ping') {
+                ws.send(JSON.stringify({ type: 'pong' }));
+                return;
+            }
+            if (isWebhookEvent(frame)) {
+                metrics.eventsReceived += 1;
+                status();
+                const result = await forwardEvent(frame, {
+                    forwardTo: options.forwardTo,
+                    fetchImpl: options.fetchImpl,
+                });
+                if (result.ok)
+                    metrics.eventsForwarded += 1;
+                else
+                    metrics.forwardErrors += 1;
+                status();
+                try {
+                    ws.send(JSON.stringify({
+                        type: 'ack',
+                        delivery_id: result.delivery_id,
+                        status: result.status,
+                    }));
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+        });
+        ws.on('close', () => {
+            metrics.connected = false;
+            status();
+            resolve(metrics);
+        });
+        ws.on('error', () => {
+            /* handled via close */
+        });
+    });
+}

package/dist/version.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The published version, in one place.
+ *
+ * Kept as a literal rather than read from `package.json` at runtime: `rootDir`
+ * is `src/`, so importing `../package.json` would drag it into `dist/` and
+ * change the emitted layout. `version.test.ts` asserts this constant matches
+ * `package.json`, so a release bump that forgets this file fails the suite
+ * instead of shipping a `User-Agent` that lies about which build is calling.
+ */
+export declare const CLI_VERSION = "0.1.0";
+/** Sent on every HTTP request the CLI makes back into ProhostAI. */
+export declare const USER_AGENT = "prohost-cli/0.1.0";

package/dist/version.js

@@ -0,0 +1,12 @@
+/**
+ * The published version, in one place.
+ *
+ * Kept as a literal rather than read from `package.json` at runtime: `rootDir`
+ * is `src/`, so importing `../package.json` would drag it into `dist/` and
+ * change the emitted layout. `version.test.ts` asserts this constant matches
+ * `package.json`, so a release bump that forgets this file fails the suite
+ * instead of shipping a `User-Agent` that lies about which build is calling.
+ */
+export const CLI_VERSION = '0.1.0';
+/** Sent on every HTTP request the CLI makes back into ProhostAI. */
+export const USER_AGENT = `prohost-cli/${CLI_VERSION}`;