@browserbasehq/orca 3.5.0-preview.0 → 3.5.0-preview.1

package/dist/cjs/lib/v3/agent/utils/captureAriaTreeProbe.d.ts

@@ -0,0 +1,35 @@
+/**
+ * captureAriaTreeProbe — capture a truncated accessibility tree of the active
+ * page for use as tier-2 evidence in the trajectory recorder.
+ *
+ * Shared by v3AgentHandler and v3CuaAgentHandler. Listener-gated by the
+ * callers so ordinary agent runs (no TrajectoryRecorder attached) don't pay
+ * the cost.
+ *
+ * The a11y tree is the same payload the agent's `ariaTree` tool sees, but
+ * captured by the harness (not the agent) so the verifier has independent
+ * textual ground truth for grounding non-visual claims — prices, names,
+ * dates, list contents — without OCR'ing screenshots.
+ *
+ * Budget: defaults to ~8000 tokens (32k chars). Per-step a11y captures
+ * across a ~30-step trajectory at that cap sum to ~240k tokens total,
+ * which the verifier handles via per-criterion top-K selection. The cap
+ * is configurable via VERIFIER_ARIATREE_TOKEN_BUDGET so consumers can
+ * trade RAM/disk for fidelity. Truncated content is marked explicitly so
+ * the verifier knows it was clipped.
+ */
+import type { V3 } from "../../v3.js";
+interface CaptureAriaTreeOptions {
+    /** Soft cap on token count (chars/4 approximation). Default 8000. */
+    tokenBudget?: number;
+    /** Hard timeout on the capture. Default 5s. */
+    timeoutMs?: number;
+}
+/**
+ * Returns the truncated a11y tree as a plain string, or undefined when
+ * capture fails. Never throws — a11y capture is best-effort tier-2 evidence,
+ * not a hard requirement, so failures are silently absorbed (the verifier
+ * surfaces this via evidence_insufficient).
+ */
+export declare function captureAriaTreeProbe(v3: V3, opts?: CaptureAriaTreeOptions): Promise<string | undefined>;
+export {};

