@enricai/barnacle 1.0.0

package/dist/scraper/session-shared.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTimeoutFetch = createTimeoutFetch;
+exports.pickRandomViewport = pickRandomViewport;
+const random_1 = require("../lib/random");
+/**
+ * Returns a fetch wrapper that aborts after `timeoutMs` milliseconds.
+ * Handles the total request timeout for Anthropic API calls; the TCP connect
+ * timeout is handled separately via setGlobalDispatcher in server.ts.
+ */
+function createTimeoutFetch(timeoutMs) {
+    return (url, init) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        // Merge with any existing signal from the caller (e.g. AI SDK's own abort signal)
+        // so both can independently cancel the request.
+        const signals = [controller.signal, init?.signal].filter((s) => s instanceof AbortSignal);
+        const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
+        return fetch(url, { ...init, signal }).finally(() => clearTimeout(timer));
+    };
+}
+/**
+ * Common desktop viewports rotated per session to reduce bot-detection
+ * fingerprinting — a fixed pixel size is an easy signal to filter on.
+ */
+const VIEWPORTS = [
+    { width: 1280, height: 720 },
+    { width: 1366, height: 768 },
+    { width: 1440, height: 900 },
+    { width: 1920, height: 1080 },
+];
+function pickRandomViewport() {
+    return (0, random_1.pickRandom)(VIEWPORTS);
+}
+//# sourceMappingURL=session-shared.js.map

package/dist/scraper/session-shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-shared.js","sourceRoot":"","sources":["../../src/scraper/session-shared.ts"],"names":[],"mappings":";;AA4BA,gDAYC;AAaD,gDAEC;AApDD,yCAA0C;AAoB1C;;;;GAIG;AACH,SAAgB,kBAAkB,CAAC,SAAiB;IAClD,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE;QACnB,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,CAAC,CAAC;QAC9D,kFAAkF;QAClF,gDAAgD;QAChD,MAAM,OAAO,GAAG,CAAC,UAAU,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC,MAAM,CACtD,CAAC,CAAC,EAAoB,EAAE,CAAC,CAAC,YAAY,WAAW,CAClD,CAAC;QACF,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QAC1E,OAAO,KAAK,CAAC,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;IAC5E,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,SAAS,GAAG;IAChB,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;IAC5B,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;IAC5B,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE;IAC5B,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;CACrB,CAAC;AAEX,SAAgB,kBAAkB;IAChC,OAAO,IAAA,mBAAU,EAAC,SAAS,CAAC,CAAC;AAC/B,CAAC"}

package/dist/scraper/session-steel.d.ts

@@ -0,0 +1,31 @@
+import { type BrowserSession } from "../scraper/session-shared";
+/**
+ * Spins up one Steel cloud browser session with residential proxies +
+ * the configured Stagehand LLM, connected via Steel's CDP endpoint.
+ *
+ * Why residential proxies: many target sites are more reliably reachable
+ * from residential IPs; datacenter ranges are commonly flagged.
+ *
+ * Why serverCache=true: Stagehand's server-side cache skips LLM inference on
+ * replay. After the first run against a page structure, subsequent `act()`
+ * calls complete in milliseconds. When the target page UI changes and a cached
+ * action fails, retry.ts wraps the next attempt — that's our recovery layer.
+ *
+ * Why selfHeal=false: Stagehand's built-in self-heal only fires on Playwright
+ * throws (element-not-found / intercepted / timeout). It does NOT catch the
+ * silent-semantic-miss case ("clicked the wrong thing, returned success"), it
+ * has open variable-loss / cache-write bugs on `main`, and the docs themselves
+ * default it off and steer production users toward observe → act. Recon-browser
+ * owns its own verify-and-retry cascade; the runtime path uses retry.ts. Keeping
+ * this off makes failure semantics clean — `act()` throws or succeeds, and our
+ * code decides what to do next.
+ *
+ * Why `env: "LOCAL"`: Steel sessions connect via a CDP URL, not Stagehand's
+ * first-party Browserbase integration. This means several Stagehand code paths
+ * gated on `env === "BROWSERBASE"` (file upload payload injection, tuned CDP
+ * timeouts, session recovery, event-window timing) stay inactive — accept this
+ * trade-off as the cost of Steel support. Switch to the Browserbase provider
+ * to activate those paths.
+ */
+export declare function createSteelBrowserSession(): Promise<BrowserSession>;
+//# sourceMappingURL=session-steel.d.ts.map

