@prohost/cli 0.1.0

package/dist/agent/run.js

@@ -0,0 +1,400 @@
+/**
+ * `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 os from 'node:os';
+import WebSocket from 'ws';
+import { completeRun, postReply } from './api.js';
+import { EVENT_AGENT_RUN_REQUESTED, EVENT_MENTION_CREATED, EVENT_MESSAGE_TEAM_CHAT, eventData, parseRunRequest, } from './contract.js';
+import { execAgent } from './exec.js';
+import { buildPrompt, replyFromStdout } from './prompt.js';
+import { RunStore } from './runstore.js';
+import { verifySignature } from './signature.js';
+import { isWebhookEvent } from '../forward.js';
+import { DEFAULT_WS_URL } from '../listen.js';
+/** Default ceiling on one agent invocation. */
+export const DEFAULT_EXEC_TIMEOUT_MS = 300_000;
+/** Reconnect backoff — full jitter between ``BASE`` and the current cap. */
+const RECONNECT_BASE_DELAY_MS = 1_000;
+const RECONNECT_MAX_DELAY_MS = 30_000;
+/** Ack status codes reported back over the socket for each frame. */
+const ACK_ACCEPTED = 200;
+const ACK_IGNORED = 204;
+const ACK_REJECTED = 401;
+function newMetrics() {
+    return {
+        connections: 0,
+        eventsReceived: 0,
+        runsStarted: 0,
+        runsSucceeded: 0,
+        runsFailed: 0,
+        signatureRejections: 0,
+        ignored: 0,
+        duplicates: 0,
+    };
+}
+function timestamp() {
+    return new Date().toISOString().slice(11, 19);
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Full-jitter exponential backoff, capped. */
+function backoffDelay(attempt) {
+    const cap = Math.min(RECONNECT_MAX_DELAY_MS, RECONNECT_BASE_DELAY_MS * 2 ** Math.max(0, attempt - 1));
+    return Math.floor(Math.random() * cap);
+}
+/** Backoff schedule for retrying a completion the server didn't accept. */
+const COMPLETION_RETRY_DELAYS_MS = [1_000, 3_000, 9_000];
+/**
+ * Complete a run, retrying transient failures.
+ *
+ * Completion is the one call that must land: nothing else can finalize an
+ * external run, so a dropped one leaves the row `running` — spinner up, the
+ * agent's next wake-up on that surface suppressed — until the 2h stale-run
+ * sweeper reaps it. A 409 (`already_resolved`) counts as done. A 4xx other
+ * than 429 is a decision, not a blip, so it isn't retried.
+ */
+async function completeWithRetry(api, path, outcome, log, sleep) {
+    let result = await completeRun(api, path, outcome);
+    for (const delay of COMPLETION_RETRY_DELAYS_MS) {
+        if (result.ok)
+            return result;
+        const retryable = result.status === 0 || result.status === 429 || result.status >= 500;
+        if (!retryable)
+            return result;
+        log(`    … completion failed (HTTP ${result.status}); retrying in ${delay / 1000}s`);
+        await sleep(delay);
+        result = await completeRun(api, path, outcome);
+    }
+    return result;
+}
+/**
+ * Handle one verified run end-to-end.
+ *
+ * Every path except a dry run — including every failure — calls the completion
+ * endpoint before returning.
+ */
+async function handleRun(run, options, api, log, sleep) {
+    const label = `run ${run.run_id.slice(0, 12)}`;
+    const surface = run.conversation_id ?? run.kind ?? 'no conversation';
+    log(`${timestamp()} ▶ ${label} started (${surface})`);
+    const prompt = buildPrompt(run, {
+        agentName: options.credentials.agent?.name ?? 'your agent',
+        mcpUrl: options.credentials.mcp_url,
+    });
+    const result = await execAgent({
+        command: options.exec,
+        prompt,
+        timeoutMs: options.timeoutMs ?? DEFAULT_EXEC_TIMEOUT_MS,
+        cwd: options.cwd,
+        spawnImpl: options.spawnImpl,
+    });
+    const seconds = (result.durationMs / 1000).toFixed(1);
+    if (!result.ok) {
+        const reason = result.error ??
+            (result.exitCode === null
+                ? 'agent command did not run'
+                : `agent command exited ${result.exitCode}`);
+        const detail = result.stderr.trim().slice(-500);
+        log(`${timestamp()} ✗ ${label} failed after ${seconds}s — ${reason}`);
+        if (detail)
+            log(`    stderr: ${detail}`);
+        if (options.dryRun) {
+            log(`    [dry-run] would report the run as failed`);
+            return 'skipped';
+        }
+        const completed = await completeWithRetry(api, run.completion_path, { ok: false, error: detail ? `${reason}: ${detail}` : reason }, log, sleep);
+        if (!completed.ok) {
+            log(`    ! could not report failure (HTTP ${completed.status}) ${completed.error ?? ''}`);
+            return 'unreported';
+        }
+        return 'failed';
+    }
+    const reply = replyFromStdout(result.stdout);
+    if (!reply) {
+        log(`${timestamp()} ✗ ${label} produced no output after ${seconds}s`);
+        if (options.dryRun)
+            return 'skipped';
+        const reported = await completeWithRetry(api, run.completion_path, { ok: false, error: 'agent produced no output' }, log, sleep);
+        return reported.ok ? 'failed' : 'unreported';
+    }
+    if (options.dryRun) {
+        const destination = run.reply_surface === 'none' ? '(no reply surface)' : `${run.reply_surface} ${run.reply_path}`;
+        log(`${timestamp()} ◦ ${label} dry-run — would post to ${destination}:`);
+        for (const line of reply.split('\n'))
+            log(`    │ ${line}`);
+        log(`    [dry-run] nothing was sent and the run was left open`);
+        return 'skipped';
+    }
+    // A run with no reply surface is a legitimate outcome, not an error: it was
+    // started by a trigger rather than by someone addressing the agent, so there
+    // is nowhere to post. Complete it as succeeded so any thinking indicator
+    // clears.
+    if (!run.reply_path || !run.reply_body_key) {
+        const why = run.reply_surface === 'none'
+            ? 'no reply surface'
+            : `${run.reply_surface} runs have nowhere to post yet`;
+        log(`${timestamp()} ✓ ${label} finished in ${seconds}s (${why})`);
+        for (const line of reply.split('\n'))
+            log(`    │ ${line}`);
+        const completed = await completeWithRetry(api, run.completion_path, { ok: true }, log, sleep);
+        if (!completed.ok) {
+            log(`    ! could not mark the run complete (HTTP ${completed.status})`);
+            return 'unreported';
+        }
+        return 'succeeded';
+    }
+    const posted = await postReply(api, run.reply_path, run.reply_body_key, reply, run.run_id);
+    if (!posted.ok) {
+        log(`${timestamp()} ✗ ${label} reply rejected (HTTP ${posted.status}) ${posted.error ?? ''}`);
+        const reported = await completeWithRetry(api, run.completion_path, { ok: false, error: `posting the reply failed with HTTP ${posted.status}` }, log, sleep);
+        return reported.ok ? 'failed' : 'unreported';
+    }
+    const completed = await completeWithRetry(api, run.completion_path, { ok: true }, log, sleep);
+    if (!completed.ok) {
+        // The reply is already in the conversation, so this is a bookkeeping
+        // failure, not a lost answer — say so precisely. Returning false lets the
+        // caller forget the run so a redelivery can retry the completion; the
+        // reply's idempotency key stops that from posting twice.
+        log(`${timestamp()} ! ${label} replied, but marking it complete failed (HTTP ${completed.status})`);
+        return 'unreported';
+    }
+    log(`${timestamp()} ✓ ${label} replied in ${seconds}s (${reply.length} chars)`);
+    return 'succeeded';
+}
+/**
+ * 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 async function runAgentHarness(options) {
+    const log = options.onLine ?? ((line) => process.stdout.write(`${line}\n`));
+    const Ctor = options.webSocketCtor ?? WebSocket;
+    const sleep = options.sleepImpl ?? defaultSleep;
+    const machine = options.machine ?? os.hostname();
+    const url = options.url ?? options.credentials.ws_url ?? DEFAULT_WS_URL;
+    const metrics = newMetrics();
+    const api = {
+        baseUrl: options.credentials.base_url,
+        apiKey: options.credentials.api_key,
+        fetchImpl: options.fetchImpl,
+    };
+    // Dedupe survives restarts: a run is recorded before its command starts, so a
+    // redelivery can never execute the agent twice.
+    const runs = RunStore.load(options.env, log);
+    // Runs this process has taken on. A redelivery for one of these is just a
+    // duplicate — the run is in flight right here. Only a run in the ledger that
+    // this process never handled is a candidate for restart recovery.
+    const handledThisSession = new Set();
+    let queue = Promise.resolve();
+    let fatal;
+    let attempt = 0;
+    const exhausted = () => options.maxConnections !== undefined && metrics.connections >= options.maxConnections;
+    while (!options.signal?.aborted && fatal === undefined && !exhausted()) {
+        metrics.connections += 1;
+        const authedThisTime = await connectOnce();
+        if (options.signal?.aborted || fatal !== undefined || exhausted())
+            break;
+        // A session that never authed is more likely a persistent problem than a
+        // blip, so only a session that did auth resets the backoff.
+        attempt = authedThisTime ? 1 : attempt + 1;
+        const delay = backoffDelay(attempt);
+        log(`${timestamp()} … disconnected; reconnecting in ${(delay / 1000).toFixed(1)}s`);
+        await sleep(delay);
+    }
+    // Let an in-flight run finish reporting before we hand back metrics.
+    await queue;
+    if (fatal !== undefined) {
+        log(`${timestamp()} ✗ ${fatal}`);
+        metrics.fatal = fatal;
+    }
+    return metrics;
+    /** One socket lifetime. Resolves ``true`` when the session ever authed. */
+    function connectOnce() {
+        const ws = new Ctor(url);
+        let authed = false;
+        return new Promise((resolve) => {
+            const close = () => {
+                try {
+                    ws.close();
+                }
+                catch {
+                    /* already closing */
+                }
+            };
+            if (options.signal) {
+                if (options.signal.aborted)
+                    close();
+                else
+                    options.signal.addEventListener('abort', close, { once: true });
+            }
+            ws.on('open', () => {
+                // `subscription_id` is a presence signal, not a scoping one: the server
+                // derives which subscription's events this socket receives from the
+                // connection itself. Sending it stamps `connected_from` with this
+                // machine's name, which is what the UI shows and what the delivery
+                // path treats as "someone is listening".
+                ws.send(JSON.stringify({
+                    type: 'auth',
+                    api_key: options.credentials.api_key,
+                    machine,
+                    ...(options.credentials.subscription_id
+                        ? { subscription_id: options.credentials.subscription_id }
+                        : {}),
+                }));
+            });
+            ws.on('message', (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') {
+                    authed = true;
+                    const name = options.credentials.agent?.name ?? 'agent';
+                    log(`${timestamp()} ● connected as "${name}" — waiting for mentions (exec: ${options.exec})`);
+                    return;
+                }
+                if (f.type === 'auth_error') {
+                    const reason = String(f.reason ?? 'unknown');
+                    const hint = reason === 'insufficient_scope'
+                        ? 'This credential is not allowed to stream events — ask your ProhostAI ' +
+                            'admin to re-issue the pairing with event-stream access.'
+                        : reason === 'stream_subscription_unavailable'
+                            ? 'This connection has no event subscription, so there is nothing to ' +
+                                'stream. Re-pair: prohost agent pair --code <code>'
+                            : 'Re-pair with: prohost agent pair --code <code>';
+                    fatal = `auth_error: ${reason}. ${hint}`;
+                    close();
+                    return;
+                }
+                if (f.type === 'ping') {
+                    ws.send(JSON.stringify({ type: 'pong' }));
+                    return;
+                }
+                if (!isWebhookEvent(frame))
+                    return;
+                metrics.eventsReceived += 1;
+                const ack = (status) => {
+                    try {
+                        ws.send(JSON.stringify({ type: 'ack', delivery_id: frame.delivery_id, status }));
+                    }
+                    catch {
+                        /* best-effort */
+                    }
+                };
+                if (frame.event !== EVENT_AGENT_RUN_REQUESTED) {
+                    if (frame.event === EVENT_MENTION_CREATED || frame.event === EVENT_MESSAGE_TEAM_CHAT) {
+                        log(`${timestamp()} ◦ ${frame.event} (no action — runs are triggered by mentions)`);
+                    }
+                    metrics.ignored += 1;
+                    ack(ACK_IGNORED);
+                    return;
+                }
+                const verified = verifySignature(options.credentials.webhook_secret, frame.payload, frame.signature);
+                if (!verified && !options.allowUnverified) {
+                    metrics.signatureRejections += 1;
+                    log(`${timestamp()} ✗ rejected ${EVENT_AGENT_RUN_REQUESTED} — signature did not verify. ` +
+                        'Not running the command. Re-pair to refresh the webhook secret, or pass ' +
+                        '--allow-unverified if you accept unauthenticated triggers.');
+                    ack(ACK_REJECTED);
+                    return;
+                }
+                const run = parseRunRequest(eventData(frame.payload));
+                if (run === null) {
+                    log(`${timestamp()} ◦ ${EVENT_AGENT_RUN_REQUESTED} without a run_id — ignoring`);
+                    metrics.ignored += 1;
+                    ack(ACK_IGNORED);
+                    return;
+                }
+                const previous = runs.get(run.run_id);
+                if (previous?.completed || handledThisSession.has(run.run_id)) {
+                    metrics.duplicates += 1;
+                    ack(ACK_ACCEPTED);
+                    return;
+                }
+                ack(ACK_ACCEPTED);
+                handledThisSession.add(run.run_id);
+                if (previous) {
+                    // We ran this one before but never got a terminal state accepted —
+                    // most likely the process died between the command and the
+                    // completion. Retry only the completion: re-running the agent could
+                    // repeat whatever it did with its credential the first time.
+                    metrics.duplicates += 1;
+                    queue = queue.then(async () => {
+                        log(`${timestamp()} ↻ run ${run.run_id.slice(0, 12)} was started before but never reported; ` +
+                            'reporting it now without re-running the agent');
+                        const recovered = await completeWithRetry(api, previous.completion_path || run.completion_path, { ok: false, error: 'the harness restarted before this run was reported' }, log, sleep);
+                        if (recovered.ok)
+                            runs.markCompleted(run.run_id);
+                    });
+                    return;
+                }
+                // Recorded BEFORE the command runs — a crash mid-run must not let a
+                // redelivery execute the agent a second time.
+                runs.markStarted(run.run_id, run.completion_path);
+                metrics.runsStarted += 1;
+                // Serialize execution but never block the socket reader: the ack and
+                // the heartbeat have to keep flowing while the agent thinks.
+                queue = queue.then(async () => {
+                    // Shutdown was requested while this sat in the queue. Don't start a
+                    // fresh command the operator is waiting to be rid of — but do close
+                    // the run out, so the server isn't left waiting on it either.
+                    if (options.signal?.aborted) {
+                        log(`${timestamp()} ⏹ run ${run.run_id.slice(0, 12)} dropped — harness is shutting down`);
+                        const closed = await completeWithRetry(api, run.completion_path, { ok: false, error: 'the harness shut down before this run started' }, log, sleep);
+                        if (closed.ok)
+                            runs.markCompleted(run.run_id);
+                        metrics.runsFailed += 1;
+                        return;
+                    }
+                    const outcome = await handleRun(run, options, api, log, sleep).catch((err) => {
+                        log(`${timestamp()} ✗ run ${run.run_id} crashed the harness handler: ${String(err)}`);
+                        return 'failed';
+                    });
+                    // Both terminal outcomes reached the completion endpoint; only then
+                    // is the run settled and safe to skip on redelivery.
+                    if (outcome === 'succeeded')
+                        metrics.runsSucceeded += 1;
+                    if (outcome === 'failed' || outcome === 'unreported')
+                        metrics.runsFailed += 1;
+                    // Only a run the server acknowledged as terminal is settled; an
+                    // unreported one stays open so a redelivery can report it.
+                    if (outcome === 'succeeded' || outcome === 'failed')
+                        runs.markCompleted(run.run_id);
+                });
+            });
+            ws.on('close', () => {
+                if (options.signal)
+                    options.signal.removeEventListener('abort', close);
+                resolve(authed);
+            });
+            ws.on('error', (err) => {
+                if (!authed)
+                    log(`${timestamp()} ✗ connection error: ${err.message}`);
+            });
+        });
+    }
+}

