@hypertabai/mcp 0.2.0 → 1.0.0

package/README.md

@@ -82,6 +82,37 @@ npx @hypertabai/mcp connect --api-key ht_sk_...
 
 Lists every Hypertab tool the server exposes. Useful for verifying credentials before wiring up an agent.
 
+## Retry-safe writes
+
+Installed Hypertab skills tell agents to pass `idempotency_key` on mutating MCP tools that expose it. The key must stay
+stable when retrying the same logical write and must change when the payload, target, or intent changes. This lets
+Hypertab dedupe transient retries, meter one logical operation once, and reject over-budget writes before mutation.
+
+Use 8-128 characters with letters, numbers, dot, underscore, colon, or hyphen. A good pattern is
+`agent:<tool>:<target>:<short-hash-or-counter>`. Batch row writes use one key per tool call, not one key per row.
+
+First-party REST commands that perform writes generate `Idempotency-Key` headers automatically unless an explicit key is
+provided by the command implementation.
+
+## Surface publishing
+
+The CLI now exposes the hosted-surface command group:
+
+```bash
+npx @hypertabai/mcp surfaces publish --dir ./dashboard --out-dir dist --slug ops-dashboard
+```
+
+This command detects the local project, runs or skips the local build, validates static output, prepares a publish manifest and file payloads, then uploads the surface through Hypertab's publish API.
+
+Current detection support:
+
+- Supported v1 targets: Vite React, Vite, Astro static, and plain static HTML.
+- Static output is considered ready when the output directory exists and contains `index.html`.
+- If output is not ready, the CLI runs `--build <command>` or the detected `package.json` `build` script, then validates output again.
+- Packaging computes MIME types, byte sizes, SHA-256 hashes, cache policies, and base64 file payloads for the server publish API.
+- API keys come from `--api-key` or `HYPERTAB_API_KEY`; use `--json` for machine-readable agent output.
+- Server app targets such as Next, SvelteKit, Nuxt, Remix, Express, and Fastify are rejected with guidance to convert the dashboard to a static browser app that calls Hypertab APIs.
+
 ## Flags
 
 ### `install`
@@ -109,6 +140,239 @@ Lists every Hypertab tool the server exposes. Useful for verifying credentials b
 | `-u, --url <url>` | `https://api.hypertab.ai/mcp` | MCP server URL |
 | `-t, --transport <type>` | `streamable-http` | `streamable-http`, `sse`, or `stdio` |
 