package/dist/scraper/session-steel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-steel.d.ts","sourceRoot":"","sources":["../../src/scraper/session-steel.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,0BAA0B,CAAC;AAKlC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CAAC,cAAc,CAAC,CAsGzE"}

package/dist/scraper/session-steel.js

@@ -0,0 +1,140 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSteelBrowserSession = createSteelBrowserSession;
+const stagehand_1 = require("@browserbasehq/stagehand");
+const steel_sdk_1 = __importDefault(require("steel-sdk"));
+const config_1 = require("../config");
+const bedrock_1 = require("../lib/bedrock");
+const errors_1 = require("../lib/errors");
+const logging_1 = require("../lib/logging");
+const session_shared_1 = require("../scraper/session-shared");
+const throttle_1 = require("../scraper/throttle");
+const logger = (0, logging_1.getLogger)({ name: "scraper/session-steel" });
+/**
+ * Spins up one Steel cloud browser session with residential proxies +
+ * the configured Stagehand LLM, connected via Steel's CDP endpoint.
+ *
+ * Why residential proxies: many target sites are more reliably reachable
+ * from residential IPs; datacenter ranges are commonly flagged.
+ *
+ * Why serverCache=true: Stagehand's server-side cache skips LLM inference on
+ * replay. After the first run against a page structure, subsequent `act()`
+ * calls complete in milliseconds. When the target page UI changes and a cached
+ * action fails, retry.ts wraps the next attempt — that's our recovery layer.
+ *
+ * Why selfHeal=false: Stagehand's built-in self-heal only fires on Playwright
+ * throws (element-not-found / intercepted / timeout). It does NOT catch the
+ * silent-semantic-miss case ("clicked the wrong thing, returned success"), it
+ * has open variable-loss / cache-write bugs on `main`, and the docs themselves
+ * default it off and steer production users toward observe → act. Recon-browser
+ * owns its own verify-and-retry cascade; the runtime path uses retry.ts. Keeping
+ * this off makes failure semantics clean — `act()` throws or succeeds, and our
+ * code decides what to do next.
+ *
+ * Why `env: "LOCAL"`: Steel sessions connect via a CDP URL, not Stagehand's
+ * first-party Browserbase integration. This means several Stagehand code paths
+ * gated on `env === "BROWSERBASE"` (file upload payload injection, tuned CDP
+ * timeouts, session recovery, event-window timing) stay inactive — accept this
+ * trade-off as the cost of Steel support. Switch to the Browserbase provider
+ * to activate those paths.
+ */
+async function createSteelBrowserSession() {
+    if (!config_1.config.scraper.steelApiKey) {
+        throw new Error("STEEL_API_KEY is required for the steel provider");
+    }
+    if (!config_1.config.scraper.useBedrock && !config_1.config.scraper.anthropicApiKey) {
+        throw new Error("ANTHROPIC_API_KEY is required for the Stagehand LLM client");
+    }
+    const steel = new steel_sdk_1.default({ steelAPIKey: config_1.config.scraper.steelApiKey });
+    const viewport = (0, session_shared_1.pickRandomViewport)();
+    const session = await steel.sessions.create({
+        timeout: config_1.config.scraper.steelSessionTimeoutMs,
+        // Lowercase the env value so SCRAPER_PROXY_TYPE="Residential" /
+        // "RESIDENTIAL" don't silently turn the proxy off.
+        useProxy: config_1.config.scraper.proxyType.toLowerCase() === "residential",
+        solveCaptcha: config_1.config.scraper.solveCaptcha,
+        dimensions: viewport,
+    });
+    // Once `sessions.create` resolves, Steel is billing for the remote session.
+    // Any failure between here and a successful return must release the session
+    // explicitly — otherwise a Stagehand init crash or Stagehand CDP connection
+    // failure leaves a live session burning minutes until Steel's own timeout.
+    let stagehand;
+    try {
+        // Steel's websocketUrl is `wss://connect.steel.dev?sessionId=…`. Stagehand's
+        // V3 CDP connector requires the apiKey as a query parameter too — without it
+        // the connection returns a 502 before the CDP handshake completes.
+        const cdpUrl = session.websocketUrl.includes("apiKey=")
+            ? session.websocketUrl
+            : `${session.websocketUrl}&apiKey=${encodeURIComponent(config_1.config.scraper.steelApiKey)}`;
+        logger.info(`created steel session ${session.id} viewport=${viewport.width}x${viewport.height}`);
+        if (config_1.config.scraper.useBedrock) {
+            logger.info(`using bedrock model ${config_1.config.bedrock.model} in region ${config_1.config.bedrock.region}`);
+        }
+        const llmClient = config_1.config.scraper.useBedrock
+            ? new stagehand_1.AISdkClient({ model: (0, bedrock_1.createBedrockModel)(config_1.config.bedrock) })
+            : undefined;
+        stagehand = new stagehand_1.Stagehand({
+            env: "LOCAL",
+            model: config_1.config.scraper.useBedrock
+                ? undefined
+                : {
+                    modelName: config_1.config.scraper.model,
+                    apiKey: config_1.config.scraper.anthropicApiKey,
+                    // @ai-sdk/anthropic has no `timeout` option; inject timeout at the fetch layer.
+                    fetch: (0, session_shared_1.createTimeoutFetch)(config_1.config.scraper.anthropicTimeoutMs),
+                },
+            llmClient,
+            serverCache: true,
+            selfHeal: false,
+            localBrowserLaunchOptions: { cdpUrl },
+            verbose: 0,
+        });
+        await stagehand.init();
+    }
+    catch (err) {
+        // Best-effort cleanup; swallow secondary failures so the original
+        // error surfaces to the caller.
+        try {
+            if (stagehand)
+                await stagehand.close();
+        }
+        catch (closeErr) {
+            logger.warn(`stagehand close during failed init: ${(0, errors_1.toErrorMessage)(closeErr)}`);
+        }
+        try {
+            await steel.sessions.release(session.id);
+        }
+        catch (releaseErr) {
+            logger.warn(`steel release during failed init for ${session.id}: ${(0, errors_1.toErrorMessage)(releaseErr)}`);
+        }
+        throw err;
+    }
+    const limiter = (0, throttle_1.createSessionLimiter)();
+    const close = async () => {
+        try {
+            await stagehand.close();
+        }
+        catch (err) {
+            logger.warn(`stagehand close failed for session ${session.id}: ${(0, errors_1.toErrorMessage)(err)}`);
+        }
+        try {
+            await steel.sessions.release(session.id);
+        }
+        catch (err) {
+            logger.warn(`steel release failed for session ${session.id}: ${(0, errors_1.toErrorMessage)(err)}`);
+        }
+        await limiter.stop({ dropWaitingJobs: true });
+    };
+    return {
+        stagehand,
+        limiter,
+        sessionId: session.id,
+        provider: "steel",
+        close,
+    };
+}
+//# sourceMappingURL=session-steel.js.map