package/dist/cjs/lib/v3/agent/utils/captureAriaTreeProbe.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureAriaTreeProbe = captureAriaTreeProbe;
+const APPROX_CHARS_PER_TOKEN = 4;
+const DEFAULT_TOKEN_BUDGET = 8_000;
+const DEFAULT_TIMEOUT_MS = 5_000;
+/**
+ * Returns the truncated a11y tree as a plain string, or undefined when
+ * capture fails. Never throws — a11y capture is best-effort tier-2 evidence,
+ * not a hard requirement, so failures are silently absorbed (the verifier
+ * surfaces this via evidence_insufficient).
+ */
+async function captureAriaTreeProbe(v3, opts = {}) {
+    const envBudget = parseInt(process.env.VERIFIER_ARIATREE_TOKEN_BUDGET ?? "", 10);
+    const tokenBudget = opts.tokenBudget ??
+        (Number.isFinite(envBudget) && envBudget > 0
+            ? envBudget
+            : DEFAULT_TOKEN_BUDGET);
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxChars = tokenBudget * APPROX_CHARS_PER_TOKEN;
+    try {
+        // v3.extract() without a schema returns { pageText } where pageText is the
+        // rendered accessibility tree — same path the agent's ariaTree tool uses.
+        const result = await v3.extract({ timeout: timeoutMs });
+        const pageText = result?.pageText;
+        if (typeof pageText !== "string" || pageText.length === 0)
+            return undefined;
+        if (pageText.length > maxChars) {
+            return (pageText.slice(0, maxChars) +
+                `\n\n[CONTENT TRUNCATED at ~${tokenBudget} tokens — set VERIFIER_ARIATREE_TOKEN_BUDGET to raise]`);
+        }
+        return pageText;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=captureAriaTreeProbe.js.map

package/dist/cjs/lib/v3/agent/utils/captureAriaTreeProbe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captureAriaTreeProbe.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/utils/captureAriaTreeProbe.ts"],"names":[],"mappings":";;AAuCA,oDAiCC;AAlDD,MAAM,sBAAsB,GAAG,CAAC,CAAC;AACjC,MAAM,oBAAoB,GAAG,KAAK,CAAC;AACnC,MAAM,kBAAkB,GAAG,KAAK,CAAC;AASjC;;;;;GAKG;AACI,KAAK,UAAU,oBAAoB,CACxC,EAAM,EACN,OAA+B,EAAE;IAEjC,MAAM,SAAS,GAAG,QAAQ,CACxB,OAAO,CAAC,GAAG,CAAC,8BAA8B,IAAI,EAAE,EAChD,EAAE,CACH,CAAC;IACF,MAAM,WAAW,GACf,IAAI,CAAC,WAAW;QAChB,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC;YAC1C,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,oBAAoB,CAAC,CAAC;IAC5B,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,kBAAkB,CAAC;IACvD,MAAM,QAAQ,GAAG,WAAW,GAAG,sBAAsB,CAAC;IAEtD,IAAI,CAAC;QACH,2EAA2E;QAC3E,0EAA0E;QAC1E,MAAM,MAAM,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;QACxD,MAAM,QAAQ,GAAG,MAAM,EAAE,QAAQ,CAAC;QAClC,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,SAAS,CAAC;QAE5E,IAAI,QAAQ,CAAC,MAAM,GAAG,QAAQ,EAAE,CAAC;YAC/B,OAAO,CACL,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC;gBAC3B,8BAA8B,WAAW,wDAAwD,CAClG,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC","sourcesContent":["/**\n * captureAriaTreeProbe — capture a truncated accessibility tree of the active\n * page for use as tier-2 evidence in the trajectory recorder.\n *\n * Shared by v3AgentHandler and v3CuaAgentHandler. Listener-gated by the\n * callers so ordinary agent runs (no TrajectoryRecorder attached) don't pay\n * the cost.\n *\n * The a11y tree is the same payload the agent's `ariaTree` tool sees, but\n * captured by the harness (not the agent) so the verifier has independent\n * textual ground truth for grounding non-visual claims — prices, names,\n * dates, list contents — without OCR'ing screenshots.\n *\n * Budget: defaults to ~8000 tokens (32k chars). Per-step a11y captures\n * across a ~30-step trajectory at that cap sum to ~240k tokens total,\n * which the verifier handles via per-criterion top-K selection. The cap\n * is configurable via VERIFIER_ARIATREE_TOKEN_BUDGET so consumers can\n * trade RAM/disk for fidelity. Truncated content is marked explicitly so\n * the verifier knows it was clipped.\n */\nimport type { V3 } from \"../../v3.js\";\n\nconst APPROX_CHARS_PER_TOKEN = 4;\nconst DEFAULT_TOKEN_BUDGET = 8_000;\nconst DEFAULT_TIMEOUT_MS = 5_000;\n\ninterface CaptureAriaTreeOptions {\n  /** Soft cap on token count (chars/4 approximation). Default 8000. */\n  tokenBudget?: number;\n  /** Hard timeout on the capture. Default 5s. */\n  timeoutMs?: number;\n}\n\n/**\n * Returns the truncated a11y tree as a plain string, or undefined when\n * capture fails. Never throws — a11y capture is best-effort tier-2 evidence,\n * not a hard requirement, so failures are silently absorbed (the verifier\n * surfaces this via evidence_insufficient).\n */\nexport async function captureAriaTreeProbe(\n  v3: V3,\n  opts: CaptureAriaTreeOptions = {},\n): Promise<string | undefined> {\n  const envBudget = parseInt(\n    process.env.VERIFIER_ARIATREE_TOKEN_BUDGET ?? \"\",\n    10,\n  );\n  const tokenBudget =\n    opts.tokenBudget ??\n    (Number.isFinite(envBudget) && envBudget > 0\n      ? envBudget\n      : DEFAULT_TOKEN_BUDGET);\n  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const maxChars = tokenBudget * APPROX_CHARS_PER_TOKEN;\n\n  try {\n    // v3.extract() without a schema returns { pageText } where pageText is the\n    // rendered accessibility tree — same path the agent's ariaTree tool uses.\n    const result = await v3.extract({ timeout: timeoutMs });\n    const pageText = result?.pageText;\n    if (typeof pageText !== \"string\" || pageText.length === 0) return undefined;\n\n    if (pageText.length > maxChars) {\n      return (\n        pageText.slice(0, maxChars) +\n        `\\n\\n[CONTENT TRUNCATED at ~${tokenBudget} tokens — set VERIFIER_ARIATREE_TOKEN_BUDGET to raise]`\n      );\n    }\n    return pageText;\n  } catch {\n    return undefined;\n  }\n}\n"]}