package/dist/agent/runstore.d.ts

@@ -0,0 +1,50 @@
+/**
+ * A small on-disk ledger of runs this machine has already started.
+ *
+ * In-memory dedupe is not enough. Webhook deliveries retry, delivery acks are
+ * not persisted server-side, and the CLI is a long-lived process that people
+ * restart — so a redelivery arriving after a restart would run the agent
+ * command a second time. That is not just a duplicate message (the reply send
+ * is idempotency-keyed): the agent holds a credential and may have created a
+ * task, sent an email, or moved a deal. Executing twice is the expensive
+ * mistake, so a run is recorded **before** the command starts and is never
+ * executed twice.
+ *
+ * The completion is tracked separately, because the two failure modes want
+ * opposite treatment: a run whose command ran but whose completion never landed
+ * should have its completion retried on redelivery — without re-running
+ * anything.
+ */
+export interface RunRecord {
+    run_id: string;
+    /** Whether the server acknowledged a terminal state for this run. */
+    completed: boolean;
+    /** Path to complete at, kept so a recovery pass needs nothing else. */
+    completion_path: string;
+    started_at: string;
+}
+/** Cap on retained records. Oldest are dropped first (insertion order). */
+export declare const RUN_LEDGER_LIMIT = 500;
+export declare function runLedgerPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Records of started runs, backed by a JSON file.
+ *
+ * Every persistence failure degrades to memory-only rather than throwing: a
+ * read-only home directory should cost dedupe-across-restarts, not the ability
+ * to answer a mention.
+ */
+export declare class RunStore {
+    private readonly file;
+    private readonly onWarn;
+    private records;
+    private constructor();
+    /** Read the ledger from disk. A missing or corrupt file starts empty. */
+    static load(env?: NodeJS.ProcessEnv, onWarn?: (line: string) => void): RunStore;
+    get(runId: string): RunRecord | undefined;
+    /** Record a run as started. Call this BEFORE running the command. */
+    markStarted(runId: string, completionPath: string): void;
+    /** Record that the server accepted a terminal state for this run. */
+    markCompleted(runId: string): void;
+    private trim;
+    private persist;
+}