package/dist/scraper/session-steel.js.map

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

package/dist/scraper/session-warmup.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Generic retrying browser-session runner. Acquires a fresh session from
+ * `sessionFactory`, runs `callback(session)`, guarantees `session.close()` in
+ * every code path, and retries up to `retryOptions.retries + 1` attempts with
+ * the caller-supplied pRetry options. On exhaustion, wraps the last error in
+ * the caller-supplied `exhaustionError`.
+ *
+ * Extracted from appcast/tokens/warmup.ts so any future recon→generate warmup
+ * flow can reuse the session-lifecycle shell without re-hand-rolling pRetry +
+ * finally-close + error-mapping each time.
+ */
+import { type Options as PRetryOptions } from "p-retry";
+import type { BrowserSession } from "../scraper/session-shared";
+export interface SessionWarmupOptions {
+    /** pRetry options forwarded verbatim. The caller controls retries, timeouts, and onFailedAttempt. */
+    retryOptions: PRetryOptions;
+    /**
+     * Invoked with the last-thrown error when all attempts are exhausted. Return
+     * the error that `withBrowserSession` should throw (typically a domain-specific
+     * error type the caller's dispatch layer understands).
+     */
+    mapExhaustionError: (err: unknown) => Error;
+}
+/**
+ * Runs `callback` inside a fresh browser session on every attempt. Guarantees
+ * that `session.close()` is called regardless of whether the callback succeeds
+ * or throws. On exhaustion, calls `opts.mapExhaustionError` with the last pRetry
+ * error and throws whatever it returns.
+ */
+export declare function withBrowserSession<T>(sessionFactory: () => Promise<BrowserSession>, callback: (session: BrowserSession, attemptNumber: number) => Promise<T>, opts: SessionWarmupOptions): Promise<T>;
+//# sourceMappingURL=session-warmup.d.ts.map