package/dist/cjs/lib/v3/agent/utils/postStepProbeEvidence.d.ts

@@ -0,0 +1,19 @@
+import type { AgentEvidenceCallback } from "../../types/public/agentEvidenceEvents.js";
+import type { LogLine } from "../../types/public/logs.js";
+import type { V3 } from "../../v3.js";
+interface CaptureProbeEvidenceOptions {
+    v3: V3;
+    url: string;
+    logger: (message: LogLine) => void;
+    warningMessage: string;
+}
+interface EmitPostStepProbeEvidenceOptions extends CaptureProbeEvidenceOptions {
+    evidenceCallback?: AgentEvidenceCallback;
+}
+export declare function captureProbeEvidence({ v3, url, logger, warningMessage, }: CaptureProbeEvidenceOptions): Promise<{
+    url: string;
+    screenshot?: Buffer;
+    ariaTree?: string;
+}>;
+export declare function emitPostStepProbeEvidence({ v3, url, evidenceCallback, logger, warningMessage, }: EmitPostStepProbeEvidenceOptions): Promise<void>;
+export {};

package/dist/cjs/lib/v3/agent/utils/postStepProbeEvidence.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.captureProbeEvidence = captureProbeEvidence;
+exports.emitPostStepProbeEvidence = emitPostStepProbeEvidence;
+const captureAriaTreeProbe_js_1 = require("./captureAriaTreeProbe.js");
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function captureProbeEvidence({ v3, url, logger, warningMessage, }) {
+    let probeUrl = url;
+    let screenshot;
+    try {
+        const page = await v3.context.awaitActivePage();
+        probeUrl = page.url();
+        screenshot = await page.screenshot({ fullPage: false });
+    }
+    catch (e) {
+        logger({
+            category: "agent",
+            message: `${warningMessage}: ${errorMessage(e)}`,
+            level: 1,
+        });
+    }
+    const ariaTree = await (0, captureAriaTreeProbe_js_1.captureAriaTreeProbe)(v3);
+    return {
+        url: probeUrl,
+        ...(screenshot ? { screenshot } : {}),
+        ...(ariaTree !== undefined ? { ariaTree } : {}),
+    };
+}
+async function emitPostStepProbeEvidence({ v3, url, evidenceCallback, logger, warningMessage, }) {
+    if (!evidenceCallback)
+        return;
+    const probe = await captureProbeEvidence({
+        v3,
+        url,
+        logger,
+        warningMessage,
+    });
+    if (probe.screenshot) {
+        await evidenceCallback({
+            type: "screenshot",
+            screenshot: probe.screenshot,
+            url: probe.url,
+            evidenceRole: "probe",
+        });
+    }
+    await evidenceCallback({
+        type: "step_observed",
+        url: probe.url,
+        ariaTree: probe.ariaTree,
+    });
+}
+//# sourceMappingURL=postStepProbeEvidence.js.map

