@prohost/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Prohost AI, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,229 @@
+# `@prohost/cli`
+
+The [ProhostAI](https://www.prohost.ai) command-line tool. Two things it does:
+
+- **`prohost agent`** — run your own local agent as a ProhostAI teammate. Someone
+  @-mentions it in the app, it runs on your machine, and its answer is posted
+  back into the conversation.
+- **`prohost listen`** — stream your account's webhooks to a local HTTP endpoint
+  while you develop against them (like `stripe listen`).
+
+You need a ProhostAI account and **Node.js 18 or newer**. Nothing to install —
+`npx` fetches it on demand:
+
+```bash
+npx @prohost/cli --help       # all commands and flags
+npx @prohost/cli --version    # the version you're running
+```
+
+## Quick start
+
+Pair once, then leave the agent running:
+
+```bash
+# 1. In ProhostAI: Hire an AI employee → Bring your own agent → copy the code.
+#    Codes are single-use and expire 15 minutes after they're generated.
+npx @prohost/cli agent pair --code <pairing-code>
+
+# 2. Point it at whatever agent you already use.
+npx @prohost/cli agent run --exec 'claude -p'
+```
+
+That's it — @-mention the agent in ProhostAI and it answers from your machine.
+The rest of this page is detail on each step.
+
+---
+
+## Bring your own agent
+
+Any agent that reads a prompt on stdin and writes its answer to stdout works —
+Claude Code, Codex CLI, goose, or a shell script you wrote yourself. The CLI
+doesn't know or care which one it is.
+
+### 1. Get a pairing code
+
+In ProhostAI: **Hire an AI employee → Bring your own agent**. You'll get a
+one-time code. It is single-use and expires 15 minutes after it's generated.
+
+### 2. Pair
+
+```bash
+npx @prohost/cli agent pair --code <pairing-code>
+```
+
+This exchanges the code for a scoped API key and stores it in
+`~/.prohost/agent.json` (`chmod 600`). The key is never printed in full — only a
+masked prefix — and the file should never be committed or copied between
+machines; re-pair instead.
+
+That gives you a **stream-only pairing**: events arrive over the websocket and
+nothing is ever POSTed to you, which is what you want on a laptop with no public
+HTTPS address. Events are still signed, and the CLI still verifies every one.
+
+Pass `--webhook-url https://…` only if something else of yours *also* needs the
+events pushed over HTTPS. It changes where events are delivered; it is not
+required to receive runs.
+
+You can also pass the code as `$PROHOST_PAIRING_CODE`.
+
+### 3. Run
+
+```bash
+npx @prohost/cli agent run --exec 'claude -p'
+```
+
+Leave it running. On every mention you'll see:
+
+```
+14:22:07 ● connected as "Ada" — waiting for mentions (exec: claude -p)
+14:24:31 ▶ run 01JQ8Z4K2M started (conversation 9f3c…)
+14:24:58 ✓ run 01JQ8Z4K2M replied in 26.4s (412 chars)
+```
+
+Other agents, same command:
+
+```bash
+npx @prohost/cli agent run --exec 'codex exec -'
+npx @prohost/cli agent run --exec 'goose run -i -'
+npx @prohost/cli agent run --exec './my-agent.sh'
+```
+
+Try it without sending anything first:
+
+```bash
+npx @prohost/cli agent run --exec 'claude -p' --dry-run
+```
+
+`--dry-run` prints the reply your agent produced and makes no writes at all —
+nothing is posted and the run is left open.
+
+### How a run works
+
+1. Someone @-mentions your agent. ProhostAI emits an `agent.run_requested` event
+   on the authenticated websocket. Your machine shows up in ProhostAI as
+   connected while `agent run` holds the socket open.
+2. The CLI verifies the event's HMAC signature. An event that doesn't verify is
+   **not executed** — the whole point of the signature is that a run event makes
+   your machine execute a command.
+3. It builds a prompt (who your agent is, the conversation, the message that
+   mentioned it) and runs your `--exec` command with that prompt on **stdin**.
+4. Your command's **stdout** is the reply. It's posted into the conversation
+   verbatim, so print the message and nothing else — no preamble, no reasoning.
+5. The run is completed either way. A command that crashes, times out, or prints
+   nothing reports `failed`; a run is never left hanging.
+
+Runs are handled one at a time, and each run executes **at most once on this
+machine** — even across restarts. Started runs are recorded in
+`~/.prohost/runs.json` before the command launches, so a webhook redelivery
+that arrives after a crash or restart will close the run out rather than run
+your agent a second time. That matters because your agent holds a credential:
+a second execution could file the same task or send the same email again, which
+no amount of message deduplication would undo.
+
+**Treat mention text as untrusted input.** The prompt contains a message someone
+else wrote, and your agent runs on your machine with whatever credentials and
+tools you gave it. Give it the access the job needs and no more — the same
+judgement you'd apply to any agent reading input from the internet. (The message
+only ever reaches your command on stdin, never the shell, so it cannot inject a
+command.)
+
+### `agent run` flags
+
+| Flag | Default | What it does |
+| --- | --- | --- |
+| `--exec` | *(required)* | Command to run for each mention. Prompt arrives on stdin. |
+| `--timeout` | `300` | Seconds one run may take before the command is killed. |
+| `--dry-run` | off | Print the reply that would be posted; write nothing. |
+| `--cwd` | current dir | Working directory for the command. |
+| `--machine` | OS hostname | Name shown next to the connection in ProhostAI. |
+| `--url` | paired value | Websocket endpoint override. |
+| `--allow-unverified` | off | Run events whose signature can't be verified. See below. |
+
+### `agent pair` flags
+
+| Flag | Default | What it does |
+| --- | --- | --- |
+| `--code` | `$PROHOST_PAIRING_CODE` | The one-time pairing code. |
+| `--webhook-url` | none | Also push events to this HTTPS endpoint. Omit for stream-only, which is the normal laptop setup. |
+| `--base-url` | `https://connect.prohost.ai` | Public API base. |
+
+### About `--allow-unverified`
+
+Every pairing gets a signing secret, including a stream-only one, so
+verification works out of the box. If a pairing somehow has no secret, the CLI
+refuses to execute run events rather than running an unauthenticated command,
+and says so. `--allow-unverified` opts out of that check — reasonable when
+you're pointing `--url` at a local test server, a bad idea anywhere your agent
+has real credentials.
+
+### Troubleshooting
+
+| You see | What it means |
+| --- | --- |
+| `No paired agent found` | Run `prohost agent pair --code <code>` first. |
+| `no event subscription was provisioned` | Pairing half-failed server-side and nothing was saved. The code is spent — generate a fresh one and pair again. |
+| `Pairing code is invalid, expired, or already used` | Codes are single-use with a 15-minute life. Generate a fresh one. |
+| `auth_error: invalid_api_key` | The connection was revoked in ProhostAI. Re-pair. |
+| `auth_error: insufficient_scope` | The credential isn't allowed to stream events — ask your ProhostAI admin to re-issue the pairing. |
+| `auth_error: stream_subscription_unavailable` | The connection has no event subscription to stream. Re-pair. |
+| `signature did not verify` | The event didn't come from ProhostAI, or your stored secret is stale. Re-pair. |
+| Replies contain your agent's reasoning | Your command is printing more than the message. Use a "print only the answer" flag (e.g. `claude -p`). |
+
+Credentials live in `~/.prohost/agent.json` and the run ledger in
+`~/.prohost/runs.json`; set `$PROHOST_HOME` to move that directory. Delete the file to un-pair locally, and revoke the connection in
+ProhostAI to invalidate the key itself.
+
+### What the pairing can and can't do
+
+The credential is deliberately narrow. It can stream events, post in internal
+team chat, manage its own task queue, file approvals, and close out its own
+runs. It **cannot** create or delete webhook subscriptions, and it cannot send
+to guest channels (OTA, SMS, email, WhatsApp) — a guest-facing send has to go
+through ProhostAI's own approval path, not around it via an API key.
+
+---
+
+## Local webhook forwarding
+
+```bash
+npx @prohost/cli listen --forward-to http://localhost:3000/webhook
+```
+
+Streams your account's webhook deliveries over an authenticated websocket and
+POSTs each payload to your local URL, preserving the `X-ProhostAI-*` headers so
+your handler sees the same shape as a production delivery.
+
+| Flag | Default | What it does |
+| --- | --- | --- |
+| `--forward-to` | *(required)* | Local URL each payload is POSTed to. |
+| `--api-key` | `$PROHOST_API_KEY` | ProhostAI API key (`ph_live_…`). |
+| `--url` | `wss://api.prohost.ai/ws/webhooks` | Websocket endpoint. |
+| `--machine` | OS hostname | Name displayed in the UI. |
+| `--subscription-id` | none | Stamp `connected_from` on a specific subscription. |
+
+---
+
+## Support
+
+Email [support@prohost.ai](mailto:support@prohost.ai). Include the output of
+`npx @prohost/cli --version`.
+
+The source lives in ProhostAI's (private) backend monorepo under
+`packages/prohost-cli`; there is no public issue tracker.
+
+---
+
+## Development
+
+For ProhostAI engineers working in the monorepo:
+
+```bash
+bun install          # from the repo root
+bun test             # package test suite
+npm run lint         # tsc --noEmit
+npm run build        # emit dist/
+npm pack             # build + tarball, exactly as published
+```
+
+`prepack` runs the build, so `npm pack` and `npm publish` can never ship a
+stale or missing `dist/`.