package/dist/agent/runstore.js

@@ -0,0 +1,107 @@
+/**
+ * A small on-disk ledger of runs this machine has already started.
+ *
+ * In-memory dedupe is not enough. Webhook deliveries retry, delivery acks are
+ * not persisted server-side, and the CLI is a long-lived process that people
+ * restart — so a redelivery arriving after a restart would run the agent
+ * command a second time. That is not just a duplicate message (the reply send
+ * is idempotency-keyed): the agent holds a credential and may have created a
+ * task, sent an email, or moved a deal. Executing twice is the expensive
+ * mistake, so a run is recorded **before** the command starts and is never
+ * executed twice.
+ *
+ * The completion is tracked separately, because the two failure modes want
+ * opposite treatment: a run whose command ran but whose completion never landed
+ * should have its completion retried on redelivery — without re-running
+ * anything.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { prohostHome } from './credentials.js';
+/** Cap on retained records. Oldest are dropped first (insertion order). */
+export const RUN_LEDGER_LIMIT = 500;
+export function runLedgerPath(env = process.env) {
+    return path.join(prohostHome(env), 'runs.json');
+}
+/**
+ * Records of started runs, backed by a JSON file.
+ *
+ * Every persistence failure degrades to memory-only rather than throwing: a
+ * read-only home directory should cost dedupe-across-restarts, not the ability
+ * to answer a mention.
+ */
+export class RunStore {
+    file;
+    onWarn;
+    records = new Map();
+    constructor(file, onWarn) {
+        this.file = file;
+        this.onWarn = onWarn;
+    }
+    /** Read the ledger from disk. A missing or corrupt file starts empty. */
+    static load(env = process.env, onWarn = () => { }) {
+        const store = new RunStore(runLedgerPath(env), onWarn);
+        try {
+            const parsed = JSON.parse(readFileSync(store.file, 'utf8'));
+            if (Array.isArray(parsed)) {
+                for (const entry of parsed) {
+                    const record = entry;
+                    if (typeof record?.run_id === 'string' && record.run_id) {
+                        store.records.set(record.run_id, {
+                            run_id: record.run_id,
+                            completed: record.completed === true,
+                            completion_path: typeof record.completion_path === 'string' ? record.completion_path : '',
+                            started_at: typeof record.started_at === 'string' ? record.started_at : '',
+                        });
+                    }
+                }
+            }
+        }
+        catch {
+            // No ledger yet, or an unreadable one — either way, start clean.
+        }
+        return store;
+    }
+    get(runId) {
+        return this.records.get(runId);
+    }
+    /** Record a run as started. Call this BEFORE running the command. */
+    markStarted(runId, completionPath) {
+        this.records.set(runId, {
+            run_id: runId,
+            completed: false,
+            completion_path: completionPath,
+            started_at: new Date().toISOString(),
+        });
+        this.trim();
+        this.persist();
+    }
+    /** Record that the server accepted a terminal state for this run. */
+    markCompleted(runId) {
+        const existing = this.records.get(runId);
+        if (!existing)
+            return;
+        existing.completed = true;
+        this.persist();
+    }
+    trim() {
+        while (this.records.size > RUN_LEDGER_LIMIT) {
+            const oldest = this.records.keys().next().value;
+            if (oldest === undefined)
+                return;
+            this.records.delete(oldest);
+        }
+    }
+    persist() {
+        try {
+            mkdirSync(path.dirname(this.file), { recursive: true, mode: 0o700 });
+            writeFileSync(this.file, `${JSON.stringify([...this.records.values()], null, 2)}\n`, {
+                mode: 0o600,
+            });
+        }
+        catch (err) {
+            this.onWarn(`    ! could not write the run ledger (${err instanceof Error ? err.message : String(err)}); ` +
+                'dedupe is memory-only until this is fixed');
+        }
+    }
+}

package/dist/agent/signature.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function canonicalJson(value: unknown): string;
+/**
+ * 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 declare function verifySignature(secret: string | null | undefined, payload: unknown, signature: string | null | undefined): boolean;