package/dist/cjs/lib/v3/agent/utils/postStepProbeEvidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postStepProbeEvidence.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/utils/postStepProbeEvidence.ts"],"names":[],"mappings":";;AAoBA,oDA8BC;AAED,8DA4BC;AA7ED,uEAAiE;AAajE,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAEM,KAAK,UAAU,oBAAoB,CAAC,EACzC,EAAE,EACF,GAAG,EACH,MAAM,EACN,cAAc,GACc;IAK5B,IAAI,QAAQ,GAAG,GAAG,CAAC;IACnB,IAAI,UAA8B,CAAC;IACnC,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;QAChD,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACtB,UAAU,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1D,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,CAAC;YACL,QAAQ,EAAE,OAAO;YACjB,OAAO,EAAE,GAAG,cAAc,KAAK,YAAY,CAAC,CAAC,CAAC,EAAE;YAChD,KAAK,EAAE,CAAC;SACT,CAAC,CAAC;IACL,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,IAAA,8CAAoB,EAAC,EAAE,CAAC,CAAC;IAChD,OAAO;QACL,GAAG,EAAE,QAAQ;QACb,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrC,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,CAAC;AACJ,CAAC;AAEM,KAAK,UAAU,yBAAyB,CAAC,EAC9C,EAAE,EACF,GAAG,EACH,gBAAgB,EAChB,MAAM,EACN,cAAc,GACmB;IACjC,IAAI,CAAC,gBAAgB;QAAE,OAAO;IAE9B,MAAM,KAAK,GAAG,MAAM,oBAAoB,CAAC;QACvC,EAAE;QACF,GAAG;QACH,MAAM;QACN,cAAc;KACf,CAAC,CAAC;IACH,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;QACrB,MAAM,gBAAgB,CAAC;YACrB,IAAI,EAAE,YAAY;YAClB,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,YAAY,EAAE,OAAO;SACtB,CAAC,CAAC;IACL,CAAC;IACD,MAAM,gBAAgB,CAAC;QACrB,IAAI,EAAE,eAAe;QACrB,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,QAAQ,EAAE,KAAK,CAAC,QAAQ;KACzB,CAAC,CAAC;AACL,CAAC","sourcesContent":["import type { AgentEvidenceCallback } from \"../../types/public/agentEvidenceEvents.js\";\nimport type { LogLine } from \"../../types/public/logs.js\";\nimport type { V3 } from \"../../v3.js\";\nimport { captureAriaTreeProbe } from \"./captureAriaTreeProbe.js\";\n\ninterface CaptureProbeEvidenceOptions {\n  v3: V3;\n  url: string;\n  logger: (message: LogLine) => void;\n  warningMessage: string;\n}\n\ninterface EmitPostStepProbeEvidenceOptions extends CaptureProbeEvidenceOptions {\n  evidenceCallback?: AgentEvidenceCallback;\n}\n\nfunction errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error);\n}\n\nexport async function captureProbeEvidence({\n  v3,\n  url,\n  logger,\n  warningMessage,\n}: CaptureProbeEvidenceOptions): Promise<{\n  url: string;\n  screenshot?: Buffer;\n  ariaTree?: string;\n}> {\n  let probeUrl = url;\n  let screenshot: Buffer | undefined;\n  try {\n    const page = await v3.context.awaitActivePage();\n    probeUrl = page.url();\n    screenshot = await page.screenshot({ fullPage: false });\n  } catch (e) {\n    logger({\n      category: \"agent\",\n      message: `${warningMessage}: ${errorMessage(e)}`,\n      level: 1,\n    });\n  }\n\n  const ariaTree = await captureAriaTreeProbe(v3);\n  return {\n    url: probeUrl,\n    ...(screenshot ? { screenshot } : {}),\n    ...(ariaTree !== undefined ? { ariaTree } : {}),\n  };\n}\n\nexport async function emitPostStepProbeEvidence({\n  v3,\n  url,\n  evidenceCallback,\n  logger,\n  warningMessage,\n}: EmitPostStepProbeEvidenceOptions): Promise<void> {\n  if (!evidenceCallback) return;\n\n  const probe = await captureProbeEvidence({\n    v3,\n    url,\n    logger,\n    warningMessage,\n  });\n  if (probe.screenshot) {\n    await evidenceCallback({\n      type: \"screenshot\",\n      screenshot: probe.screenshot,\n      url: probe.url,\n      evidenceRole: \"probe\",\n    });\n  }\n  await evidenceCallback({\n    type: \"step_observed\",\n    url: probe.url,\n    ariaTree: probe.ariaTree,\n  });\n}\n"]}

package/dist/cjs/lib/v3/agent/utils/toolOutputEvidence.d.ts

@@ -0,0 +1,2 @@
+import type { AgentStepFinishedEvent } from "../../types/public/agentEvidenceEvents.js";
+export declare function inferToolOutput(toolResult: unknown): AgentStepFinishedEvent["toolOutput"];

package/dist/cjs/lib/v3/agent/utils/toolOutputEvidence.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferToolOutput = inferToolOutput;
+const ERROR_STRING_LIMIT = 1000;
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function hasOwn(value, key) {
+    return Object.prototype.hasOwnProperty.call(value, key);
+}
+function normalizeError(value) {
+    if (value === undefined || value === null || value === false) {
+        return undefined;
+    }
+    if (value instanceof Error) {
+        return value.message;
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" ||
+        typeof value === "boolean" ||
+        typeof value === "bigint") {
+        return String(value);
+    }
+    let serialized;
+    try {
+        serialized = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        serialized = String(value);
+    }
+    if (serialized.length <= ERROR_STRING_LIMIT) {
+        return serialized;
+    }
+    return `${serialized.slice(0, ERROR_STRING_LIMIT)}... [truncated]`;
+}
+function statusCandidates(toolResult) {
+    if (!isRecord(toolResult)) {
+        return [];
+    }
+    const candidates = [toolResult];
+    const output = toolResult.output;
+    if (isRecord(output)) {
+        candidates.push(output);
+    }
+    return candidates;
+}
+function inferToolOutput(toolResult) {
+    const candidates = statusCandidates(toolResult);
+    const error = candidates
+        .map((candidate) => hasOwn(candidate, "error") ? normalizeError(candidate.error) : undefined)
+        .find((message) => message !== undefined);
+    const successFalse = candidates.some((candidate) => candidate.success === false);
+    const isError = candidates.some((candidate) => Boolean(candidate.isError));
+    return {
+        ok: error === undefined && !isError && !successFalse,
+        result: toolResult,
+        error,
+    };
+}
+//# sourceMappingURL=toolOutputEvidence.js.map