package/dist/agent/api.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The two HTTP writes the harness makes back into ProhostAI: post the reply,
+ * then close out the run.
+ *
+ * Both authenticate with the paired API key over ``X-API-Key`` and both return
+ * a result object rather than throwing — the runner has to keep going (and
+ * still complete the run) whichever one fails.
+ *
+ * The paths come from the run event itself (`reply_instructions.path` /
+ * `completion.path`), which is why these take a path rather than building one.
+ */
+export interface ApiOptions {
+    baseUrl: string;
+    apiKey: string;
+    fetchImpl?: typeof fetch;
+    /** Per-request timeout. Defaults to 30 seconds. */
+    timeoutMs?: number;
+}
+export interface ApiResult {
+    ok: boolean;
+    status: number;
+    error?: string;
+}
+/**
+ * Post the agent's reply into the conversation that triggered the run.
+ *
+ * Keyed on ``run_id`` so the send is idempotent server-side. The harness dedupes
+ * runs in memory, but that memory dies with the process: without this header a
+ * redelivered run after a restart would post the reply a second time.
+ */
+export declare function postReply(options: ApiOptions, path: string, bodyKey: string, message: string, runId: string): Promise<ApiResult>;
+/**
+ * Report a run's terminal state. Called for every run — including one whose
+ * command crashed — so the server never waits on a run this harness abandoned.
+ *
+ * A ``409`` is reported as success: it means the run already reached a terminal
+ * state (a redelivery we raced, or the 2h stale-run sweeper got there first).
+ * Treating that as a failure would only produce noise about work that is done.
+ */
+export declare function completeRun(options: ApiOptions, path: string, outcome: {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+}): Promise<ApiResult>;