package/dist/scraper/session-warmup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-warmup.d.ts","sourceRoot":"","sources":["../../src/scraper/session-warmup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAe,EAAE,KAAK,OAAO,IAAI,aAAa,EAAE,MAAM,SAAS,CAAC;AAIhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI/D,MAAM,WAAW,oBAAoB;IACnC,qGAAqG;IACrG,YAAY,EAAE,aAAa,CAAC;IAC5B;;;;OAIG;IACH,kBAAkB,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,KAAK,CAAC;CAC7C;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,cAAc,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,EAC7C,QAAQ,EAAE,CAAC,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EACxE,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,CAAC,CAAC,CAiBZ"}

package/dist/scraper/session-warmup.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Generic retrying browser-session runner. Acquires a fresh session from
+ * `sessionFactory`, runs `callback(session)`, guarantees `session.close()` in
+ * every code path, and retries up to `retryOptions.retries + 1` attempts with
+ * the caller-supplied pRetry options. On exhaustion, wraps the last error in
+ * the caller-supplied `exhaustionError`.
+ *
+ * Extracted from appcast/tokens/warmup.ts so any future recon→generate warmup
+ * flow can reuse the session-lifecycle shell without re-hand-rolling pRetry +
+ * finally-close + error-mapping each time.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withBrowserSession = withBrowserSession;
+const p_retry_1 = __importDefault(require("p-retry"));
+const errors_1 = require("../lib/errors");
+const logging_1 = require("../lib/logging");
+const logger = (0, logging_1.getLogger)({ name: "scraper/session-warmup" });
+/**
+ * Runs `callback` inside a fresh browser session on every attempt. Guarantees
+ * that `session.close()` is called regardless of whether the callback succeeds
+ * or throws. On exhaustion, calls `opts.mapExhaustionError` with the last pRetry
+ * error and throws whatever it returns.
+ */
+async function withBrowserSession(sessionFactory, callback, opts) {
+    try {
+        return await (0, p_retry_1.default)(async (attemptNumber) => {
+            const session = await sessionFactory();
+            try {
+                return await callback(session, attemptNumber);
+            }
+            finally {
+                await session.close().catch((closeErr) => {
+                    logger.warn(`session-warmup: close failed for ${session.sessionId}: ${(0, errors_1.toErrorMessage)(closeErr)}`);
+                });
+            }
+        }, opts.retryOptions);
+    }
+    catch (err) {
+        throw opts.mapExhaustionError(err);
+    }
+}
+//# sourceMappingURL=session-warmup.js.map

package/dist/scraper/session-warmup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-warmup.js","sourceRoot":"","sources":["../../src/scraper/session-warmup.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;;;AA2BH,gDAqBC;AA9CD,sDAAgE;AAEhE,yCAA8C;AAC9C,2CAA0C;AAG1C,MAAM,MAAM,GAAG,IAAA,mBAAS,EAAC,EAAE,IAAI,EAAE,wBAAwB,EAAE,CAAC,CAAC;AAa7D;;;;;GAKG;AACI,KAAK,UAAU,kBAAkB,CACtC,cAA6C,EAC7C,QAAwE,EACxE,IAA0B;IAE1B,IAAI,CAAC;QACH,OAAO,MAAM,IAAA,iBAAM,EAAC,KAAK,EAAE,aAAa,EAAE,EAAE;YAC1C,MAAM,OAAO,GAAG,MAAM,cAAc,EAAE,CAAC;YACvC,IAAI,CAAC;gBACH,OAAO,MAAM,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;YAChD,CAAC;oBAAS,CAAC;gBACT,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,EAAE;oBACvC,MAAM,CAAC,IAAI,CACT,oCAAoC,OAAO,CAAC,SAAS,KAAK,IAAA,uBAAc,EAAC,QAAQ,CAAC,EAAE,CACrF,CAAC;gBACJ,CAAC,CAAC,CAAC;YACL,CAAC;QACH,CAAC,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IACxB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC;AACH,CAAC"}