package/dist/cjs/lib/v3/agent/utils/toolOutputEvidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolOutputEvidence.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/utils/toolOutputEvidence.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AgentStepFinishedEvent } from \"../../types/public/agentEvidenceEvents.js\";\n\nconst ERROR_STRING_LIMIT = 1000;\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === \"object\" && !Array.isArray(value);\n}\n\nfunction hasOwn(value: Record<string, unknown>, key: string): boolean {\n  return Object.prototype.hasOwnProperty.call(value, key);\n}\n\nfunction normalizeError(value: unknown): string | undefined {\n  if (value === undefined || value === null || value === false) {\n    return undefined;\n  }\n  if (value instanceof Error) {\n    return value.message;\n  }\n  if (typeof value === \"string\") {\n    return value;\n  }\n  if (\n    typeof value === \"number\" ||\n    typeof value === \"boolean\" ||\n    typeof value === \"bigint\"\n  ) {\n    return String(value);\n  }\n\n  let serialized: string;\n  try {\n    serialized = JSON.stringify(value) ?? String(value);\n  } catch {\n    serialized = String(value);\n  }\n  if (serialized.length <= ERROR_STRING_LIMIT) {\n    return serialized;\n  }\n  return `${serialized.slice(0, ERROR_STRING_LIMIT)}... [truncated]`;\n}\n\nfunction statusCandidates(toolResult: unknown): Record<string, unknown>[] {\n  if (!isRecord(toolResult)) {\n    return [];\n  }\n\n  const candidates = [toolResult];\n  const output = toolResult.output;\n  if (isRecord(output)) {\n    candidates.push(output);\n  }\n  return candidates;\n}\n\nexport function inferToolOutput(\n  toolResult: unknown,\n): AgentStepFinishedEvent[\"toolOutput\"] {\n  const candidates = statusCandidates(toolResult);\n  const error = candidates\n    .map((candidate) =>\n      hasOwn(candidate, \"error\") ? normalizeError(candidate.error) : undefined,\n    )\n    .find((message): message is string => message !== undefined);\n\n  const successFalse = candidates.some(\n    (candidate) => candidate.success === false,\n  );\n  const isError = candidates.some((candidate) => Boolean(candidate.isError));\n\n  return {\n    ok: error === undefined && !isError && !successFalse,\n    result: toolResult,\n    error,\n  };\n}\n"]}

package/dist/cjs/lib/v3/agent/utils/wrapEvidenceCallback.d.ts

@@ -0,0 +1,3 @@
+import type { AgentEvidenceCallback } from "../../types/public/agentEvidenceEvents.js";
+import type { LogLine } from "../../types/public/logs.js";
+export declare function wrapEvidenceCallback(callback: AgentEvidenceCallback | undefined, logger: (message: LogLine) => void): AgentEvidenceCallback | undefined;

package/dist/cjs/lib/v3/agent/utils/wrapEvidenceCallback.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapEvidenceCallback = wrapEvidenceCallback;
+// onEvidence is a user-supplied observability hook (trajectory recording,
+// verifier capture, etc.). Wrap it once at the boundary where the handler
+// receives it so a throwing user callback can never abort the agent loop —
+// internal emit sites can then call the wrapped callback directly without
+// per-site try/catch.
+function wrapEvidenceCallback(callback, logger) {
+    if (!callback)
+        return undefined;
+    return async (event) => {
+        try {
+            await callback(event);
+        }
+        catch (e) {
+            logger({
+                category: "agent",
+                message: `Warning: onEvidence callback failed for ${event.type}: ${e instanceof Error ? e.message : String(e)}`,
+                level: 1,
+            });
+        }
+    };
+}
+//# sourceMappingURL=wrapEvidenceCallback.js.map

