@hypertabai/mcp 0.2.0 → 1.0.0

package/dist/bridge/index.js

@@ -0,0 +1,875 @@
+import { access, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { dirname } from 'node:path';
+import { createBridgeApiClient, DEFAULT_BRIDGE_TIMEOUT_MS, } from './api-client.js';
+import { prepareBridgeArtifactUpload } from './artifacts.js';
+import { defaultBridgeSpoolFile, enqueueCommandResult, enqueueEventBatch, flushBridgeSpool, readBridgeSpool, shouldSpoolBridgeFailure, } from './spool.js';
+import { classifyBridgeCommandContract } from './command-contract.js';
+export const DEFAULT_BRIDGE_API_URL = 'https://api.hypertab.ai';
+export const BRIDGE_CLIENT_TYPES = ['codex', 'claude_code', 'cursor', 'browser', 'cloud', 'other'];
+export function registerBridgeCommand(program, deps = {}) {
+    const runStart = deps.runStart ?? runBridgeDaemon;
+    const runResult = deps.runResult ?? runBridgeResult;
+    const runStatus = deps.runStatus ?? runBridgeStatus;
+    const runTokenCreate = deps.runTokenCreate ?? runBridgeTokenCreate;
+    const runEventBatch = deps.runEventBatch ?? runBridgeEventBatch;
+    const runFlush = deps.runFlush ?? runBridgeFlush;
+    const runArtifactUpload = deps.runArtifactUpload ?? runBridgeArtifactUpload;
+    const runWrapperInit = deps.runWrapperInit ?? runBridgeWrapperInit;
+    const runWrapperDoctor = deps.runWrapperDoctor ?? runBridgeWrapperDoctor;
+    const exit = deps.exit ?? ((code) => process.exit(code));
+    const bridge = program.command('bridge').description('Run the local Hypertab bridge for agent activity');
+    bridge
+        .command('start')
+        .description('Heartbeat a local agent client and claim cloud commands')
+        .option('-k, --api-key <key>', 'Hypertab bridge/API key. Prefer HYPERTAB_API_KEY env var for safety.')
+        .option('-u, --api-url <url>', 'Hypertab API URL', DEFAULT_BRIDGE_API_URL)
+        .option('--client-name <name>', 'Stable local client name. Defaults to the machine hostname.')
+        .option('--client-type <type>', `Client type: ${BRIDGE_CLIENT_TYPES.join(' | ')}`, 'codex')
+        .option('--heartbeat-interval-ms <ms>', 'Heartbeat interval for long-running mode', parsePositiveInt, 30_000)
+        .option('--command-interval-ms <ms>', 'Command claim interval for long-running mode', parsePositiveInt, 5_000)
+        .option('--command-limit <n>', 'Max commands claimed per poll', parsePositiveInt, 10)
+        .option('--session', 'Start a durable agent session after heartbeat')
+        .option('--objective <text>', 'Create a durable run for this objective')
+        .option('--run-title <title>', 'Run title when --objective is provided')
+        .option('--source <source>', 'Run source label', 'cli_bridge')
+        .option('--once', 'Run one heartbeat/claim cycle and exit')
+        .option('--json', 'Print machine-readable JSON lines')
+        .option('--spool-file <path>', 'Local JSONL spool file', defaultBridgeSpoolFile())
+        .option('--no-spool', 'Disable local event/result spooling')
+        .option('--timeout-ms <ms>', 'Bridge API request timeout in milliseconds', parsePositiveInt, DEFAULT_BRIDGE_TIMEOUT_MS)
+        .action(async (opts) => {
+        const code = await runStart(normalizeBridgeStartOptions(opts));
+        exit(code);
+    });
+    bridge
+        .command('status')
+        .description('Show local bridge freshness, attention, and command delivery health')
+        .option('-k, --api-key <key>', 'Hypertab bridge/API key. Prefer HYPERTAB_API_KEY env var for safety.')
+        .option('-u, --api-url <url>', 'Hypertab API URL', DEFAULT_BRIDGE_API_URL)
+        .option('--client-id <id>', 'Optional client id for broad bridge/API keys. Bridge-client tokens are already scoped.')
+        .option('--limit <n>', 'Max clients/runs/commands to inspect', parsePositiveInt, 50)
+        .option('--json', 'Print machine-readable JSON output')
+        .option('--timeout-ms <ms>', 'Bridge API request timeout in milliseconds', parsePositiveInt, DEFAULT_BRIDGE_TIMEOUT_MS)
+        .action(async (opts) => {
+        const code = await runStatus(normalizeBridgeStatusOptions(opts));
+        exit(code);
+    });
+    const token = bridge.command('token').description('Manage local bridge credentials');
+    token
+        .command('create')
+        .description('Mint a client-bound local bridge token')
+        .option('-k, --api-key <key>', 'Admin Hypertab API key. Prefer HYPERTAB_API_KEY env var for safety.')
+        .option('-u, --api-url <url>', 'Hypertab API URL', DEFAULT_BRIDGE_API_URL)
+        .option('--name <name>', 'Token display name. Defaults to "<client-name> bridge".')
+        .requiredOption('--client-name <name>', 'Stable local client name bound into the token')
+        .option('--client-type <type>', `Client type: ${BRIDGE_CLIENT_TYPES.join(' | ')}`, 'codex')
+        .option('--expires-in-days <days>', 'Token lifetime in days, 1-365', parsePositiveInt, 30)
+        .option('--json', 'Print machine-readable JSON output')
+        .option('--timeout-ms <ms>', 'Bridge API request timeout in milliseconds', parsePositiveInt, DEFAULT_BRIDGE_TIMEOUT_MS)
+        .action(async (opts) => {
+        const code = await runTokenCreate(normalizeBridgeTokenCreateOptions(opts));
+        exit(code);
+    });
+    bridge
+        .command('result')
+        .description('Report the result of a delivered cloud command')
+        .option('-k, --api-key <key>', 'Hypertab bridge/API key. Prefer HYPERTAB_API_KEY env var for safety.')
+        .option('-u, --api-url <url>', 'Hypertab API URL', DEFAULT_BRIDGE_API_URL)
+        .requiredOption('--command-id <id>', 'Delivered command id')
+        .option('--client-id <id>', 'Client id for broad bridge tokens. Bridge-client tokens can omit it.')
+        .requiredOption('--status <status>', 'completed | failed | cancelled')
+        .option('--error-message <message>', 'Failure/cancellation details')
+        .option('--json', 'Print machine-readable JSON output')
+        .option('--spool-file <path>', 'Local JSONL spool file', defaultBridgeSpoolFile())
+        .option('--no-spool', 'Disable local result spooling on retryable failures')
+        .option('--timeout-ms <ms>', 'Bridge API request timeout in milliseconds', parsePositiveInt, DEFAULT_BRIDGE_TIMEOUT_MS)
+        .action(async (opts) => {
+        const code = await runResult(normalizeBridgeResultOptions(opts));
+        exit(code);
+    });
+    const event = bridge.command('event').description('Send local bridge progress events');
+    event
+        .command('batch')
+        .description('Post a JSON batch of local progress events')
+        .option('-k, --api-key <key>', 'Hypertab bridge/API key. Prefer HYPERTAB_API_KEY env var for safety.')
+        .option('-u, --api-url <url>', 'Hypertab API URL', DEFAULT_BRIDGE_API_URL)
+        .requiredOption('--file <path>', 'JSON file containing { "events": [...] } or an events array')
+        .option('--json', 'Print machine-readable JSON output')
+        .option('--spool-file <path>', 'Local JSONL spool file', defaultBridgeSpoolFile())
+        .option('--no-spool', 'Disable local event spooling on retryable failures')
+        .option('--timeout-ms <ms>', 'Bridge API request timeout in milliseconds', parsePositiveInt, DEFAULT_BRIDGE_TIMEOUT_MS)
+        .action(async (opts) => {
+        const code = await runEventBatch(normalizeBridgeEventBatchOptions(opts));
+        exit(code);
+    });
+    bridge
+        .command('flush')
+        .description('Flush queued local bridge spool records')
+        .option('-k, --api-key <key>', 'Hypertab bridge/API key. Prefer HYPERTAB_API_KEY env var for safety.')
+        .option('-u, --api-url <url>', 'Hypertab API URL', DEFAULT_BRIDGE_API_URL)
+        .option('--spool-file <path>', 'Local JSONL spool file', defaultBridgeSpoolFile())
+        .option('--json', 'Print machine-readable JSON output')
+        .option('--timeout-ms <ms>', 'Bridge API request timeout in milliseconds', parsePositiveInt, DEFAULT_BRIDGE_TIMEOUT_MS)
+        .action(async (opts) => {
+        const code = await runFlush(normalizeBridgeFlushOptions(opts));
+        exit(code);
+    });
+    const artifact = bridge.command('artifact').description('Upload local bridge artifacts to Hypertab');
+    artifact
+        .command('upload')
+        .description('Upload a local file as an agent artifact')
+        .option('-k, --api-key <key>', 'Hypertab bridge/API key. Prefer HYPERTAB_API_KEY env var for safety.')
+        .option('-u, --api-url <url>', 'Hypertab API URL', DEFAULT_BRIDGE_API_URL)
+        .requiredOption('--file <path>', 'Local file to upload')
+        .option('--run-id <id>', 'Agent run id to attach the artifact to')
+        .option('--name <name>', 'Artifact display name. Defaults to the file basename.')
+        .option('--artifact-type <type>', 'Artifact type, for example screenshot, report, log, dataset, file')
+        .option('--mime-type <type>', 'Override MIME type')
+        .option('--metadata <json>', 'Metadata JSON object')
+        .option('--json', 'Print machine-readable JSON output')
+        .option('--timeout-ms <ms>', 'Bridge API request timeout in milliseconds', parsePositiveInt, DEFAULT_BRIDGE_TIMEOUT_MS)
+        .action(async (opts) => {
+        const code = await runArtifactUpload(normalizeBridgeArtifactUploadOptions(opts));
+        exit(code);
+    });
+    const wrapper = bridge.command('wrapper').description('Create local bridge wrapper starter files');
+    wrapper
+        .command('init')
+        .description('Copy a safe local bridge wrapper starter into this workspace')
+        .option('--type <type>', 'Starter type: node | shell', 'node')
+        .option('--out <path>', 'Output path. Defaults to .hypertab/bridge-wrapper.mjs or .hypertab/bridge-wrapper.sh')
+        .option('--force', 'Overwrite the output file if it already exists')
+        .option('--json', 'Print machine-readable JSON output')
+        .action(async (opts) => {
+        const code = await runWrapperInit(normalizeBridgeWrapperInitOptions(opts));
+        exit(code);
+    });
+    wrapper
+        .command('doctor')
+        .description('Check local bridge wrapper readiness without contacting Hypertab')
+        .option('--path <path>', 'Wrapper path to inspect', '.hypertab/bridge-wrapper.mjs')
+        .option('-k, --api-key <key>', 'Hypertab bridge/API key. Prefer HYPERTAB_API_KEY env var for safety.')
+        .option('--spool-file <path>', 'Local JSONL spool file', defaultBridgeSpoolFile())
+        .option('--json', 'Print machine-readable JSON output')
+        .action(async (opts) => {
+        const code = await runWrapperDoctor(normalizeBridgeWrapperDoctorOptions(opts));
+        exit(code);
+    });
+}
+export function normalizeBridgeStartOptions(opts) {
+    return {
+        apiKey: opts.apiKey,
+        apiUrl: opts.apiUrl,
+        clientName: opts.clientName,
+        clientType: normalizeBridgeClientType(opts.clientType),
+        heartbeatIntervalMs: opts.heartbeatIntervalMs,
+        commandIntervalMs: opts.commandIntervalMs,
+        commandLimit: Math.min(opts.commandLimit, 50),
+        session: opts.session ?? false,
+        objective: opts.objective,
+        runTitle: opts.runTitle,
+        source: opts.source,
+        once: opts.once ?? false,
+        json: opts.json ?? false,
+        spool: opts.spool ?? true,
+        spoolFile: opts.spoolFile ?? defaultBridgeSpoolFile(),
+        timeoutMs: opts.timeoutMs ?? DEFAULT_BRIDGE_TIMEOUT_MS,
+    };
+}
+export function normalizeBridgeResultOptions(opts) {
+    return {
+        apiKey: opts.apiKey,
+        apiUrl: opts.apiUrl,
+        commandId: opts.commandId,
+        clientId: opts.clientId,
+        status: normalizeCommandResultStatus(opts.status),
+        errorMessage: opts.errorMessage,
+        json: opts.json ?? false,
+        spool: opts.spool ?? true,
+        spoolFile: opts.spoolFile ?? defaultBridgeSpoolFile(),
+        timeoutMs: opts.timeoutMs ?? DEFAULT_BRIDGE_TIMEOUT_MS,
+    };
+}
+export function normalizeBridgeStatusOptions(opts) {
+    return {
+        apiKey: opts.apiKey,
+        apiUrl: opts.apiUrl,
+        clientId: opts.clientId,
+        limit: Math.min(opts.limit, 100),
+        json: opts.json ?? false,
+        timeoutMs: opts.timeoutMs ?? DEFAULT_BRIDGE_TIMEOUT_MS,
+    };
+}
+export function normalizeBridgeTokenCreateOptions(opts) {
+    const clientName = opts.clientName?.trim();
+    if (!clientName)
+        throw new Error('Bridge token client name is required.');
+    const expiresInDays = opts.expiresInDays ?? 30;
+    if (expiresInDays > 365)
+        throw new Error('Bridge token expiry must be between 1 and 365 days.');
+    return {
+        apiKey: opts.apiKey,
+        apiUrl: opts.apiUrl,
+        name: optionalTrimmedString(opts.name),
+        clientName,
+        clientType: normalizeBridgeClientType(opts.clientType ?? 'codex'),
+        expiresInDays,
+        json: opts.json ?? false,
+        timeoutMs: opts.timeoutMs ?? DEFAULT_BRIDGE_TIMEOUT_MS,
+    };
+}
+export function normalizeBridgeEventBatchOptions(opts) {
+    return {
+        apiKey: opts.apiKey,
+        apiUrl: opts.apiUrl,
+        file: opts.file,
+        json: opts.json ?? false,
+        spool: opts.spool ?? true,
+        spoolFile: opts.spoolFile ?? defaultBridgeSpoolFile(),
+        timeoutMs: opts.timeoutMs ?? DEFAULT_BRIDGE_TIMEOUT_MS,
+    };
+}
+export function normalizeBridgeFlushOptions(opts) {
+    return {
+        apiKey: opts.apiKey,
+        apiUrl: opts.apiUrl,
+        spoolFile: opts.spoolFile ?? defaultBridgeSpoolFile(),
+        json: opts.json ?? false,
+        timeoutMs: opts.timeoutMs ?? DEFAULT_BRIDGE_TIMEOUT_MS,
+    };
+}
+export function normalizeBridgeArtifactUploadOptions(opts) {
+    return {
+        apiKey: opts.apiKey,
+        apiUrl: opts.apiUrl,
+        file: opts.file,
+        runId: opts.runId,
+        name: opts.name,
+        artifactType: opts.artifactType,
+        mimeType: opts.mimeType,
+        metadata: opts.metadata,
+        json: opts.json ?? false,
+        timeoutMs: opts.timeoutMs ?? DEFAULT_BRIDGE_TIMEOUT_MS,
+    };
+}
+export function normalizeBridgeWrapperInitOptions(opts) {
+    return {
+        type: normalizeWrapperType(opts.type ?? 'node'),
+        out: opts.out,
+        force: opts.force ?? false,
+        json: opts.json ?? false,
+    };
+}
+export function normalizeBridgeWrapperDoctorOptions(opts) {
+    return {
+        path: opts.path,
+        apiKey: opts.apiKey,
+        spoolFile: opts.spoolFile ?? defaultBridgeSpoolFile(),
+        json: opts.json ?? false,
+    };
+}
+export function resolveBridgeApiKey(input) {
+    const key = input.apiKey ?? input.env?.HYPERTAB_API_KEY ?? process.env.HYPERTAB_API_KEY;
+    return key?.startsWith('ht_sk_') ? key : null;
+}
+export async function runBridgeDaemon(options) {
+    const stdout = options.stdout ?? process.stdout;
+    const apiKey = resolveBridgeApiKey({ apiKey: options.apiKey });
+    if (!apiKey) {
+        writeFailure(options, 'BRIDGE_API_KEY_MISSING', 'Provide a Hypertab API key with --api-key or HYPERTAB_API_KEY.');
+        return 2;
+    }
+    const client = createBridgeApiClient({ apiUrl: options.apiUrl, apiKey, timeoutMs: options.timeoutMs, fetchImpl: options.fetchImpl });
+    const context = await initializeBridge(client, options);
+    if (!context.ok) {
+        writeFailure(options, context.code, context.message, context.details);
+        return 2;
+    }
+    writeBridgeStatus(stdout, options, context.data);
+    if (options.spool)
+        await writeSpoolFlushStatus(stdout, options, await flushBridgeSpool(client, options.spoolFile));
+    let iterations = 0;
+    let lastHeartbeat = Date.now();
+    while (true) {
+        if (iterations > 0 && Date.now() - lastHeartbeat >= options.heartbeatIntervalMs) {
+            const heartbeat = await sendHeartbeat(client, options);
+            if (!heartbeat.ok) {
+                writeFailure(options, heartbeat.code, heartbeat.message, heartbeat.details);
+                return 2;
+            }
+            lastHeartbeat = Date.now();
+        }
+        const claim = await client.claimCommands({
+            client_id: context.data.client.id,
+            limit: options.commandLimit,
+        });
+        if (!claim.ok) {
+            writeFailure(options, claim.error.code, claim.error.message, claim.error.details);
+            return 2;
+        }
+        for (const command of claim.data.commands)
+            writeCommand(stdout, options, command);
+        if (options.spool)
+            await writeSpoolFlushStatus(stdout, options, await flushBridgeSpool(client, options.spoolFile));
+        iterations += 1;
+        if (options.once || (options.maxIterations !== undefined && iterations >= options.maxIterations))
+            break;
+        await (options.sleep ?? sleep)(options.commandIntervalMs);
+    }
+    if (!options.json && options.once)
+        stdout.write('Bridge cycle complete.\n');
+    return 0;
+}
+export async function runBridgeResult(options) {
+    const stdout = options.stdout ?? process.stdout;
+    const apiKey = resolveBridgeApiKey({ apiKey: options.apiKey });
+    if (!apiKey) {
+        writeFailure(options, 'BRIDGE_API_KEY_MISSING', 'Provide a Hypertab API key with --api-key or HYPERTAB_API_KEY.');
+        return 2;
+    }
+    const client = createBridgeApiClient({ apiUrl: options.apiUrl, apiKey, timeoutMs: options.timeoutMs, fetchImpl: options.fetchImpl });
+    const result = await client.reportCommandResult({
+        command_id: options.commandId,
+        client_id: options.clientId,
+        status: options.status,
+        error_message: options.errorMessage,
+    });
+    if (!result.ok) {
+        if (options.spool && shouldSpoolBridgeFailure(result.status)) {
+            await enqueueCommandResult(options.spoolFile, {
+                command_id: options.commandId,
+                client_id: options.clientId,
+                status: options.status,
+                error_message: options.errorMessage,
+            });
+            writeSpoolQueued(stdout, options, 'command_result', options.spoolFile);
+            return 0;
+        }
+        writeFailure(options, result.error.code, result.error.message, result.error.details);
+        return 2;
+    }
+    if (options.json) {
+        stdout.write(`${JSON.stringify({ success: true, data: result.data })}\n`);
+        return 0;
+    }
+    stdout.write(`Reported command ${result.data.command.id} as ${result.data.command.status ?? options.status}.\n`);
+    return 0;
+}
+export async function runBridgeStatus(options) {
+    const stdout = options.stdout ?? process.stdout;
+    const apiKey = resolveBridgeApiKey({ apiKey: options.apiKey });
+    if (!apiKey) {
+        writeFailure(options, 'BRIDGE_API_KEY_MISSING', 'Provide a Hypertab API key with --api-key or HYPERTAB_API_KEY.');
+        return 2;
+    }
+    const client = createBridgeApiClient({ apiUrl: options.apiUrl, apiKey, timeoutMs: options.timeoutMs, fetchImpl: options.fetchImpl });
+    const result = await client.getBridgeHealth({
+        client_id: options.clientId,
+        limit: options.limit,
+    });
+    if (!result.ok) {
+        writeFailure(options, result.error.code, result.error.message, result.error.details);
+        return 2;
+    }
+    writeBridgeHealthStatus(stdout, options, result.data.bridge_health);
+    return 0;
+}
+export async function runBridgeTokenCreate(options) {
+    const stdout = options.stdout ?? process.stdout;
+    const apiKey = resolveBridgeApiKey({ apiKey: options.apiKey });
+    if (!apiKey) {
+        writeFailure(options, 'BRIDGE_API_KEY_MISSING', 'Provide an admin Hypertab API key with --api-key or HYPERTAB_API_KEY to mint a bridge token.');
+        return 2;
+    }
+    const client = createBridgeApiClient({ apiUrl: options.apiUrl, apiKey, timeoutMs: options.timeoutMs, fetchImpl: options.fetchImpl });
+    const result = await client.createBridgeToken({
+        name: options.name,
+        client_name: options.clientName,
+        client_type: options.clientType,
+        expires_in_days: options.expiresInDays,
+        metadata: { source: 'hypertab_bridge_cli' },
+    });
+    if (!result.ok) {
+        writeFailure(options, result.error.code, result.error.message, result.error.details);
+        return 2;
+    }
+    writeBridgeTokenCreateStatus(stdout, options, result.data);
+    return 0;
+}
+export async function runBridgeEventBatch(options) {
+    const stdout = options.stdout ?? process.stdout;
+    const apiKey = resolveBridgeApiKey({ apiKey: options.apiKey });
+    if (!apiKey) {
+        writeFailure(options, 'BRIDGE_API_KEY_MISSING', 'Provide a Hypertab API key with --api-key or HYPERTAB_API_KEY.');
+        return 2;
+    }
+    let payload;
+    try {
+        payload = await readBridgeEventBatchFile(options.file);
+    }
+    catch (error) {
+        writeFailure(options, 'BRIDGE_EVENT_BATCH_INVALID', error instanceof Error ? error.message : 'Failed to read bridge event batch file.');
+        return 2;
+    }
+    const client = createBridgeApiClient({ apiUrl: options.apiUrl, apiKey, timeoutMs: options.timeoutMs, fetchImpl: options.fetchImpl });
+    const result = await client.appendEventBatch(payload);
+    if (!result.ok) {
+        if (options.spool && shouldSpoolBridgeFailure(result.status)) {
+            await enqueueEventBatch(options.spoolFile, payload);
+            writeSpoolQueued(stdout, options, 'event_batch', options.spoolFile);
+            return 0;
+        }
+        writeFailure(options, result.error.code, result.error.message, result.error.details);
+        return 2;
+    }
+    writeEventBatchStatus(stdout, options, result.data);
+    return 0;
+}
+export async function runBridgeFlush(options) {
+    const stdout = options.stdout ?? process.stdout;
+    const apiKey = resolveBridgeApiKey({ apiKey: options.apiKey });
+    if (!apiKey) {
+        writeFailure(options, 'BRIDGE_API_KEY_MISSING', 'Provide a Hypertab API key with --api-key or HYPERTAB_API_KEY.');
+        return 2;
+    }
+    const client = createBridgeApiClient({ apiUrl: options.apiUrl, apiKey, timeoutMs: options.timeoutMs, fetchImpl: options.fetchImpl });
+    const result = await flushBridgeSpool(client, options.spoolFile);
+    writeSpoolFlushStatus(stdout, options, result);
+    return result.remaining === 0 ? 0 : 2;
+}
+export async function runBridgeArtifactUpload(options) {
+    const stdout = options.stdout ?? process.stdout;
+    const apiKey = resolveBridgeApiKey({ apiKey: options.apiKey });
+    if (!apiKey) {
+        writeFailure(options, 'BRIDGE_API_KEY_MISSING', 'Provide a Hypertab API key with --api-key or HYPERTAB_API_KEY.');
+        return 2;
+    }
+    let payload;
+    try {
+        payload = await prepareBridgeArtifactUpload({
+            file: options.file,
+            runId: options.runId,
+            name: options.name,
+            type: options.artifactType,
+            mimeType: options.mimeType,
+            metadataJson: options.metadata,
+        });
+    }
+    catch (error) {
+        writeFailure(options, 'BRIDGE_ARTIFACT_PREPARE_FAILED', error instanceof Error ? error.message : 'Failed to prepare artifact upload.');
+        return 2;
+    }
+    if (!options.json) {
+        stdout.write(`Uploading ${payload.name} (${formatByteSize(payload.size_bytes)}) to ${options.apiUrl}...\n`);
+    }
+    const client = createBridgeApiClient({ apiUrl: options.apiUrl, apiKey, timeoutMs: options.timeoutMs, fetchImpl: options.fetchImpl });
+    const result = await client.uploadArtifact(payload);
+    if (!result.ok) {
+        writeFailure(options, result.error.code, result.error.message, result.error.details);
+        return 2;
+    }
+    writeArtifactUploadStatus(stdout, options, result.data.artifact);
+    return 0;
+}
+export async function runBridgeWrapperInit(options) {
+    const stdout = options.stdout ?? process.stdout;
+    const template = wrapperTemplateName(options.type);
+    const out = options.out ?? `.hypertab/${template}`;
+    if (!options.force && (await fileExists(out))) {
+        writeFailure(options, 'BRIDGE_WRAPPER_EXISTS', `Bridge wrapper '${out}' already exists.`, 'Pass --force to overwrite it, or choose a different --out path.');
+        return 2;
+    }
+    const body = await readFile(new URL(`../../templates/${template}`, import.meta.url), 'utf8');
+    await mkdir(dirname(out), { recursive: true });
+    await writeFile(out, body, { mode: options.type === 'shell' ? 0o755 : 0o644 });
+    const data = { path: out, type: options.type, template };
+    if (options.json) {
+        stdout.write(`${JSON.stringify({ success: true, data })}\n`);
+        return 0;
+    }
+    stdout.write(`Created ${options.type} bridge wrapper at ${out}.\n`);
+    return 0;
+}
+export async function runBridgeWrapperDoctor(options) {
+    const stdout = options.stdout ?? process.stdout;
+    const wrapperPath = options.path ?? '.hypertab/bridge-wrapper.mjs';
+    const checks = [];
+    const wrapperType = inferWrapperType(wrapperPath);
+    let body = null;
+    try {
+        const info = await stat(wrapperPath);
+        if (info.isFile()) {
+            checks.push({ id: 'wrapper_file', status: 'pass', message: `Wrapper file exists at ${wrapperPath}.` });
+            if (wrapperType === 'shell' && (info.mode & 0o111) === 0) {
+                checks.push({
+                    id: 'wrapper_executable',
+                    status: 'warn',
+                    message: 'Shell wrapper is not executable. Run chmod +x or invoke it with sh.',
+                });
+            }
+            body = await readFile(wrapperPath, 'utf8');
+        }
+        else {
+            checks.push({ id: 'wrapper_file', status: 'fail', message: `${wrapperPath} exists but is not a file.` });
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error && 'code' in error && error.code === 'ENOENT'
+            ? `Wrapper file is missing at ${wrapperPath}. Run hypertab bridge wrapper init first.`
+            : `Could not inspect wrapper file at ${wrapperPath}.`;
+        checks.push({ id: 'wrapper_file', status: 'fail', message });
+    }
+    const apiKey = resolveBridgeApiKey({ apiKey: options.apiKey, env: options.env });
+    checks.push(apiKey
+        ? { id: 'api_key', status: 'pass', message: 'HYPERTAB_API_KEY or --api-key is available.' }
+        : {
+            id: 'api_key',
+            status: 'fail',
+            message: 'Provide a Hypertab API key with HYPERTAB_API_KEY or --api-key before running the wrapper.',
+        });
+    if (body) {
+        addStarterMarkerCheck(checks, body, 'bridge_start', 'bridge start');
+        addStarterMarkerCheck(checks, body, 'event_batch', 'bridge event batch');
+        addStarterMarkerCheck(checks, body, 'command_result', 'bridge result');
+        addStarterMarkerCheck(checks, body, 'command_contract', 'contract.allowed');
+    }
+    try {
+        const records = await readBridgeSpool(options.spoolFile);
+        checks.push(records.length === 0
+            ? { id: 'spool', status: 'pass', message: `No pending bridge spool records in ${options.spoolFile}.` }
+            : {
+                id: 'spool',
+                status: 'warn',
+                message: `${records.length} pending bridge spool records are waiting to flush.`,
+                details: { file: options.spoolFile, records: records.length },
+            });
+    }
+    catch {
+        checks.push({
+            id: 'spool',
+            status: 'warn',
+            message: `Could not read bridge spool file at ${options.spoolFile}. The wrapper can recreate it when needed.`,
+        });
+    }
+    const report = {
+        path: wrapperPath,
+        type: wrapperType,
+        ready: !checks.some((check) => check.status === 'fail'),
+        spool_file: options.spoolFile,
+        checks,
+    };
+    writeBridgeWrapperDoctorStatus(stdout, options, report);
+    return report.ready ? 0 : 2;
+}
+async function initializeBridge(client, options) {
+    const heartbeat = await sendHeartbeat(client, options);
+    if (!heartbeat.ok)
+        return heartbeat;
+    const context = { client: heartbeat.data.client };
+    if (options.session || options.objective) {
+        const session = await client.startSession({
+            client_id: context.client.id,
+            metadata: { source: 'hypertab_bridge_cli' },
+        });
+        if (!session.ok)
+            return { ok: false, code: session.error.code, message: session.error.message, details: session.error.details };
+        context.session = session.data.session;
+    }
+    if (options.objective) {
+        const run = await client.createRun({
+            title: options.runTitle ?? defaultRunTitle(options.objective),
+            objective: options.objective,
+            client_id: context.client.id,
+            session_id: context.session?.id ?? null,
+            source: options.source,
+            metadata: { source: 'hypertab_bridge_cli' },
+        });
+        if (!run.ok)
+            return { ok: false, code: run.error.code, message: run.error.message, details: run.error.details };
+        context.run = run.data.run;
+        const eventPayload = {
+            events: [
+                {
+                    run_id: context.run.id,
+                    type: 'status',
+                    message: 'Local bridge connected.',
+                    data: { client_id: context.client.id, session_id: context.session?.id ?? null },
+                    idempotency_key: `bridge-start:${context.run.id}`,
+                },
+            ],
+        };
+        const event = await client.appendEventBatch(eventPayload);
+        if (!event.ok) {
+            if (options.spool && shouldSpoolBridgeFailure(event.status)) {
+                await enqueueEventBatch(options.spoolFile, eventPayload);
+                writeSpoolQueued(options.stdout ?? process.stdout, options, 'event_batch', options.spoolFile);
+                return { ok: true, data: context };
+            }
+            return { ok: false, code: event.error.code, message: event.error.message, details: event.error.details };
+        }
+    }
+    return { ok: true, data: context };
+}
+async function sendHeartbeat(client, options) {
+    const heartbeat = await client.heartbeat({
+        name: options.clientName ?? hostname(),
+        type: options.clientType,
+        metadata: {
+            source: 'hypertab_bridge_cli',
+            pid: process.pid,
+            cwd: process.cwd(),
+        },
+    });
+    if (!heartbeat.ok)
+        return { ok: false, code: heartbeat.error.code, message: heartbeat.error.message, details: heartbeat.error.details };
+    if (!heartbeat.data.client.id) {
+        return {
+            ok: false,
+            code: 'BRIDGE_CLIENT_ID_MISSING',
+            message: 'Heartbeat succeeded but the API did not return a client id.',
+        };
+    }
+    return heartbeat;
+}
+function writeBridgeStatus(stdout, options, context) {
+    if (options.json) {
+        stdout.write(`${JSON.stringify({ type: 'bridge_status', status: 'connected', ...context })}\n`);
+        return;
+    }
+    stdout.write(`Hypertab bridge connected as ${context.client.name ?? context.client.id} (${context.client.id}).\n`);
+    if (context.session)
+        stdout.write(`Session: ${context.session.id}\n`);
+    if (context.run)
+        stdout.write(`Run: ${context.run.id}\n`);
+}
+function writeCommand(stdout, options, command) {
+    const contract = classifyBridgeCommandContract(command);
+    if (options.json) {
+        stdout.write(`${JSON.stringify({ type: 'bridge_command', command, contract })}\n`);
+        return;
+    }
+    const suffix = contract.allowed ? 'allowed' : `rejected: ${contract.message ?? contract.reason ?? 'not allowed'}`;
+    stdout.write(`Command ${command.id}: ${command.command_type} (${suffix})\n`);
+}
+function writeSpoolQueued(stdout, options, type, file) {
+    if (options.json) {
+        stdout.write(`${JSON.stringify({ type: 'bridge_spool_queued', record_type: type, file })}\n`);
+        return;
+    }
+    stdout.write(`Queued ${type} in local bridge spool: ${file}\n`);
+}
+function writeSpoolFlushStatus(stdout, options, result) {
+    if (result.flushed === 0 && result.remaining === 0 && result.failed === 0)
+        return;
+    if (options.json) {
+        stdout.write(`${JSON.stringify({ type: 'bridge_spool_flush', ...result })}\n`);
+        return;
+    }
+    stdout.write(`Bridge spool: ${result.flushed} flushed, ${result.remaining} remaining.\n`);
+}
+function writeArtifactUploadStatus(stdout, options, artifact) {
+    if (options.json) {
+        stdout.write(`${JSON.stringify({ success: true, data: { artifact } })}\n`);
+        return;
+    }
+    stdout.write(`Uploaded artifact ${artifact.id}: ${artifact.name ?? 'artifact'}\n`);
+}
+function writeBridgeHealthStatus(stdout, options, health) {
+    if (options.json) {
+        stdout.write(`${JSON.stringify({ success: true, data: { bridge_health: health } })}\n`);
+        return;
+    }
+    const summary = health.summary ?? {};
+    const line = [
+        `Bridge health: ${numberValue(summary.online)} online`,
+        `${numberValue(summary.needs_attention)} attention`,
+        `${numberValue(summary.queued_commands)} queued`,
+        `${numberValue(summary.delivered_commands)} in flight`,
+        `${numberValue(summary.unsafe_commands)} unsafe`,
+    ];
+    stdout.write(`${line.join(', ')}.\n`);
+    for (const item of Array.isArray(health.clients) ? health.clients.slice(0, 10) : []) {
+        const client = objectValue(item.client);
+        const freshness = objectValue(item.freshness);
+        const name = stringValue(client.name) ?? stringValue(client.id) ?? 'unknown-client';
+        const status = stringValue(freshness.status) ?? 'unknown';
+        const age = freshness.age_seconds === null ? 'never' : `${numberValue(freshness.age_seconds)}s ago`;
+        const runs = numberValue(item.active_run_count);
+        const commands = numberValue(item.queued_command_count) + numberValue(item.delivered_command_count);
+        stdout.write(`- ${name}: ${status}, seen ${age}, runs ${runs}, commands ${commands}\n`);
+        const reasons = Array.isArray(item.attention_reasons) ? item.attention_reasons.filter((reason) => typeof reason === 'string') : [];
+        if (reasons.length > 0)
+            stdout.write(`  attention: ${reasons.map((reason) => reason.replace(/_/g, ' ')).join(', ')}\n`);
+    }
+}
+function writeBridgeTokenCreateStatus(stdout, options, data) {
+    const commands = bridgeTokenFollowUpCommands(data.token, data.client, options);
+    if (options.json) {
+        stdout.write(`${JSON.stringify({ success: true, data: { ...data, commands } })}\n`);
+        return;
+    }
+    const clientName = stringValue(data.client.name) ?? options.clientName;
+    const clientId = stringValue(data.client.id) ?? 'unknown-client';
+    stdout.write(`Created bridge-client token ${data.token.key_prefix}... for ${clientName} (${clientId}).\n`);
+    stdout.write('This token is shown once. Store it securely and use it only for this local wrapper client.\n');
+    stdout.write(`Token: ${data.token.api_key}\n`);
+    stdout.write(`Expires: ${data.token.expires_at}\n`);
+    stdout.write('Next:\n');
+    stdout.write(`  ${commands.doctor}\n`);
+    stdout.write(`  ${commands.run}\n`);
+}
+function writeEventBatchStatus(stdout, options, result) {
+    if (options.json) {
+        stdout.write(`${JSON.stringify({ success: true, data: result })}\n`);
+        return;
+    }
+    stdout.write(`Bridge events accepted: ${result.accepted}, deduped: ${result.deduped}.\n`);
+}
+function writeBridgeWrapperDoctorStatus(stdout, options, report) {
+    if (options.json) {
+        stdout.write(`${JSON.stringify({ success: report.ready, data: report })}\n`);
+        return;
+    }
+    stdout.write(`Bridge wrapper doctor: ${report.ready ? 'ready' : 'needs attention'}.\n`);
+    for (const check of report.checks) {
+        stdout.write(`- ${check.status}: ${check.message}\n`);
+    }
+}
+function writeFailure(options, code, message, details) {
+    if (options.json) {
+        const writer = options.stdout ?? process.stdout;
+        writer.write(`${JSON.stringify({ success: false, error: { code, message, details } })}\n`);
+        return;
+    }
+    const writer = options.stderr ?? process.stderr;
+    writer.write(`Error: ${message}\nCode: ${code}\n`);
+}
+function bridgeTokenFollowUpCommands(token, client, options) {
+    const clientName = stringValue(client.name) ?? options.clientName;
+    const clientType = stringValue(client.type) ?? options.clientType;
+    return {
+        doctor: `HYPERTAB_API_KEY=${shellQuote(token.api_key)} npx @hypertabai/mcp bridge wrapper doctor --path .hypertab/bridge-wrapper.mjs --json`,
+        run: [
+            `HYPERTAB_API_KEY=${shellQuote(token.api_key)}`,
+            `HYPERTAB_BRIDGE_CLIENT_NAME=${shellQuote(clientName)}`,
+            `HYPERTAB_BRIDGE_CLIENT_TYPE=${shellQuote(clientType)}`,
+            'node .hypertab/bridge-wrapper.mjs "Report local bridge health"',
+        ].join(' '),
+    };
+}
+function objectValue(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+function stringValue(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function numberValue(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+function optionalTrimmedString(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, "'\\''")}'`;
+}
+function formatByteSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+async function readBridgeEventBatchFile(file) {
+    const raw = JSON.parse(await readFile(file, 'utf8'));
+    const events = Array.isArray(raw) ? raw : objectValue(raw).events;
+    if (!Array.isArray(events))
+        throw new Error('Bridge event batch file must contain an events array.');
+    if (events.length === 0 || events.length > 250)
+        throw new Error('Bridge event batch must contain 1 to 250 events.');
+    return {
+        events: events.map((event, index) => normalizeBridgeEvent(event, index)),
+    };
+}
+function normalizeBridgeEvent(event, index) {
+    const input = objectValue(event);
+    const runId = stringValue(input.run_id);
+    const type = stringValue(input.type);
+    const message = stringValue(input.message);
+    if (!runId)
+        throw new Error(`Event ${index + 1} is missing run_id.`);
+    if (!type || !isBridgeEventType(type))
+        throw new Error(`Event ${index + 1} has an invalid type.`);
+    if (!message)
+        throw new Error(`Event ${index + 1} is missing message.`);
+    const data = objectValue(input.data);
+    const idempotencyKey = stringValue(input.idempotency_key);
+    return {
+        run_id: runId,
+        type,
+        message,
+        data: Object.keys(data).length > 0 ? data : undefined,
+        idempotency_key: idempotencyKey ?? undefined,
+    };
+}
+function isBridgeEventType(value) {
+    return ['message', 'step', 'tool_call', 'file_change', 'artifact', 'approval', 'error', 'status'].includes(value);
+}
+function normalizeBridgeClientType(value) {
+    if (BRIDGE_CLIENT_TYPES.includes(value))
+        return value;
+    throw new Error(`Invalid bridge client type '${value}'. Use one of: ${BRIDGE_CLIENT_TYPES.join(', ')}.`);
+}
+function normalizeCommandResultStatus(value) {
+    if (value === 'completed' || value === 'failed' || value === 'cancelled')
+        return value;
+    throw new Error(`Invalid command result status '${value}'. Use completed, failed, or cancelled.`);
+}
+function normalizeWrapperType(value) {
+    if (value === 'node' || value === 'shell')
+        return value;
+    throw new Error(`Invalid wrapper type '${value}'. Use node or shell.`);
+}
+function inferWrapperType(path) {
+    if (path.endsWith('.sh'))
+        return 'shell';
+    if (path.endsWith('.mjs') || path.endsWith('.js'))
+        return 'node';
+    return 'unknown';
+}
+function wrapperTemplateName(type) {
+    return type === 'shell' ? 'bridge-wrapper.sh' : 'bridge-wrapper.mjs';
+}
+function addStarterMarkerCheck(checks, body, id, marker) {
+    checks.push(body.includes(marker)
+        ? { id, status: 'pass', message: `Wrapper references ${marker}.` }
+        : {
+            id,
+            status: 'warn',
+            message: `Wrapper does not reference ${marker}; custom wrappers should provide equivalent behavior.`,
+        });
+}
+async function fileExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parsePositiveInt(value) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0)
+        throw new Error(`Expected a positive integer, received '${value}'.`);
+    return parsed;
+}
+function defaultRunTitle(objective) {
+    const trimmed = objective.trim();
+    return trimmed.length > 120 ? `${trimmed.slice(0, 117)}...` : trimmed;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=index.js.map