package/dist/scraper/session.d.ts

@@ -0,0 +1,21 @@
+import type { BrowserSession, ProviderName } from "../scraper/session-shared";
+export type { BrowserSession, ProviderName } from "../scraper/session-shared";
+/**
+ * Spins up one browser session via the configured provider. Browserbase is the
+ * default; Steel is an opt-in fallback.
+ *
+ * Provider selection (in order of precedence):
+ *   1. Explicit `opts.provider` (per-call override; CLI flags forward here)
+ *   2. `SCRAPER_PROVIDER` env var resolved at module load into `config.scraper.provider`
+ *   3. Hardcoded default ("browserbase")
+ *
+ * `advancedStealth` opts into Browserbase's Scale Plan stealth profile (uses a
+ * stronger fingerprint mitigation pipeline + forces a Windows desktop
+ * fingerprint per Browserbase's DataDome guidance). No-op when the provider
+ * is Steel — that path uses its own stealth defaults.
+ */
+export declare function createBrowserSession(opts?: {
+    provider?: ProviderName;
+    advancedStealth?: boolean;
+}): Promise<BrowserSession>;
+//# sourceMappingURL=session.d.ts.map

package/dist/scraper/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/scraper/session.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7E,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7E;;;;;;;;;;;;;GAaG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,CAAC,EAAE;IAChD,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,GAAG,OAAO,CAAC,cAAc,CAAC,CAM1B"}

package/dist/scraper/session.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBrowserSession = createBrowserSession;
+const config_1 = require("../config");
+const session_browserbase_1 = require("../scraper/session-browserbase");
+const session_steel_1 = require("../scraper/session-steel");
+/**
+ * Spins up one browser session via the configured provider. Browserbase is the
+ * default; Steel is an opt-in fallback.
+ *
+ * Provider selection (in order of precedence):
+ *   1. Explicit `opts.provider` (per-call override; CLI flags forward here)
+ *   2. `SCRAPER_PROVIDER` env var resolved at module load into `config.scraper.provider`
+ *   3. Hardcoded default ("browserbase")
+ *
+ * `advancedStealth` opts into Browserbase's Scale Plan stealth profile (uses a
+ * stronger fingerprint mitigation pipeline + forces a Windows desktop
+ * fingerprint per Browserbase's DataDome guidance). No-op when the provider
+ * is Steel — that path uses its own stealth defaults.
+ */
+async function createBrowserSession(opts) {
+    const provider = opts?.provider ?? config_1.config.scraper.provider;
+    if (provider === "browserbase") {
+        return (0, session_browserbase_1.createBrowserbaseBrowserSession)({ advancedStealth: opts?.advancedStealth });
+    }
+    return (0, session_steel_1.createSteelBrowserSession)();
+}
+//# sourceMappingURL=session.js.map

package/dist/scraper/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/scraper/session.ts"],"names":[],"mappings":";;AAqBA,oDASC;AA9BD,qCAAkC;AAClC,uEAAgF;AAEhF,2DAAoE;AAIpE;;;;;;;;;;;;;GAaG;AACI,KAAK,UAAU,oBAAoB,CAAC,IAG1C;IACC,MAAM,QAAQ,GAAG,IAAI,EAAE,QAAQ,IAAI,eAAM,CAAC,OAAO,CAAC,QAAQ,CAAC;IAC3D,IAAI,QAAQ,KAAK,aAAa,EAAE,CAAC;QAC/B,OAAO,IAAA,qDAA+B,EAAC,EAAE,eAAe,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,IAAA,yCAAyB,GAAE,CAAC;AACrC,CAAC"}