package/dist/cjs/lib/v3/agent/utils/wrapEvidenceCallback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapEvidenceCallback.js","sourceRoot":"","sources":["../../../../../../lib/v3/agent/utils/wrapEvidenceCallback.ts"],"names":[],"mappings":";;AAQA,oDAkBC;AAvBD,0EAA0E;AAC1E,0EAA0E;AAC1E,2EAA2E;AAC3E,0EAA0E;AAC1E,sBAAsB;AACtB,SAAgB,oBAAoB,CAClC,QAA2C,EAC3C,MAAkC;IAElC,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChC,OAAO,KAAK,EAAE,KAAK,EAAE,EAAE;QACrB,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,CAAC;gBACL,QAAQ,EAAE,OAAO;gBACjB,OAAO,EAAE,2CAA2C,KAAK,CAAC,IAAI,KAC5D,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAC3C,EAAE;gBACF,KAAK,EAAE,CAAC;aACT,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import type { AgentEvidenceCallback } from \"../../types/public/agentEvidenceEvents.js\";\nimport type { LogLine } from \"../../types/public/logs.js\";\n\n// onEvidence is a user-supplied observability hook (trajectory recording,\n// verifier capture, etc.). Wrap it once at the boundary where the handler\n// receives it so a throwing user callback can never abort the agent loop —\n// internal emit sites can then call the wrapped callback directly without\n// per-site try/catch.\nexport function wrapEvidenceCallback(\n  callback: AgentEvidenceCallback | undefined,\n  logger: (message: LogLine) => void,\n): AgentEvidenceCallback | undefined {\n  if (!callback) return undefined;\n  return async (event) => {\n    try {\n      await callback(event);\n    } catch (e) {\n      logger({\n        category: \"agent\",\n        message: `Warning: onEvidence callback failed for ${event.type}: ${\n          e instanceof Error ? e.message : String(e)\n        }`,\n        level: 1,\n      });\n    }\n  };\n}\n"]}

package/dist/cjs/lib/v3/api.d.ts

@@ -1,5 +1,6 @@
 import type { ActResult, AgentConfig, AgentExecuteOptions, AgentResult, ExtractResult, ObserveResult, LogLine, StagehandMetrics, BrowserbaseRegion, ActOptions, ExtractOptions, ObserveOptions, Api } from "./types/public/index.js";
 import type { SerializableResponse, AgentCacheTransferPayload } from "./types/private/index.js";
+import type { ModelConfiguration } from "./types/public/model.js";
 import type { StagehandZodSchema } from "./zodCompat.js";
 /**
  * Mapping of Browserbase regions to their corresponding Stagehand API base URLs.
@@ -41,6 +42,8 @@ interface ClientSessionStartParams extends Api.SessionStartRequest {
      *  Optional: when omitted, requests are sent without the x-model-api-key header
      *  and the server is expected to handle model authentication on its own. */
     modelApiKey?: string;
+    /** Default model config for later action requests. Not sent to /sessions/start. */
+    defaultModelConfig?: ModelConfiguration;
 }
 /**
  * Client parameters for act() method.
@@ -79,6 +82,7 @@ export declare class StagehandAPIClient {
     private sessionId?;
     private modelApiKey?;
     private modelProvider?;
+    private defaultModelConfig?;
     private region?;
     private logger;
     private fetchWithCookies;
@@ -87,7 +91,7 @@ export declare class StagehandAPIClient {
     private latestAgentCacheEntry;
     private warnedStagehandBaseUrl;
     constructor({ apiKey, projectId, logger, serverCache, }: StagehandAPIConstructorParams);
-    init({ modelName, modelApiKey, domSettleTimeoutMs, verbose, systemPrompt, selfHeal, browserbaseSessionCreateParams, browserbaseSessionID, }: ClientSessionStartParams): Promise<Api.SessionStartResult>;
+    init({ modelName, modelApiKey, defaultModelConfig, domSettleTimeoutMs, verbose, systemPrompt, selfHeal, browserbaseSessionCreateParams, browserbaseSessionID, }: ClientSessionStartParams): Promise<Api.SessionStartResult>;
     act({ input, options, frameId, }: ClientActParameters): Promise<ActResult>;
     extract<T extends StagehandZodSchema>({ instruction, schema: zodSchema, options, frameId, }: ClientExtractParameters): Promise<ExtractResult<T>>;
     observe({ instruction, options, frameId, }: ClientObserveParameters): Promise<ObserveResult>;
@@ -105,6 +109,8 @@ export declare class StagehandAPIClient {
      * model provider differs from the one used to init the session.
      */
     private prepareModelConfig;