+### `surfaces publish`
+
+| Flag | Default | Description |
+|---|---|---|
+| `-k, --api-key <key>` | `$HYPERTAB_API_KEY` later | Hypertab API key |
+| `-u, --api-url <url>` | `https://api.hypertab.ai` | Hypertab API URL |
+| `-d, --dir <path>` | `.` | Project directory to inspect and build |
+| `--out-dir <path>` | unset | Static build output directory |
+| `--slug <slug>` | unset | Hosted surface slug |
+| `--title <title>` | unset | Hosted surface title |
+| `--build <command>` | unset | Build command to run before packaging |
+| `--no-activate` | false | Upload without activating the new deployment |
+| `--json` | false | Print machine-readable JSON output |
+| `--timeout-ms <ms>` | `60000` | Publish API request timeout; stalled requests fail with `SURFACE_PUBLISH_TIMEOUT` |
+
+### `bridge start`
+
+| Flag | Default | Description |
+|---|---|---|
+| `-k, --api-key <key>` | `$HYPERTAB_API_KEY` | Hypertab bridge/API key |
+| `-u, --api-url <url>` | `https://api.hypertab.ai` | Hypertab REST API URL |
+| `--client-name <name>` | machine hostname | Stable local agent client name |
+| `--client-type <type>` | `codex` | `codex`, `claude_code`, `cursor`, `browser`, `cloud`, or `other` |
+| `--heartbeat-interval-ms <ms>` | `30000` | Heartbeat interval for long-running mode |
+| `--command-interval-ms <ms>` | `5000` | Command claim interval for long-running mode |
+| `--command-limit <n>` | `10` | Max commands claimed per poll, capped at 50 |
+| `--session` | false | Start a durable agent session |
+| `--objective <text>` | unset | Create a durable run for this objective |
+| `--run-title <title>` | first 120 chars of objective | Run title |
+| `--source <source>` | `cli_bridge` | Run source label |
+| `--once` | false | Run one heartbeat/claim cycle and exit |
+| `--json` | false | Print machine-readable JSON lines |
+| `--spool-file <path>` | `~/.hypertab/bridge-spool.jsonl` | Local JSONL spool path |
+| `--no-spool` | false | Disable local event/result spooling |
+| `--timeout-ms <ms>` | `30000` | Bridge API request timeout; stalled requests fail with `BRIDGE_REQUEST_TIMEOUT` |
+
+### `bridge result`
+
+| Flag | Default | Description |
+|---|---|---|
+| `-k, --api-key <key>` | `$HYPERTAB_API_KEY` | Hypertab bridge/API key |
+| `-u, --api-url <url>` | `https://api.hypertab.ai` | Hypertab REST API URL |
+| `--command-id <id>` | required | Delivered command id |
+| `--client-id <id>` | unset | Client id for broad bridge tokens; bridge-client tokens can omit it |
+| `--status <status>` | required | `completed`, `failed`, or `cancelled` |
+| `--error-message <message>` | unset | Failure/cancellation details |
+| `--json` | false | Print machine-readable JSON output |
+| `--spool-file <path>` | `~/.hypertab/bridge-spool.jsonl` | Local JSONL spool path |
+| `--no-spool` | false | Disable local result spooling on retryable failures |
+| `--timeout-ms <ms>` | `30000` | Bridge API request timeout; stalled requests fail with `BRIDGE_REQUEST_TIMEOUT` |
+
+### `bridge status`
+
+| Flag | Default | Description |
+|---|---|---|
+| `-k, --api-key <key>` | `$HYPERTAB_API_KEY` | Hypertab bridge/API key |
+| `-u, --api-url <url>` | `https://api.hypertab.ai` | Hypertab REST API URL |
+| `--client-id <id>` | unset | Optional client id for broad bridge/API keys |
+| `--limit <n>` | `50` | Max clients/runs/commands to inspect, capped at 100 |
+| `--json` | false | Print machine-readable JSON output |
+| `--timeout-ms <ms>` | `30000` | Bridge API request timeout; stalled requests fail with `BRIDGE_REQUEST_TIMEOUT` |
+
+### `bridge token create`
+
+| Flag | Default | Description |
+|---|---|---|
+| `-k, --api-key <key>` | `$HYPERTAB_API_KEY` | Admin Hypertab API key used only to mint the bridge token |
+| `-u, --api-url <url>` | `https://api.hypertab.ai` | Hypertab REST API URL |
+| `--name <name>` | `<client-name> bridge` | Token display name |
+| `--client-name <name>` | required | Stable local client name bound into the token |
+| `--client-type <type>` | `codex` | `codex`, `claude_code`, `cursor`, `browser`, `cloud`, or `other` |
+| `--expires-in-days <days>` | `30` | Token lifetime in days, 1-365 |
+| `--json` | false | Print machine-readable JSON output with follow-up wrapper commands |
+| `--timeout-ms <ms>` | `30000` | Bridge API request timeout; stalled requests fail with `BRIDGE_REQUEST_TIMEOUT` |
+
+### `bridge event batch`
+
+| Flag | Default | Description |
+|---|---|---|
+| `-k, --api-key <key>` | `$HYPERTAB_API_KEY` | Hypertab bridge/API key |
+| `-u, --api-url <url>` | `https://api.hypertab.ai` | Hypertab REST API URL |
+| `--file <path>` | required | JSON file containing `{ "events": [...] }` or an events array |
+| `--json` | false | Print machine-readable JSON output |
+| `--spool-file <path>` | `~/.hypertab/bridge-spool.jsonl` | Local JSONL spool path |
+| `--no-spool` | false | Disable local event spooling on retryable failures |
+| `--timeout-ms <ms>` | `30000` | Bridge API request timeout; stalled requests fail with `BRIDGE_REQUEST_TIMEOUT` |
+
+### `bridge flush`
+
+| Flag | Default | Description |
+|---|---|---|
+| `-k, --api-key <key>` | `$HYPERTAB_API_KEY` | Hypertab bridge/API key |
+| `-u, --api-url <url>` | `https://api.hypertab.ai` | Hypertab REST API URL |
+| `--spool-file <path>` | `~/.hypertab/bridge-spool.jsonl` | Local JSONL spool path |
+| `--json` | false | Print machine-readable JSON output |
+| `--timeout-ms <ms>` | `30000` | Bridge API request timeout; stalled requests fail with `BRIDGE_REQUEST_TIMEOUT` |
+
+### `bridge artifact upload`
+
+| Flag | Default | Description |
+|---|---|---|
+| `-k, --api-key <key>` | `$HYPERTAB_API_KEY` | Hypertab bridge/API key |
+| `-u, --api-url <url>` | `https://api.hypertab.ai` | Hypertab REST API URL |
+| `--file <path>` | required | Local file to upload |
+| `--run-id <id>` | unset | Agent run id to attach the artifact to. Bridge-client tokens should provide this. |
+| `--name <name>` | file basename | Artifact display name |
+| `--artifact-type <type>` | inferred | `screenshot`, `report`, `log`, `dataset`, `file`, or a custom artifact type |
+| `--mime-type <type>` | inferred | Override MIME type |
+| `--metadata <json>` | unset | Metadata JSON object |
+| `--json` | false | Print machine-readable JSON output |
+| `--timeout-ms <ms>` | `30000` | Bridge API request timeout; stalled requests fail with `BRIDGE_REQUEST_TIMEOUT` |
+
+In non-JSON mode the CLI prints an `Uploading <name> (<size>) to <api-url>...` line before the request so a stalled API never leaves the command silent. Stalled or dropped uploads are retried once automatically with a stable `Idempotency-Key` header before failing.
+
+### `bridge wrapper init`
+
+| Flag | Default | Description |
+|---|---|---|
+| `--type <type>` | `node` | Starter type: `node` or `shell` |
+| `--out <path>` | `.hypertab/bridge-wrapper.mjs` or `.hypertab/bridge-wrapper.sh` | Output path |
+| `--force` | false | Overwrite the output file if it already exists |
+| `--json` | false | Print machine-readable JSON output |
+
+### `bridge wrapper doctor`
+
+| Flag | Default | Description |
+|---|---|---|
+| `--path <path>` | `.hypertab/bridge-wrapper.mjs` | Wrapper path to inspect |
+| `-k, --api-key <key>` | `$HYPERTAB_API_KEY` | Hypertab bridge/API key presence check |
+| `--spool-file <path>` | `~/.hypertab/bridge-spool.jsonl` | Local JSONL spool path |
+| `--json` | false | Print machine-readable JSON output |
+
+Supported v1 targets are static browser dashboards: Vite, Vite React, static Astro, or plain HTML output with
+`index.html`. If detection finds a server app such as Next.js SSR/API routes, SvelteKit server routes, Nuxt, Remix,
+Express, or Fastify, convert it to a static browser surface instead of deploying it elsewhere. Keep the UI, move data and
+actions to Hypertab APIs through scoped browser tokens, keep secrets in Hypertab providers/accounts, then publish the
+static output.
+
+## Local bridge daemon
+
+The CLI also exposes a bridge command group for local agent activity:
+
+```bash
+# Mint a scoped bridge-client token with an admin key. The returned token is shown once.
+HYPERTAB_API_KEY=ht_sk_admin... npx @hypertabai/mcp bridge token create \
+  --client-name "$(hostname)-codex" \
+  --client-type codex \
+  --expires-in-days 30 \
+  --json
+
+# One heartbeat + command-claim cycle, useful for testing a bridge token
+HYPERTAB_API_KEY=ht_sk_bridge... npx @hypertabai/mcp bridge start --client-name "$(hostname)-codex" --once --json
+
+# Long-running bridge for Codex/Claude Code/Cursor wrappers
+HYPERTAB_API_KEY=ht_sk_bridge... npx @hypertabai/mcp bridge start --client-name suleman-macbook --client-type codex --json
+
+# Create a durable session/run while starting the bridge
+npx @hypertabai/mcp bridge start --api-key ht_sk_... --objective "Run today's CRM enrichment audit" --json
+
+# Report the result after a wrapper handles a delivered command
+npx @hypertabai/mcp bridge result --api-key ht_sk_... --command-id cmd_... --status completed --json
+
+# Inspect cloud-visible bridge freshness and command delivery state
+npx @hypertabai/mcp bridge status --api-key ht_sk_... --json
+
+# Send a batch of local progress events
+npx @hypertabai/mcp bridge event batch --api-key ht_sk_... --file ./.hypertab/events.json --json
+
+# Force replay of locally spooled bridge records
+npx @hypertabai/mcp bridge flush --api-key ht_sk_... --json
+
+# Upload a local screenshot/report/log/dataset into Hypertab artifact storage
+npx @hypertabai/mcp bridge artifact upload --api-key ht_sk_... --run-id run_... --file ./screenshots/final.png --json
+
+# Copy a safe starter wrapper into the current project
+npx @hypertabai/mcp bridge wrapper init --type node --out ./.hypertab/bridge-wrapper.mjs --json
+
+# Check local wrapper readiness before starting the loop
+HYPERTAB_API_KEY=ht_sk_bridge... npx @hypertabai/mcp bridge wrapper doctor --path ./.hypertab/bridge-wrapper.mjs --json
+
+# Run the starter wrapper with the same client identity bound into the bridge token
+HYPERTAB_API_KEY=ht_sk_bridge... \
+HYPERTAB_BRIDGE_CLIENT_NAME="$(hostname)-codex" \
+HYPERTAB_BRIDGE_CLIENT_TYPE=codex \
+node ./.hypertab/bridge-wrapper.mjs "Report local bridge health"
+```
+
+`bridge token create` calls `POST /auth/bridge-token` with an admin-scoped key and prints the newly minted bridge-client
+token once. Use the returned bridge token, not the admin key, for `bridge start`, wrapper doctor, wrapper run, event
+batch, command result, status, and artifact upload. The JSON output includes `commands.doctor` and `commands.run` with
+the correct `HYPERTAB_BRIDGE_CLIENT_NAME` and `HYPERTAB_BRIDGE_CLIENT_TYPE`; bridge-client tokens are bound to that
+identity, so wrapper runs must keep those values stable.
+
+`bridge start` calls the hosted REST API, not the MCP transport. It heartbeats the local client, optionally starts a
+session/run, writes a start event through the batch endpoint, claims queued commands for that client, and prints each
+command as JSON lines when `--json` is set. A wrapper around Codex, Claude Code, Cursor, or another local process can read
+those lines, inspect the included `contract` metadata, handle the request under a local allowlist/confirmation policy,
+then call `bridge result`.
+
+`bridge status` reads the hosted bridge-health snapshot. It reports online/stale/offline/never-seen clients, attention
+counts, queued commands, delivered commands waiting for a result, unsafe live commands, and per-client attention reasons.
+
+`bridge event batch` reads a JSON file containing `{ "events": [...] }` or a raw events array and posts it to the
+idempotent event-batch endpoint. Retryable failures are spooled locally and can be replayed with `bridge flush`.
+
+Retryable event-batch and command-result failures are stored in a local JSONL spool at
+`~/.hypertab/bridge-spool.jsonl` by default. `bridge start` flushes the spool during its loop, and `bridge flush` can be
+used to replay it on demand. Set `HYPERTAB_BRIDGE_SPOOL` or `--spool-file` to choose a different path.
+
+`bridge artifact upload` reads a local file, infers name/MIME/artifact type when not provided, base64-encodes the content,
+and sends it to Hypertab's authenticated artifact API. The server stores upload bytes in R2, records artifact metadata,
+and applies bridge/artifact budget checks before accepting the upload.
+
+Wrapper recipes for Codex, Claude Code, Cursor, command-result reporting, batched progress events, and artifact upload
+live in `docs/LOCAL-BRIDGE-WRAPPER-RECIPES.md` in the Hypertab repo. Safe command types and wrapper refusal rules live
+in `docs/LOCAL-BRIDGE-COMMAND-CONTRACT.md`. `bridge_command` JSON lines include `contract.allowed`, plus a refusal
+`reason` and `message` when the claimed command is unsafe or malformed.
+
+Starter wrappers ship in `templates/`:
+
+- `templates/bridge-wrapper.sh` -- minimal shell wrapper for one safe bridge cycle.
+- `templates/bridge-wrapper.mjs` -- Node wrapper with safer JSON handling and command result reporting.
+
+Both starters call `bridge start`, `bridge event batch`, `bridge status`, and `bridge result`, inspect
+`bridge_command.contract.allowed`, and refuse or cancel commands that need local policy instead of executing payloads.
+Run `hypertab bridge wrapper init --type node` or `--type shell` to copy one into `.hypertab/` with overwrite
+protection. Use `--force` only when replacing a local wrapper intentionally.
+
+Run `hypertab bridge wrapper doctor` after initialization or customization. It does not contact Hypertab; it checks the
+local wrapper file, key availability, starter safety markers, and pending local spool records. It exits nonzero only for
+hard blockers such as a missing wrapper or missing API key; custom wrapper marker gaps and pending spool records are
+warnings.
+
 ## Troubleshooting
 
 **"Failed to parse existing config"** — your client's existing config file has invalid JSON. Fix it or delete it and re-run.

