@prohost/cli 0.9.0 → 0.10.1

package/dist/agent/pair.js

@@ -10,8 +10,9 @@
  * specific than "invalid, expired, or already used".
  */
 import { USER_AGENT } from '../version.js';
+import { baseUrlProblem, endpointProblem, isAllowedBaseUrl } from './base-url.js';
 import { DEFAULT_API_BASE_URL, REDEEM_PATH } from './contract.js';
-import { CREDENTIALS_VERSION, clearCredentials, maskSecret, saveCredentials, tryLoadCredentials, } from './credentials.js';
+import { CREDENTIALS_VERSION, clearCredentials, maskSecret, saveCredentials, tryLoadCredentials, wsUrlFromBaseUrl, } from './credentials.js';
 import { DEFAULT_WS_URL } from '../listen.js';
 export class PairError extends Error {
 }
@@ -20,28 +21,34 @@ const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{
 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. */
+/**
+ * Derive the API base from the server-reported MCP URL, so the server wins —
+ * unless it is one the API key may not be sent to (see `base-url.ts`).
+ */
 function baseFromMcpUrl(mcpUrl, fallback) {
-    return mcpUrl.endsWith('/mcp') ? mcpUrl.slice(0, -'/mcp'.length) : fallback;
+    const base = mcpUrl.endsWith('/mcp') ? mcpUrl.slice(0, -'/mcp'.length) : '';
+    return base && isAllowedBaseUrl(base) ? base : fallback;
 }
 /**
  * The websocket URL the server told us to use, or ``undefined``.
  *
- * ``undefined`` covers both "this server predates the field" and "the value is
- * not a websocket URL". A cosmetic bad value must not fail a redeem — the code
- * is already spent by the time we read the body — so the caller falls back to
- * {@link DEFAULT_WS_URL} and says so.
+ * ``undefined`` covers "this server predates the field", "the value is not a
+ * websocket URL" and "it is plain ws:// off loopback". A bad value must not
+ * fail a redeem — the code is already spent by the time we read the body — so
+ * the caller falls back to the stream on the stored API base's host and says so.
  */
 function serverWsUrl(value) {
     if (typeof value !== 'string' || value.length === 0)
         return undefined;
-    try {
-        const protocol = new URL(value).protocol;
-        return protocol === 'ws:' || protocol === 'wss:' ? value : undefined;
-    }
-    catch {
-        return undefined;
-    }
+    // `wss://`, or `ws://` on loopback only: the stream's auth frame carries the key.
+    return endpointProblem(value, 'ws') === undefined ? value : undefined;
+}
+/**
+ * The MCP URL to store: the server's, unless the API key may not be sent to
+ * it, in which case the one on the (already validated) API base.
+ */
+function safeMcpUrl(mcpUrl, baseUrl) {
+    return mcpUrl && isAllowedBaseUrl(mcpUrl) ? mcpUrl : `${baseUrl}/mcp`;
 }
 /**
  * Redeem ``code`` and persist the resulting credentials.
@@ -52,6 +59,14 @@ 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(/\/+$/, '');
+    // Checked before the code is spent: the code goes to this URL, and the API
+    // key comes back from it.
+    const baseProblem = baseUrlProblem(baseUrl);
+    if (baseProblem)
+        throw new PairError(`--base-url rejected: ${baseProblem}`);
+    const wsProblem = options.wsUrl ? endpointProblem(options.wsUrl, 'ws') : undefined;
+    if (wsProblem)
+        throw new PairError(`--url rejected: ${wsProblem}`);
     if (options.webhookUrl && !options.webhookUrl.startsWith('https://')) {
         throw new PairError('--webhook-url must be an https:// URL');
     }
@@ -136,18 +151,24 @@ export async function runPair(options) {
     //   2. The server's `ws_url`, derived server-side from the same setting as
     //      `mcp_url` (`shared/agents/connections.py::pairing_endpoints`). This is
     //      the normal path, and the reason a host move no longer needs a release.
-    //   3. `DEFAULT_WS_URL`, for a server that predates the field.
+    //   3. No usable `ws_url` (a server that predates the field, or a value that
+    //      is not a websocket URL or is plain ws:// off loopback): the stream on
+    //      the stored API base's host, as the server derives it — never another
+    //      deployment's, which would get this key. For the default base that is
+    //      `DEFAULT_WS_URL`, which is also the last resort.
+    const storedBase = baseFromMcpUrl(body.mcp_url ?? '', baseUrl);
     const fromServer = serverWsUrl(body.ws_url);
-    const wsUrl = options.wsUrl ?? fromServer ?? DEFAULT_WS_URL;
+    const fallbackWsUrl = wsUrlFromBaseUrl(storedBase) ?? DEFAULT_WS_URL;
+    const wsUrl = options.wsUrl ?? fromServer ?? fallbackWsUrl;
     const credentials = {
         version: CREDENTIALS_VERSION,
-        base_url: baseFromMcpUrl(body.mcp_url ?? '', baseUrl),
+        base_url: storedBase,
         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,
+        mcp_url: safeMcpUrl(body.mcp_url, storedBase),
         events: body.events ?? [],
         agent: body.agent,
         paired_at: new Date().toISOString(),
@@ -156,7 +177,7 @@ export async function runPair(options) {
     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(`  MCP URL      ${credentials.mcp_url}`);
     // Printed because 0.1.0's wrong websocket host was invisible here: pairing
     // reported success and the mismatch only surfaced as a 403 reconnect loop in
     // a different command. Showing it makes a bad host obvious at pair time.
@@ -171,7 +192,7 @@ export async function runPair(options) {
         // answer either.
         onLine('');
         onLine(`  ! The server reported an unusable stream URL (${JSON.stringify(body.ws_url)}).`);
-        onLine(`    Using ${DEFAULT_WS_URL} instead — override with --url if that is wrong.`);
+        onLine(`    Using ${fallbackWsUrl} instead — override with --url if that is wrong.`);
     }
     if (!credentials.webhook_secret) {
         // Without a secret the runner can't prove an event came from ProhostAI,

package/dist/index.d.ts

@@ -8,6 +8,7 @@
  *     npx @prohost/cli agent pair --code <pairing-code>
  *     npx @prohost/cli agent run --exec 'claude -p'
  *     npx @prohost/cli agent install-daemon --exec 'claude -p'
+ *     npx @prohost/cli usage connect --key <api-key>
  *
  * Parses arguments with a zero-dep, zero-magic flag parser so the published
  * binary stays small and starts fast.

package/dist/index.js

@@ -8,6 +8,7 @@
  *     npx @prohost/cli agent pair --code <pairing-code>
  *     npx @prohost/cli agent run --exec 'claude -p'
  *     npx @prohost/cli agent install-daemon --exec 'claude -p'
+ *     npx @prohost/cli usage connect --key <api-key>
  *
  * Parses arguments with a zero-dep, zero-magic flag parser so the published
  * binary stays small and starts fast.
@@ -15,8 +16,10 @@
 import { realpathSync } from 'node:fs';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
+import { endpointProblem } from './agent/base-url.js';
 import { runAgent } from './agent/command.js';
 import { DEFAULT_WS_URL, runListen } from './listen.js';
+import { runUsage } from './usage/command.js';
 import { CLI_VERSION } from './version.js';
 function printHelp() {
     const lines = [
@@ -33,6 +36,9 @@ function printHelp() {
         '  prohost agent account list | remove <label>',
         '  prohost agent list                   Every paired agent on this machine, and its accounts',
         '  prohost agent workspace init --developer --repo <checkout> [--workdir <dir>]',
+        '  prohost usage connect [--key -] [--base-url <url>]   Report AI usage without pairing an agent (prompts for the key; --key - reads it from stdin)',
+        '  prohost usage discover [--dry-run] | start [--once] [--machine <name>] | status',
+        '  prohost usage install-daemon [--machine <name>] | uninstall-daemon',
         '',
         'listen flags:',
         '  --forward-to     Local URL to POST each webhook payload to (required)',
@@ -44,7 +50,7 @@ function printHelp() {
         '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.',
+        '  --base-url       Public API base. Defaults to https://connect.prohost.ai. Must be https:// (http:// only for localhost).',
         '',
         'agent run flags:',
         '  --exec           Command to run for each mention; the prompt arrives on stdin (required)',
@@ -99,6 +105,15 @@ function printHelp() {
         '  Adds the ProhostAI PR-protocol skill and the `gh pr create` gate hook from --repo (a',
         '  backend-service checkout) to the agent workspace\'s .claude/. Opt-in; nothing else changes.',
         '',
+        'Usage reporting (observer mode):',
+        '  `usage connect` stores an API key with the usage:write scope ($PROHOST_HOME/usage.json, owner-only;',
+        '  a machine with a paired agent can reuse its credential) and registers every Claude Code and Codex',
+        '  login it finds: ~/.claude*, ~/.codex*, $CLAUDE_CONFIG_DIR, $CODEX_HOME (`~/.claude-work` → "work").',
+        '  `usage start` then reports, every 5 minutes, each login\'s remaining capacity — asked of the',
+        '  unmodified CLI, at most every 15 minutes per login — and daily token totals per model and project',
+        '  folder, read from the local session logs (last 30 days, then incrementally). Never prompt text.',
+        '  `--once` runs one pass and exits. `usage status` shows what was last sent.',
+        '',
         'agent install-daemon flags:  (macOS: launchd; Linux: prints a systemd-user unit)',
         '  --exec           The same command you would pass to `agent run` (required).',
         '  --workdir, --concurrency, --repos, --idle-timeout, --timeout, --machine, --url,',
@@ -148,7 +163,8 @@ export function parseArgs(argv) {
             i += 1;
             continue;
         }
-        if (next === undefined || next.startsWith('-')) {
+        // A bare `-` is a value ("read it from stdin", as in `--key -`), not a flag.
+        if (next === undefined || (next.startsWith('-') && next !== '-')) {
             flags[key] = true;
             i += 1;
         }
@@ -182,6 +198,9 @@ async function main(argv) {
     if (command === 'agent') {
         return runAgent(subcommand, flags, printHelp, args);
     }
+    if (command === 'usage') {
+        return runUsage(subcommand, flags, printHelp);
+    }
     if (command !== 'listen') {
         process.stderr.write(`Unknown command: ${command}\n\n`);
         printHelp();
@@ -201,6 +220,12 @@ async function main(argv) {
     const url = (typeof flags['url'] === 'string' ? flags['url'] : undefined) ??
         process.env.PROHOST_WS_URL ??
         DEFAULT_WS_URL;
+    // The auth frame carries the API key: wss://, or ws:// on loopback only.
+    const urlProblem = endpointProblem(url, 'ws');
+    if (urlProblem) {
+        process.stderr.write(`✗ --url rejected: ${urlProblem}\n`);
+        return 1;
+    }
     const machine = typeof flags['machine'] === 'string' ? flags['machine'] : undefined;
     const subscriptionId = typeof flags['subscription-id'] === 'string' ? flags['subscription-id'] : undefined;
     const controller = new AbortController();

package/dist/usage/backoff.d.ts

@@ -0,0 +1,42 @@
+/**
+ * When the usage reporter may try an endpoint again, and what it says about it.
+ *
+ * The reporter runs for weeks under launchd, so it must never crash and never
+ * fill a log. Three kinds of failure, treated differently:
+ *
+ * - **Gated** — 401, 403, 404. The routes are not deployed yet, the workspace
+ *   doesn't have the feature, or the key lacks `usage:write`. None of that
+ *   changes in minutes, so wait {@link GATED_BACKOFF_MS} and say so once —
+ *   not on every retry.
+ * - **Transient** — no response, 408, 429, 5xx. Retry with exponential backoff
+ *   from {@link BASE_BACKOFF_MS} up to {@link MAX_BACKOFF_MS}; logged once
+ *   per streak.
+ * - **Rejected** — any other 4xx. A body this build got wrong; retrying soon
+ *   won't fix it, so it waits like a gated one and logs the server's reason.
+ *
+ * A success after any of these says "recovered" once and resets everything.
+ */
+import type { ApiResult } from '../agent/api.js';
+export declare const BASE_BACKOFF_MS = 60000;
+export declare const MAX_BACKOFF_MS: number;
+export declare const GATED_BACKOFF_MS: number;
+export type FailureKind = 'gated' | 'transient' | 'rejected';
+export declare function classifyFailure(result: ApiResult): FailureKind;
+export declare class Backoff {
+    private readonly name;
+    private readonly now;
+    private nextAt;
+    private failures;
+    private lastKind;
+    private lastStatus;
+    constructor(name: string, now?: () => number);
+    /** Whether a request may be made now. */
+    ready(): boolean;
+    /** When the next attempt is allowed (epoch ms; 0 = now). */
+    retryAt(): number;
+    /**
+     * Record an attempt's outcome. Returns a line to log, or `undefined` when
+     * this outcome was already reported.
+     */
+    record(result: ApiResult): string | undefined;
+}

package/dist/usage/backoff.js

@@ -0,0 +1,85 @@
+/**
+ * When the usage reporter may try an endpoint again, and what it says about it.
+ *
+ * The reporter runs for weeks under launchd, so it must never crash and never
+ * fill a log. Three kinds of failure, treated differently:
+ *
+ * - **Gated** — 401, 403, 404. The routes are not deployed yet, the workspace
+ *   doesn't have the feature, or the key lacks `usage:write`. None of that
+ *   changes in minutes, so wait {@link GATED_BACKOFF_MS} and say so once —
+ *   not on every retry.
+ * - **Transient** — no response, 408, 429, 5xx. Retry with exponential backoff
+ *   from {@link BASE_BACKOFF_MS} up to {@link MAX_BACKOFF_MS}; logged once
+ *   per streak.
+ * - **Rejected** — any other 4xx. A body this build got wrong; retrying soon
+ *   won't fix it, so it waits like a gated one and logs the server's reason.
+ *
+ * A success after any of these says "recovered" once and resets everything.
+ */
+import { describeFailure } from '../agent/api.js';
+export const BASE_BACKOFF_MS = 60_000;
+export const MAX_BACKOFF_MS = 30 * 60_000;
+export const GATED_BACKOFF_MS = 30 * 60_000;
+export function classifyFailure(result) {
+    const { status } = result;
+    if (status === 401 || status === 403 || status === 404)
+        return 'gated';
+    if (status === 0 || status === 408 || status === 429 || status >= 500)
+        return 'transient';
+    return 'rejected';
+}
+export class Backoff {
+    name;
+    now;
+    nextAt = 0;
+    failures = 0;
+    lastKind;
+    lastStatus;
+    constructor(name, now = Date.now) {
+        this.name = name;
+        this.now = now;
+    }
+    /** Whether a request may be made now. */
+    ready() {
+        return this.now() >= this.nextAt;
+    }
+    /** When the next attempt is allowed (epoch ms; 0 = now). */
+    retryAt() {
+        return this.nextAt;
+    }
+    /**
+     * Record an attempt's outcome. Returns a line to log, or `undefined` when
+     * this outcome was already reported.
+     */
+    record(result) {
+        if (result.ok) {
+            const wasFailing = this.failures > 0;
+            this.failures = 0;
+            this.nextAt = 0;
+            this.lastKind = undefined;
+            this.lastStatus = undefined;
+            return wasFailing ? `${this.name}: recovered` : undefined;
+        }
+        const kind = classifyFailure(result);
+        this.failures += 1;
+        const delay = kind === 'transient'
+            ? Math.min(MAX_BACKOFF_MS, BASE_BACKOFF_MS * 2 ** Math.min(this.failures - 1, 16))
+            : GATED_BACKOFF_MS;
+        this.nextAt = this.now() + delay;
+        const repeat = this.lastKind === kind && (kind === 'transient' || this.lastStatus === result.status);
+        this.lastKind = kind;
+        this.lastStatus = result.status;
+        if (repeat)
+            return undefined;
+        const minutes = Math.round(delay / 60_000);
+        if (kind === 'gated') {
+            return (`${this.name}: ${describeFailure(result)} — usage reporting is not available for this key yet ` +
+                `(not deployed, not enabled for the workspace, or the key lacks usage:write). ` +
+                `Retrying every ${minutes} min.`);
+        }
+        if (kind === 'rejected') {
+            return `${this.name}: ${describeFailure(result)} rejected${result.error ? ` (${result.error.slice(0, 200)})` : ''}. Retrying in ${minutes} min.`;
+        }
+        return `${this.name}: ${describeFailure(result)}. Retrying with backoff (next in ${minutes} min).`;
+    }
+}

package/dist/usage/command.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `prohost usage …` — observer mode: report this machine's Claude Code and
+ * Codex capacity and token totals to ProhostAI without pairing an agent.
+ *
+ * Flag plumbing only; the work lives in `discovery.ts`, `quota.ts`,
+ * `scanner.ts` and `service.ts`.
+ */
+import type { DiscoveryResult } from './discovery.js';
+import type { KeyStdin } from './key-input.js';
+type Flags = Record<string, string | boolean>;
+export interface UsageIO {
+    out: (line: string) => void;
+    err: (line: string) => void;
+    env?: NodeJS.ProcessEnv;
+    /** Where `connect` reads a key from (`--key -`, a pipe, or a hidden prompt). Defaults to `process.stdin`. */
+    stdin?: KeyStdin;
+}
+/** launchd label prefix for the usage reporter — distinct from the agent daemon's. */
+export declare const USAGE_LAUNCHD_PREFIX = "ai.prohost.usage";
+/** Label for the usage daemon serving one `$PROHOST_HOME`. Same digest as the agent's, other prefix. */
+export declare function usageLaunchdLabel(home: string): string;
+export declare function usageLogPath(env?: NodeJS.ProcessEnv): string;
+/** `prohost usage start` argv for a supervisor. */
+export declare function usageDaemonArguments(options: {
+    execPath: string;
+    scriptPath: string;
+    machine?: string;
+}): string[];
+/** Dispatch a `usage` subcommand. Returns the exit code. */
+export declare function runUsage(subcommand: string | undefined, flags: Flags, printHelp: () => void, io?: UsageIO): Promise<number>;
+export declare function renderDiscovery(result: DiscoveryResult, env: NodeJS.ProcessEnv, dryRun: boolean): string[];
+/** `1234567` → `1.2M`. */
+export declare function compactTokens(n: number): string;
+export {};