cloudcruise 1.0.0 → 1.1.0

package/dist/runs/RunsClient.js

@@ -0,0 +1,400 @@
+import { EventType } from '../events/types.js';
+import { AsyncEventQueue } from '../utils/asyncQueue.js';
+import { SimpleEventEmitter } from '../utils/events.js';
+/**
+ * Default error reporter for the recovery helpers. Writes to console.error
+ * so submission failures surface in customer logs even if no onError
+ * callback is provided. The runtime SimpleEventEmitter ignores async-handler
+ * returns, so without this default a rejection from /new_input_variables
+ * would become a silent unhandled rejection.
+ */
+function defaultRecoverySubmitErrorLog(operation) {
+    return (err) => {
+        try {
+            const msg = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+            console.error(`[CloudCruise SDK] ${operation} failed during recovery: ${msg}`);
+        }
+        catch {
+            // never throw from the error reporter
+        }
+    };
+}
+/**
+ * Helper for `verbose: true` mode on the recovery helpers. Writes a single
+ * line to console.error so customers can watch the recovery loop without
+ * instrumenting their own decider.
+ */
+function verboseLog(operation, message) {
+    try {
+        console.error(`[CloudCruise SDK verbose] ${operation}: ${message}`);
+    }
+    catch {
+        // never throw
+    }
+}
+export class RunsClient {
+    makeRequest;
+    workflows;
+    connectionManager;
+    constructor(connectionManager, makeRequest, workflows) {
+        this.makeRequest = makeRequest;
+        this.workflows = workflows;
+        this.connectionManager = connectionManager;
+    }
+    /**
+     * Queues a new run and returns a RunHandle.
+     * The handle exposes sessionId immediately and subscribes to SSE under the hood.
+     */
+    async start(request, options) {
+        if (this.workflows) {
+            await this.workflows.validateWorkflowInput(request.workflow_id, request.run_input_variables);
+        }
+        // Ensure client_id and connection are ready to avoid missing early events
+        const clientId = await this.connectionManager.ensureClientId();
+        await this.connectionManager.connectIfNeeded();
+        request.client_id = clientId;
+        const { session_id } = await this.makeRequest('POST', '/run', request);
+        return this.subscribeToSession(session_id, options);
+    }
+    /**
+     * Subscribes to SSE events for a given session. Returns a handle with helpers.
+     */
+    subscribeToSession(sessionId, options) {
+        const emitter = new SimpleEventEmitter();
+        const stream = new AsyncEventQueue();
+        let ended = false;
+        let closed = false;
+        let sub = null;
+        const reconnectCfg = {
+            enabled: options?.reconnect?.enabled ?? true,
+            delays: options?.reconnect?.delays ?? [1000, 3000, 10000],
+        };
+        const isTerminalEvent = (status) => status === EventType.ExecutionSuccess ||
+            status === EventType.ExecutionFailed ||
+            status === EventType.ExecutionStopped;
+        const emit = (event, payload) => {
+            emitter.emit(event, payload);
+            // Mirror only SSE messages to 'message' for catch-all consumers
+            if (event === 'run.event' || event === 'ping') {
+                emitter.emit('message', payload);
+            }
+        };
+        const endAndCleanup = (status) => {
+            if (ended)
+                return;
+            ended = true;
+            closed = true;
+            try {
+                sub?.close();
+            }
+            catch { }
+            emit('end', { type: status });
+            stream.close();
+            emitter.clear();
+        };
+        const connect = () => {
+            sub = this.connectionManager.subscribe(sessionId, { signal: options?.signal });
+            const s = sub;
+            s.on('open', () => emit('open', undefined));
+            s.on('ping', (evt) => emit('ping', evt));
+            s.on('run.event', (msg) => {
+                const sseMsg = msg;
+                if (sseMsg.event !== 'run.event')
+                    return;
+                stream.push(sseMsg);
+                emit('run.event', sseMsg);
+                // Emit typed per-event key for better DX
+                try {
+                    emitter.emit(sseMsg.data.event, sseMsg);
+                }
+                catch { }
+                const eventType = sseMsg.data.event;
+                if (typeof eventType === 'string' && isTerminalEvent(eventType)) {
+                    endAndCleanup(eventType);
+                }
+            });
+            s.on('error', (err) => {
+                emit('error', err);
+                if (!reconnectCfg.enabled || ended || closed)
+                    return;
+                (async () => {
+                    for (const base of reconnectCfg.delays) {
+                        if (ended || closed)
+                            return;
+                        await new Promise(r => setTimeout(r, base));
+                        if (ended || closed)
+                            return;
+                        try {
+                            const snapshot = await this.getResults(sessionId);
+                            const status = snapshot?.status;
+                            if (isTerminalEvent(status)) {
+                                endAndCleanup(status);
+                                return;
+                            }
+                        }
+                        catch { }
+                        emit('reconnect', { attemptDelayMs: base });
+                        return; // manager handles reconnect of mux
+                    }
+                })();
+            });
+            s.on('reconnect', (e) => emit('reconnect', e));
+            s.on('end', (e) => {
+                const t = e?.type;
+                if (t && typeof t === 'string' && isTerminalEvent(t)) {
+                    endAndCleanup(t);
+                }
+                else {
+                    // End without explicit type; still clean up
+                    endAndCleanup(EventType.ExecutionStopped);
+                }
+            });
+        };
+        connect();
+        const client = this;
+        const handle = {
+            sessionId,
+            on: (event, handler) => emitter.on(event, handler),
+            async wait() {
+                if (ended) {
+                    return await client.getResults(sessionId);
+                }
+                return await new Promise((resolve, reject) => {
+                    const offEnd = handle.on('end', async () => {
+                        offErr();
+                        try {
+                            const result = await client.getResults(sessionId);
+                            resolve(result);
+                        }
+                        catch (e) {
+                            reject(e);
+                        }
+                    });
+                    const offErr = handle.on('error', (e) => {
+                        offEnd();
+                        reject(e instanceof Error ? e : new Error('SSE error'));
+                    });
+                });
+            },
+            close() {
+                closed = true;
+                try {
+                    sub?.close();
+                }
+                catch { }
+                stream.close();
+                emitter.clear();
+            },
+            async *[Symbol.asyncIterator]() {
+                for await (const msg of stream) {
+                    yield msg;
+                }
+            },
+        };
+        return handle;
+    }
+    /**
+     * Submits user interaction data during an active run
+     * @param sessionId - The unique identifier for the workflow execution session
+     * @param data - User input data as key-value pairs
+     */
+    async submitUserInteraction(sessionId, data) {
+        const path = `/run/${sessionId}/user_interaction`;
+        await this.makeRequest('POST', path, data);
+    }
+    /**
+     * Responds to an execution.input_required event whose reason is
+     * "non_dismissible_popup" by picking one of the CTA buttons surfaced in
+     * popup_context.available_actions. The backend dispatches a synthetic
+     * click on the chosen button and resumes the workflow.
+     *
+     * Only valid while the session is waiting for input. The backing endpoint
+     * returns 400 if the wait already expired (the workspace setting
+     * input_required_timeout_seconds, default 15s, max 300s).
+     *
+     * @param sessionId - The session waiting for input.
+     * @param actionId - One of the ids in popup_context.available_actions.
+     */
+    async submitModalAction(sessionId, actionId) {
+        const path = `/run/${sessionId}/new_input_variables`;
+        await this.makeRequest('POST', path, { modal_action: actionId });
+    }
+    /**
+     * Responds to an execution.input_required event whose reason is
+     * "input_required", "incorrect_form_input", or "multiple_matching_results"
+     * by supplying the corrected/required input variables. Backend resumes from
+     * the appropriate recovery node with the new values substituted in.
+     *
+     * Mutually exclusive with submitModalAction at the endpoint level.
+     *
+     * @param sessionId - The session waiting for input.
+     * @param inputVariables - Mapping of variable name to new value.
+     */
+    async submitInputVariables(sessionId, inputVariables) {
+        const path = `/run/${sessionId}/new_input_variables`;
+        await this.makeRequest('POST', path, { input_variables: inputVariables });
+    }
+    /**
+     * Registers a listener that auto-responds ONLY to non-dismissible modal
+     * input_required events (reason === "non_dismissible_popup"). The decider
+     * receives the popup_context and must return one of the action ids in
+     * popup_context.available_actions.
+     *
+     * The SDK never picks an action on its own. The customer's decider IS the
+     * decision point. If decider throws, the listener swallows it and skips
+     * submission; the backend's input wait will time out naturally.
+     *
+     * Other input_required reasons (incorrect_form_input, etc.) are ignored
+     * here and should be routed to onInputVariablesRequired.
+     *
+     * @returns An unsubscribe callable.
+     */
+    onPopupDecisionRequired(handle, decider, onError, options) {
+        const verbose = options?.verbose === true;
+        const reportError = (err) => {
+            const reporter = onError ?? defaultRecoverySubmitErrorLog('submitModalAction');
+            try {
+                reporter(err);
+            }
+            catch {
+                // defense: a buggy onError must not crash the event loop
+            }
+        };
+        if (verbose)
+            verboseLog('onPopupDecisionRequired', 'listener registered');
+        const listener = async (event) => {
+            const payload = (event?.data?.payload ?? event?.payload);
+            if (!payload || payload.reason !== 'non_dismissible_popup' || !payload.popup_context) {
+                if (verbose) {
+                    verboseLog('onPopupDecisionRequired', `skipping reason=${payload?.reason ?? 'undefined'}`);
+                }
+                return;
+            }
+            if (verbose) {
+                const attempt = payload.popup_context.retry?.attempt;
+                const actions = payload.popup_context.available_actions?.map((a) => a.id) ?? [];
+                verboseLog('onPopupDecisionRequired', `event received attempt=${attempt} actions=${JSON.stringify(actions)}`);
+            }
+            let actionId;
+            try {
+                actionId = await decider(payload.popup_context);
+            }
+            catch (e) {
+                if (verbose)
+                    verboseLog('onPopupDecisionRequired', `decider raised: ${e}`);
+                return;
+            }
+            if (typeof actionId !== 'string' || actionId.length === 0) {
+                if (verbose)
+                    verboseLog('onPopupDecisionRequired', `decider returned non-string/empty (${JSON.stringify(actionId)}); skipping`);
+                return;
+            }
+            const sid = payload.session_id || handle.sessionId;
+            if (verbose)
+                verboseLog('onPopupDecisionRequired', `submitting modal_action=${JSON.stringify(actionId)} for session=${sid}`);
+            try {
+                await this.submitModalAction(sid, actionId);
+                if (verbose)
+                    verboseLog('onPopupDecisionRequired', `submit ok for action=${JSON.stringify(actionId)}`);
+            }
+            catch (err) {
+                reportError(err);
+            }
+        };
+        const unsubscribe = handle.on(EventType.ExecutionInputRequired, listener);
+        return typeof unsubscribe === 'function' ? unsubscribe : () => { };
+    }
+    /**
+     * Registers a listener that auto-responds ONLY to workflow-variable
+     * input_required events (reason in {"input_required",
+     * "incorrect_form_input", "multiple_matching_results"}). The decider
+     * receives the full payload and must return the input_variables dict.
+     *
+     * Counterpart to onPopupDecisionRequired. Modal events
+     * (reason === "non_dismissible_popup") are routed there and ignored here.
+     *
+     * @returns An unsubscribe callable.
+     */
+    onInputVariablesRequired(handle, decider, onError, options) {
+        const verbose = options?.verbose === true;
+        const VARIABLE_REASONS = new Set([
+            'input_required',
+            'incorrect_form_input',
+            'multiple_matching_results',
+        ]);
+        const reportError = (err) => {
+            const reporter = onError ?? defaultRecoverySubmitErrorLog('submitInputVariables');
+            try {
+                reporter(err);
+            }
+            catch {
+                // defense
+            }
+        };
+        if (verbose)
+            verboseLog('onInputVariablesRequired', 'listener registered');
+        const listener = async (event) => {
+            const payload = (event?.data?.payload ?? event?.payload);
+            if (!payload || !payload.reason || !VARIABLE_REASONS.has(payload.reason)) {
+                if (verbose)
+                    verboseLog('onInputVariablesRequired', `skipping reason=${payload?.reason ?? 'undefined'}`);
+                return;
+            }
+            if (verbose)
+                verboseLog('onInputVariablesRequired', `event received reason=${payload.reason}`);
+            let inputVars;
+            try {
+                inputVars = await decider(payload);
+            }
+            catch (e) {
+                if (verbose)
+                    verboseLog('onInputVariablesRequired', `decider raised: ${e}`);
+                return;
+            }
+            if (!inputVars || typeof inputVars !== 'object' || Array.isArray(inputVars)) {
+                if (verbose)
+                    verboseLog('onInputVariablesRequired', `decider returned non-object (${Array.isArray(inputVars) ? 'array' : typeof inputVars}); skipping`);
+                return;
+            }
+            const sid = payload.session_id || handle.sessionId;
+            if (verbose)
+                verboseLog('onInputVariablesRequired', `submitting input_variables keys=${JSON.stringify(Object.keys(inputVars))} for session=${sid}`);
+            try {
+                await this.submitInputVariables(sid, inputVars);
+                if (verbose)
+                    verboseLog('onInputVariablesRequired', 'submit ok');
+            }
+            catch (err) {
+                reportError(err);
+            }
+        };
+        const unsubscribe = handle.on(EventType.ExecutionInputRequired, listener);
+        return typeof unsubscribe === 'function' ? unsubscribe : () => { };
+    }
+    /**
+     * Retrieves comprehensive results and execution details for a specific run
+     * @param sessionId - The unique identifier for the workflow execution session
+     * @returns Promise resolving to complete run results
+     */
+    async getResults(sessionId) {
+        const path = `/run/${sessionId}`;
+        return await this.makeRequest('GET', path);
+    }
+    /**
+     * Interrupts a running browser agent run
+     * @param sessionId - The unique identifier for the workflow execution session
+     */
+    async interrupt(sessionId) {
+        const path = `/run/${sessionId}/interrupt`;
+        await this.makeRequest('POST', path);
+    }
+    /**
+     * Replays all webhooks that were sent during a session
+     * @param sessionId - The ID of the session to replay webhooks for
+     * @returns Promise resolving to webhook replay results
+     */
+    async replayWebhooks(sessionId) {
+        const path = `/webhooks/${sessionId}/replay`;
+        return await this.makeRequest('POST', path);
+    }
+}