package/dist/scraper/stagehand-guard.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Schema-enforcing wrappers around Stagehand's `act`, `observe`, and
+ * `extract`. Every Stagehand SDK call in the codebase routes through these
+ * so the engine has a single chokepoint for return-envelope validation +
+ * telemetry capture.
+ *
+ * Two enforcement modes by primitive:
+ *
+ *  - `act` and `observe`: Stagehand owns the underlying LLM call and does
+ *    not expose a caller-provided schema field on `ActOptions` /
+ *    `ObserveOptions`. The strictest enforcement Stagehand's API allows is
+ *    caller-side `safeParse` of the RETURN ENVELOPE against Zod mirrors of
+ *    Stagehand's public types (`ActResult`, `Action`). On envelope drift
+ *    (a Stagehand SDK upgrade that widens the shape, or a Stagehand bug
+ *    that emits malformed JSON), the wrapper throws
+ *    `StagehandSchemaError` and records a `failureKind:
+ *    "schema-validation-failed"` entry to the NDJSON sink, matching the
+ *    failure taxonomy of our direct Anthropic SDK callers.
+ *
+ *  - `extract`: Stagehand's 3-arg overload accepts a caller-provided Zod
+ *    schema and routes structured output through the LLM the same way our
+ *    `messages.parse + zodOutputFormat` calls do. Stagehand `safeParse`s
+ *    server-side; we `safeParse` again caller-side as defense in depth
+ *    against SDK contract drift (and to log identical telemetry).
+ *
+ * Telemetry: every wrapper call lands in `calls.ndjson` regardless of
+ * outcome (per user directive — full parity with our Anthropic SDK call
+ * telemetry). Volume is dominated by `act`: hundreds of calls per job
+ * across the cascade attempts ≈ thousands of entries per sweep. The
+ * NDJSON sink is append-only and per-URL partitioned (see
+ * `src/lib/telemetry/telemetry-paths.ts`) so this scale is intentional.
+ *
+ * Stagehand Zod compat: as of `@browserbasehq/stagehand@3.4.0`,
+ * `StagehandZodSchema = Zod4TypeAny | z3.ZodTypeAny` — both Zod v3 and v4
+ * schemas pass through cleanly (confirmed in
+ * `node_modules/@browserbasehq/stagehand/dist/esm/lib/v3/zodCompat.d.ts`).
+ * Barnacle uses Zod v4 via the `zod/v4` subpath export; that's compatible.
+ */
+import type { Action, ActOptions, ActResult, ExtractOptions, ObserveOptions, Stagehand } from "@browserbasehq/stagehand";
+import { z } from "zod/v4";
+import { type LlmCallInput } from "../lib/telemetry/call-capture";
+/**
+ * Injectable capture function — matches `captureLlmCall`'s signature. Same
+ * shape as `JudgeCaptureFn` in `@/lib/llm/judge`. Lets each guard call route
+ * its telemetry into the caller's per-run NDJSON sink instead of the global
+ * default in `captureLlmCall`. Without this, every Stagehand guard entry
+ * lands in `.barnacle/calls.ndjson` instead of the per-URL run partition.
+ */
+export type StagehandCaptureFn = (input: LlmCallInput) => Promise<void>;
+/**
+ * Zod mirror of Stagehand's public `Action` shape (from
+ * `@browserbasehq/stagehand/.../public/methods.d.ts`):
+ *
+ *   interface Action {
+ *     selector: string;
+ *     description: string;
+ *     method?: string;
+ *     arguments?: string[];
+ *   }
+ *
+ * If Stagehand widens this shape in a future minor version, our `safeParse`
+ * fails closed — we'd rather see a `schema-validation-failed` entry in
+ * telemetry than have downstream code silently consume drift.
+ */
+export declare const ACTION_SCHEMA: z.ZodObject<{
+    selector: z.ZodString;
+    description: z.ZodString;
+    method: z.ZodOptional<z.ZodString>;
+    arguments: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+/**
+ * Zod mirror of Stagehand's public `ActResult` shape. The `actions` array
+ * is sometimes empty when Stagehand acted via a path that doesn't echo the
+ * action back; the cascade's resolvedAction fallback already handles that
+ * case. We accept empty arrays here as valid per the SDK contract.
+ */
+export declare const ACT_RESULT_SCHEMA: z.ZodObject<{
+    success: z.ZodBoolean;
+    message: z.ZodString;
+    actionDescription: z.ZodString;
+    actions: z.ZodArray<z.ZodObject<{
+        selector: z.ZodString;
+        description: z.ZodString;
+        method: z.ZodOptional<z.ZodString>;
+        arguments: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+    cacheStatus: z.ZodOptional<z.ZodEnum<{
+        HIT: "HIT";
+        MISS: "MISS";
+    }>>;
+}, z.core.$strip>;
+/**
+ * Thrown by any guarded* wrapper when Stagehand's return value doesn't
+ * `safeParse` against the schema. The `kind` is always
+ * `"schema-validation-failed"` — same string the Anthropic SDK callers use
+ * — so `classifyLlmCallFailure` routes it to the same NDJSON failureKind
+ * bucket without any string-matching changes.
+ */
+export declare class StagehandSchemaError extends Error {
+    readonly kind: "schema-validation-failed";
+    readonly primitive: "act" | "observe" | "extract";
+    readonly zodError: z.ZodError;
+    readonly rawResponse: unknown;
+    constructor(primitive: "act" | "observe" | "extract", zodError: z.ZodError, rawResponse: unknown);
+}
+/**
+ * Schema-guarded wrapper around Stagehand's `act`. Same signature as the
+ * underlying call: accepts either an instruction string or a structured
+ * `Action` (from a prior `observe`). On the happy path, returns Stagehand's
+ * `ActResult` verbatim. On envelope drift, throws `StagehandSchemaError`
+ * and logs `failureKind: "schema-validation-failed"`.
+ */
+export declare function guardedAct(stagehand: Stagehand, input: string | Action, options?: ActOptions, captureFn?: StagehandCaptureFn): Promise<ActResult>;
+/**
+ * Schema-guarded wrapper around Stagehand's `observe`. Mirrors the
+ * Stagehand overloads: no args, options-only, instruction-only,
+ * instruction + options. On envelope drift (the `Action[]` shape changes),
+ * throws `StagehandSchemaError`.
+ */
+export declare function guardedObserve(stagehand: Stagehand, instruction?: string, options?: ObserveOptions, captureFn?: StagehandCaptureFn): Promise<Action[]>;
+/**
+ * Schema-guarded wrapper around Stagehand's `extract` 3-arg overload. The
+ * caller's Zod schema is what Stagehand asks the LLM to satisfy AND what we
+ * `safeParse` against caller-side. Refuse the 1-arg / 2-arg defaults; every
+ * extract call in the codebase must enforce a schema.
+ */
+export declare function guardedExtract<T extends z.ZodTypeAny>(stagehand: Stagehand, instruction: string, schema: T, options?: ExtractOptions, captureFn?: StagehandCaptureFn): Promise<z.infer<T>>;
+//# sourceMappingURL=stagehand-guard.d.ts.map

package/dist/scraper/stagehand-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stagehand-guard.d.ts","sourceRoot":"","sources":["../../src/scraper/stagehand-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,OAAO,KAAK,EACV,MAAM,EACN,UAAU,EACV,SAAS,EACT,cAAc,EACd,cAAc,EACd,SAAS,EACV,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,8BAA8B,CAAC;AAOtC;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAExE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,aAAa;;;;;iBAKxB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;iBAM5B,CAAC;AAEH;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,QAAQ,CAAC,IAAI,EAAG,0BAA0B,CAAU;IACpD,QAAQ,CAAC,SAAS,EAAE,KAAK,GAAG,SAAS,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;gBAG5B,SAAS,EAAE,KAAK,GAAG,SAAS,GAAG,SAAS,EACxC,QAAQ,EAAE,CAAC,CAAC,QAAQ,EACpB,WAAW,EAAE,OAAO;CAQvB;AAoBD;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,MAAM,GAAG,MAAM,EACtB,OAAO,CAAC,EAAE,UAAU,EACpB,SAAS,CAAC,EAAE,kBAAkB,GAC7B,OAAO,CAAC,SAAS,CAAC,CAqEpB;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,SAAS,EACpB,WAAW,CAAC,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,cAAc,EACxB,SAAS,CAAC,EAAE,kBAAkB,GAC7B,OAAO,CAAC,MAAM,EAAE,CAAC,CAkEnB;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS,CAAC,CAAC,UAAU,EACzD,SAAS,EAAE,SAAS,EACpB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,CAAC,EACT,OAAO,CAAC,EAAE,cAAc,EACxB,SAAS,CAAC,EAAE,kBAAkB,GAC7B,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAsErB"}