package/dist/agent/api.js

@@ -0,0 +1,80 @@
+/**
+ * The two HTTP writes the harness makes back into ProhostAI: post the reply,
+ * then close out the run.
+ *
+ * Both authenticate with the paired API key over ``X-API-Key`` and both return
+ * a result object rather than throwing — the runner has to keep going (and
+ * still complete the run) whichever one fails.
+ *
+ * The paths come from the run event itself (`reply_instructions.path` /
+ * `completion.path`), which is why these take a path rather than building one.
+ */
+import { USER_AGENT } from '../version.js';
+import { MAX_ERROR_CHARS, RUN_STATUS_FAILED, RUN_STATUS_SUCCEEDED } from './contract.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+async function post(options, path, body, idempotencyKey) {
+    const fetchImpl = options.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    try {
+        const response = await fetchImpl(`${options.baseUrl.replace(/\/+$/, '')}${path}`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'X-API-Key': options.apiKey,
+                'User-Agent': USER_AGENT,
+                ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
+            },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        const ok = response.status >= 200 && response.status < 300;
+        let error;
+        if (!ok) {
+            // Surface the server's reason — a scope or tier denial is the most
+            // likely failure here and the host can act on it.
+            error = await response
+                .text()
+                .then((t) => t.slice(0, 500))
+                .catch(() => undefined);
+        }
+        return { ok, status: response.status, error };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            status: 0,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Post the agent's reply into the conversation that triggered the run.
+ *
+ * Keyed on ``run_id`` so the send is idempotent server-side. The harness dedupes
+ * runs in memory, but that memory dies with the process: without this header a
+ * redelivered run after a restart would post the reply a second time.
+ */
+export async function postReply(options, path, bodyKey, message, runId) {
+    return post(options, path, { [bodyKey]: message }, `prohost-cli-run-${runId}`);
+}
+/**
+ * Report a run's terminal state. Called for every run — including one whose
+ * command crashed — so the server never waits on a run this harness abandoned.
+ *
+ * A ``409`` is reported as success: it means the run already reached a terminal
+ * state (a redelivery we raced, or the 2h stale-run sweeper got there first).
+ * Treating that as a failure would only produce noise about work that is done.
+ */
+export async function completeRun(options, path, outcome) {
+    const body = outcome.ok
+        ? { status: RUN_STATUS_SUCCEEDED }
+        : { status: RUN_STATUS_FAILED, error: outcome.error.slice(0, MAX_ERROR_CHARS) };
+    const result = await post(options, path, body);
+    if (result.status === 409)
+        return { ...result, ok: true };
+    return result;
+}

package/dist/agent/command.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Flag plumbing for `prohost agent <pair|run>`.
+ *
+ * Kept separate from the harness itself so `pair.ts` / `run.ts` stay callable
+ * (and testable) as plain async functions with no argv or process concerns.
+ */
+type Flags = Record<string, string | boolean>;
+/** Dispatch an ``agent`` subcommand. Returns the process exit code. */
+export declare function runAgent(subcommand: string | undefined, flags: Flags, printHelp: () => void): Promise<number>;
+export {};

package/dist/agent/command.js

@@ -0,0 +1,109 @@
+/**
+ * Flag plumbing for `prohost agent <pair|run>`.
+ *
+ * Kept separate from the harness itself so `pair.ts` / `run.ts` stay callable
+ * (and testable) as plain async functions with no argv or process concerns.
+ */
+import process from 'node:process';
+import { PairError, runPair } from './pair.js';
+import { CredentialsMissingError, loadCredentials } from './credentials.js';
+import { DEFAULT_EXEC_TIMEOUT_MS, runAgentHarness } from './run.js';
+function flagString(flags, name) {
+    const value = flags[name];
+    return typeof value === 'string' ? value : undefined;
+}
+/** Dispatch an ``agent`` subcommand. Returns the process exit code. */
+export async function runAgent(subcommand, flags, printHelp) {
+    if (subcommand === 'pair')
+        return pairCommand(flags);
+    if (subcommand === 'run')
+        return runCommand(flags);
+    process.stderr.write(subcommand
+        ? `Unknown agent subcommand: ${subcommand}\n\n`
+        : 'Missing agent subcommand — expected `pair` or `run`.\n\n');
+    printHelp();
+    return 1;
+}
+async function pairCommand(flags) {
+    const code = flagString(flags, 'code') ?? process.env.PROHOST_PAIRING_CODE;
+    if (!code) {
+        process.stderr.write('Missing pairing code. Pass --code or set $PROHOST_PAIRING_CODE.\n');
+        return 1;
+    }
+    try {
+        await runPair({
+            code,
+            baseUrl: flagString(flags, 'base-url'),
+            wsUrl: flagString(flags, 'url') ?? process.env.PROHOST_WS_URL,
+            webhookUrl: flagString(flags, 'webhook-url'),
+        });
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof PairError) {
+            process.stderr.write(`✗ ${err.message}\n`);
+            return 1;
+        }
+        throw err;
+    }
+}
+async function runCommand(flags) {
+    const exec = flagString(flags, 'exec');
+    if (!exec) {
+        process.stderr.write("Missing required flag: --exec. Example: prohost agent run --exec 'claude -p'\n");
+        return 1;
+    }
+    let credentials;
+    try {
+        credentials = loadCredentials();
+    }
+    catch (err) {
+        if (err instanceof CredentialsMissingError) {
+            process.stderr.write(`✗ ${err.message}\n`);
+            return 1;
+        }
+        throw err;
+    }
+    const timeoutSeconds = flagString(flags, 'timeout');
+    const parsedTimeout = timeoutSeconds === undefined ? undefined : Number(timeoutSeconds);
+    if (parsedTimeout !== undefined && (!Number.isFinite(parsedTimeout) || parsedTimeout <= 0)) {
+        process.stderr.write('--timeout must be a positive number of seconds.\n');
+        return 1;
+    }
+    // First signal stops accepting work and lets the in-flight run finish
+    // reporting itself (so the server doesn't wait on a run we abandoned); a
+    // second one means the operator wants out now.
+    const controller = new AbortController();
+    const onSig = () => {
+        if (controller.signal.aborted) {
+            process.stdout.write('\nQuitting — the in-flight run was not reported.\n');
+            process.exit(130);
+        }
+        controller.abort();
+        process.stdout.write('\nFinishing the in-flight run… press Ctrl-C again to quit immediately.\n');
+    };
+    process.on('SIGINT', onSig);
+    process.on('SIGTERM', onSig);
+    try {
+        const metrics = await runAgentHarness({
+            exec,
+            credentials,
+            url: flagString(flags, 'url') ?? process.env.PROHOST_WS_URL,
+            machine: flagString(flags, 'machine'),
+            cwd: flagString(flags, 'cwd'),
+            timeoutMs: parsedTimeout === undefined ? DEFAULT_EXEC_TIMEOUT_MS : parsedTimeout * 1000,
+            dryRun: flags['dry-run'] === true,
+            allowUnverified: flags['allow-unverified'] === true,
+            signal: controller.signal,
+        });
+        process.stdout.write(`\nRuns: ${metrics.runsSucceeded} succeeded, ${metrics.runsFailed} failed, ` +
+            `${metrics.signatureRejections} rejected.\n`);
+        // A harness that never connected must not look like a clean shutdown to a
+        // service manager or a wrapper script.
+        return metrics.fatal === undefined ? 0 : 1;
+    }
+    finally {
+        process.off('SIGINT', onSig);
+        process.off('SIGTERM', onSig);
+    }
+}