package/dist/bridge/api-client.d.ts

@@ -0,0 +1,157 @@
+export type BridgeClientType = 'codex' | 'claude_code' | 'cursor' | 'browser' | 'cloud' | 'other';
+export type BridgeCommandResultStatus = 'completed' | 'failed' | 'cancelled';
+export declare const DEFAULT_BRIDGE_TIMEOUT_MS = 30000;
+export interface BridgeAgentClient {
+    id: string;
+    name?: string;
+    type?: BridgeClientType;
+    [key: string]: unknown;
+}
+export interface BridgeAgentSession {
+    id: string;
+    client_id?: string | null;
+    [key: string]: unknown;
+}
+export interface BridgeAgentRun {
+    id: string;
+    client_id?: string | null;
+    session_id?: string | null;
+    [key: string]: unknown;
+}
+export interface BridgeAgentCommand {
+    id: string;
+    command_type: string;
+    payload?: Record<string, unknown>;
+    status?: string;
+    [key: string]: unknown;
+}
+export interface BridgeAgentArtifact {
+    id: string;
+    name?: string;
+    type?: string;
+    uri?: string | null;
+    mime_type?: string | null;
+    size_bytes?: number | null;
+    [key: string]: unknown;
+}
+export interface BridgeToken {
+    id: string;
+    api_key: string;
+    key_prefix: string;
+    name: string;
+    scopes: string[];
+    expires_at: string;
+    claims?: Record<string, unknown>;
+}
+export interface BridgeTokenCreatePayload {
+    name?: string;
+    client_name: string;
+    client_type: BridgeClientType;
+    expires_in_days: number;
+    metadata?: Record<string, unknown>;
+}
+export interface BridgeHealthSnapshot {
+    generated_at?: string;
+    summary?: Record<string, unknown>;
+    clients?: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+export interface BridgeEventBatchPayload {
+    events: Array<{
+        run_id: string;
+        type: 'message' | 'step' | 'tool_call' | 'file_change' | 'artifact' | 'approval' | 'error' | 'status';
+        message: string;
+        data?: Record<string, unknown>;
+        idempotency_key?: string;
+    }>;
+}
+export interface BridgeCommandResultPayload {
+    command_id: string;
+    client_id?: string;
+    status: BridgeCommandResultStatus;
+    error_message?: string | null;
+}
+export interface BridgeArtifactUploadPayload {
+    run_id?: string | null;
+    name: string;
+    type: string;
+    content_base64: string;
+    mime_type?: string | null;
+    size_bytes: number;
+    metadata?: Record<string, unknown>;
+}
+export interface BridgeApiError {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+export type BridgeApiResponse<T> = {
+    ok: true;
+    status: number;
+    data: T;
+} | {
+    ok: false;
+    status: number;
+    error: BridgeApiError;
+};
+export interface BridgeApiClient {
+    heartbeat(input: {
+        name: string;
+        type: BridgeClientType;
+        metadata?: Record<string, unknown>;
+    }): Promise<BridgeApiResponse<{
+        client: BridgeAgentClient;
+    }>>;
+    startSession(input: {
+        client_id: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<BridgeApiResponse<{
+        session: BridgeAgentSession;
+    }>>;
+    createRun(input: {
+        title: string;
+        objective: string;
+        client_id: string;
+        session_id?: string | null;
+        source?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<BridgeApiResponse<{
+        run: BridgeAgentRun;
+    }>>;
+    appendEventBatch(input: BridgeEventBatchPayload): Promise<BridgeApiResponse<{
+        accepted: number;
+        deduped: number;
+        events: unknown[];
+    }>>;
+    claimCommands(input: {
+        client_id: string;
+        limit?: number;
+    }): Promise<BridgeApiResponse<{
+        commands: BridgeAgentCommand[];
+        delivered: number;
+    }>>;
+    reportCommandResult(input: BridgeCommandResultPayload): Promise<BridgeApiResponse<{
+        command: BridgeAgentCommand;
+    }>>;
+    uploadArtifact(input: BridgeArtifactUploadPayload): Promise<BridgeApiResponse<{
+        artifact: BridgeAgentArtifact;
+    }>>;
+    createBridgeToken(input: BridgeTokenCreatePayload): Promise<BridgeApiResponse<{
+        token: BridgeToken;
+        client: BridgeAgentClient;
+    }>>;
+    getBridgeHealth(input: {
+        client_id?: string;
+        limit?: number;
+    }): Promise<BridgeApiResponse<{
+        bridge_health: BridgeHealthSnapshot;
+    }>>;
+}
+export interface BridgeApiClientOptions {
+    apiUrl: string;
+    apiKey: string;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}
+export declare function createBridgeApiClient(options: BridgeApiClientOptions): BridgeApiClient;
+//# sourceMappingURL=api-client.d.ts.map

package/dist/bridge/api-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.d.ts","sourceRoot":"","sources":["../../src/bridge/api-client.ts"],"names":[],"mappings":"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"}

package/dist/bridge/api-client.js

@@ -0,0 +1,140 @@
+import { buildClientOperationIdempotencyKey, OPERATION_IDEMPOTENCY_HEADER } from '../idempotency.js';
+export const DEFAULT_BRIDGE_TIMEOUT_MS = 30_000;
+export function createBridgeApiClient(options) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_BRIDGE_TIMEOUT_MS;
+    const requestOnce = async (path, input) => {
+        const fetchImpl = options.fetchImpl ?? fetch;
+        const controller = new AbortController();
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeoutMs);
+        try {
+            const headers = {
+                Authorization: `Bearer ${options.apiKey}`,
+                'Content-Type': 'application/json',
+            };
+            if (input.idempotencyKey)
+                headers[OPERATION_IDEMPOTENCY_HEADER] = input.idempotencyKey;
+            const res = await fetchImpl(`${options.apiUrl.replace(/\/$/, '')}${path}`, {
+                method: input.method ?? (input.body === undefined ? 'GET' : 'POST'),
+                headers,
+                body: input.body === undefined ? undefined : JSON.stringify(input.body),
+                signal: controller.signal,
+            });
+            return await parseBridgeResponse(res);
+        }
+        catch (error) {
+            if (timedOut) {
+                return {
+                    ok: false,
+                    status: 0,
+                    error: {
+                        code: 'BRIDGE_REQUEST_TIMEOUT',
+                        message: `Bridge API request to ${path} timed out after ${timeoutMs}ms without a response. ` +
+                            'The Hypertab API may be stalled. Retry the command, or pass --timeout-ms to wait longer. ' +
+                            'Spooled event/result records stay queued locally and flush on the next bridge cycle.',
+                        details: { path, timeout_ms: timeoutMs },
+                    },
+                };
+            }
+            return {
+                ok: false,
+                status: 0,
+                error: {
+                    code: 'BRIDGE_API_UNREACHABLE',
+                    message: error instanceof Error ? error.message : 'Bridge API request failed before receiving a response.',
+                },
+            };
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
+    const request = async (path, input = {}) => {
+        const first = await requestOnce(path, input);
+        // Retry exactly once, only for operations that carry an idempotent contract,
+        // and only on transient failures where no response was received (status 0).
+        if (first.ok || !input.retryOnTransientFailure || first.status !== 0)
+            return first;
+        return requestOnce(path, input);
+    };
+    return {
+        heartbeat: (input) => request('/api/agent/clients/heartbeat', { body: input }),
+        startSession: (input) => request('/api/agent/sessions', { body: input }),
+        createRun: (input) => request('/api/agent/runs', { body: input }),
+        appendEventBatch: (input) => request('/api/agent/events/batch', { body: input }),
+        claimCommands: (input) => request('/api/agent/commands/claim', { body: input }),
+        reportCommandResult: (input) => request(`/api/agent/commands/${encodeURIComponent(input.command_id)}/result`, {
+            body: {
+                client_id: input.client_id,
+                status: input.status,
+                error_message: input.error_message,
+            },
+            retryOnTransientFailure: true,
+            idempotencyKey: buildClientOperationIdempotencyKey({
+                operation: 'bridge.command.result',
+                target: input.command_id,
+                payload: {
+                    client_id: input.client_id ?? null,
+                    status: input.status,
+                    error_message: input.error_message ?? null,
+                },
+            }),
+        }),
+        uploadArtifact: (input) => request('/api/agent/artifacts', {
+            body: input,
+            retryOnTransientFailure: true,
+            idempotencyKey: buildClientOperationIdempotencyKey({
+                operation: 'bridge.artifact.upload',
+                target: input.run_id ?? undefined,
+                fingerprint: `${input.name}|${input.size_bytes}|${input.content_base64}`,
+            }),
+        }),
+        createBridgeToken: (input) => request('/auth/bridge-token', { body: input }),
+        getBridgeHealth: (input) => request(`/api/agent/bridge/health${bridgeHealthQuery(input)}`, { retryOnTransientFailure: true }),
+    };
+}
+function bridgeHealthQuery(input) {
+    const params = new URLSearchParams();
+    if (input.client_id)
+        params.set('client_id', input.client_id);
+    if (input.limit)
+        params.set('limit', String(input.limit));
+    const query = params.toString();
+    return query ? `?${query}` : '';
+}
+async function parseBridgeResponse(res) {
+    const text = await res.text();
+    const payload = parseEnvelope(text);
+    if (res.ok && payload.success === true) {
+        return { ok: true, status: res.status, data: payload.data };
+    }
+    return {
+        ok: false,
+        status: res.status,
+        error: {
+            code: payload.error?.code ?? 'BRIDGE_API_FAILED',
+            message: payload.error?.message ?? `Bridge API failed with HTTP ${res.status}.`,
+            details: payload.error?.details,
+        },
+    };
+}
+function parseEnvelope(text) {
+    if (!text)
+        return {};
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return {
+            success: false,
+            error: {
+                code: 'BRIDGE_API_INVALID_JSON',
+                message: text.slice(0, 500),
+            },
+        };
+    }
+}
+//# sourceMappingURL=api-client.js.map

package/dist/bridge/api-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-client.js","sourceRoot":"","sources":["../../src/bridge/api-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kCAAkC,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAA;AAKpG,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAA;AAmK/C,MAAM,UAAU,qBAAqB,CAAC,OAA+B;IACpE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,yBAAyB,CAAA;IAEhE,MAAM,WAAW,GAAG,KAAK,EAAK,IAAY,EAAE,KAAyB,EAAiC,EAAE;QACvG,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,CAAA;QAC5C,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;QACxC,IAAI,QAAQ,GAAG,KAAK,CAAA;QACpB,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC7B,QAAQ,GAAG,IAAI,CAAA;YACf,UAAU,CAAC,KAAK,EAAE,CAAA;QACnB,CAAC,EAAE,SAAS,CAAC,CAAA;QACb,IAAI,CAAC;YACJ,MAAM,OAAO,GAA2B;gBACvC,aAAa,EAAE,UAAU,OAAO,CAAC,MAAM,EAAE;gBACzC,cAAc,EAAE,kBAAkB;aAClC,CAAA;YACD,IAAI,KAAK,CAAC,cAAc;gBAAE,OAAO,CAAC,4BAA4B,CAAC,GAAG,KAAK,CAAC,cAAc,CAAA;YACtF,MAAM,GAAG,GAAG,MAAM,SAAS,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE;gBAC1E,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;gBACnE,OAAO;gBACP,IAAI,EAAE,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC;gBACvE,MAAM,EAAE,UAAU,CAAC,MAAM;aACzB,CAAC,CAAA;YACF,OAAO,MAAM,mBAAmB,CAAI,GAAG,CAAC,CAAA;QACzC,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,IAAI,QAAQ,EAAE,CAAC;gBACd,OAAO;oBACN,EAAE,EAAE,KAAK;oBACT,MAAM,EAAE,CAAC;oBACT,KAAK,EAAE;wBACN,IAAI,EAAE,wBAAwB;wBAC9B,OAAO,EACN,yBAAyB,IAAI,oBAAoB,SAAS,yBAAyB;4BACnF,2FAA2F;4BAC3F,sFAAsF;wBACvF,OAAO,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE;qBACxC;iBACD,CAAA;YACF,CAAC;YACD,OAAO;gBACN,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,CAAC;gBACT,KAAK,EAAE;oBACN,IAAI,EAAE,wBAAwB;oBAC9B,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,wDAAwD;iBAC1G;aACD,CAAA;QACF,CAAC;gBAAS,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAA;QACpB,CAAC;IACF,CAAC,CAAA;IAED,MAAM,OAAO,GAAG,KAAK,EAAK,IAAY,EAAE,QAA4B,EAAE,EAAiC,EAAE;QACxG,MAAM,KAAK,GAAG,MAAM,WAAW,CAAI,IAAI,EAAE,KAAK,CAAC,CAAA;QAC/C,6EAA6E;QAC7E,4EAA4E;QAC5E,IAAI,KAAK,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,uBAAuB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAA;QAClF,OAAO,WAAW,CAAI,IAAI,EAAE,KAAK,CAAC,CAAA;IACnC,CAAC,CAAA;IAED,OAAO;QACN,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,8BAA8B,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QAC9E,YAAY,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,qBAAqB,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QACxE,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QACjE,gBAAgB,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,yBAAyB,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QAChF,aAAa,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,2BAA2B,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QAC/E,mBAAmB,EAAE,CAAC,KAAK,EAAE,EAAE,CAC9B,OAAO,CAAC,uBAAuB,kBAAkB,CAAC,KAAK,CAAC,UAAU,CAAC,SAAS,EAAE;YAC7E,IAAI,EAAE;gBACL,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,aAAa,EAAE,KAAK,CAAC,aAAa;aAClC;YACD,uBAAuB,EAAE,IAAI;YAC7B,cAAc,EAAE,kCAAkC,CAAC;gBAClD,SAAS,EAAE,uBAAuB;gBAClC,MAAM,EAAE,KAAK,CAAC,UAAU;gBACxB,OAAO,EAAE;oBACR,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI;oBAClC,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,IAAI;iBAC1C;aACD,CAAC;SACF,CAAC;QACH,cAAc,EAAE,CAAC,KAAK,EAAE,EAAE,CACzB,OAAO,CAAC,sBAAsB,EAAE;YAC/B,IAAI,EAAE,KAAK;YACX,uBAAuB,EAAE,IAAI;YAC7B,cAAc,EAAE,kCAAkC,CAAC;gBAClD,SAAS,EAAE,wBAAwB;gBACnC,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,SAAS;gBACjC,WAAW,EAAE,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,cAAc,EAAE;aACxE,CAAC;SACF,CAAC;QACH,iBAAiB,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,oBAAoB,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;QAC5E,eAAe,EAAE,CAAC,KAAK,EAAE,EAAE,CAC1B,OAAO,CAAC,2BAA2B,iBAAiB,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,uBAAuB,EAAE,IAAI,EAAE,CAAC;KAClG,CAAA;AACF,CAAC;AAED,SAAS,iBAAiB,CAAC,KAA6C;IACvE,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAA;IACpC,IAAI,KAAK,CAAC,SAAS;QAAE,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,SAAS,CAAC,CAAA;IAC7D,IAAI,KAAK,CAAC,KAAK;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAA;IACzD,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAA;IAC/B,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAA;AAChC,CAAC;AAED,KAAK,UAAU,mBAAmB,CAAI,GAAa;IAClD,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAA;IAC7B,MAAM,OAAO,GAAG,aAAa,CAAI,IAAI,CAAC,CAAA;IACtC,IAAI,GAAG,CAAC,EAAE,IAAI,OAAO,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QACxC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,IAAS,EAAE,CAAA;IACjE,CAAC;IAED,OAAO;QACN,EAAE,EAAE,KAAK;QACT,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,KAAK,EAAE;YACN,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE,IAAI,IAAI,mBAAmB;YAChD,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO,IAAI,+BAA+B,GAAG,CAAC,MAAM,GAAG;YAC/E,OAAO,EAAE,OAAO,CAAC,KAAK,EAAE,OAAO;SAC/B;KACD,CAAA;AACF,CAAC;AAED,SAAS,aAAa,CAAI,IAAY;IACrC,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAA;IACpB,IAAI,CAAC;QACJ,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAmB,CAAA;IAC1C,CAAC;IAAC,MAAM,CAAC;QACR,OAAO;YACN,OAAO,EAAE,KAAK;YACd,KAAK,EAAE;gBACN,IAAI,EAAE,yBAAyB;gBAC/B,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;aAC3B;SACD,CAAA;IACF,CAAC;AACF,CAAC"}

package/dist/bridge/artifacts.d.ts

@@ -0,0 +1,11 @@
+import type { BridgeArtifactUploadPayload } from './api-client.js';
+export interface PrepareBridgeArtifactInput {
+    file: string;
+    runId?: string;
+    name?: string;
+    type?: string;
+    mimeType?: string;
+    metadataJson?: string;
+}
+export declare function prepareBridgeArtifactUpload(input: PrepareBridgeArtifactInput): Promise<BridgeArtifactUploadPayload>;
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/bridge/artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../src/bridge/artifacts.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAA;AAElE,MAAM,WAAW,0BAA0B;IAC1C,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,wBAAsB,2BAA2B,CAAC,KAAK,EAAE,0BAA0B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAYzH"}

package/dist/bridge/artifacts.js

@@ -0,0 +1,45 @@
+import { readFile, stat } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { lookup } from 'mime-types';
+export async function prepareBridgeArtifactUpload(input) {
+    const [bytes, stats] = await Promise.all([readFile(input.file), stat(input.file)]);
+    if (!stats.isFile())
+        throw new Error(`Artifact path '${input.file}' is not a file.`);
+    return {
+        run_id: input.runId ?? null,
+        name: input.name ?? basename(input.file),
+        type: input.type ?? inferArtifactType(input.file),
+        content_base64: bytes.toString('base64'),
+        mime_type: input.mimeType ?? inferMimeType(input.file),
+        size_bytes: bytes.byteLength,
+        metadata: parseMetadata(input.metadataJson),
+    };
+}
+function inferMimeType(file) {
+    const detected = lookup(file);
+    return typeof detected === 'string' ? detected : 'application/octet-stream';
+}
+function inferArtifactType(file) {
+    const mimeType = inferMimeType(file);
+    if (mimeType === 'application/json')
+        return 'dataset';
+    if (mimeType === 'text/csv')
+        return 'dataset';
+    if (mimeType?.startsWith('image/'))
+        return 'screenshot';
+    if (mimeType?.startsWith('text/'))
+        return 'log';
+    if (mimeType === 'application/pdf')
+        return 'report';
+    return 'file';
+}
+function parseMetadata(metadataJson) {
+    if (!metadataJson)
+        return undefined;
+    const parsed = JSON.parse(metadataJson);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('Artifact metadata must be a JSON object.');
+    }
+    return parsed;
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/bridge/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../../src/bridge/artifacts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AACjD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAA;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAYnC,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,KAAiC;IAClF,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IAClF,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,KAAK,CAAC,IAAI,kBAAkB,CAAC,CAAA;IACpF,OAAO;QACN,MAAM,EAAE,KAAK,CAAC,KAAK,IAAI,IAAI;QAC3B,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;QACxC,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,iBAAiB,CAAC,KAAK,CAAC,IAAI,CAAC;QACjD,cAAc,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC;QACxC,SAAS,EAAE,KAAK,CAAC,QAAQ,IAAI,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC;QACtD,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,QAAQ,EAAE,aAAa,CAAC,KAAK,CAAC,YAAY,CAAC;KAC3C,CAAA;AACF,CAAC;AAED,SAAS,aAAa,CAAC,IAAY;IAClC,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAA;IAC7B,OAAO,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,0BAA0B,CAAA;AAC5E,CAAC;AAED,SAAS,iBAAiB,CAAC,IAAY;IACtC,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,CAAA;IACpC,IAAI,QAAQ,KAAK,kBAAkB;QAAE,OAAO,SAAS,CAAA;IACrD,IAAI,QAAQ,KAAK,UAAU;QAAE,OAAO,SAAS,CAAA;IAC7C,IAAI,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,YAAY,CAAA;IACvD,IAAI,QAAQ,EAAE,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAA;IAC/C,IAAI,QAAQ,KAAK,iBAAiB;QAAE,OAAO,QAAQ,CAAA;IACnD,OAAO,MAAM,CAAA;AACd,CAAC;AAED,SAAS,aAAa,CAAC,YAAgC;IACtD,IAAI,CAAC,YAAY;QAAE,OAAO,SAAS,CAAA;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAY,CAAA;IAClD,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAA;IAC5D,CAAC;IACD,OAAO,MAAiC,CAAA;AACzC,CAAC"}