@tangle-network/browser-agent-driver 0.6.0

package/dist/providers/sandbox-backend.d.ts

@@ -0,0 +1,22 @@
+import type { ModelMessage } from 'ai';
+export interface SandboxBackendPromptOptions {
+    sidecarUrl?: string;
+    authToken?: string;
+    backendType?: string;
+    /** Named sandbox profile/preset identifier */
+    backendProfile?: string;
+    /** @deprecated Legacy alias for backendProfile */
+    backendProfileId?: string;
+    backendModelProvider?: string;
+    model: string;
+    system?: string;
+    messages: ModelMessage[];
+    timeoutMs?: number;
+    debug?: boolean;
+}
+export interface SandboxBackendPromptResult {
+    text: string;
+    warnings: string[];
+}
+export declare function generateWithSandboxBackend(options: SandboxBackendPromptOptions): Promise<SandboxBackendPromptResult>;
+//# sourceMappingURL=sandbox-backend.d.ts.map

package/dist/providers/sandbox-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-backend.d.ts","sourceRoot":"","sources":["../../src/providers/sandbox-backend.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAiCvC,MAAM,WAAW,2BAA2B;IAC1C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAqND,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CA6ErC"}

package/dist/providers/sandbox-backend.js

@@ -0,0 +1,259 @@
+import { randomUUID } from 'node:crypto';
+function normalizeSidecarUrl(input) {
+    const envUrl = process.env.SANDBOX_SIDECAR_URL || process.env.SIDECAR_URL;
+    const raw = input?.trim() || envUrl?.trim() || `http://127.0.0.1:${process.env.SIDECAR_PORT || '8080'}`;
+    return raw.replace(/\/$/, '');
+}
+function resolveAuthToken(input) {
+    if (input?.trim())
+        return input.trim();
+    if (process.env.SANDBOX_SIDECAR_AUTH_TOKEN?.trim())
+        return process.env.SANDBOX_SIDECAR_AUTH_TOKEN.trim();
+    if (process.env.SIDECAR_AUTH_TOKEN?.trim())
+        return process.env.SIDECAR_AUTH_TOKEN.trim();
+    const tokens = (process.env.SIDECAR_AUTH_TOKENS || '')
+        .split(/[,\s]+/g)
+        .map((value) => value.trim())
+        .filter(Boolean);
+    return tokens[0];
+}
+function resolveBackendType(model, explicitType) {
+    const candidate = explicitType?.trim() || process.env.SANDBOX_BACKEND_TYPE?.trim();
+    if (candidate)
+        return candidate;
+    if (/^(claude|sonnet|opus|haiku)([-: ]|$)/i.test(model))
+        return 'claude-code';
+    if (/^(gpt|o[134]|codex)([-: ]|$)/i.test(model))
+        return 'codex';
+    throw new Error('sandbox-backend requires SANDBOX_BACKEND_TYPE or --sandbox-backend-type when the backend cannot be inferred from the model.');
+}
+function buildHeaders(authToken) {
+    return {
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+        ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
+    };
+}
+function modelMessageToText(message) {
+    if (typeof message.content === 'string')
+        return message.content;
+    if (!Array.isArray(message.content))
+        return '';
+    return message.content
+        .map((part) => {
+        if (part.type === 'text')
+            return part.text;
+        if (part.type === 'image')
+            return `[Image attachment: ${part.mediaType}]`;
+        return '';
+    })
+        .filter(Boolean)
+        .join('\n');
+}
+function buildTranscript(messages) {
+    const lines = [];
+    for (const message of messages) {
+        const content = modelMessageToText(message).trim();
+        if (!content)
+            continue;
+        lines.push(`${message.role.toUpperCase()}:`);
+        lines.push(content);
+        lines.push('');
+    }
+    return lines.join('\n').trim();
+}
+function getLatestUserAttachments(messages) {
+    const latestUser = [...messages].reverse().find((message) => message.role === 'user');
+    if (!latestUser || !Array.isArray(latestUser.content))
+        return [];
+    const attachments = [];
+    let imageIndex = 0;
+    for (const part of latestUser.content) {
+        if (part.type !== 'image' || !part.image)
+            continue;
+        imageIndex += 1;
+        const mediaType = part.mediaType || 'image/jpeg';
+        const imageValue = typeof part.image === 'string'
+            ? part.image
+            : part.image instanceof URL
+                ? part.image.toString()
+                : null;
+        if (!imageValue)
+            continue;
+        const url = imageValue.startsWith('data:')
+            ? imageValue
+            : `data:${mediaType};base64,${imageValue}`;
+        const ext = mediaType.includes('png') ? 'png' : 'jpg';
+        attachments.push({
+            type: 'file',
+            filename: `browser-screenshot-${imageIndex}.${ext}`,
+            mediaType,
+            url,
+        });
+    }
+    return attachments;
+}
+async function requestJson(sidecarUrl, path, init) {
+    const response = await fetch(`${sidecarUrl}${path}`, init);
+    const text = await response.text();
+    if (!response.ok) {
+        throw new Error(text || `${response.status} ${response.statusText}`);
+    }
+    return text ? JSON.parse(text) : {};
+}
+async function collectAssistantText(sidecarUrl, authToken, sessionId, assistantMessageId, timeoutMs, debug) {
+    const response = await fetch(`${sidecarUrl}/agents/events?sessionId=${encodeURIComponent(sessionId)}`, {
+        method: 'GET',
+        headers: {
+            Accept: 'text/event-stream',
+            ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
+        },
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!response.ok || !response.body) {
+        throw new Error(`Failed to open sidecar event stream: ${response.status} ${response.statusText}`);
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let text = '';
+    let errorMessage;
+    const warnings = [];
+    const handleEvent = (rawData) => {
+        const event = JSON.parse(rawData);
+        if (debug) {
+            console.log('[sandbox-backend:event]', JSON.stringify(event));
+        }
+        if (event.type === 'warning') {
+            const message = typeof event.properties?.message === 'string' ? event.properties.message : '';
+            if (message)
+                warnings.push(message);
+            return;
+        }
+        if (event.type === 'session.error') {
+            errorMessage = event.properties?.error?.message || 'Sidecar backend session failed';
+            return;
+        }
+        if (event.type === 'message.part.updated') {
+            const part = event.properties?.part;
+            const messageId = typeof part?.messageID === 'string' ? part.messageID : undefined;
+            if (assistantMessageId && messageId && messageId !== assistantMessageId) {
+                return;
+            }
+            const delta = typeof event.properties?.delta === 'string' ? event.properties.delta : undefined;
+            if (delta) {
+                text += delta;
+                return;
+            }
+            if (part?.type === 'text' && typeof part.text === 'string') {
+                text = part.text;
+            }
+            return;
+        }
+        if (event.type === 'raw') {
+            const rawEvent = event.properties?.event;
+            const rawItem = rawEvent?.item;
+            if (rawEvent?.type === 'item.completed' && rawItem?.type === 'agent_message' && typeof rawItem.text === 'string') {
+                text = rawItem.text;
+            }
+            return;
+        }
+        if (event.type === 'message.complete' || event.type === 'session.idle' || event.type === 'done') {
+            throw new Error('__SANDBOX_DONE__');
+        }
+    };
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            while (true) {
+                const boundary = buffer.indexOf('\n\n');
+                if (boundary === -1)
+                    break;
+                const chunk = buffer.slice(0, boundary);
+                buffer = buffer.slice(boundary + 2);
+                const dataLines = chunk
+                    .split('\n')
+                    .filter((line) => line.startsWith('data:'))
+                    .map((line) => line.slice(5).trimStart());
+                if (dataLines.length === 0)
+                    continue;
+                handleEvent(dataLines.join('\n'));
+            }
+        }
+    }
+    catch (error) {
+        if (!(error instanceof Error && error.message === '__SANDBOX_DONE__')) {
+            throw error;
+        }
+    }
+    finally {
+        try {
+            await reader.cancel();
+        }
+        catch { }
+    }
+    if (errorMessage) {
+        throw new Error(errorMessage);
+    }
+    return { text: text.trim(), warnings };
+}
+export async function generateWithSandboxBackend(options) {
+    const timeoutMs = options.timeoutMs ?? 60_000;
+    const sidecarUrl = normalizeSidecarUrl(options.sidecarUrl);
+    const authToken = resolveAuthToken(options.authToken);
+    const backendType = resolveBackendType(options.model, options.backendType);
+    const backendProfile = options.backendProfile?.trim() ||
+        options.backendProfileId?.trim() ||
+        process.env.SANDBOX_BACKEND_PROFILE?.trim() ||
+        process.env.SANDBOX_BACKEND_PROFILE_ID?.trim();
+    const backendModelProvider = options.backendModelProvider?.trim() || process.env.SANDBOX_BACKEND_MODEL_PROVIDER?.trim();
+    const session = await requestJson(sidecarUrl, '/agents/sessions', {
+        method: 'POST',
+        headers: buildHeaders(authToken),
+        body: JSON.stringify({
+            title: `abd-${randomUUID()}`,
+            backend: {
+                type: backendType,
+                ...(backendProfile ? { profile: backendProfile } : {}),
+                model: {
+                    model: options.model,
+                    ...(backendModelProvider ? { provider: backendModelProvider } : {}),
+                },
+            },
+        }),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    try {
+        const transcript = buildTranscript(options.messages);
+        const parts = [
+            {
+                type: 'text',
+                text: transcript,
+            },
+            ...getLatestUserAttachments(options.messages),
+        ];
+        const started = await requestJson(sidecarUrl, `/agents/sessions/${encodeURIComponent(session.id)}/messages`, {
+            method: 'POST',
+            headers: buildHeaders(authToken),
+            body: JSON.stringify({
+                system: options.system,
+                parts,
+            }),
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        return await collectAssistantText(sidecarUrl, authToken, session.id, started.info?.id, timeoutMs, options.debug === true);
+    }
+    finally {
+        await fetch(`${sidecarUrl}/agents/sessions/${encodeURIComponent(session.id)}`, {
+            method: 'DELETE',
+            headers: {
+                Accept: 'application/json',
+                ...(authToken ? { Authorization: `Bearer ${authToken}` } : {}),
+            },
+        }).catch(() => { });
+    }
+}
+//# sourceMappingURL=sandbox-backend.js.map

package/dist/providers/sandbox-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox-backend.js","sourceRoot":"","sources":["../../src/providers/sandbox-backend.ts"],"names":[],"mappings":"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"}

package/dist/recovery.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Recovery strategies for common failure modes.
+ *
+ * Automatically triggered by the Runner when it detects patterns like:
+ * - Stuck (same URL + snapshot for multiple turns)
+ * - Consecutive selector failures
+ * - Loading states
+ * - Blocking overlays
+ */
+import type { Action, PageState, Turn } from './types.js';
+export interface RecoveryContext {
+    /** Recent turns for pattern analysis */
+    recentTurns: Turn[];
+    /** Current page state */
+    currentState: PageState;
+    /** Number of consecutive errors */
+    consecutiveErrors: number;
+}
+export interface RecoveryAction {
+    /** What strategy was triggered */
+    strategy: string;
+    /** Feedback to inject into the brain's conversation */
+    feedback: string;
+    /** Milliseconds to wait before continuing */
+    waitMs?: number;
+    /** Concrete action for the runner to execute before continuing */
+    forceAction?: 'reload' | 'escape' | 'scrollTop';
+    /** Optional direct browser action to execute before continuing */
+    forceBrowserAction?: Action;
+}
+export interface SnapshotElement {
+    role: string;
+    name: string;
+    ref: string;
+}
+/**
+ * Compute a simple hash of a snapshot string for change detection.
+ * Uses a fast DJB2-like hash — not cryptographic, just for equality checks.
+ */
+export declare function snapshotHash(snapshot: string): number;
+/**
+ * Detect if the agent is stuck (same URL + similar snapshot for N turns).
+ */
+export declare function detectStuck(turns: Turn[], threshold?: number): boolean;
+/**
+ * Detect consecutive action failures (selector not found, click intercepted, etc.)
+ */
+export declare function detectSelectorFailures(turns: Turn[], threshold?: number): boolean;
+/**
+ * Detect loading states in the snapshot.
+ * Patterns are anchored to avoid false-positives on words like "downloading" or
+ * "loading" appearing in regular page content (e.g., "Loading dock", "Processing fees").
+ */
+export declare function detectLoadingState(snapshot: string): boolean;
+/** Parse interactive elements from a snapshot into role/name/ref triples. */
+export declare function parseSnapshotElements(snapshot: string): SnapshotElement[];
+export interface BlockingModalDetection {
+    kind: 'quota-limit' | 'blocking-modal' | 'verification-override';
+    strategy: string;
+    feedback: string;
+    action?: Action;
+    forceAction?: 'escape';
+}
+export interface TerminalBlockerDetection {
+    kind: 'network-unreachable' | 'bot-challenge' | 'dev-environment-unavailable';
+    strategy: 'terminal-network-error' | 'terminal-bot-challenge' | 'terminal-dev-environment-unavailable';
+    reason: string;
+    evidence: string[];
+}
+/**
+ * Detect blocking dialogs/modals and suggest an immediate remediation action.
+ * This is intentionally deterministic so common blockers are handled without
+ * waiting for the LLM to rediscover basic escape hatches every run.
+ */
+export declare function detectBlockingModal(snapshot: string): BlockingModalDetection | null;
+/**
+ * Detect blockers that should terminate the run immediately.
+ * These are conditions the agent cannot reliably resolve by trying more actions.
+ */
+export declare function detectTerminalBlocker(state: PageState): TerminalBlockerDetection | null;
+/**
+ * Detect persistent app-native environment blockers that are unlikely to be fixed
+ * by more navigation attempts inside the same run.
+ */
+export declare function detectPersistentTerminalBlocker(recentTurns: Turn[], currentState: PageState): TerminalBlockerDetection | null;
+/**
+ * Analyze the current state and return a recovery action if needed.
+ * Returns null if no recovery is warranted.
+ */
+export declare function analyzeRecovery(ctx: RecoveryContext): RecoveryAction | null;
+//# sourceMappingURL=recovery.d.ts.map

package/dist/recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.d.ts","sourceRoot":"","sources":["../src/recovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,wCAAwC;IACxC,WAAW,EAAE,IAAI,EAAE,CAAC;IACpB,yBAAyB;IACzB,YAAY,EAAE,SAAS,CAAC;IACxB,mCAAmC;IACnC,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,WAAW,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,WAAW,CAAC;IAChD,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAMrD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,SAAS,SAAI,GAAG,OAAO,CAyCjE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,SAAS,SAAI,GAAG,OAAO,CAI5E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAW5D;AAED,6EAA6E;AAC7E,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,EAAE,CAYzE;AA2BD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,aAAa,GAAG,gBAAgB,GAAG,uBAAuB,CAAC;IACjE,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,QAAQ,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,qBAAqB,GAAG,eAAe,GAAG,6BAA6B,CAAC;IAC9E,QAAQ,EAAE,wBAAwB,GAAG,wBAAwB,GAAG,sCAAsC,CAAC;IACvG,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,sBAAsB,GAAG,IAAI,CA4MnF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,SAAS,GAAG,wBAAwB,GAAG,IAAI,CAkDvF;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,CAC7C,WAAW,EAAE,IAAI,EAAE,EACnB,YAAY,EAAE,SAAS,GACtB,wBAAwB,GAAG,IAAI,CA0CjC;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,eAAe,GAAG,cAAc,GAAG,IAAI,CAuG3E"}