+    private getDefaultModelConfig;
+    private getModelProvider;
     private consumeFinishedEventData;
     private execute;
     /**

package/dist/cjs/lib/v3/api.js

@@ -42,6 +42,7 @@ class StagehandAPIClient {
     sessionId;
     modelApiKey;
     modelProvider;
+    defaultModelConfig;
     region;
     logger;
     fetchWithCookies;
@@ -57,7 +58,7 @@ class StagehandAPIClient {
         // Create a single cookie jar instance that will persist across all requests
         this.fetchWithCookies = (0, fetch_cookie_1.default)(fetch);
     }
-    async init({ modelName, modelApiKey, domSettleTimeoutMs, verbose, systemPrompt, selfHeal, browserbaseSessionCreateParams, browserbaseSessionID,
+    async init({ modelName, modelApiKey, defaultModelConfig, domSettleTimeoutMs, verbose, systemPrompt, selfHeal, browserbaseSessionCreateParams, browserbaseSessionID,
     // browser,  TODO for local browsers
      }) {
         this.modelApiKey = modelApiKey;
@@ -65,6 +66,9 @@ class StagehandAPIClient {
         this.modelProvider = modelName?.includes("/")
             ? modelName.split("/")[0]
             : undefined;
+        this.defaultModelConfig = defaultModelConfig
+            ? this.prepareModelConfig(defaultModelConfig)
+            : undefined;
         // Store the region for multi-region API URL resolution
         this.region = browserbaseSessionCreateParams?.region;
         this.logger({
@@ -118,13 +122,21 @@ class StagehandAPIClient {
             // eslint-disable-next-line @typescript-eslint/no-unused-vars
             const { page: _, serverCache: enableCache, ...restOptions } = options;
             serverCache = enableCache;
+            if (restOptions.model) {
+                restOptions.model = this.prepareModelConfig(restOptions.model);
+            }
+            else if (this.defaultModelConfig) {
+                restOptions.model = this.getDefaultModelConfig();
+            }
             if (Object.keys(restOptions).length > 0) {
-                if (restOptions.model) {
-                    restOptions.model = this.prepareModelConfig(restOptions.model);
-                }
                 wireOptions = restOptions;
             }
         }
+        else if (this.defaultModelConfig) {
+            wireOptions = {
+                model: this.getDefaultModelConfig(),
+            };
+        }
         // Build wire-format request body
         const requestBody = {
             input,
@@ -147,13 +159,21 @@ class StagehandAPIClient {
             // eslint-disable-next-line @typescript-eslint/no-unused-vars
             const { page: _, serverCache: enableCache, ...restOptions } = options;
             serverCache = enableCache;
+            if (restOptions.model) {
+                restOptions.model = this.prepareModelConfig(restOptions.model);
+            }
+            else if (this.defaultModelConfig) {
+                restOptions.model = this.getDefaultModelConfig();
+            }
             if (Object.keys(restOptions).length > 0) {
-                if (restOptions.model) {
-                    restOptions.model = this.prepareModelConfig(restOptions.model);
-                }
                 wireOptions = restOptions;
             }
         }
+        else if (this.defaultModelConfig) {
+            wireOptions = {
+                model: this.getDefaultModelConfig(),
+            };
+        }
         // Build wire-format request body
         const requestBody = {
             instruction,
@@ -175,13 +195,21 @@ class StagehandAPIClient {
             // eslint-disable-next-line @typescript-eslint/no-unused-vars
             const { page: _, serverCache: enableCache, ...restOptions } = options;
             serverCache = enableCache;
+            if (restOptions.model) {
+                restOptions.model = this.prepareModelConfig(restOptions.model);
+            }
+            else if (this.defaultModelConfig) {
+                restOptions.model = this.getDefaultModelConfig();
+            }
             if (Object.keys(restOptions).length > 0) {
-                if (restOptions.model) {
-                    restOptions.model = this.prepareModelConfig(restOptions.model);
-                }
                 wireOptions = restOptions;
             }
         }
+        else if (this.defaultModelConfig) {
+            wireOptions = {
+                model: this.getDefaultModelConfig(),
+            };
+        }
         // Build wire-format request body
         const requestBody = {
             instruction,
@@ -195,7 +223,19 @@ class StagehandAPIClient {
         });
     }
     async goto(url, options, frameId) {
-        const requestBody = { url, options, frameId };
+        const publicOptions = { ...(options ?? {}) };
+        delete publicOptions.model;
+        const wireOptions = {
+            ...publicOptions,
+            ...(this.defaultModelConfig
+                ? { model: this.getDefaultModelConfig() }
+                : {}),
+        };
+        const requestBody = {
+            url,
+            options: Object.keys(wireOptions).length > 0 ? wireOptions : undefined,
+            frameId,
+        };
         return this.execute({
             method: "navigate",
             args: requestBody,
@@ -225,7 +265,7 @@ class StagehandAPIClient {
             cua: agentConfig.mode === undefined ? agentConfig.cua : undefined,
             model: agentConfig.model
                 ? this.prepareModelConfig(agentConfig.model)
-                : undefined,
+                : this.getDefaultModelConfig(),
             executionModel: agentConfig.executionModel
                 ? this.prepareModelConfig(agentConfig.executionModel)
                 : undefined,
@@ -381,28 +421,41 @@ class StagehandAPIClient {
     prepareModelConfig(model) {
         if (typeof model === "string") {
             // Extract provider from model string (e.g., "openai/gpt-5-nano" -> "openai")
-            const provider = model.includes("/") ? model.split("/")[0] : undefined;
+            const provider = this.getModelProvider(model);
+            const inheritedDefault = provider && provider === this.modelProvider
+                ? this.getDefaultModelConfig()
+                : undefined;
             const apiKey = provider && provider !== this.modelProvider
                 ? ((0, utils_js_1.loadApiKeyFromEnv)(provider, this.logger) ?? this.modelApiKey)
                 : this.modelApiKey;
             return {
+                ...inheritedDefault,
                 modelName: model,
                 ...(apiKey ? { apiKey } : {}),
             };
         }
-        if (!model.apiKey) {
-            const provider = model.modelName?.includes("/")
-                ? model.modelName.split("/")[0]
+        const provider = this.getModelProvider(model.modelName);
+        const inheritedDefault = provider && provider === this.modelProvider
+            ? this.getDefaultModelConfig()
+            : undefined;
+        const apiKey = !model.apiKey && provider && provider !== this.modelProvider
+            ? ((0, utils_js_1.loadApiKeyFromEnv)(provider, this.logger) ?? this.modelApiKey)
+            : !model.apiKey
+                ? this.modelApiKey
                 : undefined;
-            const apiKey = provider && provider !== this.modelProvider
-                ? ((0, utils_js_1.loadApiKeyFromEnv)(provider, this.logger) ?? this.modelApiKey)
-                : this.modelApiKey;
-            return {
-                ...model,
-                ...(apiKey ? { apiKey } : {}),
-            };
-        }
-        return model;
+        return {
+            ...inheritedDefault,
+            ...model,
+            ...(apiKey ? { apiKey } : {}),
+        };
+    }
+    getDefaultModelConfig() {
+        return this.defaultModelConfig
+            ? { ...this.defaultModelConfig }
+            : undefined;
+    }
+    getModelProvider(modelName) {
+        return modelName?.includes("/") ? modelName.split("/")[0] : undefined;
     }
     consumeFinishedEventData() {
         const data = this.lastFinishedEventData;
@@ -584,12 +637,30 @@ class StagehandAPIClient {
         else {
             baseUrl = getApiUrlForRegion(this.region);
         }
+        const headers = {
+            ...defaultHeaders,
+            ...options.headers,
+        };
+        if (path.endsWith("/navigate")) {
+            let body = options.body;
+            if (typeof options.body === "string") {
+                try {
+                    body = JSON.parse(options.body);
+                }
+                catch {
+                    body = options.body;
+                }
+            }
+            console.log("Stagehand goto request", JSON.stringify({
+                url: `${baseUrl}${path}`,
+                method: options.method,
+                headers,
+                body,
+            }, null, 2));
+        }
         const response = await this.fetchWithCookies(`${baseUrl}${path}`, {
             ...options,
-            headers: {
-                ...defaultHeaders,
-                ...options.headers,
-            },
+            headers,
         });
         return response;
     }