package/dist/runs/types.d.ts

@@ -0,0 +1,157 @@
+/**
+ * CloudCruise Runs API Type Definitions
+ */
+import type { EventType, RunEventMessage, EventPayloadMap, ExecutionQueuedPayload, ExecutionStartPayload, ExecutionStepPayload, InteractionWaitingPayload, InteractionFinishedPayload, AgentErrorAnalysisPayload, ExecutionRequeuedPayload, EndRunPayload, EndRunError, ExecutionStoppedEarlyPayload, FileUploadedPayload, ScreenshotUploadedPayload } from '../events/types.js';
+export type { EventType };
+export type { ExecutionQueuedPayload, ExecutionStartPayload, ExecutionStepPayload, InteractionWaitingPayload, InteractionFinishedPayload, AgentErrorAnalysisPayload, ExecutionRequeuedPayload, EndRunPayload, EndRunError, ExecutionStoppedEarlyPayload, FileUploadedPayload, ScreenshotUploadedPayload, EventPayloadMap, };
+export interface DryRun {
+    enabled: boolean;
+    add_to_output?: Record<string, any>;
+}
+export interface Metadata {
+    metadata: Record<string, any>;
+}
+export interface RunSpecificWebhook {
+    url: string;
+    event_types_subscribed: EventType[];
+    secret: string;
+    validity: number;
+}
+export type PayloadWebhook = Metadata | RunSpecificWebhook;
+export interface StartRunRequest {
+    workflow_id: string;
+    run_input_variables: Record<string, any>;
+    dry_run?: DryRun;
+    webhook?: PayloadWebhook;
+    additional_context?: Record<string, any>;
+    client_id?: string;
+}
+export interface StartRunResponse {
+    session_id: string;
+}
+export type UserInteractionData = Record<string, any>;
+export interface VideoUrl {
+    timestamp: string;
+    session_id: string;
+    signed_screen_recording_url: string;
+    signed_screen_recording_url_expires: string;
+}
+export interface RunError {
+    prompt?: string | null;
+    message?: string | null;
+    error_id?: string | null;
+    full_url?: string | null;
+    llm_model?: string | null;
+    created_at?: string | null;
+    error_code?: string | null;
+    action_type?: string | null;
+    action_display_name?: string | null;
+}
+export interface SignedFileUrl {
+    signed_file_url: string;
+    file_name: string;
+    timestamp: string;
+    signed_file_url_expires: string;
+    metadata: Record<string, any>;
+}
+export interface SignedScreenshotUrl {
+    signed_screenshot_url: string;
+    node_display_name: string;
+    timestamp: string;
+    signed_screenshot_url_expires: string;
+    error_screenshot: boolean;
+    full_length_screenshot?: boolean;
+    retry_index?: number;
+}
+export interface WorkflowError {
+    message: string;
+    error_id: string;
+    full_url?: string | null;
+    created_at?: string | null;
+    error_code?: string | null;
+    action_type?: string | null;
+    action_display_name?: string | null;
+    llm_error_category?: string | null;
+    original_error?: string | null;
+}
+export interface RunResult {
+    session_id: string;
+    status: EventType;
+    input_variables: Record<string, any>;
+    data: Record<string, any>;
+    video_urls: VideoUrl[];
+    file_urls: SignedFileUrl[];
+    screenshot_urls: SignedScreenshotUrl[];
+    errors: RunError[] | null;
+}
+export interface GetRunResult {
+    data: Record<string, any> | null;
+    session_id: string;
+    errors: WorkflowError[];
+    status: EventType;
+    input_variables: Record<string, any>;
+    workflow_id: string | null;
+    session_retries: number | null;
+    encrypted_variables: string[] | null;
+    video_urls: VideoUrl[] | null;
+    screenshot_urls?: SignedScreenshotUrl[] | null;
+    file_urls: SignedFileUrl[] | null;
+}
+export interface WebhookEvent {
+    success: boolean;
+    response: string;
+    error: string;
+}
+export interface WebhookReplayResponse {
+    status: string;
+    info: string;
+    nr_success: number;
+    nr_failed: number;
+    webhook_events: WebhookEvent[];
+}
+/**
+ * Streaming (SSE) types
+ */
+export type SseEventName = 'run.event' | 'ping';
+export type RunEventEnvelope<E extends EventType = EventType> = RunEventMessage<E>;
+export interface PingEnvelope {
+    event: 'ping';
+    data: {
+        ts: number;
+    } | Record<string, any>;
+}
+export type SseMessage<E extends EventType = EventType> = RunEventEnvelope<E> | PingEnvelope;
+export interface RunStreamOptions {
+    signal?: AbortSignal;
+    withCredentials?: boolean;
+    headers?: Record<string, string>;
+    reconnect?: {
+        enabled?: boolean;
+        delays?: number[];
+        jitter?: number;
+    };
+}
+export type RunEventMap = {
+    [K in EventType]: RunEventEnvelope<K>;
+};
+export type RunHandleEventMap = {
+    'open': undefined;
+    'close': undefined;
+    'reconnect': {
+        attemptDelayMs: number;
+    };
+    'error': unknown;
+    'end': {
+        type: EventType;
+    };
+    'run.event': SseMessage;
+    'ping': PingEnvelope;
+    'message': SseMessage | PingEnvelope;
+} & RunEventMap;
+export interface RunHandle {
+    sessionId: string;
+    on<K extends keyof RunHandleEventMap>(event: K, handler: (e: RunHandleEventMap[K]) => void): () => void;
+    wait(): Promise<GetRunResult>;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<SseMessage>;
+}