package/dist/agent/contract.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 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 declare const DEFAULT_API_BASE_URL = "https://connect.prohost.ai";
+/** Fired when a paired agent is given work — the trigger to run. */
+export declare const EVENT_AGENT_RUN_REQUESTED = "agent.run_requested";
+/** Informational events the harness logs but does not act on. */
+export declare const EVENT_MENTION_CREATED = "mention.created";
+export declare const EVENT_MESSAGE_TEAM_CHAT = "message.team_chat";
+/** Terminal statuses accepted by the run-completion endpoint. */
+export declare const RUN_STATUS_SUCCEEDED = "succeeded";
+export declare const RUN_STATUS_FAILED = "failed";
+/** Server-side cap on the `error` field of a completion (`MAX_ERROR_CHARS`). */
+export declare const MAX_ERROR_CHARS = 1000;
+/** `POST` — exchange a one-time pairing code for a scoped credential. */
+export declare const REDEEM_PATH = "/v1/agent-pairing/redeem";
+/** `POST` — send a message into a conversation as the paired agent. */
+export declare function conversationMessagesPath(conversationId: string): string;
+/** `POST` — close out a run. Must be called for every run, success or not. */
+export declare function agentRunCompletePath(runId: string): string;
+/** The `agent.run_requested` payload, as far as the harness cares about it. */
+export interface AgentRunRequest {
+    run_id: string;
+    agent_id?: string;
+    agent_user_id?: string;
+    agent_name?: string;
+    account_id?: string;
+    /** Why the agent woke — `team_chat_mention`, `task_comment`, … */
+    kind?: string;
+    conversation_id?: string;
+    task_id?: string;
+    cleaning_id?: string;
+    trigger_source?: string;
+    trigger_message_id?: string;
+    /** Capped inline excerpt of the message that woke the agent. */
+    trigger_text?: string;
+    trigger_user_id?: string;
+    /** For a trigger fan-out with no surface: the event type that fired it. */
+    trigger_type?: string;
+    /** For a trigger fan-out with no surface: the entity that event was about. */
+    trigger_entity_id?: string;
+    /**
+     * What the run is about, exactly as the server declared it. This is NOT the
+     * same question as "can the reply be posted": a task run is a task run even
+     * though the external API has no task-comment route yet, and the agent needs
+     * to be told that to answer sensibly. Postability is `reply_path` +
+     * `reply_body_key`.
+     */
+    reply_surface: ReplySurface;
+    /** Server-supplied path to post the reply to. Absent when there is nowhere. */
+    reply_path?: string;
+    /**
+     * JSON field the reply text goes in — taken from the event's
+     * ``reply_instructions.body_field`` when present. Conversations take
+     * ``message``; comment surfaces take ``content``
+     * (`shared/comments/schemas.py`).
+     */
+    reply_body_key?: string;
+    /** Server-supplied path to complete the run at. */
+    completion_path: string;
+}
+/** Reply destinations the server can bind a run to, including future surfaces. */
+export type ReplySurface = 'conversation' | 'task' | 'cleaning' | 'none' | (string & {});
+/**
+ * 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 declare function eventData(payload: Record<string, unknown>): Record<string, unknown>;
+/**
+ * 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 declare function parseRunRequest(data: Record<string, unknown>): AgentRunRequest | null;