package/dist/runs/types.js

@@ -0,0 +1,4 @@
+/**
+ * CloudCruise Runs API Type Definitions
+ */
+export {};

package/dist/utils/asyncQueue.d.ts

@@ -0,0 +1,9 @@
+export declare class AsyncEventQueue<T> implements AsyncIterable<T> {
+    private items;
+    private pending;
+    private done;
+    push(item: T): void;
+    close(): void;
+    next(): Promise<IteratorResult<T>>;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}

package/dist/utils/asyncQueue.js

@@ -0,0 +1,43 @@
+export class AsyncEventQueue {
+    items = [];
+    pending = null;
+    done = false;
+    push(item) {
+        if (this.done)
+            return;
+        if (this.pending) {
+            const resolve = this.pending;
+            this.pending = null;
+            resolve({ value: item, done: false });
+        }
+        else {
+            this.items.push(item);
+        }
+    }
+    close() {
+        if (this.done)
+            return;
+        this.done = true;
+        if (this.pending) {
+            const resolve = this.pending;
+            this.pending = null;
+            resolve({ value: undefined, done: true });
+        }
+    }
+    async next() {
+        if (this.items.length) {
+            return { value: this.items.shift(), done: false };
+        }
+        if (this.done) {
+            return { value: undefined, done: true };
+        }
+        return await new Promise(resolve => {
+            this.pending = resolve;
+        });
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => this.next(),
+        };
+    }
+}

package/dist/utils/connectionManager.d.ts

@@ -0,0 +1,29 @@
+import type { SseMessage } from '../runs/types.js';
+type Listener = (e: unknown) => void;
+interface SubscribeOptions {
+    signal?: AbortSignal;
+}
+export interface SessionSubscription {
+    on(event: string, handler: Listener): () => void;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<SseMessage>;
+}
+export declare class ConnectionManager {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private clientId;
+    private conn;
+    private connecting;
+    private connected;
+    private reconnecting;
+    private readonly reconnectDelays;
+    private readonly sessions;
+    constructor(baseUrl: string, apiKey: string);
+    ensureClientId(): Promise<string>;
+    private generateClientId;
+    connectIfNeeded(): Promise<void>;
+    subscribe(sessionId: string, opts?: SubscribeOptions): SessionSubscription;
+    private openMuxConnection;
+    private scheduleReconnect;
+}
+export {};